请求镜像

请求镜像（也称流量影子）将线上流量的副本发送到辅助后端，而主请求则继续发往生产后端。镜像副本的响应会被丢弃。客户端永远看不到镜像流量，镜像失败也永远不会影响主响应。

请求镜像的工作原理

网关在代理请求时，会检查匹配的 HTTPRoute 是否在后端规则上附加了 RequestMirror 过滤器。如果镜像过滤器存在且采样决策选中了该请求，网关会将请求分叉为两条路径：

主路径正常前往选定的生产后端。客户端接收到此响应。
镜像路径将同一请求的副本（相同 Header、相同请求体、相同方法）发送到另一个后端，即影子后端。镜像响应会被完整消费然后丢弃。

镜像是发后即忘。如果影子后端响应慢，主响应不会被延迟。如果影子后端返回错误，主响应不受影响。如果影子后端超时，网关会断开镜像连接并继续前行。

配置请求镜像

镜像作为过滤器配置在 HTTPRoute 后端规则上。RequestMirror 过滤器类型携带一个指向影子后端的 backendRef，以及用于细粒度采样的 percent（0 到 100）或 fraction：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: production-route
  namespace: nantian-demo
spec:
  parentRefs:
    - name: nantian-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: production-service
          port: 8080
      filters:
        - type: RequestMirror
          requestMirror:
            backendRef:
              name: canary-service
              namespace: nantian-demo
              port: 8080
            percent: 5

此配置将匹配 /api 路径前缀的 5% 请求镜像到 canary-service 后端。其余 95% 的请求只发送到 production-service。两个后端会收到完全相同的镜像请求副本。

采样选项

镜像流量的百分比由以下两个字段之一控制：

字段	类型	示例	使用场景
`percent`	u32（0-100）	`percent: 10` 镜像 10% 的请求。	简单的基于百分比的采样。
`fraction`	`{ numerator, denominator }`	`fraction: { numerator: 1, denominator: 1000 }` 镜像千分之一的请求。	流量非常高时的精确分数采样。

当 percent 和 fraction 同时设置时，fraction 优先级更高。当两者都不存在或为零时，不会镜像任何请求。percent: 100 表示镜像每一个请求。

采样决策在每个请求上独立做出，基于按请求播种的随机数生成器。在数千次请求中，实际镜像率会收敛到配置的百分比。对于低流量路由，单次突发可能会偏离目标比例。

镜像请求的执行

镜像请求作为子请求在网关的连接池中执行。网关对镜像流量强制执行并发预算，防止镜像耗尽后端连接。默认预算为整个数据平面进程中最多 1024 个并发镜像子请求。你可以通过数据平面配置中的 configureRequestMirrorBudget 进行调整。

当镜像预算耗尽时，新的镜像会被直接丢弃，不会向调用方返回任何错误。每丢弃 256 次会记录一条警告日志。如果镜像请求体通道已满（消费前最多缓存一个请求体数据块），镜像也会被丢弃，这样可以防止慢速影子后端在内存中无上限地缓冲请求体。

对于无请求体的请求（GET、HEAD、DELETE），镜像子请求发送 Header 并等待影子后端响应，然后丢弃响应。等待时间上限为 100 毫秒。如果影子后端在此时间内未响应，镜像将超时，后台任务也会被放弃。

性能影响

镜像流量与主流量共享网关的连接池和 CPU 资源。在较高的镜像比例下，开销是显著的：

每个镜像请求在处理期间会消耗连接池中的一个后端连接。
请求体镜像需要为影子路径复制请求体字节。大请求体（上传、流式传输）会放大内存和网络开销。
镜像子请求使用的 I/O 线程原本可以处理主请求。

从较低的镜像比例（1% 到 5%）开始，逐步提高，同时监控网关的资源使用和延迟。100ms 的镜像等待超时意味着慢速影子后端不会阻塞主连接，但仍会消耗连接槽位。

镜像不会影响主响应的延迟路径。主响应在网关等待任何镜像响应之前就已发送给客户端。镜像等待在主响应流完成后以后台任务的方式运行。

使用场景

请求镜像的常见模式：

灰度测试。 将新版本的服务部署为影子后端。将部分生产流量镜像到该后端，对比生产实例和影子实例的响应体和状态码。如果影子出现不一致，你可以在向用户上线之前发现回归问题。

预发环境验证。 将镜像流量导向在真实负载下运行但不对用户可见的预发环境。验证数据库迁移、API schema 变更和基础设施更新在生产流量模式下表现是否正确。

负载测试。 将流量镜像到运行负载测试工具的独立集群。镜像流量作为可重现的真实工作负载，无需生成合成请求的开销。

可观测性预热。 将镜像流量导入新的可观测性管道（追踪后端、日志聚合器），在主流量进入之前验证你的埋点能正确捕获 Span 和指标。