如何利用 ngx_http_mirror_module 实现生产环境负载均衡流量的一键实时镜像-Nginx-PHP中文网

ngx_http_mirror_module 是请求复制模块，仅异步克隆原始请求至镜像服务，不复制响应、非阻塞、仅支持单目标；需配合 map 采样、upstream 高可用、limit_req 限速及日志观测等实现生产就绪。

如何利用 ngx_http_mirror_module 实现生产环境负载均衡流量的一键实时镜像

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）与重试机制，避免单点故障导致镜像中断。
镜像流量隔离与限速：在 /mirror location 中添加 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 采集。
简易连通性验证：临时在 /mirror location 中加入 return 200 "mirrored\n"; 并 curl 主服务，确认 access_log 中出现 "mirror_request":"1" 且镜像服务收到请求。
不建议依赖 mirror 模块做 A/B 测试或灰度发布：它不控制响应，也无法拦截或修改主链路行为；这类场景应使用 split_clients 或 lua-resty-balancer 等方案。