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及持续时间，确认是否在预期窗口内退出
