Nginx灰度发布通过请求特征（Header/Cookie/IP/URL参数）精准分流至新旧版本，推荐用map+geo替代if提升性能，支持动态更新与兜底策略。
利用 Nginx 实现后端节点灰度流量切换，核心是通过请求特征（如 Header、Cookie、IP 或 URL 参数）将部分流量精准路由到新版本服务，其余流量仍走旧版本。关键在于灵活配置匹配规则与 upstream 分组，不依赖外部组件即可完成轻量级灰度发布。
基于请求头（Header）做灰度分流
适用于前端或网关层可主动注入标识的场景，例如在测试时手动添加 X-Release: v2 请求头。
配置示例：
upstream backend-v1 {
server 192.168.1.10:8080;
}
upstream backend-v2 {
server 192.168.1.11:8080;
}
<p>server {
location /api/ {
if ($http_x_release = "v2") {
proxy_pass <a href="https://www.php.cn/link/486ab59b600e55d3ba1cd240be7483e2">https://www.php.cn/link/486ab59b600e55d3ba1cd240be7483e2</a>;
break;
}
proxy_pass <a href="https://www.php.cn/link/09a6fe5ea4948f06c3565fb75e49c1e5">https://www.php.cn/link/09a6fe5ea4948f06c3565fb75e49c1e5</a>;
}
}注意：if 在 location 中慎用，更推荐用 map 指令提升性能和可维护性：
map $http_x_release $upstream_backend {
default backend-v1;
"v2" backend-v2;
}
<p>server {
location /api/ {
proxy_pass <a href="https://www.php.cn/link/417dedd041fefe5dbdea9cd22d424d86">https://www.php.cn/link/417dedd041fefe5dbdea9cd22d424d86</a>;
}
}按用户 Cookie 或登录 ID 灰度
适合对特定用户群（如内部员工、灰度白名单）开放新功能，避免影响普通用户。
- 提取 Cookie 中的
user_id或自定义字段，用正则匹配目标用户 - 结合
map将匹配结果映射为 upstream 名称 - 示例：只让 user_id 为 1001~1005 的用户走 v2
map $cookie_user_id $upstream_backend {
~^(100[1-5])$ backend-v2;
default backend-v1;
}按 IP 段或来源做小流量验证
常用于上线初期验证稳定性，例如只放行公司出口 IP 或某测试机流量到新版本。
- 使用
geo指令预定义 IP 匹配规则，比每次用 if 判断更高效 - 可配合随机数实现百分比灰度（如 5% 流量）
geo $gray_ip {
default 0;
192.168.1.0/24 1; # 内网全部灰度
203.0.113.42 1; # 单个测试 IP
}
<p>map $gray_ip $upstream_backend {
1 backend-v2;
0 backend-v1;
}动态更新灰度策略（无需 reload）
生产环境频繁调整灰度比例或规则时，硬 reload Nginx 会中断连接。推荐方式：
- 用
include引入外部 map 文件（如/etc/nginx/conf.d/gray.map），修改后仅需nginx -s reload - 结合 Lua 模块（如 lua-resty-balancer）实现运行时动态 upstream 切换
- 搭配 Consul 或 etcd + OpenResty，自动同步灰度开关状态
不复杂但容易忽略：所有灰度规则应有明确兜底逻辑，确保未匹配请求始终落入稳定版本；同时建议在响应头中添加 X-Backend-Version 方便客户端或监控识别实际路由路径。
