ngx_http_mirror_module实现流量镜像的核心是异步、无干扰、可降级：需在location/server中配置mirror指令，目标URI须合法，POST等需开启mirror_request_body，配合limit_req、map和upstream健康检查控制流量与容错。
使用 ngx_http_mirror_module 实现生产流量镜像采集，核心在于“不干扰主请求、异步转发副本、目标服务可降级”。它不是代理，而是对每个入站请求自动发起一个完全独立的镜像子请求，主响应不受镜像成败影响。
镜像配置必须满足三个前提
否则镜像会失败或拖慢主线程：
-
必须启用
mirror指令且作用于 location 或 server 块内，不能放在 if 或 rewrite 后； - 镜像目标（
mirror后的 URI）必须是同域内部 location 或带协议的完整 URL（如http://mirror-svc/），但 Nginx 不校验该地址是否可达； -
被镜像的请求方法默认为 GET，若需镜像 POST/PUT 等，需显式用
mirror_request_body on;（Nginx ≥ 1.13.4），否则镜像请求体为空。
避免压垮镜像服务的关键控制项
镜像流量和原始流量 1:1 复制，不做采样时极易打爆下游。建议组合以下策略：
- 用
limit_req对镜像 location 限流，例如每秒最多 100 个镜像请求； - 配合
map模块按请求路径、Header 或参数做条件镜像，比如只镜像/api/v1/order和带X-Mirror-Enabled: true的请求； - 镜像 upstream 配置中启用
max_fails=1 fail_timeout=10s，让镜像服务短暂不可用时自动跳过，不重试、不阻塞主流程。
真实可用的最小化配置示例
以下配置实现：仅对带指定 Header 的 POST 请求镜像，镜像体完整透传，镜像失败不报错、不重试：
upstream mirror_backend {
server 10.10.20.5:8080 max_fails=1 fail_timeout=10s;
}
<p>map $http_x_mirror_enabled $do_mirror {
"true" "/mirror";
default "";
}</p><p>server {
listen 80;
location / {
proxy_pass <a href="https://www.php.cn/link/6ddc098a344870bdb384e1de45e4c8ea">https://www.php.cn/link/6ddc098a344870bdb384e1de45e4c8ea</a>;</p><pre class="brush:php;toolbar:false;"> mirror $do_mirror;
mirror_request_body on;
# 镜像专用 location，不参与主代理逻辑
location = /mirror {
internal; # 仅限 mirror 指令调用，禁止外部访问
proxy_pass http://mirror_backend$request_uri;
proxy_pass_request_body on;
proxy_set_header Content-Length $content_length;
proxy_set_header X-Original-Method $request_method;
proxy_set_header X-Original-Uri $request_uri;
}
}}
镜像数据消费端注意事项
接收镜像的服务要能承受突发流量，并做好幂等与容错：
- 镜像请求可能重复（如上游重试、Nginx 重载时短暂双写），建议用
X-Request-ID或时间戳 + body hash 去重； - 不要在镜像处理中修改业务状态（如扣库存、发消息），它只是观测通道；
- 推荐将镜像数据写入 Kafka 或本地日志文件再异步解析，避免直连数据库造成瓶颈。
不复杂但容易忽略：镜像请求的超时由 proxy_read_timeout 和 proxy_connect_timeout 控制，务必设为较小值（如 1s），防止镜像服务卡住拖慢整个 Nginx 工作进程。
