如何配置 proxy_next_upstream 在 TCP 节点连接失败时自动尝试下一台-Nginx-PHP中文网

nginx 在 tcp 连接失败时自动切换 upstream 节点需同时满足：upstream 至少两个节点、proxy_next_upstream error 配置在 location/server 块内、proxy_pass 指向该 upstream；配合 proxy_connect_timeout 和 proxy_next_upstream_tries 实现容错。

如何配置 proxy_next_upstream 在 tcp 节点连接失败时自动尝试下一台

要让 Nginx 在 TCP 连接失败时自动切换到下一个 upstream 节点，核心是启用并正确配置 proxy_next_upstream error，因为 error 类型专门覆盖建连阶段的底层失败（如连接被拒、连接重置、DNS 解析失败等）。

必须满足的三个前提条件

仅写 proxy_next_upstream error 不够，以下三点缺一不可：

upstream 至少定义两个可用节点：单节点无“下一个”可切，重试逻辑直接失效
配置必须放在 location 或 server 块内：写在 http 全局块中不会自动继承，需显式作用于具体代理路径
proxy_pass 必须指向该 upstream 名称：例如 proxy_pass http://backend;，不能是直连 IP

关键参数搭配说明

TCP 连接失败由 proxy_connect_timeout 控制超时边界，它和 error 协同工作：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

proxy_connect_timeout 5s：Nginx 等待后端 SYN-ACK 最多 5 秒，超时即触发 error
proxy_next_upstream error：捕获该 error，立即发起对下一节点的建连请求
proxy_next_upstream_tries 3：限制最多尝试 3 次（含首次），防止单点故障引发雪崩

完整可运行示例

以下配置实现「TCP 连不上就换人」的容错闭环：

upstream backend {
    server 10.0.1.10:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.11:8080 max_fails=3 fail_timeout=30s;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_connect_timeout 5s;
        proxy_next_upstream error;
        proxy_next_upstream_tries 3;
        proxy_next_upstream_timeout 15s;
    }
}

当第一个节点宕机（如 systemctl stop app），Nginx 在 5 秒内收不到 SYN-ACK，立刻记一次 error 并转向第二个节点——整个过程对客户端透明，延迟基本等于一次建连耗时。