在微服务灰度发布、A/B 测试和故障演练等场景中，集群流量控制如果只依赖域名和路径，往往无法满足精细化的分流需求。比如同一个入口域名下，希望根据请求头 X-Region 的值把用户请求发送到不同地域的服务实例，或者根据 X-User-Type 把内部测试用户与普通用户隔离开。与此同时，线上流量镜像也是一种常见需求：在不影响真实请求的前提下，把请求异步复制到预发布或影子服务，用于验证新版本逻辑、进行性能压测或安全审计。Kubernetes 本身的基础 Ingress 资源并不直接支持这些能力，但通过 Ingress NGINX、Istio 等扩展可以轻松实现。
一、基于请求头路由的实现基础
Kubernetes 原生 Ingress API 在设计上只关注 host 和 path 两个维度的匹配，无法单独根据 HTTP 请求头做转发判断。要实现基于头的路由，需要借助 Ingress Controller 的扩展能力或服务网格层面的路由规则。目前最常用的两种方式是 Ingress NGINX 的 canary 注解和 Istio 的 VirtualService。
Ingress NGINX 提供了一组 canary 相关注解，其中 nginx.ingress.kubernetes.io/canary-by-header 可以指定一个请求头名称。当请求携带该请求头时，流量会被转发到 canary Ingress 对应的后端服务。例如主 Ingress 将请求转发到 app-v1 服务，而 canary Ingress 将满足条件的请求转发到 app-v2 服务。默认情况下只要请求头存在，就会命中 canary 规则；如果还设置了 canary-by-header-value，则必须请求头的值与该注解指定的值完全一致才会命中。
这种机制非常适合简单的灰度场景，比如内部用户带上 X-Canary: always 就能访问到新版本服务。但它也有局限：一个 canary Ingress 只能绑定一个服务，多个不同请求头值需要映射到多个版本时，配置会变得复杂。此时更适合使用 Istio 的 VirtualService 来声明式地描述请求头匹配规则。
下面是一个 Ingress NGINX 通过请求头进行灰度路由的示例，canary Ingress 会把带 X-Canary: true 的请求发送到 app-v2 服务：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app-canary
annotations:
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "X-Canary"
nginx.ingress.kubernetes.io/canary-by-header-value: "true"
spec:
rules:
- host: app.ippipp.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-v2
port:
number: 80
主 Ingress 不需要 canary 注解，它会把其余不满足 canary 条件的请求继续转发到 app-v1。两个 Ingress 必须共享相同的 host 和 path，否则分流规则不会生效。
二、流量镜像的工作机制与配置
流量镜像也叫影子流量，指的是把生产流量复制一份异步发送到另一个目标服务，而客户端仍然只接收主服务的响应。镜像请求的结果不会返回给客户端，主服务也不会因为镜像请求失败而受影响。这种能力在预发布验证中非常有用：可以让测试服务接触真实请求的完整上下文，又不会污染线上数据或影响用户请求。
在 NGINX 中，流量镜像通过 mirror 指令实现。Kubernetes 的 Ingress NGINX 没有直接提供镜像注解，但可以通过 server-snippet 或 configuration-snippet 注入 NGINX 配置。下面是一个使用 server-snippet 配置镜像的 Ingress 示例，它把发往 app-stable 的请求复制一份给 app-shadow：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app-stable
annotations:
nginx.ingress.kubernetes.io/server-snippet: |
location / {
mirror /mirror;
mirror_request_body on;
}
location = /mirror {
internal;
proxy_pass http://app-shadow.default.svc.cluster.local$request_uri;
}
spec:
rules:
- host: app.ippipp.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-stable
port:
number: 80
上述配置中，mirror 指令会把请求复制到内部 location = /mirror，再由该 location 转发到影子服务。这里必须加上 internal，防止外部客户端直接访问镜像路径。还需要注意 mirror_request_body on，否则默认只镜像请求头，不镜像请求体，很多 POST 场景会丢失数据。
Istio 的流量镜像能力更加原生和直观。在 VirtualService 的 HTTP 路由中，可以直接使用 mirror 字段指定镜像目标，还可以通过 mirrorPercentage 控制镜像比例。下面的示例将 100% 的请求镜像到 reviews-v3 服务：
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: reviews-route
spec:
hosts:
- reviews.prod.svc.cluster.local
http:
- route:
- destination:
host: reviews.prod.svc.cluster.local
subset: v1
mirror:
host: reviews.prod.svc.cluster.local
subset: v3
mirrorPercentage:
value: 100
三、Istio VirtualService 头路由与镜像组合实践
Istio 的 VirtualService 支持在 http 列表里定义多个 match 条件，每个 match 下可以精确匹配请求头。请求头匹配的值支持 exact、prefix 和 regex 三种模式，而且多个条件之间是逻辑与的关系。匹配规则从上到下依次评估，命中第一个规则后不再继续匹配后续规则，因此配置顺序会影响路由结果。
假设一个评论服务有三个版本：v1 为稳定版本，v2 为内部测试版本，v3 为影子分析版本。需求是：当请求头 end-user 的值为 jason 时，路由到 v2；同时把这些请求镜像一份到 v3，用于观察新版本对特定用户请求的处理表现。其他请求继续访问 v1。对应的 VirtualService 配置如下：
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: reviews-route
spec:
hosts:
- reviews.prod.svc.cluster.local
http:
- match:
- headers:
end-user:
exact: jason
route:
- destination:
host: reviews.prod.svc.cluster.local
subset: v2
mirror:
host: reviews.prod.svc.cluster.local
subset: v3
mirrorPercentage:
value: 100
- route:
- destination:
host: reviews.prod.svc.cluster.local
subset: v1
上面的规则中，第一个 match 使用 exact 精确比较请求头 end-user 的值。如果请求头不存在或者值不是 jason，则会跳过第一个 match，继续执行第二个路由规则，把所有请求发送到 v1。如果希望匹配值不区分大小写，可以在 match 下添加 ignoreUriCase: true，但请求头名称本身通常仍区分大小写。
要使用 subset 路由，还必须配置对应的 DestinationRule，为每个版本定义子集。示例配置如下：
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: reviews-destination
spec:
host: reviews.prod.svc.cluster.local
subsets:
- name: v1
labels:
version: v1
- name: v2
labels:
version: v2
- name: v3
labels:
version: v3
需要注意的是，镜像目标服务接收到的请求头、请求体与原始请求基本一致，但源 IP 等网络层信息会发生变化。镜像请求如果产生副作用，比如写入数据库、发送短信或触发订单创建，就可能造成数据重复或错误。因此镜像目标应该尽量是无状态的只读服务，或者使用独立的测试数据库。
四、NGINX Ingress 头路由与镜像配置解析
除了 canary 注解，Ingress NGINX 还支持通过配置片段实现更灵活的请求头判断和镜像转发。比如当需要根据多个请求头组合条件进行路由时，可以在 configuration-snippet 中写一段 NGINX 配置，利用 if 指令检查变量。以下示例配置了两个服务：当请求头 X-Env 为 test 时转发到 app-test，否则转发到 app-prod。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app-header-route
annotations:
nginx.ingress.kubernetes.io/configuration-snippet: |
if ($http_x_env = "test") {
proxy_pass http://app-test.default.svc.cluster.local;
break;
}
proxy_pass http://app-prod.default.svc.cluster.local;
spec:
rules:
- host: app.ippipp.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-prod
port:
number: 80
这种写法虽然灵活，但 NGINX 官方文档明确指出 if 指令在 location 场景下容易产生不可预期的行为，尤其是与 proxy_pass 搭配时需要特别小心。因此当路由逻辑变得复杂时，更推荐使用 Istio 或者在应用层实现路由决策。
Kubernetes Gateway API 也在逐步完善基于请求头的路由能力。Gateway API 的 HTTPRoute 资源原生支持 matches 字段，可以配置 headers 匹配。虽然目前多数集群仍以 Ingress 为主，但 Gateway API 是未来更标准化的方向，值得关注。
五、常见问题与避坑指南
基于请求头的路由虽然灵活，但错误配置可能导致流量全部落入同一服务，或者出现部分请求匹配不到任何规则的情况。尤其是在使用多个 canary Ingress 时，如果注解值写错或者大小写不匹配，灰度服务可能一直收不到请求。排查时可以先用 curl 命令显式携带请求头访问入口，观察响应是否来自预期版本。
流量镜像最常见的坑是忽视副作用。镜像请求会真实地到达目标服务，如果目标服务连接的是生产数据库或外部支付接口，就可能造成重复扣款、脏数据等问题。因此镜像目标环境必须与生产环境在数据层面隔离。另一个问题是镜像失败处理：镜像请求是非阻塞的，目标服务超时或返回错误不会影响主请求，但这不意味着可以完全忽略镜像服务的健康状态。建议对镜像目标的错误日志和延迟指标进行独立监控，否则可能出现镜像数据长期缺失而没人发现的情况。
性能方面，镜像会消耗额外的网络带宽和 CPU，尤其是请求体较大的场景。如果不需要镜像请求体，应关闭 mirror_request_body 或适当降低镜像比例。在 Istio 中可以通过 mirrorPercentage 设置小于 100 的比例，但在 Envoy 实现中，百分比是按请求次数随机采样的，不能保证严格精确。
最后要提醒的是，请求头值可能来自用户输入，存在大小写不一致、编码异常或被恶意构造的风险。在设计匹配规则时，尽量使用精确匹配并明确可接受的值集合，避免直接使用未校验的用户输入作为路由依据。对于安全敏感场景，还应在服务端再次校验身份和权限，不能只依赖入口层的请求头路由。
Kubernetes基于头的路由流量镜像修改时间：2026-08-26 12:03:47