Nginx 工程实践 -- 21. 流量镜像 mirror

想在不影响线上用户的前提下验证新版本,最常见的做法是把真实流量复制一份给测试环境——线上主请求照常响应,影子请求打到新版本做验证。Nginx 的 ngx_http_mirror_module(1.13.4+)让这件事在网关层完成,不需要改应用代码。

flowchart TD
    A["主请求"] --> B["Nginx 处理
返回主响应"] A -->|"mirror"| C["影子请求
复制到测试上游"] C --> D["响应被丢弃
仅用于记录 / 压测"] B --> E["客户端只收到主响应"] D --> F["影子日志 / 测试环境"]

一、基本配置

1
2
3
4
5
6
7
8
9
10
location /api/ {
mirror /mirror;
proxy_pass http://backend_prod;
}

location = /mirror {
internal;
proxy_pass http://backend_test$request_uri;
proxy_set_header Host $host;
}
  • mirror /mirror; 声明一个内部 location 作为影子目标;
  • 影子 location 通常加 internal,只能由镜像触发,不能外部直连;
  • 影子请求与原请求并发发出,主请求的响应不等影子。

二、镜像请求体

默认只镜像请求行和头,不镜像请求体。需要压测带 body 的接口时开启:

1
2
3
4
5
location /upload/ {
mirror /mirror;
mirror_request_body on;
proxy_pass http://backend_prod;
}
  • mirror_request_body off(默认):影子请求不带 body;
  • 对大 body 开启镜像会显著增加带宽和内存,按需使用。

三、适用场景

场景说明
版本验证真实流量打到新版本,验证行为一致性
性能压测复制线上流量做影子压测,不影响用户
数据复现把请求复制到记录系统,排查"线上才复现"的问题
灰度对照新旧版本同时处理,比对响应差异

四、关键行为与限制

  • 影子请求的响应被丢弃,其状态码不影响主请求;
  • 影子请求失败不会让主请求报错,但会记录错误日志;
  • 镜像是在 proxy_pass/fastcgi_pass 等内容处理器阶段触发,不在 access 阶段;
  • 一个 location 可配置多条 mirror,镜像到多个目标;
  • 镜像请求会继承原始请求的部分头(如 Host),需要时用 proxy_set_header 覆盖;
  • 注意避免"镜像套镜像":影子 location 自身不要再开 mirror。

五、常见坑

坑说明
以为影子响应会影响主请求响应被丢弃,主请求不受影响
影子 location 未加 internal可被外部直接访问,变成公开代理
默认没带请求体压测 body 接口要 mirror_request_body on
镜像到同上游造成流量翻倍影子目标要指向独立测试环境
未处理镜像超时影子目标慢会拖慢工作进程的连接资源,配 proxy_*_timeout
在影子 location 里再镜像无限递归,配置前检查

参考链接

  1. Nginx 官方文档:ngx_http_mirror_module —— mirror、mirror_request_body;
  2. Nginx 官方文档:ngx_http_proxy_module —— 影子请求转发的代理参数;
  3. Nginx 官方文档:ngx_http_core_module(internal) —— 限制内部访问。

小结

  • mirror 把请求复制到影子 location,主请求照常返回;
  • 影子响应被丢弃,只用于验证/压测/记录;
  • 默认不镜像 body,压测带 body 接口要 mirror_request_body on;
  • 影子 location 加 internal,避免被外部直连;
  • 影子目标要独立,避免流量翻倍打到生产。

系列导航


Nginx 工程实践 -- 21. 流量镜像 mirror
https://bubao.github.io/posts/f1a2b3c4.html
作者
一念
发布于
2026年11月21日
许可协议