用途:在服务器、Worker 与长驻进程中实现优雅关闭,确保部署或重启时不丢失在途请求、后台任务可完成或检查点保存、外部资源干净释放,并以合适状态码退出。适用于 Kubernetes、ECS、Docker Compose 等编排环境及 systemd、PM2 等进程管理器中的零停机部署。
主要能力与用法:
- 启动时注册 SIGTERM 与 SIGINT 处理器,用 isShuttingDown 标志防止重复关闭。
- 收到信号后立即停止接受新工作:HTTP 调用 server.close(),队列 Worker 停止轮询。
- 带硬性截止时间排空在途工作,DRAIN_TIMEOUT_MS 应小于编排器的终止宽限期(如 K8s terminationGracePeriodSeconds 默认 30s,排空设 25s),超时强制 process.exit(1)。
- 提供就绪与存活探针:/readyz 在关闭期间返回 503,/healthz 在监听器可用时保持 200;健康路由须注册在拒绝中间件之前。
- 跟踪活跃连接,用 once 守卫同时监听 finish 与 close 事件,客户端中断时也能正确递减计数。
- 退出前 flush 日志、指标、队列等缓冲,并用 process.exit(0) 表示正常、exit(1) 表示超时或错误。
框架注意:FastAPI 配合 Uvicorn 时由 Uvicorn 负责 SIGTERM 与请求排空及 --timeout-graceful-shutdown,不应替换其信号处理器,lifespan shutdown 仅用于释放资源,且发生在排空之后。
限制:WebSocket/SSE 需应用层关闭帧;Node.js cluster 各 Worker 需独立处理信号;Heroku、Railway 等平台宽限期较短,需调整排空超时;本技能不替代环境相关验证、测试与专家评审。配置与代码示例以原文为准。