如何设置worker_shutdown_timeout以实现热重载时WebSocket连接的平稳关闭？

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

`worker_shutdown_timeout` 配置项不能使 WebSocket 连接平滑退出，导致 WebSocket 连接平滑退出失败，实际效果无效。Nginx 不解析 WebSocket 帧结构，无法判断消息是否收发完成，应当指定触发的是强制终止 TCP 连接，这可能导致连接中断。正确配置能降低影响的，是一套合理的配置与同步机制。

为什么不能依赖 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 代理能成立的前提，缺一不可：

• 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 峰值