新版本上线最怕什么?怕的不是"有 bug",而是"一上线全量用户一起踩 bug"。灰度发布(也叫金丝雀发布)就是为了把风险关进笼子:先让一小部分流量走新版本,观察没问题再逐步放大,一旦发现问题能立刻把流量切回旧版本。它不需要多高深的架构,很多时候一台 Nginx 就能撑起一套够用的灰度方案。
这篇文章从最朴素的"按权重分流"讲起,逐步展开到按用户、按 IP、按请求头的定向灰度,再讲怎么在 Nginx 层做快速回滚、怎么保证灰度期间的会话一致性,以及灰度到底该看哪些指标来决定"放量还是回滚"。文中涉及的权重比例、观察时长都是常见经验值,要结合你的业务量级和风险承受度调整。
读完之后,你应该能用反向代理搭出一套可控的灰度发布流程:新版本先接住 1%~5% 的流量,通过观测再逐步放开;出问题时一键把 upstream 改回旧版本,秒级回滚。所有改配置的操作都会强调 nginx -t 校验、备份和回滚。
一、灰度发布要解决的三个问题
一套完整的灰度发布,本质要回答三个问题:
- 怎么分流量:新版本接多少比例、接哪些人的流量。
- 怎么保证体验:同一个用户不能一会儿新、一会儿旧(会话一致性)。
- 怎么快速回滚:发现问题时,多久能把所有流量切回旧版本。
第 1 个决定灰度"灵不灵",第 2 个决定灰度"稳不稳",第 3 个决定灰度"敢不敢用"。很多团队只做了第 1 个,结果用户在两个版本之间反复横跳,报出各种"偶现怪异 bug";或者没有回滚手段,出事了只能手忙脚乱地重启。
主流的分流维度有几种,各有适用场景:
| 分流维度 | 实现方式 | 适用场景 | 风险 |
|---|---|---|---|
| 按权重 | Nginx upstream 加权轮询 |
通用灰度,先放小比例 | 同一用户可能落到不同版本 |
| 按 IP | split_clients 或 map $remote_addr |
内部测试、固定人群 | NAT 用户可能一起进灰度 |
| 按 Cookie | map $cookie_ver |
保证同一用户固定版本 | 需要应用配合下发 cookie |
| 按请求头 | map $http_x_gray |
内部测试、定向验证 | 外部用户无法触发 |
| 按用户 ID | map + 自定义规则 |
精准灰度 | 需应用传递标识 |
二、最基础的方式:upstream 权重分流
用两个 upstream(一个旧版本、一个新版本),通过权重控制比例:
upstream backend_old {
server 127.0.0.1:8080; # 旧版本
}
upstream backend_new {
server 127.0.0.1:8081; # 新版本
}
# 按 95:5 分流,即 5% 流量进新版本(经验值,从 1%~5% 起步)
split_clients "${remote_addr}${http_user_agent}" $backend_pool {
5% backend_new;
* backend_old;
}
server {
listen 80;
server_name www.example.com;
location / {
proxy_pass http://$backend_pool;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
split_clients 基于一个字符串做哈希,把请求确定性分发到不同池。用 ${remote_addr}${http_user_agent} 组合做 key,能大致保证同一个 IP+浏览器固定落到同一个版本,缓解"用户横跳"问题。不过它本质是按比例分布,5% 只是概率意义上的 5%,实际样本里可能略有偏差。
更常见的做法是直接在 upstream 里用权重:
upstream backend {
server 127.0.0.1:8080 weight=95; # 旧版本 95%
server 127.0.0.1:8081 weight=5; # 新版本 5%
}
缺点是轮询是按请求均摊,同一个用户的不同请求可能分别落到新旧版本,会话一致性差。所以权重法适合无状态接口(如纯 API、静态接口),对依赖本地 session 的应用要慎重。
三、定向灰度:按 IP、请求头、Cookie
要做"只让测试同学和公司内网进新版本",用 map 更精准:
# 定义灰度判断:内网 IP 或带 X-Gray 头的请求进新版本
map $http_x_gray $use_new {
default 0;
"1" 1;
}
map $remote_addr $is_internal {
default 0;
10.0.0.0/8 1; # Nginx map 支持 CIDR(需较新版本)
}
server {
listen 80;
server_name www.example.com;
# 命中灰度条件就走新版本
set $target backend_old;
if ($use_new = 1) { set $target backend_new; }
if ($is_internal = 1) { set $target backend_new; }
location / {
proxy_pass http://$target;
proxy_set_header Host $host;
}
}
这样,公司内网或带 X-Gray: 1 头的请求走新版本,其他人走旧版本。测试时用一个浏览器插件或 curl -H "X-Gray: 1" 就能把指定请求切到新版,非常方便定向验证。
按 Cookie 保证会话一致性是体验最好的方案:
map $cookie_grayver $target {
default backend_old;
"new" backend_new;
}
server {
location / {
proxy_pass http://$target;
# 若请求里还没有灰度标记,可由应用下发(示例)
add_header Set-Cookie "grayver=new; Path=/; Max-Age=86400" always;
}
}
应用在用户首次命中灰度时下发 grayver=new 的 Cookie,之后这个用户的所有请求都稳定走新版本,直到 Cookie 过期。这样既保证了"同一用户版本一致",又能在需要时只清 Cookie 就让他回到旧版本。
风险提示:if 在 Nginx 的 location 里有"if is evil"的坑(某些指令在 if 块里行为不符合直觉),能用 map 就优先用 map,它更安全也更快。所有配置改完先 nginx -t 校验,再 nginx -s reload。
四、回滚:把流量一秒切回去
灰度最大的价值在回滚。回滚的本质就是"让新版本的流量归零"。几种做法:
方式一:改权重。 把新版本权重从 5 改成 0:
upstream backend {
server 127.0.0.1:8080 weight=100; # 旧版本 100%
server 127.0.0.1:8081 down; # 新版本下线(保留节点便于再上线)
}
down 标记让该节点不参与调度,但配置还在,改天要再灰度时把 down 去掉即可,不用重写整段。
方式二:切换分流比例。 用 split_clients 的话,把 5% 改成 0%。
# 改配置后标准动作
sudo cp /etc/nginx/conf.d/gray.conf /etc/nginx/conf.d/gray.conf.bak # 先备份
sudo vim /etc/nginx/conf.d/gray.conf
sudo nginx -t && sudo nginx -s reload
# 回滚:还原备份再 reload
# sudo cp /etc/nginx/conf.d/gray.conf.bak /etc/nginx/conf.d/gray.conf && sudo nginx -t && sudo nginx -s reload
reload 是平滑的,不会断开现有连接,秒级生效,这就是"Nginx 层灰度"的最大优势——回滚成本极低。
方式三:DNS/负载均衡层切换。 如果灰度是在云负载均衡或 DNS 上做的,回滚就是把权重或解析切回旧版本,但 DNS 有 TTL 缓存(常见 60~600s),回滚不如 Nginx 层快。
五、放量决策:看哪些指标
灰度不是"放上去就不管了",要根据指标决定下一步。建议观察这几类:
| 指标类别 | 具体指标 | 判断 |
|---|---|---|
| 错误 | 5xx 比例、异常数 | 新版本明显高于旧版 → 回滚 |
| 延迟 | P95/P99 响应时间 | 明显劣化 → 暂停放量 |
| 业务 | 转化率、下单成功率 | 下降 → 排查后决定 |
| 资源 | CPU、内存、GC 频率 | 异常升高 → 关注 |
经验节奏(供参考):1% 观察 10~30 分钟 → 5% 观察 30~60 分钟 → 20% → 50% → 100%。每一档都要对比新旧版本的指标差异,确认无异常再进入下一档。对核心交易类业务,观察时间要更长,甚至跨一个业务高峰。
关键是要保证新旧版本的指标可对比:在 Nginx 日志里给请求打上版本标记(如日志里加上 $upstream_addr 或自定义头),这样统计时能区分"新版本的问题"和"整体的问题"。
# 日志格式里加入上游地址,便于按版本分析
log_format gray '$remote_addr - $upstream_addr [$time_local] '
'"$request" $status $body_bytes_sent $request_time';
access_log /var/log/nginx/access.log gray;
# 按上游地址统计 5xx,快速判断新版本是否异常
awk '$9 ~ /^5/ {print $3}' /var/log/nginx/access.log | sort | uniq -c | sort -rn
灰度决策最忌"凭感觉"。有人看到新版本没报错就直接全量,结果用户侧偶发的兼容问题要等到大范围暴露才被发现;也有人一有风吹草动就回滚,白白浪费一次发版窗口。更稳妥的心态是:把灰度当成一次"受控实验",先明确这次发版想验证什么(新功能是否生效、某个 bug 是否修复、性能有没有变化),再据此设定观察指标和放量门槛。只有当指标达到预期、且新旧版本差异在可接受范围内,才推进下一档。这个过程可以慢一点,但每一步都要有数据支撑。
六、灰度与优雅停机的配合
灰度发布常和滚动更新一起用。切流量时,旧版本实例要优雅停机(处理完在途请求再退出),否则回滚或放量过程中会有短暂 5xx。配合方式是:先从 upstream 摘除待停节点(或用 down),等一小段(如 5~10s,经验值)让在途请求结束,再停止进程。
# 摘除节点:加 down 标记后 reload,之后才去停进程
upstream backend {
server 127.0.0.1:8080;
server 127.0.0.1:8081 down; # 准备停的节点
}
常见问题
Q1:灰度时用户一会儿新一会儿旧,怎么解决?
用 Cookie 或用户 ID 做分片 key,保证同一用户固定落到一个版本。纯权重轮询无法保证会话一致性,只适合无状态接口。
Q2:Nginx 灰度回滚要多久?
改 upstream 权重或 down 后 nginx -s reload,秒级生效且不断连接。这也是优先在 Nginx 层做灰度的原因。
Q3:split_clients 的百分比是精确的吗?
是概率意义上的,基于请求 key 哈希分配,样本足够大时接近设定比例,但小样本会有偏差,不能当精确控制用。
Q4:灰度放量到多少可以全量?
没有固定值。核心业务建议按 1%→5%→20%→50%→100% 分批,每档观察错误率、延迟、业务指标,确认平稳再推进(比例为经验值)。
Q5:灰度期间怎么保证数据库兼容?
新老版本要共用数据库时,schema 变更必须向后兼容(先加字段不删、新老都能读);破坏性变更要分多次发布,先兼容再清理,避免回滚时旧版本读不了新结构。
总结
- 灰度发布解决"分流量、保体验、能回滚"三件事,Nginx 反向代理是最轻量、回滚最快的落地方式。
- 分流维度按需选:无状态用权重或
split_clients,定向测试用map匹配 IP/请求头,会话一致性用 Cookie 或用户 ID。 - 回滚就是把新版本权重归零或标记
down,nginx -t后reload秒级生效;改前备份,随时还原。 - 放量要按比例分批推进并对比新旧版本的错误率、延迟、业务指标,日志里打上版本标记才能对比。
- 灰度要配合优雅停机:先摘流量、等在途请求结束、再停进程,并保证数据库 schema 前后兼容,回滚才安全。
企业QQ咨询




