API接口版本不匹配源于流量路由与后端实际版本脱节，需通过upstream分组隔离、请求特征精准路由、主动健康检查及发布期版本守门机制协同解决。
API 接口版本不匹配，本质是流量路由与后端实际版本脱节——请求被分发到旧版节点，而客户端期望新版行为。这不是 Nginx 故意“发错”，而是配置未对齐版本生命周期所致。关键在三点：让 Nginx 知道版本、让流量带版本标识、让不匹配的请求及时拦截或重定向。
用 upstream 分组隔离不同版本
避免把 v1 和 v2 服务混在一个 upstream 里。每个版本单独定义，物理隔离，便于独立扩缩容和灰度控制：
- 为 v1 和 v2 分别建 upstream 块，例如 upstream api_v1 和 upstream api_v2
- 每个 upstream 内只放对应版本的后端地址（如 10.0.1.10:8080 是 v1，10.0.1.20:8081 是 v2）
- 不要给同一台机器同时注册两个版本；若需共存，必须监听不同端口或路径，并明确归属
按请求特征精准路由到目标版本
仅靠轮询或 IP hash 无法区分版本意图。必须从请求中提取明确信号，再映射到对应 upstream：
- Header 路由最可靠：客户端带 X-API-Version: v2，Nginx 用 if 或 map 提取并 proxy_pass 到 api_v2
- Query 参数辅助验证：如 /user?version=v2，适合测试或临时切流，但不建议长期用于生产
- 路径前缀强制绑定：/v2/** → api_v2，需客户端配合升级路径，适合强契约场景
加主动健康检查识别“假存活”节点
后端进程还在跑，不代表它已是新版本。Nginx 默认的 max_fails 只看连通性，不验版本。必须主动探活：
- 为每个 server 配置 version 探针，例如 proxy_pass http://backend/health?check=version
- 后端返回 200 + 正确版本号（如 { "version": "v2.3" }），Nginx 才认为该节点可服务当前流量
- 开源版可用 log_by_lua_block 拦截响应头 X-Backend-Version，不匹配则 return 503 并告警
发布期间启用版本守门机制
上线新版本时，旧节点不能立刻下线，但也不该继续接新请求。需要一层“守门”逻辑：
- 用 map 指令提取请求中的版本标识（header/cookie/query），生成 $req_version 变量
- 在 location 中对比 $req_version 与 upstream 当前预期版本（可通过变量或外部配置注入）
- 不一致时，return 451 或 302 重定向到统一降级页，而非转发给错误版本
