实现应用平滑升级时的流量无损代理，关键不是只写对 proxy_pass，而是构建“健康检查+连接复用+超时协同”机制：启用被动健康检查（max_fails=1 fail_timeout=10s），开启 keepalive 连接池，精细化设置超时参数，并配合后端优雅下线流程。
要实现应用平滑升级时的流量无损代理，关键不是只写对 proxy_pass，而是围绕它构建一套能容忍后端短暂不可用、避免请求中断、支持优雅下线的反向代理机制。Nginx 本身不主动感知后端是否“正在重启”，必须靠配置组合来兜底。
核心：用健康检查 + 连接复用 + 超时协同控制
仅靠 proxy_pass http://backend; 无法做到无损——一旦后端进程重启、端口短暂断开，Nginx 默认会立即返回 502，且可能复用已失效的连接。需叠加以下三项：
-
启用被动健康检查：在 upstream 块中配置
max_fails=1 fail_timeout=10s，让 Nginx 在单次失败后暂时摘除节点 10 秒，避免雪崩式重试 -
开启 keepalive 连接池：用
keepalive 32;（配合proxy_http_version 1.1;和proxy_set_header Connection '';），减少握手开销，也降低因连接复用导致的“旧连接发往已关闭端口”的概率 -
精细化设置超时参数：把
proxy_connect_timeout（建连）、proxy_send_timeout（发请求）、proxy_read_timeout（等响应）分别设为 3s / 60s / 60s —— 连接超时要短，业务超时要长，给后端留出升级窗口
配合后端优雅下线流程
Nginx 的“无损”是配合后端行为的。若后端 Spring Boot 应用未做 shutdown hook 或 actuator 的 readiness 探针，Nginx 就无从判断“该不该转发”。建议：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- 后端启动就暴露
/actuator/health/readiness，返回{"status":"UP"}才允许接入流量 - 升级前先调用
/actuator/health/liveness确认旧实例仍可响应，再发POST /actuator/shutdown触发优雅停机（或通过信号量 + preStop hook） - Nginx 可用
ngx_http_upstream_check_module（需编译进）或外部工具轮询 readiness，动态更新 upstream，但更轻量的做法是：升级时先nginx -s reload暂时移除旧 server，等旧连接自然 drain 完
避免常见翻车点
很多“看似平滑”的配置在压测或真实升级中失效，往往卡在这些细节：
-
没配
proxy_buffering off;：大响应体或流式接口（如 SSE）容易因 buffer 满而阻塞，导致请求卡住甚至超时 -
忽略
proxy_next_upstream error timeout http_502;：默认不重试 502，必须显式加上，才能在后端瞬时不可用时自动切到其他节点（多实例场景） - worker_processes 或 worker_connections 不足：升级期间连接数突增，若配置过小，会直接触发 502，而非重试或等待
- 日志里出现 “upstream prematurely closed connection” 却没排查：这说明后端提前关了连接，大概率是没等完所有响应就退出了，需检查后端 shutdown 超时和连接池释放逻辑
一个最小可用示例
假设后端服务部署在 8080/8081 两个端口，升级时逐个滚动替换：
upstream app_backend {
server 127.0.0.1:8080 max_fails=1 fail_timeout=10s;
server 127.0.0.1:8081 max_fails=1 fail_timeout=10s;
keepalive 32;
}
server {
listen 80;
location /api/ {
proxy_pass http://app_backend;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_connect_timeout 3s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_buffering off;
proxy_next_upstream error timeout http_502;
}
}
这个配置不依赖商业版或外部组件，适用于开源 Nginx 1.16+，重点在于每个参数都有明确作用，且彼此不冲突。
