服务器业务灰度发布如何操作

学完这篇你能得到一套可照做的服务器业务灰度发布流程：用 Nginx 先把 5% 流量切到新版本，确认无异常后逐步放大到 100%，出问题可快速回滚。

第一步：先定灰度目标与回滚条件

这一步要确认“旧版本是谁、新版本是谁、什么情况必须回滚”，做完后你手里有一张发布检查单。假设旧版本为 v1.2.0，运行在 10.0.0.11:8080；新版本为 v1.2.1，准备部署到 10.0.0.12:8080。回滚条件写死为：5xx 错误率大于 1% 持续 3 分钟，或 P95 响应时间大于 500ms，或错误日志突增。每个服务必须提供健康检查接口，例如 /healthz。

第二步：部署新版本，但先不接入主流量

这一步是把新版本跑起来并自测通过，做完后新版本只允许你手动访问，线上用户仍然走旧版本。在 10.0.0.12 上执行：

docker run -d --name app-v1.2.1 -p 8080:8080 \
  -e APP_VERSION=v1.2.1 \
  registry.example.com/app:v1.2.1
curl -fsS http://10.0.0.12:8080/healthz

返回 {"status":"ok"} 才算通过。此时不要改 Nginx 配置。

注意：新版本端口不要和旧版本冲突；如果同机部署，用 8081 等不同端口。

第三步：用 Nginx 权重切 5% 流量

这一步是让 Nginx 按比例把少量流量分给新版本，做完后约 5% 请求进入 v1.2.1。编辑 /etc/nginx/conf.d/app.conf，Nginx 版本以 1.24.0 为例：

upstream app_backend {
    server 10.0.0.11:8080 weight=95 max_fails=3 fail_timeout=10s;
    server 10.0.0.12:8080 weight=5  max_fails=3 fail_timeout=10s;
}

server {
    listen 80;
    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

执行 nginx -t && nginx -s reload。nginx -t 必须显示 syntax is ok 和 test is successful。

注意：weight 只在默认轮询算法下按比例生效；如果你配置了 ip_hash，权重不会按预期分流，应先去掉 ip_hash 或改用 random。

第四步：按请求头做精准灰度

这一步是让测试账号或内部员工优先进入新版本，做完后普通用户仍走旧版。在 Nginx 的 http 块中加入：

map $http_x_gray $gray_backend {
    default "10.0.0.11:8080";
    "true"  "10.0.0.12:8080";
}

在 server 的 location / 中改为：

proxy_pass http://$gray_backend;

nginx -s reload 后，用 curl -H "x-gray: true" http://你的域名/version 验证是否返回 v1.2.1。

注意：map 必须放在 http 块，不能放在 server 或 location 里；请求头名称在 Nginx 变量中要写成小写并用下划线，例如 $http_x_gray。

第五步：观察指标，决定放大或回滚

这一步要确认灰度版本是否健康，做完后决定下一步是加权重还是回滚。先给 Nginx 日志加上游地址，在 http 块配置：

log_format main '$remote_addr "$request" $status upstream=$upstream_addr';
access_log /var/log/nginx/access.log main;

统计新版本请求量：

awk -F'upstream=' '{print $2}' /var/log/nginx/access.log | sort | uniq -c

观察 10 到 30 分钟。若 5xx 超过 1%，立即回滚：把 10.0.0.12:8080 改成 down，执行 nginx -t && nginx -s reload。

注意：回滚不是删容器，而是先切流量；确认旧版本稳定后再处理新版本。

第六步：逐步放大到全量并清理

这一步是把权重从 5% 提升到 10%、30%、50%、100%，每档至少观察 10 分钟。最终配置改为：

upstream app_backend {
    server 10.0.0.12:8080 weight=100;
    server 10.0.0.11:8080 down;
}

执行 nginx -t && nginx -s reload。稳定运行 24 小时后再下线旧版本，但保留旧镜像和 Nginx 旧配置至少一个发布周期。

如果使用 Kubernetes 1.28 和 Ingress-Nginx 1.9.0，可给新 Ingress 加注解 nginx.ingress.kubernetes.io/canary: "true"、nginx.ingress.kubernetes.io/canary-weight: "5"，逐步调大数值，回滚时删除该 Ingress 或把权重改为 0。

小结

灰度发布的关键是：新版本先部署不接流量；按权重或请求头小流量验证；用健康检查、5xx、P95 决定放大或回滚；每档观察后再继续；全量后保留旧版本和配置，确保随时能退回去。