Nginx 流量镜像配置文档10% 比例采样适用文件http.confNginx/OpenResty 版本支持split_clients与mirror指令的版本OpenResty ≥ 1.13.x / Nginx ≥ 1.13.x。 部署形态两份配置互为副本结构相同通常部署在不同节点或环境共用同一套镜像策略。一、概述在http.conf中加入了一套轻量级、可控比例的流量镜像Traffic Mirroring / Shadowing机制目标把生产线上经过 Nginx 的请求按一定比例复制一份到镜像后端用于影子流量分析、压测、问题复现等。核心原则镜像请求不影响主链路业务响应不返回给客户端。通过split_clients做 A/B 比例控制本次设置为10% 开启 / 90% 关闭。镜像后端通过internal内部 location 转发对外不可直接访问。镜像链路设置严格的超时连接 500ms、收发 3s避免拖垮主链路。二、详解改动 1在server块开头新增split_clients位置server块内、location之前请求方法校验之后。if ( $request_method !~* GET|POST|OPTIONS ) { return 405; } ​ # 流量镜像比例控制10% split_clients $request_id $mirror_ratio { 10% mirror_enable; * mirror_disable; }作用使用 nginx 的split_clients指令对每一个请求以$request_id作为 hash 输入做稳定 hash 抽样10%的请求$mirror_ratio mirror_enable允许镜像。90%的请求$mirror_ratio mirror_disable禁止镜像。由于split_clients基于 hash同一请求 ID 的采样结果稳定便于灰度分析。2在internal_mirror_sn中增加条件判断# 镜像流量内部 location location /internal_mirror_sn { internal; proxy_pass http://mirror_sn$request_uri; ​ if ($mirror_ratio mirror_disable) { return 404; } ​ # 同步透传请求头 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Mirror-Flag sn-traffic; ... }作用借助 nginxmirror指令的跳转到 internal location机制先到达/internal_mirror_sn在真正发起后端转发前二次校验$mirror_ratio如果是mirror_disable即 90% 的请求直接return 404立刻丢弃镜像请求不再占用上游连接只有mirror_enable时才执行proxy_pass真正把请求打到镜像后端。nginxmirror指令本身不支持做条件判断它是无条件触发所以必须借由internal location if实现按比例开关。三、整体流量走向与控制原理1. 关键组件组件说明split_clients $request_id $mirror_ratio比例控制器10/90 分流mirror /internal_mirror_sn镜像指令在每个 location 中触发location /internal_mirror_sninternal镜像接收与转发点upstream mirror_sn镜像后端集群当前指向国产化环境的SLBproxy_next_upstream off镜像失败不重试避免阻塞主链路2. 单请求完整流向图┌─────────────────────────────────────────┐ 客户端请求 ──▶ │ Nginx ( 生产环境节点 server 块) │ │ │ │ 1) 方法校验 (GET/POST/OPTIONS 通过) │ │ 2) split_clients 按 $request_id 抽样 │ │ → 10% → mirror_enable │ │ → 90% → mirror_disable │ │ 3) 匹配对应 location正常 proxy_pass │ │ 到业务上游主链路不受影响 │ │ 4) 同时触发 mirror 指令 │ └───────────────┬─────────────────────────┘ │ (镜像) ▼ ┌─────────────────────────────────────────┐ │ location /internal_mirror_sn │ │ (internal仅供内部跳转) │ │ │ │ if ($mirror_ratio mirror_disable) │ │ return 404; ← 丢弃90% 请求 │ │ else │ │ proxy_pass http://mirror_sn$uri │ │ → 10.248.135.95:20080 │ └─────────────────────────────────────────┘ │ ▼ 镜像后端用于影子分析3. 主链路 vs 镜像链路关键区别维度主链路镜像链路是否返回给客户端✅ 是❌ 否响应丢弃失败是否影响业务是否连接失败只记日志超时设置通常 60s/180s严格 500ms/3s是否允许重试通常proxy_next_upstream onoff禁止重试是否带请求体根据业务而定mirror_request_body on带 body采样比例100%10%四、哪些流量走镜像哪些不走1. 走镜像的 location已显式声明mirror /internal_mirror_sn通过扫描两份配置以下 location 均启用了镜像业务模块Location 前缀/精确路径说明工作流图/workflow-diagram工作流图代理数字化监管/szhjg/、/szhjg-rmp/数字化监管相关接口PXF 代理/pxf-proxy-HTTPS 上游代理网关/px-gateway网关入口登录/login登录接口K8s API/k8s-api//k8s-api/api/xxx → /api/xxx通用网关/px-、/sx-、/fbs-、/sn-微服务网关调用FDD/pxf-common-fdd大文件上传WebSocket/websocket、/noticeWebsocket、/chanelmoitorWebsocket、/mpushWebsocket、/nettyWebsocketWebSocket 入口Nacos/nacos注册中心 UI/APIAI/聊天/chat、/knowlwdge_base、/ai-智能问答相关以上 location 内 10% 的请求会被镜像90% 会在internal入口被丢弃。2. 不走镜像的请求所有非 GET/POST/OPTIONS方法如PUT、DELETE、PATCH在 server 入口被return 405直接拒绝不会进入任何 location自然也不会被镜像。静态资源类 location未配置mirror这些 location 直接返回本地文件不发起镜像/error_page///.well-known/pki-validation//ht-portal//pxf-k8s-tool/、/res//pxf-注意这是静态资源分支与/px-网关分支不同/common//index.html、/pxf-(*)/index.html特殊 rewrite 重定向location /pxf-sxservice-omarketservice/#/1rewrite ^ https://www.baidu.com/— 直接重定向不进入 mirror 链路。3. 总结一句话凡是配置了mirror /internal_mirror_sn的 location其请求中的10%会被同步复制一份发往镜像后端未配置 mirror 的 location与被 405 拦截的请求永远不会走镜像。五、延时分析镜像链路设计了硬性短超时以保护主链路阶段配置超时值建立连接proxy_connect_timeout500 ms读取响应proxy_read_timeout3 s发送请求proxy_send_timeout3 s重试proxy_next_upstream off失败不重试Keepalivekeepalive 64、keepalive_timeout 30s、keepalive_requests 500长连接复用对主链路的影响nginxmirror指令默认行为是异步镜像请求与主请求并行发送主链路响应时间不会直接叠加镜像耗时。唯一会影响主链路的场景镜像后端连接耗尽极端情况在internal中排队等待但连接超时被限制在 500 ms 内。由于mirror_request_body onPOST 等带 body 的请求会先把 body 落盘/缓存再镜像body 较大时会有少量 I/O 开销。实际经验值场景镜像对主链路延时的额外影响镜像后端正常、空闲 1 ms异步 keepalive镜像后端慢 / 超时主链路几乎无影响500 ms 触发超时后丢弃大 body 镜像1 MB1~5 msbody 缓存镜像后端宕机主链路无影响连接 500 ms 内失败并丢弃六、上游upstream配置说明upstream mirror_sn { server 国产化环境地址和端口; keepalive 64; keepalive_timeout 30s; keepalive_requests 500; }如需高可用可扩展多台upstream mirror_sn { server 1.1.1.1:80; server 1.1.1.2:80; keepalive 64; keepalive_timeout 30s; keepalive_requests 500; }keepalive 64每个 worker 与上游最多维持 64 条长连接复用连接降低握手开销。keepalive_requests 500单条长连接最多处理 500 个请求后主动重建避免长时间复用带来的资源泄漏。keepalive_timeout 30s空闲连接保持 30 秒。七、镜像请求的关键 Header/internal_mirror_sn中透传了以下 header便于后端识别与审计Header值用途Host$host保留原始域名X-Real-IP$remote_addr真实客户端 IPX-Forwarded-For$proxy_add_x_forwarded_for完整代理链路X-Mirror-Flagsn-traffic镜像流量标识后端可据此区分影子流量与真实流量Connection关闭客户端侧的Connection头配合 keepalive镜像后端服务必须识别X-Mirror-Flag: sn-traffic避免将影子流量写入生产库 / 发送通知 / 触发副作用。八、比例控制如何调整采样率只需修改split_clients块即可两文件同步修改# 关闭镜像全量丢弃 split_clients $request_id $mirror_ratio { 0% mirror_enable; * mirror_disable; } ​ # 50% 镜像 split_clients $request_id $mirror_ratio { 50% mirror_enable; * mirror_disable; } ​ # 100% 全量镜像 split_clients $request_id $mirror_ratio { * mirror_enable; }调整后nginx -s reload即可热生效无需重启进程。九、部署与验证步骤1. 语法检查nginx -t -c nginx.conf2. 热加载nginx -s reload3. 验证镜像是否生效方法一观察镜像后端 access log在 国产化服务上检查请求量是否符合 ~10% 比例。抽样日志中的X-Mirror-Flag: sn-trafficheader 是否存在。方法二观察 nginx 自带的 mirror logtail -f /var/logs/nginx/mirror_sn_access.log tail -f /var/logs/nginx/mirror_sn_error.log方法三临时改为 100% 做冒烟测试split_clients $request_id $mirror_ratio { * mirror_enable; # 临时全量 }验证通过后改回 10%。4. 确认 90% 请求被正确丢弃抽样mirror_sn_error.log可见 404被if丢弃的请求不会产生这条日志nginx 会直接 short-circuit。主链路响应时间不应出现明显异常波动。十、故障排查清单现象可能原因处理建议镜像后端收到 0 请求split_clients写成0%或internal的if误判检查$mirror_ratio实际值开启 debug log主链路变慢镜像后端连接耗尽 / body 太大调小采样率、扩大keepalive、限制 body 大小镜像后端写入生产库后端未识别X-Mirror-Flag后端增加拦截逻辑识别到X-Mirror-Flag时跳过副作用比例不准差几个百分点hash 抖动 业务低谷正常现象split_clients是统计意义上的近似reload 后配置未生效nginx 不支持split_clients升级到 OpenResty ≥ 1.13.x 或 Nginx ≥ 1.13.x十一、附录完整配置文件参考A.split_clients块# 流量镜像比例控制10% split_clients $request_id $mirror_ratio { 10% mirror_enable; * mirror_disable; }B. if 判断以及对应location下开启流量镜像if ($mirror_ratio mirror_disable) { return 404; } #在每个对应的location下开启 mirror /internal_mirror_sn; mirror_request_body on;C. 完整的镜像接收 location参考现状location /internal_mirror_sn { internal; proxy_pass http://mirror_sn$request_uri; if ($mirror_ratio mirror_disable) { return 404; } proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Mirror-Flag sn-traffic; proxy_http_version 1.1; proxy_set_header Connection ; proxy_connect_timeout 500ms; proxy_read_timeout 3s; proxy_send_timeout 3s; proxy_next_upstream off; }