PM2 优雅退出与零停机平滑重载实践

在日常 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) 安全退出

要实现真正的生产级高可用,必须同时满足两个层面的要求:

  1. 应用层面(Graceful Shutdown):服务实例在收到退出指令时,先拒收新请求,把手上正在跑的请求全部消化干净,再关闭底层依赖资源,最后自尽;
  2. 编排层面(Zero-Downtime Reload):PM2 在 Cluster 集群模式下采用“滚动更新”策略:先拉起新进程并确认其完全健康就绪(Ready),再将流量切入,最后通知旧进程优雅退出。

二、PM2 的信号机制与关键配置

1. PM2 退出信号传递链路

当我们在终端执行 pm2 reload 或 pm2 stop 时,PM2 内部会触发如下生命周期:

  1. 发送通知信号:PM2 默认向子进程发送 SIGINT(可在配置中修改为 SIGTERM);
  2. 等待优雅退出:PM2 开启内部倒计时,等待子进程自身执行清理并调用 process.exit(0);
  3. 超时无情强杀:如果在规定的 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');

/**
* 为 HTTP 服务挂载生产级优雅退出机制
* @param {http.Server} server HTTP 服务器实例
* @param {Object} options 配置项
* @param {Function} options.onCleanup 自定义基础设施清理回调 (如关闭 DB/Redis)
* @param {number} options.timeout 超时兜底强杀时间 (毫秒),默认 10000ms
*/
function setupGracefulShutdown(server, options = {}) {
const { onCleanup, timeout = 10000 } = options;
let isShuttingDown = false;

// 记录所有活跃的底层 Socket 连接 (处理 HTTP Keep-Alive 问题)
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} 信号,准备安全停机...`);

// 1. 设置超时兜底防死锁定时器:防止某些死循环或挂起连接导致进程永久假死
const forceExitTimer = setTimeout(() => {
console.error('[Graceful Shutdown] ⚠️ 停机超时,强制终止进程 (SIGKILL 兜底)!');
process.exit(1);
}, timeout);
forceExitTimer.unref(); // 不阻碍事件循环正常退出

// 2. 停止接收新的连接请求
server.close(async err => {
if (err) {
console.error('[Graceful Shutdown] 关闭 HTTP 监听端口出错:', err);
process.exit(1);
}
console.log('[Graceful Shutdown] ✅ HTTP 服务已停止接收新请求,在途请求已处理完毕');

// 3. 执行数据库连接池、MQ、Redis 等外部资源清理
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);
}
});

// 4. Node.js 18.2.0+ 原生提供 server.closeIdleConnections() 断开空闲 Keep-Alive 连接
if (typeof server.closeIdleConnections === 'function') {
server.closeIdleConnections();
} else {
// 兼容低版本 Node:针对未处于活跃请求中的 idle socket 优雅销毁
for (const socket of openSockets) {
// 如果 socket 没有在处理请求,则销毁
if (!socket._httpMessage) {
socket.destroy();
}
}
}
}

// 监听常见的终止信号
process.on('SIGINT', () => handleSignal('SIGINT')); // PM2 reload / Ctrl+C
process.on('SIGTERM', () => handleSignal('SIGTERM')); // Kubernetes / Docker 默认信号
}

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) => {
// 模拟一个耗时 2 秒的写库业务
await new Promise(r => setTimeout(r, 2000));
res.json({ success: true, message: '订单处理完毕' });
});

const server = app.listen(3000, () => {
console.log('HTTP 服务运行在端口 3000');

// 【极其关键】通知 PM2 新进程已就绪,可以安全切入流量
if (process.send) {
process.send('ready');
}
});

// 挂载优雅退出逻辑
setupGracefulShutdown(server, {
timeout: 8000, // 8 秒兜底超时
onCleanup: async () => {
// 关闭 MySQL / MongoDB / Redis 连接池
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', // 或者指定核心数如 4
exec_mode: 'cluster', // 开启集群模式,多实例共享同端口

// 零停机核心握手配置
wait_ready: true, // 等待应用内部发出 process.send('ready') 才视为就绪
listen_timeout: 10000, // 等待应用就绪的超时时间 (10秒)

// 优雅退出时长配置
kill_timeout: 8000, // 留给应用执行清理的缓冲时长 (8秒),必须大于应用内部清理所需时长
shutdown_with_message: false, // 设置为 false 保证发送标准 POSIX 信号 (SIGINT)

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

# 生产更新代码后,千万不要用 pm2 restart!必须使用 reload:
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?

参考与扩展阅读


PM2 优雅退出与零停机平滑重载实践
https://bubao.github.io/posts/84550d96.html
作者
一念
发布于
2021年11月26日
许可协议