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 | |
mirror /mirror;声明一个内部 location 作为影子目标;- 影子 location 通常加
internal,只能由镜像触发,不能外部直连; - 影子请求与原请求并发发出,主请求的响应不等影子。
二、镜像请求体
默认只镜像请求行和头,不镜像请求体。需要压测带 body 的接口时开启:
1 | |
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 里再镜像 | 无限递归,配置前检查 |
参考链接
- Nginx 官方文档:ngx_http_mirror_module ——
mirror、mirror_request_body; - Nginx 官方文档:ngx_http_proxy_module —— 影子请求转发的代理参数;
- 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
