一个 Node 服务在容器里频繁重启,编排平台只显示「退出码 137」,应用日志最后一行停在某个批量查询。137 等于 128 加 9,表示进程被 SIGKILL 杀掉,容器场景里最常见的原因是内存超过 limit,被内核 OOM killer 选中。不是 Node 主动退出,所以没有任何异常栈,光看应用日志永远找不到原因。

第二个事故发生在每次发布。新版本滚动上线,旧容器收到 SIGTERM,进程里没有注册信号处理,Node 默认直接退出。反向代理上还有几十个在途请求,连接突然断开,用户看到 502。发布越频繁,502 的尖峰越规律,但很多人把它当成「发布的正常现象」。

第三个问题更隐蔽。健康检查接口一直返回 {"status":"ok"},编排因此认为实例健康。某次数据库连接池耗尽,所有业务接口 500,健康检查仍然 200,流量继续往这个实例上打。探针问的是「进程还在吗」,而编排需要知道的是「现在能不能接业务流量」,这是两个不同的问题。这篇是「Node.js Web」组的最后一篇,把配置、日志、健康检查、优雅退出、构建和反向代理串成一条上线链路。所有端点示例都在本机 Express 5 实例上真实请求过;容器和 PM2 部分没有可用环境,会明确标注。

启动时把配置校验完

十二要素应用(Twelve-Factor App)把配置定义在环境变量里,代码库不保存环境差异。落地时最容易犯的错是「缺变量就用默认值兜住」:数据库地址没配,默认连本地;密钥没配,默认用一串固定字符。结果是测试环境能跑,生产静默连错库,直到数据写乱才发现。

正确做法是启动时一次性解析全部配置,缺什么、类型不对、长度不够,都在启动阶段失败。用 zod 写一个 schema,safeParse 失败就打印问题并退出,不进入监听:

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.string().min(1),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug']).default('info'),
});

const parsed = envSchema.safeParse(process.env);
if (!parsed.success) {
  console.error(JSON.stringify({ msg: 'invalid_config', issues: parsed.error.issues }));
  process.exit(1);
}

export const config = parsed.data;

这段代码有三个刻意设计。第一,PORT 用 coerce 转成数字,避免字符串参与比较;第二,JWT_SECRET 要求至少 32 个字符,短密钥在 HMAC 下强度不够;第三,解析失败直接退出,进程不会带着半套配置对外服务。启动失败比运行中随机失败容易排查得多。

密钥不要写进镜像,也不要写进 .env 后提交。镜像里只有代码和依赖,配置由编排平台、密钥管理系统或启动参数注入。日志里永远不要打印完整配置,尤其是连接串和密钥;要打印就打印「键存在、来源、长度」这类元信息。

NODE_ENV 不是万能开关

NODE_ENV 是一个约定,Express 和很多库会读它。设成 production 时,Express 会关闭一些开发期的行为,模板缓存也会开启;很多库会据此减少日志或启用优化。它不是安全边界,也不该用来决定「连哪个数据库」。

常见错误是用 NODE_ENV 区分开发、测试、预发、生产四个环境。它只有三个常见取值,预发到底算不算生产,团队每次都吵。更清楚的做法是另设一个 APP_ENV 表示部署环境,NODE_ENV 只表示运行模式。数据库地址、第三方沙箱、日志级别都由具体配置项决定,不由一个字符串推断。

另一个错误是在生产把 NODE_ENV 设成 development,为了「看更详细的错误」。这会让错误响应带堆栈,也可能让某些库输出调试信息,既是安全风险也是性能负担。需要详细日志就把 LOG_LEVEL 调成 debug,不要把运行模式改回开发。

结构化日志:pino、请求 ID 与脱敏

日志的第一用途不是「记录一切」,而是「出问题时能在几分钟内定位」。纯文本日志靠人眼搜关键词,结构化日志把字段固定下来,采集系统可以按 reqId、status、path 聚合。pino 是 Node 里常用的 JSON 日志库,写入开销低,字段稳定。

import pino from 'pino';

export const logger = pino({
  level: config.LOG_LEVEL,
  redact: {
    paths: ['req.headers.authorization', 'req.headers.cookie', 'password', '*.password'],
    censor: '[redacted]',
  },
});

请求 ID 是串联一次请求全部日志的关键。入口处读 x-request-id,没有就生成一个,写回响应头,再用子 logger 带上这个字段。反向代理、网关、下游服务都传同一个 ID,排查时按它过滤,能看到完整链路。

app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] || randomUUID();
  res.setHeader('x-request-id', req.id);
  req.log = logger.child({ reqId: req.id });
  const start = process.hrtime.bigint();
  res.on('finish', () => {
    req.log.info({
      method: req.method,
      path: req.path,
      status: res.statusCode,
      durationMs: Number(process.hrtime.bigint() - start) / 1e6,
    }, 'request completed');
  });
  next();
});

脱敏要在日志库层做,而不是靠每个调用点自觉。上面配置会把 authorization、cookie 和任意层级的 password 替换成 [redacted]。真实输出长这样:

{"level":30,"time":1794010823027,"pid":51424,"hostname":"...","req":{"id":"req-7f3a","method":"POST","url":"/auth/login","headers":{"authorization":"[redacted]"}},"password":"[redacted]","msg":"request completed"}

注意脱敏只能处理「已知字段名」。如果有人把令牌拼进 URL 查询串,或者把用户手机号写进 msg,配置拦不住。代码评审时要盯住日志语句,尤其是异常分支里的 JSON.stringify(req.body),那是最容易泄露密码的地方。

日志量和成本要一起考虑。每个请求一行访问日志,加上业务日志和错误堆栈,高流量下很容易把磁盘打满。访问日志可以采样,错误日志不要采样;关键业务操作保留完整记录,健康检查这类高频低价值日志可以降到 debug 或直接不记。

/healthz 与 /readyz 的分工

健康检查至少分两种。存活检查(liveness)回答「进程还活着吗」,失败时编排会重启容器;就绪检查(readiness)回答「现在能接业务流量吗」,失败时编排把实例从负载均衡里摘掉,但不重启。把两者混成一个接口,会出现「数据库短暂抖动导致全部容器被重启」的连锁反应。

/healthz 应该极轻:不查数据库、不查 Redis、不做鉴权,只返回进程状态。它检查的是事件循环是否还能响应,如果这个接口都超时,进程大概率已经卡死,重启是合理的。

app.get('/healthz', (req, res) => {
  res.status(200).json({ status: 'alive' });
});

起服务后先确认两个探针:

curl -i http://127.0.0.1:3000/healthz
curl -i http://127.0.0.1:3000/readyz

真实请求返回:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"alive"}

/readyz 要检查关键依赖,但也不能变成全量体检。数据库执行一次 select 1,Redis 执行一次 ping,迁移是否完成可以读一个标记。任何一项失败就返回 503,并在响应体里说明哪一项 down,方便排障,但不要泄露连接串。

app.get('/readyz', async (req, res) => {
  if (shuttingDown) {
    return res.status(503).json({ status: 'shutting_down' });
  }
  try {
    await pool.query('select 1');
    res.status(200).json({ status: 'ready', checks: { db: 'up' } });
  } catch {
    res.status(503).json({ status: 'not_ready', checks: { db: 'down' } });
  }
});

数据库正常和异常两种真实响应:

HTTP/1.1 200 OK
{"status":"ready","checks":{"db":"up"}}

HTTP/1.1 503 Service Unavailable
{"status":"not_ready","checks":{"db":"down"}}

就绪检查不要每次请求都打数据库。探针可能每几秒一次,多个副本叠加会形成稳定的额外查询量。可以在进程内缓存结果一到两秒,既保证及时性,又不至于把健康检查变成数据库压力源。检查本身要设超时,数据库连接卡住时,探针不能跟着挂几分钟。

探针参数也要按启动过程调。initialDelaySeconds 要覆盖进程启动、连接池预热和迁移完成的时间,太短会让新实例还没准备好就被判定失败;periodSeconds 一般五到十秒,failureThreshold 给三次左右的容忍,避免一次网络抖动就摘流量。存活失败会重启容器,就绪失败只摘流量,两个探针的阈值不要混着配。

优雅退出:先摘流量,再排空,最后关连接

容器收到 SIGTERM 后,编排会同时开始从负载均衡摘流量,但已经建立的连接和已经进来的请求还在。应用应该停止接受新连接,等待在途请求完成,再关闭数据库池和队列,最后退出。整个过程要有上限,不能无限等。

摘流量: 编排或代理先停止把新请求发给这个实例,但已经建立的连接还留着。
停止接受: server.close() 不再接受新连接,同时通知探针进入 shutting_down。
等待在途: 给正在执行的请求留出完成时间,能排空就排空,不能就记录数量。
关闭依赖: 请求结束后再关数据库池和队列,顺序反了会让在途请求拿不到连接。
强制上限: 宽限期到点仍未结束,记录日志并以非零码退出,避免永久挂住。
let shuttingDown = false;

async function shutdown(signal) {
  if (shuttingDown) return;
  shuttingDown = true;
  logger.info({ signal }, 'shutdown_started');

  const force = setTimeout(() => {
    logger.error({ signal }, 'shutdown_forced');
    process.exit(1);
  }, 15000);

  server.close(async () => {
    await pool.end();
    await queue.close();
    clearTimeout(force);
    logger.info({ signal }, 'shutdown_completed');
    process.exit(0);
  });
}

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

server.close() 的回调只在所有连接关闭后才执行,包括空闲的 keep-alive 连接。本机实测一个 400 毫秒的请求,在 705 毫秒时调用 server.close(),在途请求正常返回 200,但回调直到 3076 毫秒才触发。多出来的时间不是业务请求,而是 keep-alive 空闲连接的等待。这个数字说明:只写 server.close() 不加超时,排空时间会不可控。

可以主动调用 server.closeIdleConnections() 缩短空闲连接的等待,并配合一个硬超时,在宽限期结束前强制退出。关闭顺序也要注意:先停 HTTP,再关数据库池和队列;如果先关池,还在执行的请求会突然拿不到连接,反而制造 500。

不要在处理函数里直接调用 process.exit()。它会立刻终止进程,不等待日志刷盘,也不等待在途响应。所有退出路径都应该走同一个 shutdown 函数,保证顺序一致、日志完整。

构建与进程管理:npm ci、镜像、PM2

上线用的依赖清单要固定下来,示例服务的 package.json 只保留运行期需要的四个包:

{
  "name": "orders-api",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "scripts": {
    "start": "node src/server.js",
    "migrate": "node-pg-migrate up"
  },
  "dependencies": {
    "express": "^5.3.0",
    "pino": "^10.4.0",
    "pg": "^8.23.1",
    "zod": "^4.6.7"
  }
}

部署时安装依赖要用 npm ci,不要用 npm install。ci 严格按 package-lock.json 安装,lock 与 package.json 不一致时直接失败,保证每次构建的依赖树一致。生产环境加 --omit=dev 跳过开发依赖,减小镜像体积和攻击面。

npm ci --omit=dev
npm start

构建镜像时用多阶段:第一阶段装全量依赖并跑测试,第二阶段只复制生产依赖和源码。基础镜像选官方的 Node 24 slim 或固定小版本,不要用 latest。容器里用非 root 用户运行,设置 NODE_ENV=production,把 CMD 写成 node src/server.js,让 Node 直接作为 PID 1 接收信号;如果前面套了 shell,信号可能传不到 Node。

FROM node:24-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:24-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY package.json ./
COPY src ./src
USER node
CMD ["node", "src/server.js"]

先复制 package.json 和 package-lock.json 再执行 npm ci,是为了利用镜像层缓存:依赖没变时,这一层直接复用,构建更快。源码复制放在后面,避免改一行代码就重装全部依赖。同时用 .dockerignore 排除 node_modules、.env、.git 和测试产物,防止把本地文件带进镜像。

本机没有 Docker 和 PM2,镜像构建和 PM2 命令未在本机实测,上面的 Dockerfile 只作为结构参考。PM2 适合没有容器编排、直接在虚拟机上跑的场景,用 pm2 start src/server.js --name orders-api 启动,pm2 reload 做滚动重启。它和容器的选择不是技术高低,而是运维方式:容器把环境打包,PM2 依赖宿主机环境。镜像标签也不要只用 latest,每次构建打一个不可变标签,回滚时才有明确目标。

如果用 PM2 的 cluster 模式,要确认应用本身能在多进程下工作:端口由 PM2 分配还是各进程抢同一个端口、定时任务会不会重复、内存限制怎么设。不要因为「多核」就无脑开满,数据库连接池会按进程数成倍增长。

反向代理超时与 502

502 表示代理连不上上游,504 表示上游超时。发布时的 502 通常是旧进程已经退出,新进程还没监听,或者代理配置的上游地址短暂不可用。优雅退出只能减少在途请求被切断,不能消除切换窗口;滚动发布要保证「先起新实例、就绪后再摘旧实例」。

代理的超时要和应用的超时对齐。代理读超时短于应用处理时间,长请求会被代理切断,用户看到 504,应用还在继续算;代理读超时太长,卡住的请求会占满连接。把代理的 proxy_connect_timeout、proxy_read_timeout 和应用里外部调用的超时一起看,不要让它们各说各话。

另外两个容易忽略的配置是请求体大小和请求头超时。代理允许的 body 小于应用的限制,用户会在代理层被拒;请求头过大或过慢,代理可能直接断开。上线前用真实的文件上传和长轮询各压一次,别只看 GET 接口。

还有一种 502 不是超时,而是上游返回了代理无法解析的响应,比如应用在响应头已经发出后崩溃,连接被重置。这类问题在应用日志里往往只有半条访问日志,排查时要同时看代理的 upstream 状态和应用的退出原因,不能只盯着超时配置。

NestJS 的上线能力对照

NestJS 11 把配置、健康检查和生命周期做成了模块。@nestjs/config 负责读取环境变量,通常再配 zod 或 class-validator 做校验;@nestjs/terminus 提供 HealthCheckService 和数据库健康指示器,可以把存活与就绪拆成两个路由;日志可以接到 pino;enableShutdownHooks() 会在收到 SIGTERM 时调用模块的 onModuleDestroy。

Express 里这些是手写的中间件和退出函数,NestJS 里是模块和生命周期钩子。差别在装配方式,不在可靠性本身。NestJS 的 shutdown hook 也不会自动等你排空 HTTP 连接和队列,server.close、Worker 关闭、硬超时仍然要自己确认。选框架不会替你决定停机宽限期,只会换一个地方写。

现象、真实原因与第一步

现象真实原因第一步查什么
容器退出码 137内存超过 limit,被内核 OOM killer 杀掉看容器内存曲线和 dmesg,对比 Node 堆上限与 limit
发布时出现 502 尖峰旧进程直接退出,在途请求被切断,或新实例未就绪检查 SIGTERM 处理、就绪探针和滚动发布顺序
重启后 EADDRINUSE旧进程还没退出,新进程已经启动看端口占用 PID,确认停机宽限期和进程管理配置
/healthz 200 但业务全 500存活检查没覆盖依赖,实例仍在接流量补 /readyz 检查数据库和关键依赖,确认探针指向它
日志时间差八小时容器时区是 UTC,业务按北京时间理解确认 TZ 和日志时间格式,统一存 UTC、展示时转换
错误日志找不到对应请求没有请求 ID,或网关未透传 x-request-id在入口生成 ID 并写回响应头,检查代理是否保留该头
停机超过编排宽限期被强杀排空逻辑等 keep-alive 连接,或任务执行太久看 server.close 回调时间,加空闲连接关闭和硬超时
npm ci 构建失败lock 与 package.json 不一致,或锁文件没提交本地执行 npm ci 复现,确认 lock 已提交且未被手改
长请求 504,应用仍在执行代理读超时短于应用处理时间对比代理与应用超时,给外部调用设独立超时和取消

边界与代价

健康检查不是免费的。每次检查都打数据库、Redis,探针频率乘以副本数就是稳定的额外负载;检查写得太复杂,自己也会成为故障点。存活检查要轻,就绪检查要有限、有缓存、有超时,这是两条硬规则。

结构化日志有存储成本。字段越多、日志越全,磁盘和采集费用越高。脱敏、采样、保留期要一起设计。错误日志保留久一点,访问日志按流量采样,健康检查日志可以不留。不要为了「以后可能用得上」把请求体全量记下来,那既贵又容易泄露隐私。

优雅退出受制于编排。应用愿意等三十秒,编排只给十秒,最后还是硬杀;代理的读超时是五秒,应用等三十秒也没有意义。停机宽限期、代理超时、应用硬超时三个数字必须一起定,并且写进发布检查清单。

最后,部署方案没有绝对优劣。容器适合标准化和弹性,PM2 适合小团队在虚拟机上快速跑;Kubernetes 的就绪探针很完善,单机 docker compose 也能用健康检查。关键是理解每个开关在故障时会发生什么,而不是照抄一份配置。

当天能自己验证的练习

  1. 删掉 JWT_SECRET 后启动服务,确认 zod 校验打印 invalid_config 并以非零码退出;再补一个不足 32 字符的值,确认同样被拒绝。
  2. 请求 /healthz 和 /readyz,记录 200 的响应体;把数据库连接指向一个关闭的端口,确认 /readyz 变成 503,而 /healthz 仍是 200。
  3. 发起一个耗时 400 毫秒的请求,在 700 毫秒时调用 server.close(),记录在途请求的状态码和 close 回调的实际耗时,观察 keep-alive 带来的额外等待。
  4. 用 pino 打印一条带 authorization 和 password 的日志,确认输出里两处都是 [redacted];再把请求 ID 写进响应头,确认客户端能拿到同一个值。
  5. 在一个干净目录执行 npm ci --omit=dev,确认 node_modules 里没有测试框架;再故意改一行 package.json 的依赖版本,观察 npm ci 如何拒绝安装。

小结

这一组六篇从空目录走到上线,最后收束成四句话:配置在启动时校验,错误就退出;日志用结构化字段和请求 ID,敏感字段在库层脱敏;存活与就绪分开,依赖不可用时不要接流量;退出走同一条排空路径,并且给整个流程设硬上限。

Express 只是这条链路的第一环。路由、数据、鉴权、队列、部署,每一环都有独立的失败模式,但排查方法是一致的:先看现象,再问「这一步真正负责什么」,最后用最小实验复现。把这六篇里的表格和练习跑一遍,比记住任何框架的 API 都更有用。