如何设置Nginx worker_shutdown_timeout 以实现WebSocket长连接在热重载中平稳关闭？

本文共计992个文字，预计阅读时间需要4分钟。

worker_shutdown_timeout 对 WebSocket 连接无效，设置了白名单。 它仅对 HTTP 请求起作用，而 WebSocket 是通过 TCP 长连接传输的。Nginx 不解析请求栈、不知业务状态，所谓的等待请求完成根本未提及。强行依赖它做 reload，只会让客户端收到 WebSocket is closed before the connection is established 或直接断开连接，消息截断、重连风暴全来了。

为什么 worker_shutdown_timeout 在 WebSocket 场景下形同虚设

根本原因在于 Nginx 的代理层级和协议理解能力：

• Nginx 在 http 块中代理 WebSocket 时，实际走的是 HTTP Upgrade 流程，但一旦升级完成，后续所有二进制帧都按原始 TCP 流透传，不解析、不缓冲、不判断帧边界
• worker_shutdown_timeout 的退出逻辑依赖“请求完成”信号——HTTP 有明确的 request/response 边界，WebSocket 没有；Nginx 看不到 FIN 何时该发，也等不到“消息收完了”这个状态
• 旧 Worker 收到 QUIT 后会关闭监听 socket、释放空闲连接，但对已建立的 WebSocket 连接，只能干等内核 TCP keepalive 超时（默认 2 小时）或客户端主动断开；你配了 worker_shutdown_timeout 30s，它照样会在 30 秒后 强制 kill 掉还在传数据的连接
• 日志里频繁出现 open socket left in connection 或 aborting，就是强制终止未 clean up 的表现

真正能降低 WebSocket 中断风险的配置项

别碰 worker_shutdown_timeout，转而聚焦三个更关键、且实际生效的参数：

• proxy_read_timeout 3600 和 proxy_send_timeout 3600：必须显式加大，否则默认 60 秒就会中断静默中的长连接；值要大于客户端最大心跳间隔
• keepalive_timeout 600：避免因短超时导致连接频繁重建，加重服务端压力；注意这个是给 HTTP/1.1 keepalive 用的，不影响 WebSocket 本身，但影响 Upgrade 前的握手阶段稳定性
• proxy_buffering off：强制禁用缓冲，防止 Nginx 把未发完的帧卡在内存里延迟感知断连；尤其在服务端写入慢时，这是隐蔽的中断源

reload 时 WebSocket 不丢连接的实操路径

单靠 Nginx 配置做不到“优雅”，必须服务端、Nginx、客户端三方配合：

• 后端提供健康检查端点（如 /healthz），返回 503 时 Nginx 自动摘除该 upstream server；滚动更新前先触发此状态，让流量自然流走
• 客户端实现指数退避重连（1s → 2s → 4s），并为每条业务消息附加唯一 message_id，服务端幂等处理；哪怕断了也能续上
• K8s 场景下，Ingress Nginx Controller 会自动启用连接 draining：旧 Pod 收到 TERM 后，Kube-proxy 停止转发新流量，同时等待活跃连接自然关闭；此时再配合 preStop hook 执行 sleep 30，比 Nginx 自己的 worker_shutdown_timeout 更可控
• 运维侧 reload 前必跑：nginx -t 验证语法 + curl -I http://localhost/healthz 确认上游就绪 + ss -tn state established '( sport = :443 )' | wc -l 快速评估当前长连接规模

最易被忽略的一点：很多人以为把 worker_shutdown_timeout 设大就能“多等一会儿”，其实它对 WebSocket 根本不触发优雅逻辑，只起强制截止作用。真正的平滑，藏在服务端的可下线通知、Nginx 的 timeout 配置、客户端的容错设计这三者的咬合里——缺一不可。