Nginx权重配置实现灰度引流教程

Nginx权重灰度通过upstream的weight参数实现HTTP层流量比例分发，如v1:weight=20、v2:weight=1达成5%新版本引流，轻量稳定但不支持用户级精细化路由。

通过Nginx权重配置实现灰度引流，核心是利用upstream模块的weight参数控制不同后端节点的流量比例，适合在不引入复杂网关或服务网格的前提下，快速落地小规模灰度发布。它轻量、稳定、无需额外组件，但仅适用于HTTP层且不支持基于用户ID、Header等精细化路由。

一、明确灰度目标与流量比例

先确定灰度策略：比如将5%的请求导到新版本服务（v2），95%仍走老版本（v1）。注意权重不是百分比，而是相对值——只要比例一致即可，例如weight=1和weight=19就等效于5% : 95%。

• 避免使用过大的数值（如weight=95和weight=5），易因四舍五入或连接复用导致实际偏差增大
• 若需动态调整，建议从较小基数起步（如v1 weight=20，v2 weight=1），后续可平滑加权
• 确保新旧服务部署在不同IP/端口或通过不同server_name区分，否则无法独立配置

二、配置带权重的upstream及server块

在nginx.conf或站点配置文件中定义upstream，并在location中proxy_pass指向它：

upstream backend {
    server 192.168.1.10:8080 weight=20;  # v1老版本
    server 192.168.1.11:8080 weight=1;   # v2新版本
}
server {
listen 80;
server_name example.com;
location / {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
}

重启Nginx生效：nginx -t && nginx -s reload。此时请求会按权重轮询分发，整体符合预设比例。

• 默认负载策略为weighted round-robin，无需额外声明
• 若某台机器宕机，Nginx会自动剔除并重试，但不会自动恢复，需配合max_fails和fail_timeout增强健壮性
• 不建议在灰度初期关闭健康检查，可临时设为max_fails=1 fail_timeout=10s

三、验证灰度效果与常见问题排查

上线后需确认流量是否真实按预期分配。最简单方式是让新旧服务在响应头中返回版本标识：

# v1服务返回：X-App-Version: v1.2.0
# v2服务返回：X-App-Version: v2.0.0

用curl批量请求并统计版本分布：

for i in {1..1000}; do curl -sI https://example.com | grep "X-App-Version"; done | sort | uniq -c

• 若结果严重偏离设定比例（如期望5%，实测0%或20%），检查是否启用了keepalive导致连接复用，长期TCP连接会使单个客户端始终落在同一节点
• 确认Nginx未启用ip_hash或hash $cookie_xxx等会破坏权重的策略
• 查看nginx -V确认编译参数含--with-http_upstream_module（默认都包含）

四、进阶提示：平滑过渡与安全兜底

灰度不是一次性切流，应分阶段推进：

• 第一阶段：1%权重观察日志与错误率，重点关注5xx和超时
• 第二阶段：升至5%，接入监控看P95延迟、QPS变化
• 第三阶段：10%~30%，加入业务关键路径验证（如下单、支付）
• 始终保留快速回滚能力：把v1权重调回100%，reload即可秒级生效

若需更高精度控制（如只对特定UA或Query参数放行），可在location中结合if或map做前置判断，再proxy_pass到不同upstream，但这已超出纯权重范畴，属于条件灰度。