worker_shutdown_timeout对WebSocket无效，因Nginx不解析WebSocket帧，无法判断消息收发状态，仅能强制终止TCP连接，导致帧截断、异常断连及重连风暴。
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），确认旧连接是否自然衰减而非突降。
worker_shutdown_timeout 的合理用途
它仍有价值，但仅限于 HTTP 流量缓冲：
- 可设为 30s～2m（例如
worker_shutdown_timeout 60s;），放在events块中； - 作用是为正在传输的大文件下载、HTTP/2 流、慢速 POST 等留出完成窗口；
- 配置后必须执行
nginx -t && nginx -s reload才生效，不能只改配置不重载。
