在日常 Node.js 服务端开发与部署中,很多人习惯直接使用 pm2 restart app 或者开启 --watch 依赖文件变动自动重启。
但在高并发生产环境中,这种粗暴的重启方式往往是重大生产事故的导火索:正在处理的请求被瞬间腰斩(客户端报 502 / Connection Reset),未完成的数据库事务产生孤儿脏数据,消息队列消费到一半未 ACK 导致死锁或重复投递。
本文将从操作系统信号机制到 Node.js 事件循环底层,系统性拆解 优雅停机(Graceful Shutdown) 与 零停机重载(Zero-Downtime Reload) 的工业级最佳实践。
一、为什么需要优雅退出?生产事故复盘
当我们执行 kill -9 <pid> 或默认重启命令时,操作系统会强制向进程发送 SIGKILL 信号,Node.js 运行时根本来不及执行任何清理逻辑就被瞬间抹杀。
1 2 3 4 5 6 7 8 9 10
| 常规暴力重启: [客户端请求中...] ──> [PM2 强杀旧进程 SIGKILL] ──> ❌ 客户端 502 Bad Gateway / 连接重置 ❌ 数据库事务中途断开,产生脏数据 ❌ Redis 连接池未释放,连接数暴涨
优雅退出 (Graceful Shutdown): [客户端请求中...] ──> [PM2 发送 SIGINT] ──> ✋ 停止接收新连接 (关闭监听端口) ──> ⏳ 继续处理完毕在途存量请求 ──> 🔌 关闭数据库/Redis 连接池 ──> 🏁 process.exit(0) 安全退出
|
要实现真正的生产级高可用,必须同时满足两个层面的要求:
- 应用层面(Graceful Shutdown):服务实例在收到退出指令时,先拒收新请求,把手上正在跑的请求全部消化干净,再关闭底层依赖资源,最后自尽;
- 编排层面(Zero-Downtime Reload):PM2 在 Cluster 集群模式下采用“滚动更新”策略:先拉起新进程并确认其完全健康就绪(Ready),再将流量切入,最后通知旧进程优雅退出。
二、PM2 的信号机制与关键配置
1. PM2 退出信号传递链路
当我们在终端执行 pm2 reload 或 pm2 stop 时,PM2 内部会触发如下生命周期:
- 发送通知信号:PM2 默认向子进程发送
SIGINT(可在配置中修改为 SIGTERM); - 等待优雅退出:PM2 开启内部倒计时,等待子进程自身执行清理并调用
process.exit(0); - 超时无情强杀:如果在规定的
kill_timeout 时间内子进程仍未退出,PM2 将直接发送 SIGKILL(强制物理抹杀)。
2. 致命的默认值:1600ms
PM2 默认的 kill_timeout 仅为 1600ms(1.6 秒)!
在稍微复杂的业务中,一个耗时稍长的大报表查询、外部第三方支付网关回调、或者大文件分片写入往往需要 3~5 秒。如果使用默认配置,哪怕你的代码写了优雅停机逻辑,1.6 秒一到依然会被 PM2 一刀切强杀。
因此,在 PM2 配置中显式调大 kill_timeout 是优雅停机生效的首要前提。
三、代码级实现:完整的优雅停机四步闭环
下面以标准的 HTTP 服务(兼容 Express / Koa / 原生 http)为例,实现工业级的停机处理逻辑。
1. 核心四步处理流程
1 2 3 4 5 6 7 8 9 10 11 12 13
| [收到 SIGINT / SIGTERM 信号] │ ▼ [第 1 步: 标记停机状态,并调用 server.close()] ──> 不再接收新的 TCP 连接 │ ▼ [第 2 步: 针对现有 Keep-Alive 空闲长连接进行断开] ──> 防止老客户端长连接霸占进程 │ ▼ [第 3 步: 消化完在途请求,等待 server.close() 回调] │ ▼ [第 4 步: 关闭数据库连接池、Redis 等基础设施] ──> process.exit(0)
|
2. 生产级优雅停机封装代码
创建 graceful-shutdown.js 模块:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
| const http = require('http');
function setupGracefulShutdown(server, options = {}) { const { onCleanup, timeout = 10000 } = options; let isShuttingDown = false;
const openSockets = new Set(); server.on('connection', socket => { openSockets.add(socket); socket.on('close', () => openSockets.delete(socket)); });
async function handleSignal(signal) { if (isShuttingDown) return; isShuttingDown = true; console.log(`\n[Graceful Shutdown] 收到 ${signal} 信号,准备安全停机...`);
const forceExitTimer = setTimeout(() => { console.error('[Graceful Shutdown] ⚠️ 停机超时,强制终止进程 (SIGKILL 兜底)!'); process.exit(1); }, timeout); forceExitTimer.unref();
server.close(async err => { if (err) { console.error('[Graceful Shutdown] 关闭 HTTP 监听端口出错:', err); process.exit(1); } console.log('[Graceful Shutdown] ✅ HTTP 服务已停止接收新请求,在途请求已处理完毕');
try { if (typeof onCleanup === 'function') { console.log('[Graceful Shutdown] 正在释放数据库/中间件资源连接池...'); await onCleanup(); console.log('[Graceful Shutdown] ✅ 外部资源连接池已安全关闭'); } console.log('[Graceful Shutdown] 🎉 优雅退出完毕,进程平稳退出'); process.exit(0); } catch (cleanupErr) { console.error('[Graceful Shutdown] 清理资源时发生异常:', cleanupErr); process.exit(1); } });
if (typeof server.closeIdleConnections === 'function') { server.closeIdleConnections(); } else { for (const socket of openSockets) { if (!socket._httpMessage) { socket.destroy(); } } } }
process.on('SIGINT', () => handleSignal('SIGINT')); process.on('SIGTERM', () => handleSignal('SIGTERM')); }
module.exports = { setupGracefulShutdown };
|
3. 在业务服务中接入
在你的应用入口(如 app.js 或 server.js)中:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
| const express = require('express'); const { setupGracefulShutdown } = require('./graceful-shutdown'); const db = require('./models/db');
const app = express();
app.get('/api/order', async (req, res) => { await new Promise(r => setTimeout(r, 2000)); res.json({ success: true, message: '订单处理完毕' }); });
const server = app.listen(3000, () => { console.log('HTTP 服务运行在端口 3000');
if (process.send) { process.send('ready'); } });
setupGracefulShutdown(server, { timeout: 8000, onCleanup: async () => { await db.closePool(); } });
|
四、PM2 集群模式与零停机重载配置
有了应用内部的优雅停机还不够,必须通过 PM2 的 Cluster 集群模式 与 就绪握手机制 实现滚动态热更新。
1. 标准 ecosystem.config.js 配置
在项目根目录下创建 PM2 配置文件:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
| module.exports = { apps: [ { name: 'my-production-app', script: './app.js', instances: 'max', exec_mode: 'cluster',
wait_ready: true, listen_timeout: 10000, kill_timeout: 8000, shutdown_with_message: false,
env_production: { NODE_ENV: 'production', PORT: 3000 } } ] };
|
2. 关键配置深度解析
| 配置项 | 作用与原理 |
|---|
exec_mode: 'cluster' | 利用 Node.js 原生 cluster 模块由 Master 进程反向代理分发连接,允许多个实例共用一个监听端口。 |
wait_ready: true | 极为关键! PM2 默认只要执行到 listen() 就认为启动成功。但很多服务在 listen() 之后还需要初始化数据库连接池、加载缓存字典等。配置该项后,PM2 会等你的代码执行 process.send('ready'),才确认新实例上线并切入流量! |
kill_timeout: 8000 | 给予旧进程 8 秒的充足时间处理完手头积压的请求并释放数据库连接,防止被提前强杀。 |
3. 正确的运维部署发布命令
1 2 3 4 5 6 7
| pm2 start ecosystem.config.js --env production
git pull npm install --production pm2 reload ecosystem.config.js --env production
|
💡 pm2 reload 与 pm2 restart 的本质区别:
pm2 restart:将所有实例瞬间全部杀掉,然后再批量拉起新实例。期间服务完全不可用,必有大片停机中断!pm2 reload:单实例逐个滚动更新。先启动 Instance 0,等待其发送 ready 握手信号切入流量后,再向旧的 Instance 0 发送 SIGINT 进行优雅停机;接着以此类推处理下一个实例,做到全程 0 毫秒停机中断!
五、生产环境四大典型暗坑与避坑策略
1. HTTP Keep-Alive 导致进程一直无法退出
在 HTTP/1.1 中,浏览器或反向代理(如 Nginx、CDN)会保持持久连接(Keep-Alive)。当调用 server.close() 时,Node.js 只会拒绝新建连接,但如果已建立的长连接一直空闲挂着不发请求,server.close 的回调永远不会触发!
- 解决之道:务必在调用
server.close() 时搭配调用 Node.js 18+ 的 server.closeIdleConnections(),主动断开所有处于空闲状态的 Keep-Alive 连接。
2. 长轮询与定时器悬挂事件循环
如果项目里存在 setInterval 没有执行 clearInterval,或者未设置 timer.unref(),Node.js 的事件循环队列永远不会清空,哪怕没有请求,进程也会赖着不退直到被 PM2 强杀。
- 解决之道:在优雅停机的清理回调中,逐一注销未完成的轮询定时器与后台定时任务。
3. Docker / K8s 容器环境下的 PID 1 信号丢失
当你在 Docker 中使用 CMD npm start 或 CMD node app.js 时,如果启动方式不当,Node.js 可能会以非 PID 1 进程运行(前面套了一层 shell),或者作为 PID 1 却无法处理信号(Linux 内核默认不为 PID 1 安装默认信号处理程序)。容器收到 docker stop 时发送的 SIGTERM 根本传递不到 Node 进程!
- 解决之道:
- 使用 exec 格式的 Dockerfile 指令:
CMD ["node", "app.js"]; - 或者引入小型轻量 init 系统,如
tini:ENTRYPOINT ["/sbin/tini", "--"]。
4. 为什么不能只靠全局变量 isAppRunning = false 拦截?
有些开发者尝试在 Express 中间件里通过判断一个全局变量来返回 503 Service Unavailable。这种方式不仅增加了每个请求的处理损耗,而且对客户端依然返回了错误响应,算不上真正的平滑重载。
- 正确做法:依靠
server.close() 让内核层停止接收 TCP 握手,同时依靠 PM2 Cluster 或上层 Nginx 的健康检查与重试机制,将新请求平稳过渡到已经就绪的新进程。
六、总结与自查清单
生产环境的高可用往往就隐藏在这些细微的停机重启细节之中:
1 2 3 4 5 6 7 8
| [生产就绪自查清单] [ ] 1. 代码中是否监听了 SIGINT 与 SIGTERM 信号? [ ] 2. 停机流程是否遵循:停止接客 -> 处理在途 -> 关闭连接池 -> 安全退出的顺序? [ ] 3. 是否正确处理了 Keep-Alive 闲置连接并设置了兜底超时定时器? [ ] 4. PM2 ecosystem.config.js 中是否配置了 exec_mode: 'cluster'? [ ] 5. kill_timeout 是否配置充足 (推荐 5000ms ~ 10000ms)? [ ] 6. 是否开启了 wait_ready: true 并在服务完全就绪后上报 process.send('ready')? [ ] 7. 部署脚本中是否严格执行 pm2 reload 而非 pm2 restart?
|
参考与扩展阅读