worker_shutdown_timeout对WebSocket无效，仅强制关闭TCP连接，易致帧截断和1006错误；需配合proxy_http_version 1.1、Upgrade与Connection头，及proxy_read/send_timeout、keepalive_timeout等配置缓解影响，并依赖后端健康检查、Nginx draining和客户端重连机制实现平滑过渡。
worker_shutdown_timeout 本身不能让 WebSocket 连接“平滑退出”，它对 WebSocket 实际无效。Nginx 不解析 WebSocket 帧，无法判断消息是否收发完成，该指令触发的是强制终止 TCP 连接，容易导致帧截断、1006 错误或重连风暴。真正能降低影响的，是一套配合配置与协同机制。
为什么不能依赖 worker_shutdown_timeout 控制 WebSocket
Nginx 在反向代理模式下仅透传 WebSocket 流量，不识别帧边界、心跳或业务语义。当旧 worker 进入 shutting down 状态后：
- 它会停止 accept 新连接，但不会主动关闭已建立的 WebSocket TCP 连接
- worker_shutdown_timeout 到期时，Nginx 强制 close socket，内核可能丢弃未发出的 FIN 或未确认的帧
- 日志中常见 open socket left in connection 或 aborting 提示，说明连接未 clean up
- 客户端感知为异常断连，而非 graceful close
必须配套的代理层基础配置
即使不靠 worker_shutdown_timeout，以下三项是 WebSocket 代理能成立的前提，缺一不可：
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- proxy_http_version 1.1; —— HTTP/1.0 不支持 Upgrade 协议升级
- proxy_set_header Upgrade $http_upgrade; —— 透传客户端发起的 Upgrade 请求头
- proxy_set_header Connection "upgrade"; —— 显式声明升级意图，引号不可省略
缺少任一，reload 后连接会立即降级为短连接，前端报错 WebSocket is closed before the connection is established。
缓解 reload 冲击的实用配置组合
虽然无法实现 WebSocket 的真正优雅退出，但可通过以下配置显著减少中断概率和影响范围：
- proxy_read_timeout 3600; 和 proxy_send_timeout 3600; —— 防止 Nginx 因空闲超时（默认 60s）主动断开活跃连接
- keepalive_timeout 600s; —— 延长 HTTP keep-alive 时间，减少连接频繁重建带来的抖动
- proxy_buffering off; —— 关闭缓冲，避免 Nginx 暂存未转发的 WebSocket 数据，导致延迟断连
- worker_shutdown_timeout 30s;（放在 events 块中）—— 对 HTTP 类流量（如健康检查、SSE、上传进度）提供缓冲窗口，间接保护部分关联行为
更可靠的平滑过渡方案
单靠 Nginx 配置无法解决本质问题。推荐采用服务端、Nginx、客户端三方协同策略：
- 后端主动配合：提供 /healthz 或 /ready 接口，返回 503 表示准备下线；配合 Kubernetes readiness probe 快速摘除节点
-
Nginx 层 draining：在滚动更新前，先临时将 upstream server 标记为
down或用max_fails=1 fail_timeout=1s加速剔除 - 客户端容错设计：实现指数退避重连（如 1s → 2s → 4s）、握手失败自动重试、关键消息带唯一 ID 并服务端幂等处理
-
运维节奏控制：避免高频 reload；生产环境使用 CI/CD 流水线统一灰度，配合监控观察
nginx.connections.active下降趋势与nginx.worker.processes.exiting峰值
