如何在 Node.js API 中实现优雅关闭（部署时零请求丢失）

2026西湖龙井茶官网DTC发售：茶农直供，政府溯源防伪到农户家 

在没有正确实现优雅关闭的情况下部署一个 Node.js API，就如同直接拔掉正在运行的服务器的电源线。每一次滚动部署、每一次 Kubernetes Pod 重启、每一次 Docker 容器停止——如果你的应用忽略了 SIGTERM 信号，就会导致正在进行中的请求被丢弃、数据库事务损坏，并让客户端面对 502 错误。

本指南涵盖了在 2026 年为 Node.js API 正确实现优雅关闭所需的一切内容——从 SIGTERM 信号处理的基础知识，到长连接排空、数据库清理、Kubernetes 配置，以及经过生产环境验证的最佳实践模式。

为什么在 2026 年优雅关闭依然至关重要

现代 API 运行在编排环境中。无论是 Kubernetes、Docker Swarm、ECS，还是简单的 docker compose down 命令——它们都使用相同的关闭流程：

1. 容器接收到 SIGTERM 信号（礼貌性停止请求）
2. 编排器等待 terminationGracePeriodSeconds（Kubernetes 默认为 30 秒）
3. 如果容器仍在运行：则会收到 SIGKILL 信号（强制终止，无法执行清理操作）

常见的两种失败模式如下：

模式一 —— 完全忽略： 应用根本不监听 SIGTERM 信号。Docker 等待 10 秒后直接发送 SIGKILL 信号，所有正在进行的请求都会被中断。

模式二 —— 立即退出： 应用在收到 SIGTERM 信号后立即调用 process.exit(0)。结果相同——请求被丢弃，数据库连接在查询中途被切断。

其代价是：在一个每秒处理 1,000 个请求的繁忙 API 上进行滚动部署时，每次 10 秒的硬性关闭会导致约 10,000 个请求失败。若同时滚动更新 5 个 Pod，则每次部署会产生 50,000 个错误。

最小但正确的实现方式

以下是基础实现——每个 Node.js API 都应包含以下代码：

// server.js
import express from 'express';

const app = express();

app.get('/api/health', (req, res) => res.json({ status: 'ok' }));

app.get('/api/data', async (req, res) => {
  const data = await db.query('SELECT * FROM items LIMIT 100');
  res.json(data);
}