nginx reload 导致 websocket 断连的本质是旧 worker 进程强制终止长连接，需通过 worker_shutdown_timeout、stream 模块透传或后端状态外置实现平滑过渡。

Reload Nginx 时 WebSocket 连接大面积断连，本质不是“重连失败”，而是连接被强制中断——Nginx reload 默认会关闭所有现存连接（包括已升级的 WebSocket），导致客户端瞬间失联。这不是前端重连逻辑能解决的问题，必须从 Nginx 的进程模型和连接管理机制入手优化。

理解 reload 的真实行为

Nginx reload 并非热更新：它启动新 worker 进程，但旧 worker 进程在处理完当前请求后会退出；而 WebSocket 是长连接，不属“请求-响应”范畴，旧 worker 不会等待其自然关闭，而是直接终止 TCP 连接。客户端收到 FIN/RST 包，触发 onclose，此时无论前端重连多快，都已产生业务中断。

启用 graceful shutdown 与连接平滑过渡

让旧 worker 在退出前继续服务已有 WebSocket 连接，直到连接自然关闭或超时：

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

• 在 nginx.conf 的 http 或 stream 块中添加：
  worker_shutdown_timeout 60s; —— 允许旧 worker 最多再运行 60 秒，期间持续处理活跃连接
• 确保 upstream 配置启用 keepalive：
  upstream ws_backend {
    server 127.0.0.1:8080;
    keepalive 32;
  }
• 配合 proxy_http_version 1.1 和 upgrade 头透传，使连接真正复用底层 TCP 连接池，减少 reload 时的连接重建压力

启用 nginx-stream-module 处理 WebSocket（推荐）

HTTP 模块对长连接 reload 支持有限；stream 模块工作在 TCP 层，天然支持连接透传，reload 时不会干扰已建立的 WebSocket 流：

• 确认已编译或加载 nginx-stream-module（主流发行版默认包含）
• 在 nginx.conf 中新增 stream 块（非 http 块）：
  stream {
    upstream ws_stream {
      server 127.0.0.1:8080;
    }
    server {
      listen 8081;
      proxy_pass ws_stream;
      proxy_timeout 86400;
      proxy_responses 1;
    }
  }
• 前端连接地址改为 ws://your-domain.com:8081/xxx，绕过 HTTP 层代理，彻底规避 upgrade 头丢失与 reload 断连问题

配合后端实现连接状态可迁移（高阶）

即使 Nginx 层优化到位，单点故障仍可能引发批量断连。建议后端引入连接状态外部化：

• 将用户连接 ID、会话状态、最后消息 ID 写入 Redis 等共享存储
• reload 后，客户端重连时携带上次连接 ID，后端快速恢复上下文，避免重复登录或消息丢失
• 结合 Nginx 的 proxy_next_upstream error timeout，当某 backend 实例不可达时自动切到健康节点，进一步降低 reload 影响面