ngx_http_mirror_module 是请求复制模块，仅异步克隆原始请求至镜像服务，不复制响应、非阻塞、仅支持单目标；需配合 map 采样、upstream 高可用、limit_req 限速及日志观测等实现生产就绪。
ngx_http_mirror_module 本身不用于负载均衡，也不提供“一键实时镜像”的开箱即用能力。它是一个请求复制模块，核心作用是将进入 Nginx 的原始请求（只读、非阻塞）异步克隆一份，转发到指定的镜像服务，而不影响主请求的正常处理流程和响应。在生产环境中实现“流量镜像”，关键在于正确配置 mirror 指令、合理设计镜像后端、并配合可观测性与稳定性保障措施。
明确 mirror 模块的核心行为
理解以下三点，避免常见误用：
- 只复制请求，不复制响应：镜像请求的返回结果被 Nginx 完全忽略，不会影响客户端响应内容、状态码或响应头。
- 非阻塞、异步发送：主请求处理不受镜像请求超时、失败或慢响应影响；即使镜像服务宕机，主链路完全不受损。
- 仅支持单个镜像目标（或通过 upstream 配合实现有限轮询）：mirror 指令只接受一个 URI 或 location，不能原生做多目标分发或加权镜像。
基础镜像配置：最小可行示例
以下为典型反向代理场景下的镜像配置片段（假设主服务在 backend，镜像服务部署在 mirror.example.com）：
upstream backend {
server 10.0.1.10:8080;
}
<p>server {
listen 80;
location / {</p><h1>启用镜像：将所有 / 下请求复制一份到 /mirror/</h1><pre class="brush:php;toolbar:false;"> mirror /mirror;
mirror_request_body on; # 必须开启，否则 POST/PUT 等带 body 的请求无法镜像
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# 镜像专用 location，转发到真实镜像服务
location = /mirror {
internal; # 仅限内部调用，禁止外部直接访问
proxy_pass https://mirror.example.com$request_uri;
proxy_pass_request_body on;
proxy_set_header X-Mirror-Timestamp $msec;
proxy_set_header X-Original-Host $host;
# 建议禁用响应体透传（镜像服务无需返回给 Nginx）
proxy_buffering off;
proxy_buffer_size 4k;
proxy_buffers 8 4k;
}}
注意：mirror_request_body on 是必须项；internal 是安全底线；$request_uri 保证路径和 query 参数完整保留。
生产就绪的关键增强点
真实环境需补充以下能力，才能称得上“可用、可控、可观察”：
-
按条件镜像：使用
mirror指令配合map变量，实现采样（如 1%）、特定 path、header 或 cookie 触发镜像。例如：map $arg_debug $mirror_target { default ""; "true" "/mirror"; }，再写mirror $mirror_target; -
镜像服务高可用：将
proxy_pass指向一个 upstream 组，启用健康检查（health_check）与重试机制，避免单点故障导致镜像中断。 -
镜像流量隔离与限速：在
/mirrorlocation 中添加limit_req，防止突发流量打垮镜像服务；也可用proxy_next_upstream error timeout自动容错。 -
关键字段注入：除
X-Mirror-Timestamp外，建议添加X-Mirror-ID $request_id，便于在镜像服务中与原始请求日志关联比对。
配套可观测性与验证手段
镜像是否生效？是否丢包？延迟如何？需主动观测：
-
日志标记：在 access_log 中增加
$mirror_request变量（Nginx 1.13.4+），该变量值为 1 表示当前请求被镜像，可用于统计镜像率。 - 镜像服务埋点：镜像服务自身记录接收时间、原始 host、URI、body size、$request_id，输出结构化日志供 ELK 或 Prometheus 采集。
-
简易连通性验证：临时在
/mirrorlocation 中加入return 200 "mirrored\n";并 curl 主服务，确认 access_log 中出现"mirror_request":"1"且镜像服务收到请求。 -
不建议依赖 mirror 模块做 A/B 测试或灰度发布：它不控制响应，也无法拦截或修改主链路行为；这类场景应使用
split_clients或lua-resty-balancer等方案。
