worker_shutdown_timeout 是 Nginx 热重载时旧 worker 处理残留连接的最长等待时间，需据业务类型（API、上传、长连接、外部依赖）设为 10–30s 至 300s 不等，并协同 proxy_timeout、client_timeout 等参数确保优雅退出。
worker_shutdown_timeout 是 Nginx 实现真正平滑热重载的关键控制参数，尤其在高频率发布、灰度切换或 A/B 版本快速轮转的场景中，它直接决定旧 worker 进程是否能在退出前完整处理完所有活跃连接。设得太短，未完成的请求会被强制中断；设得太长，旧进程滞留内存和句柄，拖慢整体响应并增加资源压力。
worker_shutdown_timeout 的作用机制
该指令定义了旧 worker 进程在收到 QUIT 信号后，允许继续处理已有连接的最大时长。超时后，即使仍有未关闭的连接（如长轮询、SSE、大文件上传中段），进程也会被强制终止。它不控制新连接的建立——新连接从 reload 完成起就由新 worker 接管，只影响“正在路上”的请求生命周期。
注意：此参数仅对旧 worker 生效，且必须配合 nginx 的标准 reload 流程（发送 HUP 或执行 nginx -s reload）才起作用；单纯重启或 kill -9 会跳过整个优雅退出逻辑。
如何根据业务特征设定合理值
没有通用固定值，需结合实际请求行为估算：
- 普通 REST API（JSON 响应，平均耗时 ≤200ms）：设为 10～30 秒足够。多数连接在几秒内自然结束，预留缓冲应对偶发慢查询或网络延迟。
- 文件上传接口（支持 100MB+ 大文件）：需覆盖最大上传时间。例如客户端带宽 1MB/s，上传 100MB 需约 100 秒，则建议设为 120～180 秒，并同步检查 client_header_timeout 和 client_body_timeout 是否匹配。
- 长连接服务（WebSocket、SSE、gRPC-Web）：不能仅看单次响应，要考虑心跳间隔与最长空闲容忍。若心跳 30 秒一次，期望保持连接 5 分钟，则至少设为 300 秒，否则可能在 reload 瞬间断连。
- 依赖外部慢服务（如同步调用第三方支付回调）：以该外部链路 P99 耗时为基准，再加 20%～50% 余量。例如支付回调平均 8 秒、P99 为 25 秒，可设为 40 秒。
与其他参数的协同配置要点
单独调大 worker_shutdown_timeout 不足以保障完整性，还需检查配套设置：
- 确保 proxy_read_timeout / proxy_send_timeout ≥ worker_shutdown_timeout：反向代理场景下，若 upstream 响应慢于 shutdown 超时，Nginx 可能提前关闭连接，导致后端仍在处理但客户端已断开。
- client_header_timeout 和 client_body_timeout 应 ≤ worker_shutdown_timeout：避免客户端迟迟不发完 header/body，却卡住旧 worker 直到 shutdown 超时才释放。
- 不要忽略 keepalive_timeout：若客户端复用连接且 idle 时间接近 shutdown 时限，可能因 keepalive 超时先关闭连接，反而降低 shutdown 压力；但若 keepalive_timeout 过长（如 75 秒），而 shutdown 设为 30 秒，则旧 worker 仍需等满 30 秒才能退出，造成冗余等待。
-
配合日志验证效果：开启 error_log warn 级别，观察 reload 后是否有
worker process .* exited on signal 15（优雅退出）或exited on signal 9（被强制杀掉）。后者说明 timeout 不足或存在阻塞逻辑。
生产环境调优建议
首次上线建议分阶段验证：
- 先设为 60 秒，观察 1～2 次 reload 后的 access 日志与错误日志，确认无 499（客户端主动关闭）或 502/504 异常上升；
- 用 ab 或 wrk 模拟长请求（如 sleep=5s 的后端），触发 reload，抓包验证 TCP 连接是否自然 FIN；
- 逐步收窄至业务真实 P99+10 秒，并持续监控 worker 进程存活时间分布（可通过 /nginx_status 或 Prometheus + nginx-vts-exporter）；
- 在 conf.d/ 中单独定义该参数，避免全局污染，例如：
location /api/v2/ {
proxy_pass http://backend_v2;
worker_shutdown_timeout 90s;
}
