Node.js 多进程与 PM2 进程管理实战

// 这段 JSON 解析会阻塞 3 秒，期间所有请求全部挂起
const data = JSON.parse(readBigFileSync('/tmp/huge.json'));

import cluster from 'node:cluster';
import http from 'node:http';
import { cpus } from 'node:os';

if (cluster.isPrimary) {
  const count = cpus().length; // 主进程：按 CPU 核数 fork
  console.log(`主进程 ${process.pid} 启动，fork ${count} 个 worker`);
  for (let i = 0; i < count; i++) cluster.fork();
  cluster.on('exit', (worker) => {
    console.log(`worker ${worker.process.pid} 退出`);
    cluster.fork(); // 崩溃自动拉起新 worker
  });
} else {
  // 工作进程：业务代码，各进程共享同一端口
  http.createServer((req, res) => {
    res.end(`worker ${process.pid} 处理 ${req.url}`);
  }).listen(3000);
}

// worker 内发消息给主进程
process.send({ type: 'report', pid: process.pid });

// 主进程广播给所有 worker
for (const id in cluster.workers) {
  cluster.workers[id].send({ type: 'shutdown-now' });
}

主进程先创建 socket 监听 3000
每个 worker fork 时继承该 socket 的文件描述符
内核把连接分发给不同 worker

连接 A → worker 1
连接 B → worker 2
连接 C → worker 3
连接 D → worker 1（循环）

hash(clientId) % workerCount → 固定的 worker

npm i -g pm2            # 安装
pm2 start app.js        # 启动单进程
pm2 start app.js -i 4   # 启动 4 个进程（集群模式）
pm2 status              # 查看状态
pm2 stop app && pm2 delete app   # 停止并从 PM2 移除

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'web-api',
    script: './dist/index.js',
    instances: 'max',            // 自动按 CPU 核数
    exec_mode: 'cluster',        // cluster 模式（非 fork）
    max_memory_restart: '512M',  // 内存超限自动重启
    autorestart: true,           // 崩溃自动重启
    env: { NODE_ENV: 'production', PORT: 3000 },
  }],
};

pm2 start ecosystem.config.js

pm2 logs web-api        # 实时日志（可加 --lines 200）
pm2 monit              # 终端监控面板
pm2 reload web-api     # 零停机重载（仅集群模式）
pm2 restart web-api    # 有停机的重启
pm2 save               # 保存进程列表，开机自启
pm2 startup            # 生成开机自启脚本

PM2 Daemon（守护）
 ├─ worker 1（业务）  崩溃 → 立即 fork 新 worker
 ├─ worker 2（业务）
 └─ worker 3（业务）

// 配置节流：1 分钟内最多重启 10 次，避免疯狂重启
module.exports = {
  apps: [{
    name: 'web-api',
    script: './dist/index.js',
    instances: 2,
    max_restarts: 10,          // 1 分钟内最大重启次数
    restart_delay: 3000,       // 重启间隔 3 秒
    exp_backoff_restart_delay: 200, // 指数退避重启
  }],
};

module.exports = {
  apps: [{
    name: 'web-api',
    script: './src/index.js',
    watch: ['src'],            // 监听目录变化自动重启
    ignore_watch: ['node_modules', 'dist'],
    watch_delay: 1000,         // 防抖 1 秒
  }],
};

pm2 reload web-api

// 业务代码里监听退出信号，先排空再退出
process.on('SIGINT', () => {
  server.close(() => process.exit(0)); // 停止接收新连接，排空在途
});

// PM2 侧配合
module.exports = {
  apps: [{
    name: 'web-api',
    script: './dist/index.js',
    instances: 2,
    kill_timeout: 5000,       // 给 worker 5 秒处理退出
    listen_timeout: 3000,     // 等新 worker 监听就绪
    wait_ready: true,         // 业务主动发 ready 信号
  }],
};

process.send('ready'); // 依赖初始化完成后通知 PM2

git pull → npm ci → 构建 dist
pm2 reload web-api          # 逐实例滚动，零停机
pm2 save                    # 保存最新列表
curl 健康检查端点            # 验证全绿

module.exports = {
  apps: [{
    name: 'web-api',
    script: './dist/index.js',
    out_file: '/var/log/web-api/out.log',    // stdout
    error_file: '/var/log/web-api/err.log',  // stderr
    log_file: '',                            // 禁用合并日志
    merge_logs: true,                        // 多实例日志合并
    time: true,                              // 每行加时间戳
  }],
};

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 7       # 保留 7 份
pm2 set pm2-logrotate:compress true
pm2 set pm2-logrotate:rotateInterval '0 0 * * *'   # 每天零点

pm2 monit   # 交互式面板：CPU、内存、重启次数