worker_shutdown_timeout是nginx 1.19.10+引入的优雅重载关键参数，用于限定旧worker在reload时继续处理已建立连接的最大时长（如30s），避免长连接被强制中断，须配置在main块中，不可置于events或http内。
要让 Nginx 在重载配置（nginx -s reload）时，负载均衡流量平滑切换、避免连接中断或 worker 长时间卡在 shutting down 状态，关键之一就是合理配置 worker_shutdown_timeout。它不直接控制负载均衡逻辑，但决定了旧 worker 进程能“优雅等待”多久才强制退出——这对长连接（如 WebSocket、HTTP/2 流、Keep-Alive 慢客户端）尤其重要。
worker_shutdown_timeout 的作用机制
当执行 reload 时，Master 进程会启动新 worker，同时向旧 worker 发送 QUIT 信号，进入优雅关闭流程。此时旧 worker 不再接受新连接，但会继续处理已建立的活跃连接（包括后端 upstream 的长连接、客户端未完成的请求等）。worker_shutdown_timeout 就是这个“继续服务”的最长时限。超时后，即使连接尚未自然结束，worker 也会强制退出。
若该值缺失或设为 0（默认无值），旧 worker 可能无限期等待，导致：
- worker 进程数虚高，资源占用持续上升
- 部分连接被异常中止（如 TCP RST），影响用户体验
- 负载均衡节点看似在线，实则无法及时释放连接，干扰上游健康检查与故障转移
推荐配置值与依据
不是越长越好，也不是越短越安全，需结合业务连接特征设定：
-
普通 HTTP/1.1（短连接为主）：设为
5s～15s即可。绝大多数请求已在几秒内完成，留出缓冲应对偶发延迟 -
启用了 Keep-Alive 或大量长轮询：建议
30s～60s。覆盖典型空闲连接超时窗口（如浏览器默认 keepalive timeout 通常为 5～75 秒） -
WebSocket / gRPC / HTTP/2 流式服务：必须设为
1m～5m，甚至更长（如10m）。这类连接生命周期由业务决定，不能被 reload 强制打断 -
Ingress Nginx（K8s 场景）：生产环境推荐
3m起步，并配合upstream的keepalive_timeout和proxy_next_upstream_timeout统一收敛
配置位置与语法
该指令只能放在 main 块（全局块），不可写在 events 或 http 内：
正确写法：
user nginx;
worker_processes auto;
worker_shutdown_timeout 3m; # ← 放在这里
pid /run/nginx.pid;
<p>events {
worker_connections 1024;
}</p><p>http {
...
}</p>
错误写法：放在 http 或 server 块内将被忽略，Nginx 启动时也不会报错，容易误以为生效。
配合其他关键参数协同生效
单靠 worker_shutdown_timeout 不足以保障平滑切换，还需检查以下配置是否匹配：
-
proxy_http_version 1.1;+proxy_set_header Connection '';：确保 upstream 连接复用开启，减少 reload 时新建连接压力 -
keepalive 32;（在upstream块中）：设置与后端的长连接池大小，避免每次请求都重建连接 -
proxy_next_upstream error timeout http_502 http_503 http_504;：增强容错，当某 worker 正在 shutdown 导致短暂不可用时，请求可自动转发至其他健康 worker -
worker_rlimit_nofile与系统ulimit -n匹配：防止因文件描述符不足导致新 worker 无法接收连接
