详解 stream 模块下的 proxy_timeout 与客户端连接保持策略-Nginx-PHP中文网

proxy_timeout是Nginx stream模块中控制连接空闲超时的核心参数，定义连接建立后无数据传输时的自动断开时间，默认60秒；需≥后端wait_timeout（如MySQL默认28800秒），典型值设1h，配合tcp_nodelay和upstream keepalive可提升长连接稳定性与资源效率。

详解 stream 模块下的 proxy_timeout 与客户端连接保持策略

proxy_timeout 是 Nginx stream 模块中控制客户端连接空闲超时的核心指令，它不作用于传输耗时，而是决定“连接建立后，若双方都不发数据，多久断开”。这个值直接影响长连接稳定性、资源占用和业务可用性。

proxy_timeout 的真实含义与常见误区

它不是“整个请求处理时间上限”，而是连接空闲等待时间：从最后一个字节收/发完成起计时，期间无任何 TCP 数据流动即触发断连。
默认值为 60 秒（部分旧版本为 6 秒），对数据库类服务明显偏短。
不等于后端 wait_timeout 或 interactive_timeout，但应 ≥ 后端对应值，否则 Nginx 会先于数据库主动断开连接。
不受 HTTP 层 keepalive_timeout 影响——stream 模块完全独立于 http 上下文。

例如 MySQL 默认 wait_timeout = 28800（8 小时），若 proxy_timeout 30s，则所有空闲连接在 30 秒后被 Nginx RST 掉，客户端收到 “Connection reset by peer”。

如何设置合理的 proxy_timeout 值

MySQL / PostgreSQL：设为 1h 或 30000s，略大于数据库 wait_timeout 即可
Redis（短连接模式）：可设为 30s～60s，配合客户端快速重连
自定义长连接服务（如 IoT 心跳通道）：建议 2h～24h，并启用 tcp_nodelay on 减少心跳延迟
高并发短连接场景（如批量导入）：可适当调低（如 10s），加快连接回收

配置示例：

server {
    listen 3307;
    proxy_pass mysql_backend;
    proxy_timeout 1h;        # 关键：匹配后端空闲容忍窗口
    tcp_nodelay on;          # 关键：禁用 Nagle 算法，避免小包合并延迟
}

客户端连接保持的协同要点

Nginx 不控制客户端行为，但网关设计必须引导客户端合理复用连接：

Nginx Reverse Proxy

配置 Nginx 反向代理，实现域名绑定。用户说“绑定域名”“配置 Nginx”“反向代理”时触发，将域名绑定到指定 IP:端口。

下载

禁止频繁新建连接：Java 客户端应使用 HikariCP（MySQL）、Lettuce（Redis）等带连接池的驱动；Node.js 应复用 net.Socket 实例
避免 DNS 轮询干扰：对外暴露固定 VIP + 端口，不依赖客户端做服务发现或轮询
客户端侧 timeout 设置要匹配：
- connectTimeout 应 > 网络建连抖动（通常 3s～5s）
- socketTimeout（读超时）应 > 最大单次操作预期耗时，但 proxy_timeout，防止 Nginx 先断而客户端还在等
Linux 内核辅助优化（客户端和服务端均可配）：
- net.ipv4.tcp_tw_reuse = 1：允许 TIME_WAIT 套接字重新用于新连接
- net.ipv4.ip_local_port_range = "1024 65535"：扩大临时端口范围，缓解端口耗尽

配合 upstream 连接复用提升效率

虽然 stream 模块不解析协议，但它支持对 upstream 的连接池复用（类似 HTTP 的 keepalive）：

在 upstream 块中添加：

upstream mysql_backend {
    server 192.168.1.10:3306;
    server 192.168.1.11:3306;
    keepalive 32;             # 每个 worker 对该 upstream 最多缓存 32 个空闲连接
    keepalive_timeout 60s;    # 空闲连接保活时长，超时自动关闭
}