NestJS 应用生产环境部署：Docker 容器化配置与性能优化

一、构建生产级 Dockerfile：多阶段构建与最小化镜像

在默认开发流程中，NestJS 依赖大量的构建与测试工具，包括 TypeScript 编译器 (tsc)、Nest CLI (@nestjs/cli)、代码检查工具 (eslint) 以及单元测试套件 (jest)。若直接把本地目录拷贝并打包进镜像，最终产物不仅体积臃肿（通常在 1.2GB 以上），还会将源代码暴露在容器内，并引入潜在的开发依赖安全漏洞。

解决该问题的标准路径是多阶段构建 (Multi-stage Build)：将环境解耦为依赖安装、代码编译、依赖裁剪和最终轻量运行四个独立阶段。编译完成后的最终镜像仅包含 Node.js 运行时、编译后的 dist 目录以及必要的生产依赖。

1. 配置严密的 .dockerignore

在执行 Docker 构建前，必须首先在项目根目录创建 .dockerignore 文件。它能阻断本地 node_modules、临时产物与本地密钥被意外打入镜像构建上下文，既保护敏感信息，又提升构建缓存命中率：

# .dockerignore
node_modules
dist
npm-debug.log
yarn-error.log
.git
.gitignore
.env
.env.*
test
coverage
*.md
docker-compose*.yml

2. 完整的多阶段 Dockerfile

以下是经过生产实战检验的 NestJS Dockerfile。基础镜像选用轻量且安全的 node:20-alpine，并在最终阶段引入 dumb-init 来安全管理进程生命周期：

# ==========================================
# 阶段 1: 全量依赖安装 (包含 devDependencies)
# ==========================================
FROM node:20-alpine AS deps
WORKDIR /usr/src/app

# 利用 Docker 层缓存：仅当 lock 文件变更时才重新运行 npm ci
COPY package*.json ./
RUN npm ci

# ==========================================
# 阶段 2: 应用编译与打包
# ==========================================
FROM node:20-alpine AS builder
WORKDIR /usr/src/app

COPY --from=deps /usr/src/app/node_modules ./node_modules
COPY . .

# 执行 Nest CLI 编译，输出生产级原生 JavaScript 至 dist/ 目录
RUN npm run build

# ==========================================
# 阶段 3: 提取纯净的生产依赖
# ==========================================
FROM node:20-alpine AS prod-deps
WORKDIR /usr/src/app

COPY package*.json ./
# --omit=dev 会剔除所有开发依赖 (TypeScript、Jest、ESLint 等)
RUN npm ci --omit=dev && npm cache clean --force

# ==========================================
# 阶段 4: 最终生产运行时镜像 (Runner)
# ==========================================
FROM node:20-alpine AS runner
WORKDIR /usr/src/app

# 安装 dumb-init 处理 PID 1 信号转发与僵尸进程回收
RUN apk add --no-cache dumb-init

# 声明生产环境标识
ENV NODE_ENV=production
ENV PORT=3000

# 从对应构建阶段精准复制产物
COPY --from=prod-deps /usr/src/app/node_modules ./node_modules
COPY --from=builder /usr/src/app/dist ./dist
COPY package.json ./

# 切换为基础镜像内置的非 root 用户，杜绝容器逃逸与越权风险
USER node

EXPOSE 3000

# 使用 dumb-init 作为 PID 1 启动进程
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["node", "dist/main.js"]

二、容器运行时生命周期：PID 1 陷阱与优雅停机

许多开发者在完成镜像制作后，直接以 CMD ["node", "dist/main.js"] 运行应用。在本地测试时表面正常，但在 Kubernetes 或 Docker Swarm 进行滚动更新（Rolling Update）时，常会出现请求超时、客户端收到 502/504 错误或数据库事务半途断开的情况。这背后是 Linux 容器内核的 PID 1 信号机制。

1. 为什么 Node.js 不能直接担任 PID 1

在 Linux 操作系统中，PID 为 1 的进程（通常为 systemd 或 init）享有特殊地位：

1. 信号忽略机制：对于非 PID 1 进程，未注册处理函数的 SIGINT 或 SIGTERM 会触发默认动作（终止进程）；但对于 PID 1 进程，内核会主动丢弃未显式声明监听的信号，以防操作系统崩溃。
2. Node.js 的设计假设：Node.js 并非为担任操作系统的 Init 进程而设计。当编排调度平台下发 docker stop（默认发送 SIGTERM）时，作为 PID 1 的 Node 进程会忽略该信号，直到 10 秒超时耗尽，宿主机发出 SIGKILL 强制斩杀进程，正在处理的业务请求瞬间崩塌。
3. 孤儿进程回收：当应用内部派生子进程崩溃时，必须由 PID 1 负责 waitpid 回收。Node.js 不具备自动清理僵尸进程的机制，长时间运行可能耗尽系统进程表。

通过在 Dockerfile 中引入 dumb-init（或 Docker 原生参数 --init），让轻量的 C 语言初始化程序担当 PID 1，能够即时将 SIGTERM、SIGINT 完整转递给 Node 子进程，并在父子进程退出时正确清理资源。

2. NestJS 开启优雅退出钩子

仅有信号传递还不够，NestJS 应用必须在代码层面监听并响应这些信号。在项目入口 src/main.ts 中调用 app.enableShutdownHooks() 即可激活 NestJS 的生命周期钩子：

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { Logger } from '@nestjs/common';

async function bootstrap() {
  const logger = new Logger('Bootstrap');
  const app = await NestFactory.create(AppModule, {
    // 生产环境建议关闭默认的绚丽彩色日志，统一输出单行标准格式
    logger: ['error', 'warn', 'log'],
  });

  // 必须显式开启停机钩子，监听 SIGTERM、SIGINT 信号
  app.enableShutdownHooks();

  const port = process.env.PORT || 3000;
  await app.listen(port, '0.0.0.0');
  logger.log(`NestJS 应用已启动，监听端口: ${port}`);
}

bootstrap();

当业务模块（如数据库连接、消息队列消费者）实现 OnApplicationShutdown 接口时，NestJS 会在收到停止信号后按拓扑逆序优雅断开外部连接，确保无数据丢失：

// src/database/database.service.ts
import { Injectable, OnApplicationShutdown, Logger } from '@nestjs/common';

@Injectable()
export class DatabaseService implements OnApplicationShutdown {
  private readonly logger = new Logger(DatabaseService.name);

  async onApplicationShutdown(signal?: string) {
    this.logger.log(`接收到系统信号 [${signal}]，正在关闭数据库连接池与事务...`);
    // 执行具体连接池释放操作，例如：await this.pool.end();
    this.logger.log('数据库连接池已安全释放');
  }
}

三、运行时性能优化：引擎选型与 V8 内存限制

容器化并非简单将应用打包，更要根据宿主机的硬件限制调教 Node.js 运行时底座。特别是在微服务架构中，多个容器共享宿主机物理资源，精细化的资源配额至关重要。

1. HTTP 底层适配器切换：Fastify 代替 Express

NestJS 默认采用 Express 作为底层 HTTP 服务器。Express 生态成熟，但其基于原生 JSON.stringify 的序列化与层层嵌套的中间件机制在高并发下 CPU 开销显著。

对于追求高吞吐、低延迟的 API 接口或微服务网关，切换为 Fastify 适配器可在同等容器资源下将吞吐量（RPS）提升 2 至 3 倍，同时大幅降低请求抖动：

# 依赖安装
npm install --save @nestjs/platform-fastify

// src/main.ts (基于 Fastify 驱动)
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({
      logger: false, // 禁用 fastify 内置打印，交由 Nest 全局 Logger 托管
      trustProxy: true, // 容器部署位于 Nginx/Ingress 之后时必须开启，以正确读取客户端真实 IP
    }),
  );

  app.enableShutdownHooks();
  // 容器化网络监听必须绑定 0.0.0.0，否则外部流量无法映射进入
  await app.listen(3000, '0.0.0.0');
}

bootstrap();

2. 严控 Node.js V8 堆内存：规避 OOM Killer 猝死

在 Linux 容器中，最常见的线上隐蔽崩溃是 OOM (Out Of Memory) 137 错误。通常表现为容器突然重启，但应用日志中没有记录任何 Error 堆栈。

其根本原因在于：Node.js V8 引擎在默认情况下不会完全感知容器的 cgroups 内存配额。假设在 Docker Compose 或 K8s 中给容器分配了 1024MB 内存，若未明确设置 V8 堆上限，V8 会根据宿主机物理内存（例如 32GB）去推算堆大小，迟迟不执行激进的 Full GC 垃圾回收。当容器总内存（堆内存 + 堆外网络 Buffer + C++ 原生扩展 + 操作系统开销）突破 1024MB 时，Linux 内核会直接触发 OOM Killer 强制杀死进程。

核心防护准则：将 V8 堆上限限制在容器物理配额的 70% ~ 75%，预留 25%~30% 给堆外内存与系统进程。

# 以 1GB 容器内存限制为例，通过环境变量注入 Node 启动选项
NODE_OPTIONS="--max-old-space-size=768" node dist/main.js

当堆内存达到 768MB 时，V8 引擎会主动暂停并触发全量垃圾回收，释放无效对象，从而在应用层消化内存峰值，避免被宿主机内核强行击杀。

3. 单容器单进程原则 vs 多进程 PM2

在裸机部署时代，工程师习惯用 PM2 启动 cluster 模式来榨干多核 CPU。但在现代化容器编排体系下，在 Docker 容器内部再跑 PM2 Cluster 是一种反模式：

• 破坏编排监控：Kubernetes 和 Docker 依靠容器标准输出（stdout/stderr）采集日志，依靠容器进程退出码判断健康状态。嵌套 PM2 会掩盖内部 Node 进程的崩溃，导致探针失灵。
• 资源颗粒度失控：容器的优势在于弹性横向伸缩（Horizontal Pod Autoscaling）。标准做法是每个容器分配单一进程（例如限制 1 核 1GB），需要更高吞吐时直接将容器副本数从 3 个扩容到 10 个，由外部负载均衡分发流量。

四、生产部署落地验证与自检清单

为了在生产环境中将以上配置完整联动，我们采用标准的 docker-compose.yml 建立一个高可靠的部署规范，包含健康探测、资源约束与日志滚动策略：

# docker-compose.yml
version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    image: my-nestjs-app:1.0.0
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - NODE_OPTIONS=--max-old-space-size=768
    deploy:
      resources:
        limits:
          cpus: '1.5'
          memory: 1024M
        reservations:
          cpus: '0.5'
          memory: 512M
    healthcheck:
      # 定期探测容器内部健康状态，失败时编排系统将重新拉起
      test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:3000/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 20s
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "5"

生产上线验收标准 (Checklist)

按照上述配置构建并运行后的 NestJS 生产镜像，不仅具备严密的隔离性与最小化的攻击面，还能在节点调度、故障自愈与滚动升级过程中保持连接平滑过渡，为高并发业务场景提供坚实的底层容器支撑。