如何配置 worker_shutdown_timeout 确保热重启时 WebSocket 长连接平滑退出-Nginx-PHP中文网

worker_shutdown_timeout对WebSocket无效，因Nginx不解析WebSocket帧，无法判断消息收发状态，仅能强制终止TCP连接，导致帧截断、异常断连及重连风暴。

如何配置 worker_shutdown_timeout 确保热重启时 websocket 长连接平滑退出

worker_shutdown_timeout 本身对 WebSocket 连接**不生效**，它无法确保 WebSocket 长连接平滑退出。Nginx 不解析 WebSocket 帧，无法判断连接中消息是否收发完成，因此该参数仅作用于 HTTP 请求的优雅关闭，对 WebSocket 只会触发强制终止 TCP 连接，导致帧截断、客户端报错或重连风暴。

为什么 worker_shutdown_timeout 对 WebSocket 无效

Nginx 在反向代理模式下对 WebSocket 是透传（L4/L7 proxy），不处理协议语义：

它不识别 WebSocket 的 ping/pong、文本/二进制帧，也不跟踪应用层连接状态；
reload 时，worker 进程收到 QUIT 信号后，会关闭监听套接字、释放空闲连接，但对已建立的 WebSocket 连接只能等待内核 TCP keepalive 或客户端主动断开；
一旦 worker_shutdown_timeout 到期，未完成传输的连接会被 abrupt close，日志中常见 open socket left in connection 或 aborting 警告。

真正影响 WebSocket 平滑退出的关键配置

保障 WebSocket 在 reload 时不中断，核心是让 Nginx **不主动关闭长连接**，并配合后端与客户端行为：

WebSocket 8.18.2

WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。

下载

proxy_read_timeout 3600; —— 必须显式设置足够大（如 1 小时），避免 Nginx 默认 60s 超时后主动断开空闲连接；
proxy_send_timeout 3600; —— 同理，防止服务端响应慢时被误杀；
proxy_http_version 1.1; —— 强制使用 HTTP/1.1，否则无法支持 Upgrade 升级；
proxy_set_header Upgrade $http_upgrade; —— 透传客户端 Upgrade 头；
proxy_set_header Connection "upgrade"; —— 注意引号不可省，显式声明升级意图；
keepalive_timeout 600s; —— 延长复用连接生命周期，减少频繁重建带来的抖动。

必须配合的服务端与客户端策略

单靠 Nginx 配置无法实现“优雅”，需三方协同：

后端提供健康检查端点（如 /healthz），reload 前返回 503，让上游负载均衡器（或 Nginx upstream）自动摘除节点；
客户端实现带退避的重连机制（如 1s → 2s → 4s 指数增长），并为关键消息添加唯一 ID 实现幂等；
运维侧采用滚动更新：K8s 中设 maxUnavailable=1 + minReadySeconds，Ingress Controller 自动触发 draining；
监控 Active connections 变化趋势（通过 nginx_stub_status），确认旧连接是否自然衰减而非突降。