nginx mirror模块（1.13.4+内置）可零成本异步镜像生产流量至测试环境：需确认版本及模块启用，配置mirror指令指向/internal路由，proxy_pass转发并按需设置mirror_request_body，全程不阻塞主流程。
Nginx 的 mirror 模块（自 1.13.4 版本起内置）支持将主请求的副本异步发送到指定上游，**不干扰原始响应流程**，非常适合将线上真实流量“镜像”到预发布环境做灰度验证。关键在于：镜像请求是只读、非阻塞、无副作用的——它不影响线上用户访问，也不要求预发布服务返回任何内容给客户端。
一、确认 Nginx 版本并启用 mirror 模块
运行 nginx -v 确保版本 ≥ 1.13.4；该模块默认编译进核心，无需额外加载。若使用旧版或定制编译的 Nginx，可通过 nginx -V 2>&1 | grep -o with-http-mirror-module 验证是否包含。
二、配置镜像 upstream 和 location 规则
在 http 块中定义预发布服务的 upstream：
upstream preview_backend {
server 192.168.10.50:8080;
# 可加 backup / max_fails / fail_timeout 等健康检查参数
}
在目标 location 中添加 mirror 指令，并用 mirror_request_body off;（可选）避免大文件体重复发送：
location /api/ {
proxy_pass https://prod_backend;
mirror /mirror-api;
mirror_request_body off;
}
location = /mirror-api {
internal;
proxy_pass https://preview_backend$request_uri;
proxy_set_header X-Original-Host $host;
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Mirror-Traffic "true";
}
注意：internal 表示该 location 只能被内部指令（如 mirror）调用，禁止外部直接访问。
三、控制镜像范围与安全隔离
避免全量镜像影响预发布稳定性，建议按需限制：
- 用
mirror指令配合if或 map 实现条件镜像，例如仅镜像 POST 请求：
if ($request_method = POST) {
mirror /mirror-api;
} - 通过
map定义镜像开关，结合 header 或 cookie 动态启用：
map $http_x_enable_mirror $mirror_target {
"1" "/mirror-api";
default "";
}
mirror $mirror_target; - 预发布服务应忽略镜像请求的响应结果，且不修改数据库或发通知——可在应用层识别
X-Mirror-Traffic: true头做逻辑拦截。
四、验证与可观测性要点
镜像本身不报错不代表成功，需主动观测：
- 在预发布 Nginx 或应用日志中过滤
X-Mirror-Traffic，确认请求到达； - 用
stub_status或 Prometheus + nginx-vts-exporter 监控mirror子请求的 QPS 和失败数； - 镜像请求默认超时为 60s，若预发布响应慢，建议显式设置：
proxy_read_timeout 10;
proxy_connect_timeout 3;
proxy_send_timeout 3; - 避免镜像请求携带敏感 Cookie 或 Authorization，可用
proxy_set_header覆盖或清空：
proxy_set_header Cookie "";
proxy_set_header Authorization "";
镜像不是转发，不等待响应，不改变主流程——只要配置正确、网络可达、预发布服务能接收请求，就能稳定复现线上流量特征。重点不在“怎么配”，而在于“配得稳、看得清、控得住”。
