ngx_http_mirror_module模块详解

Hello.Reader

1262人浏览 · 2025-05-15 09:15:00

Hello.Reader · 2025-05-15 09:15:00 发布

一、模块概述

模块名称：ngx_http_mirror_module
引入版本：1.13.4
功能：
1. 对匹配的主请求路径生成一个或多个“镜像”子请求，异步发送到指定 URI；
2. 镜像子请求的响应不参与主请求流程，失败或延迟都不会影响用户体验；
3. 支持同时镜像请求头和（可选）请求体。

二、示例配置

http {
    server {
        listen 80;
        server_name www.example.com;

        # 1. 主入口：正常将 / 请求代理到后端
        location / {
            mirror          /mirror;                  # 将此请求镜像一份到 /mirror
            proxy_pass      http://backend;
        }

        # 2. 镜像接收：内部使用，不对外可见
        location = /mirror {
            internal;                                 # 只能由内部子请求访问
            proxy_pass      http://log_backend$request_uri;
            proxy_pass_request_body  off;             # 不将主请求体再转发给日志后端
            proxy_set_header Content-Length "";       # 清除长度
            proxy_set_header X-Original-URI $request_uri;
        }
    }
}

客户端访问 / 时，Nginx 会同时发起：
- 主请求：代理到 http://backend 并将响应返回给客户端。
- 镜像子请求：向内部路径 /mirror 发送一份完全相同的请求，后台再转发到 http://log_backend$request_uri，用于日志、灰度或流量复制等。
/mirror 路径通过 internal; 限制只能由 Nginx 内部触发，不对外暴露。
主流量与镜像流量并行，互不阻塞。

三、指令详解

1. `mirror`

Syntax:   mirror <uri> | off;
Default:  mirror off;
Context:  http, server, location

功能：设置一个或多个目标 URI，将匹配的主请求“镜像”到这些后台 URI。
参数：
- <uri>：以内部或外部 location 定义的 URI（可以带 args），必须至少包含一个；
- off：禁止本级及下级继承的所有 mirror 配置。
特点：
- 可在同级配置多次 mirror，会为每个目标分别发起子请求；
- 子请求使用与主请求相同的请求方法、头部和（可选）请求体。

示例：

# 同时镜像到 /mirror1 和 /mirror2
location /api/ {
    mirror /mirror1;
    mirror /mirror2;
    proxy_pass http://backend_api;
}

2. `mirror_request_body`

Syntax:   mirror_request_body on | off;
Default:  mirror_request_body on;
Context:  http, server, location

功能：控制是否将客户端请求体包含在镜像子请求中。
参数：
- on：开启请求体镜像（默认）；
- off：关闭请求体镜像，仅传递请求头。
注意事项：
- 当开启时，Nginx 会先完整读取客户端请求体，然后才向各镜像目标发起子请求；
- 这会禁用主请求上游（如 proxy_pass/fastcgi_pass 等）的无缓冲请求体传输，改为先缓冲后转发。

示例：

location /upload {
    mirror /mirror_upload;
    mirror_request_body off;       # 仅复制头部，不复制可能很大的请求体
    proxy_pass http://upload_backend;
}

四、使用建议

慎选镜像目标
- 镜像 URI 必须 internal 或通过访问控制保证安全；
- 后端可独立扩容，避免镜像量过大导致日志服务压垮。
请求体大小考虑
- 默认 mirror_request_body on，会缓存完整请求体，适合小请求；
- 大文件上传或流式接口建议 off，只复制必要头部或元数据。
并发与资源
- 每个主请求会新增同等数量的子请求，注意限制 worker_connections、proxy_buffer 大小等资源；
- 合理设置 proxy_connect_timeout、proxy_read_timeout，确保镜像子请求失败也能快速退出。
多目标镜像
- 可对同一路径配置多次 mirror，实现并行多套日志或测试环境隔离；
- 目标越多，对 Nginx 资源（连接、内存）消耗越大。
链路追踪
- 建议在镜像子请求中通过 proxy_set_header X-Original-URI $request_uri 或类似自定义 Header，方便后台区分日志来源。