旧版接口平滑迁移核心是新旧服务共存、流量可控、切换无感，关键在于控制转发逻辑与过渡安全：按路径/域名/请求头分流、透传原始上下文、健康检查与降级兜底、全链路可观测性。
用 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，而是让每一次转发都可预期、可追溯、可回滚。
