worker_shutdown_timeout 是 Gunicorn 控制 worker 优雅关闭的超时时间，默认30秒；它确保正在处理的请求完成后再退出，避免502等错误，但不管理网络连接或阻止新请求，需配合反向代理健康检查等机制实现平滑重启。
worker_shutdown_timeout 是 Gunicorn 等 WSGI 服务器中控制工作进程（worker）在接收到关闭信号后，等待当前请求完成再退出的超时时间。它本身不直接处理连接，而是为“优雅关闭”提供关键的时间窗口——让正在处理的请求跑完，避免强制中断导致客户端收到错误（如 502 Bad Gateway 或连接重置）。
明确它的作用边界
这个参数只影响 worker 进程自身的生命周期，不接管网络层连接（如 TCP keep-alive、TLS 握手、HTTP/2 流）。它不能：
- 阻止新请求被负载均衡器转发到即将关闭的 worker（需配合外部健康检查或预关闭通知）
- 主动断开空闲长连接（如 Server-Sent Events、WebSocket），这些需应用层自行管理
- 替代反向代理（如 Nginx）的
proxy_read_timeout或proxy_send_timeout
设置合理值的关键依据
值太小 → 请求被强行终止；值太大 → 重启拖慢，资源释放延迟。建议按以下方式估算：
- 查看生产环境 P95/P99 响应耗时（例如 800ms），加上少量缓冲（如 +200ms）
- 若存在已知长任务（如文件导出、报表生成），设为该任务最坏情况耗时（但建议改用异步队列，而非阻塞 worker）
- 常见安全范围：10–30 秒。Gunicorn 默认是 30 秒，多数 Web API 场景设为
--worker-shutdown-timeout 15更平衡
必须配合的外部机制
单靠 worker_shutdown_timeout 无法实现真正平滑。需组合以下措施：
-
反向代理健康检查：Nginx 配置
health_check或使用max_fails=1 fail_timeout=10s，在 worker 开始关闭时快速将其从 upstream 摘除 -
启动预热与就绪探针：新 worker 启动后，先通过
/healthz?ready=1等端点确认可服务，再通知 LB 加入流量 -
应用层清理钩子：在 Python 中监听
SIGTERM，关闭数据库连接池、取消 pending 的 asyncio tasks、清空本地缓存等（Gunicorn 提供on_exit和pre_request钩子）
验证是否生效的小技巧
不要只看日志里有没有 “Shutting down…”。实测更可靠：
- 用
curl -v http://your-app/long-endpoint?sleep=12（模拟 12 秒请求），同时发kill -TERM $(pgrep -f 'gunicorn.*wsgi') - 观察该请求是否成功返回（而非 connection refused / 502），且 worker 进程在约 12–15 秒后才退出（
ps aux | grep gunicorn） - 检查 access log 中该请求状态码是否为 200，而不是 500 或缺失
