Nginx 实现 Python 新旧 API 平滑过渡，核心是通过分版本 upstream 物理隔离后端服务，并基于路径、Header 或参数精准路由；配合 rewrite 兼容旧路径，透传关键请求头，结合健康检查与版本守门机制保障灰度安全。
用 Nginx 做 Python 服务的旧版 API 平滑过渡，核心不是替换后端代码，而是让新旧两个 Python 应用（比如 FastAPI v1 和 v2）同时在线，由 Nginx 按规则分流请求——客户端无感知，调用链不中断，灰度可控。
分版本定义 upstream，物理隔离后端
避免把新旧 Python 服务混在同一个 upstream 里。每个版本单独声明，便于独立管理、扩缩容和健康检查：
- 旧版 Python 服务（如运行在 10.0.1.10:8000，提供
/api/v1/接口）→ 定义为upstream api_v1 - 新版 Python 服务（如运行在 10.0.1.20:8001，支持
/api/v2/或统一根路径）→ 定义为upstream api_v2 - 确保两个服务监听不同地址或端口，不共用同一进程；若必须同机部署，至少用不同端口+明确 upstream 归属
按请求特征精准路由，支持多种灰度方式
不依赖轮询，而是从请求中提取明确信号，决定转发到哪个 Python 版本：
提示词大师-python版
下载
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
-
路径前缀路由：最直观，适合客户端已配合升级 URL 的场景
location /api/v2/ { proxy_pass http://api_v2; }
location /api/v1/ { proxy_pass http://api_v1; } -
Header 路由（推荐）：客户端带
X-API-Version: v2，Nginx 用map提取并绑定 upstream
map $http_x_api_version $target_upstream { default api_v1; "v2" api_v2; }
location /api/ { proxy_pass http://$target_upstream; } -
Query 参数辅助验证：如
/api/users?version=v2，仅用于测试或临时切流，不建议长期生产使用
用 rewrite 实现路径兼容，旧客户端无需改调用
当新版 Python 服务已弃用路径中的版本号（如只接受 /api/users），但旧客户端仍发 /api/v1/users，可用 rewrite 内部重写：
立即学习“Python免费学习笔记（深入）”；
- 在对应 location 中写：
location /api/v1/ {
rewrite ^/api/v1/(.*)$ /api/$1 break;
proxy_pass http://api_v2;
} - 注意用
break防止重复匹配；若新版服务也挂载在/api/v2/下，可改为rewrite ^/api/v1/(.*)$ /api/v2/$1 break; - 所有 rewrite 后的请求，仍需透传原始 Host、X-Real-IP、X-Forwarded-For 等头，确保 Python 后端日志和鉴权正常
加健康检查与守门机制，防止流量误入错误版本
光靠 IP 连通性不够——后端进程活着，不代表它已是目标版本。必须主动验证：
- 为每个 upstream 的 server 配置健康探针，例如：
server 10.0.1.20:8001 max_fails=2 fail_timeout=10s;
health_check interval=5 fails=2 passes=2 uri="/health?check=version" match=status_ok; - 后端 Python 服务在
/health?check=version返回 200 + JSON：{"version": "v2.1"} - 发布期间启用“版本守门”：用 map 提取请求版本标识，再比对当前 upstream 所属版本；不一致时直接 return 451 或跳转降级页，不转发
