Nginx无缝灰度发布依赖map+upstream+变量路由组合：map精准识别用户特征（Cookie/请求头/IP），定义隔离的stable/canary upstream，proxy_pass引用变量动态路由，reload即可秒级切换或回滚。
用 Nginx 实现无缝灰度发布，关键不是写一堆 if 判断，而是靠 map + upstream + 变量路由 这套组合——不重启、不中断、秒级生效，真正把“无缝”落到实处。
用 map 指令精准识别用户特征
map 是 Nginx 里最稳定、最推荐的条件映射方式，放在 http 块里，全局生效且无性能损耗。它能把请求中的任意字段（Header、Cookie、IP）转成一个变量，后续直接用于路由。
- 按 Cookie 区分用户：比如内部员工固定走灰度，可提取 cookie 中的 uid 或自定义键
- 按请求头控制：前端或测试工具加
X-Release: v2，Nginx 提前映射到对应后端 - 按 IP 段放行：内网办公网段（如 192.168.10.0/24）全部进灰度，配置简洁又可靠
- 组合使用更稳妥：先用 geo 判定是否内网，再用 map 对公网用户按 Cookie 二次筛选，避免规则冲突
定义两套独立 upstream 隔离环境
灰度和稳定版本必须部署在完全隔离的后端服务上，不能共用同一组 server。每套 upstream 要单独定义，带健康检查参数（如 max_fails=1 fail_timeout=60s），确保故障自动剔除。
- stable 环境：指向旧版服务（如 10.0.1.100:8080）
- canary 环境：指向新版服务（如 10.0.1.101:8080）
- 别把灰度和稳定混在一个 upstream 里配 weight——那叫权重分流，不是真灰度，无法定向验证特定人群
用变量 proxy_pass 实现动态路由
proxy_pass 后面不能硬编码，必须引用变量（如 http://$upstream_backend），而这个变量由 map 动态赋值。这样 reload 配置后，新请求立刻按规则走对应 upstream，老连接不受影响，真正无缝。
- map 的结果必须是已定义的 upstream 名称（不能含斜杠、空格或下划线以外的符号）
- 避免在 location 块里用 if + set 做路由判断——if 在某些场景下不可靠，且容易触发 Nginx 的重写循环
- 如果需要更复杂逻辑（比如按 uid 取模 100 控制 5% 流量），可用 set_by_lua_block，它比 access_by_lua_block 性能更好、阶段更早
切换与回滚只需改一行再 reload
上线验证没问题后，想全量切流？不用动代码、不用重启应用，只改 Nginx 配置里 map 的 default 值，或者直接改 set $active_env 行，然后执行 nginx -s reload。整个过程毫秒级完成，用户无感知。
- 回滚同理：改回原配置 + reload，流量瞬间回到旧版
- 建议把灰度开关做成独立配置文件（如 include /etc/nginx/conf.d/gray.conf），方便运维快速启停
- 配合日志格式记录 $upstream_backend，便于后续分析哪部分流量走了哪个版本
