企业官网建设流程全解析

• 文档
• 教程
• 后端

导读

在 Kubernetes 等容器化运行环境中，容器的创建与销毁是家常便饭——无论是滚动更新、节点迁移还是资源调度，都可能随时向进程发送 SIGTERM 信号。本指南以 sections/docker/graceful-shutdown.basque.md（及其英文原版 sections/docker/graceful-shutdown.md）为核心，系统讲解 Node.js 应用优雅关闭的完整方法论：如何在宽限期内排空存量请求、拒绝新请求、释放资源并记录关键日志，同时给出CMD ["node", ...]、TINI 入口点等可直接落地的 Dockerfile 写法与反模式警示。读完本文，你将掌握一套可在生产环境复用的优雅关闭设计模板。

为什么"优雅关闭"在容器世界里成了必修课

在传统虚拟机或裸机部署中，进程往往"长寿"，优雅关闭只是锦上添花。但在 Docker 化的运行环境（如 Kubernetes）中，情况完全不同：容器频繁地诞生和消亡。这不仅仅发生在代码抛错时，更多时候是出于合理原因——容器迁移、用新版本替换旧版本、资源重新调度等。

这一过程的实现方式是：编排平台向进程发送一个SIGTERM 信号，并给出一段宽限期（grace period）。Kubernetes 的默认宽限期为30 秒（可通过terminationGracePeriodSeconds调整）。这意味着开发者必须在有限的时间内完成两件事：

1. 妥善处理正在执行中的请求（让它们完整返回，而不是被硬生生掐断）；
2. 完成资源清理（数据库连接池、消息队列消费者、文件句柄、定时器等）。

如果处理不当，进程直接退出，成千上万的用户将得不到任何响应——这正是 README.md 第 8.6 条"Shutdown smartly and gracefully"所强调的后果："Dying immediately means not responding to thousands of disappointed users（立即死亡意味着无法响应成千上万失望的用户）"。

优雅关闭的五个关键环节

实践层面，优雅关闭远比"在process.on('SIGTERM')里写几行代码"复杂。它是一场多方协调的编排，至少需要串起以下环节：

1. 通知负载均衡器：通过健康检查（health-check）接口，告诉 LoadBalancer"应用已不再接受新流量"。此时应将健康检查端点切换为失败状态，让新请求被路由到其他实例。
2. 等待存量请求完成：已进入应用、正在处理中的请求必须被允许跑完，而不是立即中断。
3. 拒绝新请求：在宽限期内，任何新到达的请求都应被明确拒绝或直接忽略，避免在半关闭状态下产生脏数据。
4. 清理资源：关闭数据库连接池、消息队列订阅、定时任务、日志流等所有外部资源。
5. 记录收尾日志：在进程退出前，输出包含关闭原因、耗时、未完成请求数等信息的日志，便于事后排障。

此外还有一个常被忽略的细节：Keep-Alive 长连接。如果启用了 HTTP keep-alive，客户端会复用已有的 TCP 连接，而服务端此时正准备关闭——必须通知客户端"请建立新连接"，否则客户端会一直复用一条即将失效的连接。像 Stoppable 这样的库可以极大地帮助实现这一点：它在收到关闭信号后停止接受新连接，等待存量连接自然结束，必要时还能主动关闭空闲的 keep-alive 连接。

正确起点：让 Node.js 成为 PID1 根进程

优雅关闭的前提是代码能收到 SIGTERM。而信号能否送达，取决于容器启动方式。第一个正确姿势是：直接用node命令启动应用，让 Node.js 成为容器内的根进程（PID1）：

FROM node:12-slim # 构建逻辑在此处 CMD ["node", "index.js"] # 上面这一行使 Node.js 成为根进程（PID1）

以 exec 形式（JSON 数组）直接调用node，Node 进程就会直接继承容器收到的 SIGTERM，从而触发你注册的process.on('SIGTERM')处理器。这一做法与 bootstrap-using-node.md 中"Bootstrap using Node"的建议完全一致：不要用npm start启动应用。

进阶方案：用 TINI 作为入口点转发信号

如果你的应用会派生子进程（如使用child_process、集群模块等），情况会更复杂：一旦 PID1 进程意外退出，子进程不会被正确清理，宿主机会残留僵尸进程。此时推荐引入 TINI（Tiny Process Manager）作为容器入口点，由它充当 PID1、负责信号转发与子进程回收：

FROM node:12-slim # 构建逻辑在此处 ENV TINI_VERSION v0.19.0 ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini /tini RUN chmod +x /tini ENTRYPOINT ["/tini", "--"] CMD ["node", "index.js"] # 现在 Node 成为 TINI 的子进程，TINI 扮演 PID1 角色

这里的关键在于ENTRYPOINT ["/tini", "--"]：--之后的内容（即CMD）会作为子命令交给 TINI 托管。TINI 作为 PID1 会正确地接收并向子进程转发信号，同时负责在子进程退出后回收僵尸进程，这是npm start方案完全做不到的。

反模式：用npm start启动进程

最容易踩的坑是下面这种写法：

FROM node:12-slim # 构建逻辑在此处 CMD ["npm", "start"] # 现在 Node 成为 npm 的子进程，且收不到信号

为什么这是反模式？因为npm是一个额外的中间进程，它默认不会把收到的信号转发给应用。结果是：容器收到 SIGTERM 后，你的 Node 应用根本无从感知，自然也就失去了优雅关闭的机会，正在处理的请求和数据可能一并丢失。

bootstrap-using-node.md 给出了更完整的证据——用npm start启动时，进程树会变成三层：

$ ps falx UID PID PPID COMMAND 0 1 0 npm 0 16 1 sh -c node server.js 0 17 16 \_ node server.js

在npm之下还嵌套了一个sh -cshell 层。这三个进程除了增加开销外没有任何收益，还会让信号传递链路变得脆弱。同理，CMD "node server.js"（单个字符串形式）也会启动 bash/ash shell 来执行命令，效果与npm start几乎一样，同样应避免。README 第 8.2 条也明确建议：使用CMD ['node','server.js']启动应用，避免使用不传递 OS 信号的 npm 脚本，以防止子进程、信号处理、优雅关闭及僵尸进程方面的连锁问题。

仓库内的完整参考：一个可运行的多阶段构建示例

本仓库在 sections/examples/dockerfile/Dockerfile 中提供了一个完整的多阶段构建示例，可作为上述原则的落地范本。其运行阶段的关键片段如下：

# 运行阶段 FROM node:14.8.0-alpine as app USER node EXPOSE 3000 WORKDIR /home/node/app COPY --chown=node:node --from=build package.json package-lock.json ./ COPY --chown=node:node --from=build node_modules ./node_modules COPY --chown=node:node --from=build dist ./dist RUN npm prune --production && npm cache clean --force # ✅ 参见第 8.2 条：避免使用 npm start CMD [ "node", "dist/app.js" ]

注意三处细节，它们与优雅关闭直接相关：

• CMD [ "node", "dist/app.js" ]：采用 exec 形式直接调用 node，确保 Node 成为 PID1 并接收 SIGTERM；
• USER node：以非特权用户运行（见 generic-tips.md 中"Use unprivileged containers"原则），减小攻击面；
• npm prune --production：在生产镜像中清除开发依赖，缩小镜像与攻击面（对应 README 第 8.5 条）。

配合的 src/app.ts 是一个基于 Express 的最小 HTTP 服务，监听 3000 端口——读者可以以此为起点，加入process.on('SIGTERM')处理器和 Stoppable 之类的连接管理库，改造成完整的优雅关闭示例。

关闭阶段全景图

下图清晰地展示了从"编排平台决定终止容器"到"进程最终退出"的完整阶段流转，涵盖健康检查失效、存量请求排空、资源清理等关键节点：

Kubernetes 中 Node.js 优雅关闭的完整阶段流程图

最小可运行的优雅关闭代码骨架

综合以上原则，一个生产级的优雅关闭骨架应包含如下要点（伪代码示意，读者可结合自己的框架实现）：

const server = require('http').createServer(app); function shutdown(signal) { console.log(`${signal} 已收到，开始优雅关闭`); server.close(() => { // 1. 停止接收新连接 // 2. 等待存量请求完成（可用 Stoppable 强化 keep-alive 处理） // 3. 清理数据库连接、消息队列、定时器等资源 console.log('所有资源已清理，进程退出'); process.exit(0); }); // 兜底：宽限期（如 30s）耗尽仍未完成，则强制退出 setTimeout(() => process.exit(1), 30000).unref(); } process.on('SIGTERM', shutdown); process.on('SIGINT', shutdown);

要点解读：

• 同时监听SIGTERM（编排平台发送）与SIGINT（Ctrl+C 等场景）；
• server.close()之后必须等待回调，而不是直接process.exit()；
• 设置一个与容器宽限期对齐的兜底强制退出定时器（unref()避免它阻止进程自然退出），防止资源泄漏导致进程永远挂起、被编排平台强杀。

小结

优雅关闭在容器化时代从"可选项"变成了"必选项"。把它做对，需要同时管好四个层面：启动方式（让 Node 成为 PID1 或使用 TINI）、信号处理（监听 SIGTERM 并排空存量请求）、入口流量（通过健康检查通知负载均衡器）、资源清理（连接、句柄、定时器与收尾日志）。本仓库的 README.md 第 8.6 条、bootstrap-using-node.md 以及 examples/dockerfile 示例共同构成了这套实践的完整证据链，可直接作为团队落地的参考基准。

• 文档
• 教程
• 后端