全站无损平滑迁移依赖upstream协同、上下文保真、健康兜底与热重载：定义双upstream启用max_fails/fail_timeout/slow_start，按路径/域名/灰度分流，透传Host/X-Real-IP/X-Forwarded-Proto，配置proxy_next_upstream自动回退，并通过日志标记upstream_addr和服务版本实现可观测。
全站无损平滑迁移不是靠单个 proxy_pass 实现的，而是靠 upstream 协同、请求上下文保真、健康兜底和热重载机制共同保障的。核心目标是：用户无感知、请求不丢包、切流可逆、出错自动回退。
定义双 upstream 并启用健康检查
把新旧服务都注册进 upstream，让 Nginx 能动态识别可用节点：
- 用
max_fails=2 fail_timeout=5s做基础探活，避免瞬时抖动误摘 - 对新服务加
slow_start=30s，上线初期逐步增加流量，防止冷启动雪崩 - 若需 HTTP 级探测（比如检查返回 200 + 特定 body），可启用
nginx_upstream_check_module
示例配置：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
server 10.0.1.10:8080 max_fails=2 fail_timeout=5s;
}
upstream new_backend {
server 10.0.1.20:8080 max_fails=2 fail_timeout=5s slow_start=30s;
}
按路径/域名/灰度标识精准分流
全站迁移≠一次性切流，必须支持细粒度控制：
-
路径隔离：如
location /v1/ { proxy_pass http://old_backend; }，location /v2/ { proxy_pass http://new_backend; } -
域名隔离：旧流量走
legacy.example.com，新流量走api.example.com，两者共存 -
灰度分流：用
map提取请求头或 Cookie，例如map $http_x_release_phase $target { default old; "v3" new; }，再在proxy_pass中引用$target
透传原始上下文，避免后端异常
后端常依赖 Host、协议、真实 IP 做签名、跳转或日志，Nginx 必须显式传递：
-
proxy_set_header Host $host;（防止被覆盖成 upstream 地址） -
proxy_set_header X-Real-IP $remote_addr;和X-Forwarded-For $proxy_add_x_forwarded_for; -
proxy_set_header X-Forwarded-Proto $scheme;（HTTPS 下重定向才不会变成 http://） - 若后端用 WebSocket 或长连接，加
proxy_http_version 1.1;和proxy_set_header Upgrade $http_upgrade;
配置自动故障回退与可观测性
新服务不稳定时，不能让用户看到 502，而应静默切回旧服务：
-
proxy_next_upstream error timeout http_500;—— 出错即尝试 fallback - 配合
error_page 502 = @fallback;或直接在 location 内用 if 判断，指向旧 upstream - 在
log_format中加入$upstream_addr和自定义 header（如$upstream_http_x_service_version），方便快速比对新旧服务调用量与延迟
