worker_shutdown_timeout 是 nginx 热加载时控制旧 worker 处理已有连接的最长时间，需按业务类型（如 rest、大文件上传、websocket）设定，并与 proxy_read_timeout 等参数协同配置，否则无法避免连接中断。

调优 worker_shutdown_timeout 是解决 Nginx 热加载（nginx -s reload）时代理连接流失的核心手段，但它的作用不是“保连接”，而是为已建立的连接争取完整处理时间。关键在于：设得太短，连接被粗暴中断；设得不合理，旧 worker 滞留拖慢服务。它必须结合业务特征和配套超时参数协同生效。

明确它管什么、不管什么

该指令只影响 旧 worker 进程在 reload 过程中对已有连接的最长服务时长：

• 它不控制新连接——reload 完成后，新连接立即由新 worker 接管
• 它不解析应用层协议——对 WebSocket 帧、gRPC 流、SSE 数据无感知，只按 TCP 连接计时
• 它不替代 proxy_read_timeout 或 client_body_timeout——这些参数决定 Nginx 何时主动断开上游或客户端连接
• 它仅在标准 reload 流程中生效，kill -9 或 systemctl restart 会跳过整个优雅退出逻辑

按业务类型设定合理值

不能统一设 30s。必须根据你最长的可控连接生命周期来反推：

• 普通 REST API（JSON 响应，P99 ≤ 1s）：设为 15–30 秒。覆盖慢查询、网络抖动、重试延迟即可
• 大文件上传（如支持 500MB）：按最差上行带宽估算。例如用户平均 2MB/s，传完需 250 秒，则设为 300 秒，并确保 client_body_timeout ≥ 300
• WebSocket / SSE / HTTP/2 流：以心跳周期 × 最大容忍空闲次数为准。若心跳 30 秒、允许断 3 次，至少设为 120 秒；生产环境建议 300 秒起步
• 强依赖外部慢服务（如第三方支付回调）：取该链路 P99 耗时 + 40% 余量。P99 是 28 秒，就设为 40 秒

必须同步检查的配套参数

单独调大 worker_shutdown_timeout 无效，上下游超时必须形成闭环：

• proxy_read_timeout 和 proxy_send_timeout 必须 ≥ worker_shutdown_timeout，否则 Nginx 会在 upstream 响应完成前主动断连
• client_header_timeout 和 client_body_timeout 应 ≤ worker_shutdown_timeout，防止慢客户端把旧 worker 卡在读头/读体阶段
• WebSocket 场景下，proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade" 三项缺一不可，否则 reload 后直接降级为短连接

验证是否真正生效

不要只看进程状态。用真实流量验证：

• 部署一个模拟长响应接口（如返回 25 秒后的内容），并带上 X-Worker-Pid 头标识进程
• 用 curl -v http://your-domain/slow 发起请求，同时执行 nginx -s reload
• 观察响应是否完整返回且状态码为 200；若返回 Connection reset 或超时，说明 timeout 不足或 proxy_* 超时未对齐
• 检查 error.log 中是否有 worker process is shutting down 及持续时间，确认是否在预期窗口内退出