Node.js 优雅停机与健康检查实战

发布/重启时 K8s 或 PM2 发 SIGTERM
进程没处理 → 立即退出
在途请求被掐断 → 用户看到 502/重置
数据库写入半途而废 → 数据不一致

1. 停止接收新请求
2. 排空已接收的在途请求
3. 释放外部资源（数据库连接、队列）
4. 兜底超时后强制退出

function shutdown(reason) {
  console.log(`收到 ${reason}，开始优雅停机`);
  // 此处安排：停新请求 → 排空 → 释放 → 退出
}

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

只注册一次 → 避免多次触发重复清理
幂等处理   → 第二个信号直接 process.exit(1)
带原因日志 → 便于排查谁发的信号

const server = http.createServer(handler);

process.on('SIGTERM', () => {
  server.close(() => {
    console.log('所有连接已关闭，退出');
    process.exit(0);
  });
});

server.listen(3000);

const server = http.createServer(handler);
server.keepAliveTimeout = 5000;      // 空闲 5 秒断开
server.headersTimeout = 8000;

process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
  // 强关空闲 keep-alive：遍历连接调用 end/destroy
  for (const socket of server.connections ?? []) {
    if (socket.idleTimeout === undefined) socket.end();
  }
});

正常路径 → server.close() 等排空 → exit(0)
兜底路径 → 超时强制 destroy 连接 → exit(0)

let inflight = 0;
const server = http.createServer(async (req, res) => {
  inflight++;
  try {
    await handle(req, res);
  } finally {
    inflight--;
    if (isShuttingDown && inflight === 0) process.exit(0);
  }
});

let isShuttingDown = false;
const server = http.createServer((req, res) => {
  if (isShuttingDown) {
    res.writeHead(503, { 'Retry-After': '5' });
    res.end('正在停机，请稍后重试');
    return;
  }
  handle(req, res);
});

process.on('SIGTERM', () => {
  isShuttingDown = true;
  const timer = setTimeout(() => {
    console.error('排空超时，强制退出');
    process.exit(1);
  }, 30 * 1000);
  timer.unref();           // 定时器不阻塞进程退出
  server.close(() => process.exit(0));
});

数据库连接池   → 关闭空闲连接
消息队列消费者 → 停止消费
定时任务       → clearInterval
WebSocket 连接 → 通知后关闭

liveness（存活）   → 进程活着就行，挂了重启
readiness（就绪）  → 依赖就绪、能接流量，没就绪不发流量

// 只检查进程存活
app.get('/healthz', (req, res) => {
  res.json({ status: 'ok', pid: process.pid });
});

// 检查关键依赖（DB、Redis、队列）
app.get('/readyz', async (req, res) => {
  try {
    await db.ping();
    await redis.ping();
    res.json({ status: 'ready' });
  } catch (err) {
    res.status(503).json({ status: 'not-ready', reason: err.message });
  }
});

// 停机时 readiness 立即返回 503，调度系统先摘流量
let isShuttingDown = false;
app.get('/readyz', (req, res) => {
  if (isShuttingDown) return res.status(503).json({ status: 'stopping' });
  res.json({ status: 'ready' });
});

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          livenessProbe:
            httpGet: { path: /healthz, port: 3000 }
            initialDelaySeconds: 10
            periodSeconds: 10
          readinessProbe:
            httpGet: { path: /readyz, port: 3000 }
            initialDelaySeconds: 5
            periodSeconds: 5
          terminationGracePeriodSeconds: 30

1. K8s 更新 Pod 状态为 Terminating
2. readiness 探针失败 → 从 Service 摘流量
3. K8s 发 SIGTERM
4. 进程优雅排空
5. 超过 terminationGracePeriodSeconds → SIGKILL

lifecycle:
  preStop:
    exec:
      command: ["/bin/sh", "-c", "sleep 5"]

module.exports = {
  apps: [{
    name: 'web-api',
    script: './dist/index.js',
    instances: 2,
    kill_timeout: 15000,   // 最多等 15 秒优雅退出
    listen_timeout: 3000,  // 等待新进程监听就绪
  }],
};

// 依赖初始化完成后
process.send('ready');   // 告诉 PM2：我准备好了

pm2 reload → 对旧实例发 SIGINT/SIGTERM
进程监听到信号 → 排空 → 退出
新实例启动 → 依赖就绪 → 发 ready → 接流量