五步部署快连VPN

1. 准备规则文件

   把分流决策从代码里抽出来，成为一份可版本管理的配置。

   /opt/kl/rules.yaml

   default: direct
   rules:
     - label: kl.route=proxy
       action: proxy
     - image: "registry.ci.acme.com/builder/*"
       action: proxy
     - cidr: "10.0.0.0/8"
       action: direct
     - cidr: "169.254.0.0/16"
       action: direct   # 云元数据必须直连

   默认动作设为 direct，保证规则有遗漏时流量仍按原链路走；内网段与云元数据地址显式声明为直连，避免容器访问内部服务时被规则误送至隧道。各维度的优先级与写法见 分流规则优先级。

2. 拉取并校验官方镜像

   锁定 tag 与 digest，确保运行的是未被替换的官方构建。

   终端

   docker pull registry.kiualanad.com.cn/kl/kl-proxy:v2.4.1
   docker image inspect registry.kiualanad.com.cn/kl/kl-proxy:v2.4.1 \
     --format '{{index .RepoDigests 0}}'

   tag 可以被重新指向，digest 不行。请把命令输出的完整 digest 写入部署基线，并与 下载页的来源核验一节给出的摘要比对；离线环境还需执行 sha256sum -c 校验归档文件后再导入。

3. 创建业务网络并接入容器

   独立网络让加速容器与业务容器共享同一网络命名空间。

   终端

   docker network create kl-net
   
   docker run -d --name kl-proxy \
     --network kl-net \
     --cap-add NET_ADMIN --device /dev/net/tun \
     -v /opt/kl/rules.yaml:/etc/kl/rules.yaml:ro \
     --restart unless-stopped \
     registry.kiualanad.com.cn/kl/kl-proxy:v2.4.1 \
     --config /etc/kl/rules.yaml --mode container
   
   docker network connect kl-net your-app

   --mode container 表示加速只在容器网络命名空间内生效，不会写入宿主机 main 路由表。NET_ADMIN 与 /dev/net/tun 只授予加速容器自身，用于在容器内建立隧道设备与策略路由表，不改变宿主机能力集。隔离原理见 隔离架构。

4. 设置分流标签

   用标签精确控制「哪些容器走加速」，无需重建镜像。

   Kubernetes · DaemonSet 片段

   metadata:
     labels:
       kl.route: proxy      # 命中优先级 100 的标签规则
     annotations:
       kl.cn/config: /etc/kl/rules.yaml

   标签规则优先级最高，会覆盖镜像名与域名维度的判断；注解用于告诉注入组件去哪里读取规则文件，规则本身仍以 ConfigMap 只读挂载。集群环境的完整注入方式见 场景方案 · Kubernetes。

5. 验证生效并确认宿主机零改动

   用前后 diff 证明宿主机路由没有被写入任何新规则。

   终端 · 校验

   # 1) 记录宿主机当前规则
   ip rule show > /tmp/before.txt
   
   # 2) 触发一次业务请求，检查容器内命中
   docker exec kl-proxy kl-ctl status
   
   # 3) 再次对比，确认 main 表零变更
   ip rule show > /tmp/after.txt
   diff /tmp/before.txt /tmp/after.txt && echo "宿主机路由未变更"
   
   # 4) 确认 core dump 已关闭
   docker exec kl-proxy sh -c 'ulimit -c'

   预期输出

   第 2 条应输出容器内的策略路由表（表 100 指向隧道设备）与规则命中统计，能看到哪条规则被命中；第 3 条的 diff 无差异并打印「宿主机路由未变更」，说明 main 表新增规则数为 0；第 4 条输出 0，表示崩溃转储已关闭。其他等价验证方式见 如何验证零改动。

services:
  kl-proxy:
    image: registry.kiualanad.com.cn/kl/kl-proxy:v2.4.1
    container_name: kl-proxy
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    volumes:
      - kl-rules:/etc/kl:ro
    networks:
      - kl-net
    command: ["--config", "/etc/kl/rules.yaml", "--mode", "container"]

  your-app:
    image: registry.ci.acme.com/builder/app:latest
    restart: unless-stopped
    networks:
      - kl-net
    labels:
      kl.route: proxy

networks:
  kl-net:
    name: kl-net

volumes:
  kl-rules:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /opt/kl

cap_add + devices

等价于命令行的 --cap-add NET_ADMIN --device /dev/net/tun。两者只作用于加速容器自身，用于在容器命名空间内建立隧道设备与策略路由表。

volumes → kl-rules

等价于命令行的 -v /opt/kl/rules.yaml:/etc/kl/rules.yaml:ro。这里把宿主机目录 /opt/kl 声明为一个 driver_opts.type=none 的本地卷，再只读挂载到容器的 /etc/kl，规则文件的来源路径与只读属性完全不变。

command

等价于镜像启动参数 --config /etc/kl/rules.yaml --mode container。--mode container 是宿主机路由零改写的关键，不要改成 node。

labels.kl.route

等价于在业务容器上声明分流标签，命中优先级 100 的标签规则。Docker 场景同样支持这一写法，Kubernetes 下改由 DaemonSet 注入方式实现。