快连VPN 智能分流引擎 - 六维分流规则与优先级说明

Q: 未命中任何规则的流量会怎么处理？

未命中任何维度的流量走配置里的默认动作，即 default: direct。默认动作可以改成 proxy，但建议保持 direct：这样新增流量必须被显式规则覆盖，规则遗漏时表现为「没走加速」而不是「被静默代理」，排查成本更低。

Q: 规则文件改动后如何生效？需要重建容器吗？

规则文件以只读卷挂载到 /etc/kl/rules.yaml，进程按固定间隔比对文件内容，检测到变更后重新加载规则表并输出一次加载事件，无需重建容器，也不需要重启业务容器。加载失败时保留上一份可用规则并在状态输出中给出原因码。

01 · 设计动机

为什么需要分流引擎

全局加速和按域名分流都只解决了部分问题。分流引擎要做的是把「哪些流量走哪个出口」变成一份可版本管理、可审计的显式配置。

全局加速的副作用

接入后所有出向流量都改道

容器内的内网调用、云元数据访问、数据库连接一并被送进加速链路，表现为接口变慢、连接超时，甚至把实例凭据暴露给第三方链路。开关只有开与关两种粒度，无法只对某类流量生效。

按域名分流的局限

只看得到域名，看不到发起方

域名表无法覆盖镜像仓库、CDN 短链与解析结果动态变化的场景；同一域名在不同工作负载里的意图也不相同。缺少进程、镜像与标签这些维度，规则会迅速膨胀且互相冲突。

多出口下的归属不清

无法回答「这条流量走了哪个出口」

当合规要求按租户、按命名空间区分出口时，单一全局配置不产生任何归属证据。缺少命中记录，审计只能靠事后抓包反推，结论不可复现。

分流引擎的定位

分流引擎不是一个加速通道，而是加速通道前面的决策层：它按固定优先级逐层匹配规则，为每条连接选定出口，并把命中结果记录为可导出的决策元数据。引擎只在容器网络命名空间内工作，不修改宿主机路由，隔离边界见隔离架构；镜像获取方式见快连下载。

02 · 优先级表

六个维度的匹配优先级

优先级数字越小越先匹配。命中任一维度后立即停止向下遍历，后面的规则不再评估。默认动作固定为 999，作为兜底。

表 1：智能分流六维优先级表（规则格式基于 v2.4.1；字段与取值以官方镜像内置的规则 schema 为准）
优先级	匹配维度	匹配对象	规则写法示例	命中后动作
100	标签	容器或工作负载 label	kl.route=proxy	整容器强制走代理
200	镜像名	容器镜像引用	registry.cn-hangzhou.aliyuncs.com/acme/*	该镜像的出向流量走代理
300	进程名	容器内发起连接的进程	npm \| pip \| gradle	仅构建类进程走代理
400	域名	连接目标域名	*.npmjs.org	命中域名走代理，其余直连
500	IP 段	目标地址	10.0.0.0/8, 172.17.0.0/16	内网地址段保持直连
600	端口	目标端口	443, 8443	仅匹配端口走代理
999	默认动作	以上均未命中的流量	default: direct	兜底直连

169.254.0.0/16 必须 direct

云厂商实例元数据服务位于链路本地地址段 169.254.0.0/16。该网段被送入代理出口意味着实例凭据要经过第三方链路：轻则元数据请求超时、业务取不到实例身份，重则构成凭据外泄。引擎为该网段保留强制直连路径，无论是否被其它规则覆盖都不会改写其出口。请勿为该网段编写任何指向 proxy 的规则。

优先级是分流规则的判据，标签打法的完整说明见部署文档的设置分流标签一步；协议与端口的对应关系见镜像矩阵。

03 · 规则文件

规则文件写法

规则文件为 YAML，挂载到容器的 /etc/kl/rules.yaml。文件顶层只有 default 与 rules 两项，rules 为有序列表，顺序即优先级顺序。

/opt/kl/rules.yaml

default: direct          # 兜底动作：未命中任何规则时直连

rules:
  # 优先级 100 · 标签：调度侧的显式意图，最高优先级
  - label: kl.route=proxy
    action: proxy

  # 优先级 200 · 镜像名：同类镜像整体划到加速出口
  - image: "registry.cn-hangzhou.aliyuncs.com/acme/*"
    action: proxy

  # 优先级 300 · 进程名：只把构建类进程放进加速链路
  - process: "npm|pip|gradle"
    action: proxy

  # 优先级 400 · 域名：支持 *. 前缀通配
  - domain: "*.npmjs.org"
    action: proxy

  # 优先级 500 · IP 段：逗号分隔，内网地址段保持直连
  - cidr: "10.0.0.0/8,172.17.0.0/16"
    action: direct

  # 优先级 600 · 端口：逗号分隔，仅匹配端口走代理
  - port: "443,8443"
    action: proxy

YAML schema 说明

default: 字符串类型，取值为 direct 或 proxy，对应优先级 999。缺省时按 direct 处理。
rules: 有序列表，每一项描述一个匹配条件与其动作。列表顺序即匹配顺序，写在前面的规则先被评估。
匹配字段: 每条规则只声明一个匹配字段：label、image、process、domain、cidr、port。同一条规则里混合多个字段不会被解析。
匹配值语法: 字符串类型。image 与 domain 支持 * 通配；process 支持 | 分隔的多个候选；cidr 与 port 支持逗号分隔的多个取值。
action: 字符串类型，取值为 direct 或 proxy，表示命中后该连接的出口。
文件加载方式: 以只读卷挂载到 /etc/kl/rules.yaml，由 --config /etc/kl/rules.yaml 指定。文件内容变化后进程重新加载规则表，加载失败时保留上一份可用规则。

把规则纳入版本管理

规则文件是纯文本，适合与业务代码一起进版本库、评审后发布。修改规则不需要重建镜像或重启业务容器，先在预发环境用同一份文件验证命中情况，再灰度到生产。完整发布流程见快连VPN 部署文档。

04 · 配置示例

典型配置示例

下面三段配置覆盖最常见的三类需求：构建加速、多出口审计、内网强制直连。均为完整可读版本，可直接改写为部署基线。

场景一：CI 构建容器整体走加速

构建容器内除了依赖下载，还会访问内网制品库与云元数据。用镜像名规则把构建流量整体划到加速出口，同时保留内网直连路径：

rules.yaml · CI 构建

default: direct
rules:
  # 构建容器整体走加速
  - image: "registry.cn-hangzhou.aliyuncs.com/acme/builder/*"
    action: proxy

  # 内网制品库保持直连，避免绕行
  - cidr: "10.0.0.0/8,172.17.0.0/16"
    action: direct

  # 云元数据必须直连
  - cidr: "169.254.0.0/16"
    action: direct

未给构建容器打标签时，镜像名规则即可生效；若该镜像还有需要直连的使用场景，改用标签规则显式指定，避免影响同一镜像的其它引用。相关场景说明见场景方案。

场景二：多出口审计，按命名空间分出口

集群内不同命名空间需要走不同出口时，用标签区分出口组。每条命中都会产生决策记录，可用于回答「这条流量走了哪个出口」：

rules.yaml · 多出口

default: direct
rules:
  # 出口 A：研发命名空间
  - label: kl.route=proxy
    action: proxy
    note: "出口A / egress-a"

  # 出口 B：测试命名空间走另一条链路
  - label: kl.route=proxy-b
    action: proxy
    note: "出口B / egress-b"

  # 生产命名空间显式直连
  - label: kl.route=direct
    action: direct

note 字段为可选备注，用于在审计输出中标注出口归属，示例值仅为口径说明。命名空间维度的隔离原理见容器网络隔离。

场景三：内网与云元数据强制直连

作为其它规则的基础底稿，建议每个环境都保留这一段，避免新增规则时把内网与元数据地址误送进加速链路：

rules.yaml · 强制直连底稿

default: proxy          # 默认走加速，其余显式例外
rules:
  # 内网地址段直连
  - cidr: "10.0.0.0/8,172.16.0.0/12,172.17.0.0/16,192.168.0.0/16"
    action: direct

  # 链路本地与云元数据直连，任何情况下不改写
  - cidr: "169.254.0.0/16"
    action: direct

  # 集群内部服务地址直连
  - domain: "*.svc.cluster.local,*.internal.corp"
    action: direct

这一段把默认动作改为 proxy，因此所有内网类目标都必须显式列出。规则越完备越需要定期复核，复核方式见常见问题。

05 · 命中审计

命中审计

每条连接在确定出口的同时产生一条决策记录，包含规则编号、命中维度、动作与时间戳四个字段，用于解释分流行为与核对配置。

终端 · 查看命中状态

docker exec kl-proxy kl-ctl status

表 2：`kl-ctl status` 输出字段含义（字段名与取值格式以 v2.4.1 实际输出为准）
字段	含义	排查用途
rule	命中的规则编号与优先级	判断命中的是不是预期那条规则
dimension	命中维度：label / image / process / domain / cidr / port / default	定位是哪一层规则生效
action	该连接的出口动作：proxy 或 direct	确认流量最终走了哪条链路
at	决策时间戳	与业务侧日志对齐，定位变更引入的时间点

审计只记录决策元数据

审计记录中只有规则编号、命中维度、动作与时间戳，不包含访问域名、目标 IP、会话内容与账号标识，因此可用于导出与交付。日志白名单范围、崩溃转储关闭与内存中的密钥生命周期说明见零日志隐私栈。

若命中结果与预期不符，先核对容器标签与规则文件是否匹配，再确认维度顺序是否符合优先级表；镜像启动参数与规则挂载方式见部署文档。

06 · 常见问题

分流相关常见问题

以下四条是分流规则使用过程中最常被问到的问题。更完整的问题清单见快连VPN 常见问题。

分流规则的匹配顺序是怎样的？为什么标签优先级最高？

引擎按「标签 → 镜像名 → 进程名 → 域名 → IP 段 → 端口 → 默认动作」的顺序逐层匹配，命中任一维度即停止向下遍历，对应优先级 100、200、300、400、500、600、999。标签放在最前，是因为它代表调度侧的显式意图：同一个镜像可能同时被需要加速和需要直连的工作负载引用，只有容器或工作负载级的标签能区分这两种用法。

未命中任何规则的流量会怎么处理？

未命中任何维度的流量走配置里的默认动作，即 default: direct。默认动作可以改成 proxy，但建议保持 direct：这样新增流量必须被显式规则覆盖，规则遗漏时表现为「没走加速」而不是「被静默代理」，排查成本更低。

为什么 169.254.0.0/16 必须保持 direct，不能被其它规则覆盖？

169.254.0.0/16 是云厂商实例元数据服务所在的链路本地地址段。把它送进代理出口意味着把实例凭据交给第三方链路：轻则元数据请求超时导致业务取不到实例身份，重则构成凭据外泄。引擎为该网段保留强制直连路径，即使其它规则命中也不改写其出口。

规则文件改动后如何生效？需要重建容器吗？

规则文件以只读卷挂载到 /etc/kl/rules.yaml，进程按固定间隔比对文件内容，检测到变更后重新加载规则表并输出一次加载事件，无需重建容器，也不需要重启业务容器。加载失败时保留上一份可用规则并在状态输出中给出原因码。

智能分流引擎：六个维度决定流量出口