Nginx 实现 API 多版本发布需满足流量可编排、版本可隔离、故障可收敛：通过 map 解析 gray_version Cookie 动态路由至独立 upstream；各版本启用健康检查与服务发现；proxy_pass 动态转发，透传灰度标识；叠加 backup 降级、Keepalived 高可用及限流熔断机制。
用 Nginx 实现高可用环境下的 API 多版本发布，核心是“流量可编排、版本可隔离、故障可收敛”——不改业务代码，全在网关层完成灰度控制与弹性容灾。
基于 Cookie 的动态版本路由
客户端通过携带 gray_version Cookie（如 v2 或 beta）声明期望版本，Nginx 在 http 块中用 map 指令解析并映射到对应 upstream 名称：
- 必须设置
default分支（例如指向v1），避免无 Cookie 或非法值导致 500 错误 - 支持别名映射，如
"beta" "v2"，方便运营侧灵活切换，无需改代码 - Cookie 值建议限定为小写字母、数字、短横线，便于日志分析和 WAF 规则匹配
独立版本 upstream 集群
每个 API 版本（如 v1、v2）对应一个物理或逻辑隔离的 upstream 块，实现资源与健康状态解耦：
- 各集群启用独立健康检查（
max_fails=2 fail_timeout=30s），故障节点自动剔除 - 生产环境避免写死 IP，推荐对接 Nacos/Consul，实现服务发现与自动节点同步
- 灰度版本（如
v2）建议部署在独立资源池，网络层面与主干流量隔离，防干扰
运行时 proxy_pass 与链路透传
在 location 中动态拼接 upstream 名，并转发请求：
- 使用
set $upstream_name "backend_$backend_group"构造合法 upstream 变量名 -
proxy_pass http://$upstream_name要求 Nginx ≥ 1.19；旧版本需引入 Lua 或split_clients - 透传原始 Cookie 和自定义 Header（如
X-Gray-Version），便于后端日志追踪与全链路染色
高可用增强机制
在多版本基础上叠加容灾能力，保障灰度期间主干服务不受影响：
- 为每个 upstream 设置
backup节点，当全部主版本异常时自动降级至兜底集群 - 配合 Keepalived 部署双 Nginx 实例，共享虚拟 IP，单点宕机秒级切换
- 启用限流（
limit_req）与熔断（proxy_next_upstream error timeout），防雪崩扩散
