如何设置worker_shutdown_timeout以实现负载均衡在重载时平滑切换连接？

本文共计840个文字，预计阅读时间需要4分钟。

当需要让Nginx在重载配置时平滑切换，可以使用以下命令：

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 { ... }

错误写法：放在 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 无法接收连接