Nginx 自1.13.4起提供ngx_http_mirror_module模块，支持异步镜像请求至指定upstream而不影响主流程；需编译启用--with-http-mirror-module，配置中mirror须在proxy_pass前，/mirror location须加internal限制。
Nginx 本身不内置 mirror 模块，但自 1.13.4 版本起官方提供了 ngx_http_mirror_module（需编译启用），它支持将请求**异步镜像**一份到指定 upstream，原始请求不受影响。配合 proxy_pass 可实现「主代理 + 流量镜像」的典型灰度/监控场景。
确认 Nginx 已启用 mirror 模块
运行以下命令检查是否已编译该模块：
nginx -V 2>&1 | grep -o with-http-mirror-module
若无输出，说明未启用，需重新编译 Nginx 并添加 --with-http-mirror-module 参数。
基础 mirror + proxy_pass 配置结构
核心逻辑：先用 mirror 指令触发镜像，再用 proxy_pass 处理原始请求。注意：mirror 是异步非阻塞的，且镜像请求会继承原始请求的 method、headers、body（默认）。
示例配置：
upstream backend {
server 10.0.0.10:8080;
}
<p>upstream mirror_backend {
server 10.0.0.20:8080;
}</p><p>server {
listen 80;
location /api/ {</p><h1>步骤1：镜像请求到 mirror_backend（路径保持不变）</h1><pre class="brush:php;toolbar:false;"> mirror /mirror;
mirror_request_body on; # 默认为 on，镜像请求体
# 步骤2：主请求代理到 backend
proxy_pass http://backend;
# 可选：透传关键 header
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
}
# 镜像专用 location，仅用于接收 mirror 指令发起的子请求
location = /mirror {
internal; # 强制内部访问，禁止外部直接请求
proxy_pass http://mirror_backend$request_uri;
proxy_set_header X-Mirror-Request "true";
}
}
关键配置说明与常见注意事项
-
mirror必须写在proxy_pass之前 —— 否则镜像不会触发； -
location = /mirror必须加internal—— 防止被恶意构造 URL 直接调用； -
proxy_pass在/mirror中使用$request_uri可完整保留原始路径和 query； - 镜像请求默认复用原始请求的 body，如需禁用（例如大文件上传场景），设
mirror_request_body off； - 镜像请求的超时、重试等由
proxy_*指令控制（如proxy_timeout），不影响主流程； - 若需对镜像请求改写路径（如加前缀
/mirror-log），可在location /mirror中用rewrite或调整proxy_pass目标路径。
验证镜像是否生效
可通过后端日志或抓包确认：
- 主服务（
backend）只收到 1 次请求； - 镜像服务（
mirror_backend）同步收到 1 次同 path、同 method、同 body 的请求； - 响应头中不会出现镜像相关字段 —— 因为镜像是完全独立的子请求，主响应不受干扰。
可临时在 /mirror 块中加 access_log /var/log/nginx/mirror.log; 单独记录镜像流量便于调试。
