Node.js 服务怎么优雅退出:别让部署变成一阵 502
发布新版本时,进程管理器给旧进程发了 SIGTERM。如果应用当场退出,正在处理的请求可能中断;如果永远不退出,部署又会卡住。优雅退出不是“收到信号等几秒”这么简单,而是停止接新活、给旧活有限时间收尾,再交还资源。
示例使用 Node.js 20+ 的内置 HTTP 模块,保存为 server.mjs:
import http from 'node:http';
let draining = false;
const server = http.createServer((req, res) => {
if (req.url === '/ready') {
res.writeHead(draining ? 503 : 200);
return res.end(draining ? 'draining' : 'ready');
}
if (draining) {
res.writeHead(503, { 'Connection': 'close' });
return res.end('shutting down');
}
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('hello\n');
});
server.listen(3000, '127.0.0.1', () => console.log('listening on 3000'));
function shutdown(signal) {
if (draining) return;
draining = true;
console.log(`${signal}: draining`);
const deadline = setTimeout(() => {
console.error('shutdown deadline exceeded');
server.closeAllConnections();
process.exit(1);
}, 10_000);
deadline.unref();
server.close((err) => {
clearTimeout(deadline);
if (err) { console.error(err); process.exitCode = 1; }
// 真实应用此处还要等待数据库连接池、消费者、遥测等资源关闭。
});
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
执行 node server.mjs,另开终端访问 curl -i http://127.0.0.1:3000/ready;然后在服务终端按 Ctrl+C。这个示例监听本机,不直接暴露公网;容器中需要根据网络架构调整监听地址。
看起来简单,坑都在边界
server.close() 停止接受新连接并等待 HTTP 连接处理;关闭过程的具体连接行为与 Node 版本有关。强制关闭应有截止时间,并理解它会中断仍在进行的请求。WebSocket 等升级后的连接需要单独追踪和关闭,closeAllConnections() 不负责所有升级连接。数据库池、后台队列和定时任务也需要按各自 API 停止;示例不假装已经做完这些。
生产负载均衡器需要先把实例标记为不再就绪,再留出路由配置传播时间,然后停止接收连接;不同平台的健康检查和终止顺序不同。容器编排的终止宽限期必须大于应用关闭期限,否则还没收尾就会被强杀。对于长任务,应设计持久化队列、重试和幂等,而不是寄希望于无限延长关机时间。
验证时用慢请求模拟进行中的工作,发送 SIGTERM,并检查请求是否完成、readiness 是否变化、超时后进程是否退出。还要测连续两次信号、数据库关闭失败和长连接;不要只看本机 hello world。
上线前的实测步骤
为测试服务临时添加一个需要几秒才完成的受控端点;发起请求后立即发送 SIGTERM,记录请求结果和进程退出时间。再模拟一个永不完成的请求,确认超过截止时间会退出。不要用真实生产写操作做这个实验。检查平台的终止宽限期是否覆盖路由摘除、应用排空和资源关闭的总时间。
此外,示例没有处理队列消费者:真实服务应先停止拉取新任务,等待已领取任务完成或按队列协议释放,避免两个实例同时处理同一任务。强制退出可能发生在写入中途,因此业务仍需要幂等和恢复机制;优雅退出能降低中断概率,不能保证所有操作绝不丢失。