proxy_next_upstream 定义上游失败时的重试触发条件，需配合 proxy_next_upstream_tries 和 proxy_next_upstream_timeout 控制重试次数与总超时；仅当 upstream 配置多台服务器时才能真正切换节点。
proxy_next_upstream 是 Nginx 代理模块中控制上游服务器失败时是否重试的关键指令。它不决定“重试几次”或“重试多久”，而是定义“在什么条件下触发重试”，真正决定重试行为的是它与 proxy_next_upstream_tries 和 proxy_next_upstream_timeout 的组合使用。
明确重试触发条件
该指令后跟一个或多个响应状态或错误类型，满足任一条件即尝试切换到下一个 upstream server（前提是配置了多个 server 或启用了 keepalive 连接池）：
- error：与上游建立连接时发生错误（如拒绝连接、超时）
- timeout：连接上游或等待响应超时（由 proxy_connect_timeout / proxy_read_timeout 控制）
- invalid_header：上游返回空响应或非法 HTTP 头（如无 Status-Line）
- http_500、http_502、http_503、http_504：收到对应 HTTP 状态码时重试
- http_404 等非 5xx 也可显式启用，但需谨慎——通常 404 表示业务不存在，重试无意义
配合 tries 和 timeout 控制重试上限
仅设置 proxy_next_upstream 不会自动无限重试。必须搭配以下两个指令才能生效：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- proxy_next_upstream_tries：最多尝试多少次（含首次请求），默认为 0（不限），建议设为 2–3 避免雪崩
- proxy_next_upstream_timeout：整个重试过程的总超时时间（从第一次请求开始计），单位秒，默认 0（不限）
例如：proxy_next_upstream error timeout http_502 http_503; proxy_next_upstream_tries 3; proxy_next_upstream_timeout 10; 表示：遇到连接错误、超时或返回 502/503 时，最多再试 2 次（共 3 次请求），且所有尝试加起来不能超过 10 秒。
注意 upstream 配置的影响
重试能否真正“换机器”，取决于 upstream 块中是否定义了多个 server：
- 单台 upstream server：即使配置了重试，也只会反复打同一台，除非它已标记为 down 或通过 health_check 被剔除
- 多台 server：Nginx 按配置顺序或负载均衡策略（如 round-robin、least_conn）选择下一台；失败后跳过当前节点，继续尝试列表中的下一个
- 配合 max_fails 和 fail_timeout 可实现临时摘除机制，让重试更有效
常见误区与建议
避免把重试当作兜底方案：
- 不要对 http_404 或 http_401 开启重试——这类响应是业务逻辑结果，换服务器无意义
- 慎用 off 值：显式写
proxy_next_upstream off;可彻底禁用重试（包括默认行为），适合强一致性场景 - 日志中可通过 $upstream_addr 和 $upstream_status 查看实际走了哪台、返回什么状态，用于验证重试是否按预期工作
