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，但这已超出纯权重范畴，属于条件灰度。
