nginx 实现版本分发需 upstream 分组隔离、精准路由匹配（header/路径前缀）及健康检查与灰度控制；示例配置含 api_v1/api_v2 分组、map 动态路由和 proxy_pass 转发。
要让 Nginx 在负载均衡基础上支持后端服务的版本分发（比如 v1、v2、v3），关键不是只做流量均摊，而是实现按版本路由 + 独立管理 + 安全过渡。这需要 upstream 分组隔离、精准匹配规则和配套运维机制三者配合。
为每个版本定义独立的 upstream 组
不同版本的服务应完全隔离，避免混用或误切。不能把 v1 和 v2 的实例写进同一个 upstream。
- 用语义化名称定义组，例如 upstream api_v1 和 upstream api_v2
- 每个组内可配置 weight（如性能强的 v2 实例设 weight=2）、max_fails 和 fail_timeout 控制容错
- 支持 backup 标记备用节点，或 down 临时下线某实例而不删配置
根据请求特征选择目标版本
路由逻辑要清晰、可维护，优先使用 header 或路径前缀，避免依赖易变参数。
- Header 路由：检查 $http_x_api_version，匹配 v2 就 proxy_pass 到 api_v2，否则走 api_v1
- 路径前缀路由：用 location /v2/ 直接指向 api_v2，适合客户端已升级路径的场景
- 避免 query 参数长期路由：如 if ($arg_version = "v2") 仅用于临时调试，生产环境不推荐
加入健康检查与灰度控制能力
版本切换是否可靠，取决于能否感知状态、限制范围、逐步验证。
- 启用 health_check（需编译含 upstream_health_check_module），定期探测 /health 端点自动剔除异常节点
- 灰度发布时，先用 map 指令结合 IP 段或自定义 Header（如 X-Env: staging）分流小部分流量到 v2
- 下线旧版前，后端应主动返回 503 或配合服务发现系统（如 Consul）通知 Nginx 更新状态
附：一个最小可用配置片段
在 http 块中添加：
upstream api_v1 {
server 10.0.1.10:8080 max_fails=2 fail_timeout=10s;
server 10.0.1.11:8080 weight=2;
}
upstream api_v2 {
server 10.0.1.20:8081 max_fails=2 fail_timeout=10s;
server 10.0.1.21:8081 backup;
}
map $http_x_api_version $backend {
"v2" "api_v2";
default "api_v1";
}
server {
listen 80;
location / {
proxy_pass http://$backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
