旧版接口平滑迁移核心是新旧服务共存、流量可控、切换无感，关键在于控制转发逻辑与过渡安全：按路径/域名/请求头分流、透传原始上下文、健康检查与降级兜底、全链路可观测性。

用 proxy_pass 做旧版接口平滑迁移，核心是让新旧服务共存、流量可控、切换无感。关键不在“怎么转发”，而在“怎么控制转发逻辑”和“如何保障过渡安全”。

按路径或域名精准分流请求

迁移不是全量切流，而是逐步将特定接口导流到新服务。Nginx 的 location 匹配能力足够支撑这种细粒度路由：

• 按路径前缀区分：比如 /api/v1/users/ 还走旧服务，/api/v2/users/ 指向新服务
• 按请求头或参数灰度：用 map 指令提取 $http_x_version 或 $arg_env，动态设置后端 upstream
• 按域名隔离：如 old.api.example.com 固定代理旧服务，api.example.com 默认走新服务，兼容期两者并存

保留原始请求上下文不丢失

后端服务依赖的 Host、IP、协议等信息，若被 Nginx 默认覆盖，会导致签名失败、重定向异常或日志混乱：

• 显式透传 Host：proxy_set_header Host $host;（避免变成 upstream 的地址）
• 传递真实客户端 IP：proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
• 维持协议一致性：proxy_set_header X-Forwarded-Proto $scheme;，尤其影响 HTTPS 下的重定向和资源链接生成

加一层健康检查与降级兜底

新服务上线初期不稳定，不能让一次 502 直接中断所有调用：

• 启用 upstream 的健康检查：health_check interval=3 fails=2 passes=2;，自动摘除异常节点
• 配置 proxy_next_upstream error timeout http_500;，当新服务不可用时，自动回退到旧服务（需 upstream 中同时定义两套 server）
• 用 return 404 或 error_page 404 = @fallback 对未迁移路径做明确响应，避免静默失败

迁移过程留痕与可观测性

光转发不够，得知道谁在调用、哪条路径已切流、错误是否集中爆发：

• 在 log_format 中加入 $upstream_addr 和 $upstream_http_x_service_version（如果新服务返回该 header），区分请求最终走向
• 对关键迁移路径单独配置 access_log，便于快速比对新旧服务调用量和耗时
• 配合 Prometheus + nginx-vts-module 或 nginx-lua-prometheus，暴露 per-location 的成功率、P95 延迟指标

整个过程不复杂但容易忽略细节。重点不是写多少 proxy_pass，而是让每一次转发都可预期、可追溯、可回滚。