Docker 部署 Node.js：没人告诉你的生产级配置 | Akousa

2025年11月10日11 分钟阅读

Docker 部署 Node.js：没人告诉你的生产级配置

多阶段构建、非 root 用户、健康检查、密钥管理和镜像体积优化。我在每个 Node.js 生产部署中使用的 Docker 模式。

大多数生产环境中的 Node.js Dockerfile 都是有问题的。不是"稍微不够优化"那种问题。我说的是以 root 运行、打了 600MB 镜像还带着 devDependencies、没有健康检查，密钥硬编码在环境变量里——任何人用 docker inspect 就能看到。

我知道，因为那些 Dockerfile 就是我写的。写了好几年。它们能跑，所以我从没质疑过。然后有一天安全审计标记了我们的容器——以 PID 1 root 运行，对整个文件系统拥有写权限——我才意识到"能用"和"生产就绪"完全是两码事。

这是我现在在每个 Node.js 项目中使用的 Docker 配置。不是理论性的。它运行着这个站点和我维护的其他几个服务。这里的每个模式都是因为我要么在替代方案上栽过跟头，要么亲眼看着别人栽跟头。

为什么你当前的 Dockerfile 大概率是错的

让我猜猜你的 Dockerfile 长什么样：

dockerfile

FROM node:20
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "server.js"]

这是 Dockerfile 的"hello world"。它能跑。但它至少有五个在生产环境中会坑你的问题。

以 root 运行

默认情况下，node Docker 镜像以 root 运行。这意味着你的应用进程在容器内拥有 root 权限。如果有人利用了你应用中的漏洞——路径遍历 bug、SSRF、某个带后门的依赖——他们就拥有了容器文件系统的 root 访问权限，可以修改二进制文件、安装包，甚至可能进一步提权，具体取决于你的容器运行时配置。

"但容器是隔离的啊！"部分是。容器逃逸是真实存在的。CVE-2024-21626、CVE-2019-5736——这些都是真实世界的容器突破事件。以非 root 运行是一种纵深防御措施。零成本，却能封堵整类攻击。

在生产环境安装 devDependencies

不带参数的 npm install 会安装所有东西。你的测试运行器、linter、构建工具、类型检查器——全都堆在生产镜像里。这会让你的镜像膨胀数百 MB，并增加攻击面。每多一个包就是另一个 Trivy 或 Snyk 可能标记的潜在漏洞。

dockerfile

# 单阶段：约 600MB
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]
 
# 多阶段：约 150MB
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
CMD ["node", "dist/server.js"]

dockerfile

# ============================================
# 阶段 1：安装依赖
# ============================================
FROM node:20-alpine AS deps
 
# 安全：在做任何事之前先创建工作目录
WORKDIR /app
 
# 基于 lockfile 安装依赖
# 先只复制 package 文件——这对层缓存至关重要
COPY package.json package-lock.json ./
 
# ci 比 install 更好：更快、更严格、可复现
# --omit=dev 在这个阶段排除 devDependencies
RUN npm ci --omit=dev
 
# ============================================
# 阶段 2：构建应用
# ============================================
FROM node:20-alpine AS builder
 
WORKDIR /app
 
# 复制 package 文件并安装所有依赖（包括 dev）
COPY package.json package-lock.json ./
RUN npm ci
 
# 现在复制源代码——这里的改动不会使 npm ci 缓存失效
COPY . .
 
# 构建应用（TypeScript 编译、Next.js 构建等）
RUN npm run build
 
# ============================================
# 阶段 3：生产运行器
# ============================================
FROM node:20-alpine AS runner
 
# 添加标签用于镜像元数据
LABEL maintainer="your-email@example.com"
LABEL org.opencontainers.image.source="https://github.com/yourorg/yourrepo"
 
# 安全：安装 dumb-init 以正确处理 PID 1 的信号
RUN apk add --no-cache dumb-init
 
# 安全：在做任何事之前设置 NODE_ENV
ENV NODE_ENV=production
 
# 安全：使用非 root 用户
# node 镜像已经包含一个 'node' 用户（uid 1000）
USER node
 
# 创建归属于 node 用户的应用目录
WORKDIR /app
 
# 从 deps 阶段复制生产依赖
COPY --from=deps --chown=node:node /app/node_modules ./node_modules
 
# 从 builder 阶段复制构建产物
COPY --from=deps --chown=node:node /app/package.json ./
COPY --from=builder --chown=node:node /app/dist ./dist
 
# 暴露端口（仅作文档——不会发布它）
EXPOSE 3000
 
# 健康检查：alpine 中没有 curl，使用 node
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
# 使用 dumb-init 作为 PID 1 以正确处理信号
ENTRYPOINT ["dumb-init", "--"]
 
# 启动应用
CMD ["node", "dist/server.js"]

javascript

// server.js
const server = app.listen(3000);
 
process.on("SIGTERM", () => {
  console.log("SIGTERM received, shutting down gracefully");
  server.close(() => {
    console.log("HTTP server closed");
    // 关闭数据库连接、刷新日志等
    process.exit(0);
  });
});

# .dockerignore
node_modules
npm-debug.log*
.git
.gitignore
.env
.env.*
!.env.example
Dockerfile
docker-compose*.yml
.dockerignore
README.md
LICENSE
.github
.vscode
.idea
coverage
.nyc_output
*.test.ts
*.test.js
*.spec.ts
*.spec.js
__tests__
test
tests
docs
.husky
.eslintrc*
.prettierrc*
tsconfig.json
jest.config.*
vitest.config.*

dockerfile

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
 
# 在构建时挂载密钥——它永远不会存储在镜像中
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci
 
COPY . .
RUN npm run build

yaml

# docker-compose.yml（Swarm 模式）
version: "3.8"
services:
  api:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
 
secrets:
  db_password:
    external: true
  api_key:
    external: true

javascript

import { readFileSync } from "fs";
 
function getSecret(name) {
  try {
    return readFileSync(`/run/secrets/${name}`, "utf8").trim();
  } catch {
    // 本地开发时回退到环境变量
    return process.env[name.toUpperCase()];
  }
}
 
const dbPassword = getSecret("db_password");

dockerfile

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"

javascript

// healthcheck.js
const http = require("http");
 
const options = {
  hostname: "localhost",
  port: 3000,
  path: "/health",
  timeout: 5000,
};
 
const req = http.request(options, (res) => {
  process.exit(res.statusCode === 200 ? 0 : 1);
});
 
req.on("error", () => process.exit(1));
req.on("timeout", () => {
  req.destroy();
  process.exit(1);
});
 
req.end();

javascript

app.get("/health", async (req, res) => {
  const checks = {
    uptime: process.uptime(),
    timestamp: Date.now(),
    status: "ok",
  };
 
  try {
    // 检查数据库连接
    await db.query("SELECT 1");
    checks.database = "connected";
  } catch (err) {
    checks.database = "disconnected";
    checks.status = "degraded";
  }
 
  try {
    // 检查 Redis 连接
    await redis.ping();
    checks.redis = "connected";
  } catch (err) {
    checks.redis = "disconnected";
    checks.status = "degraded";
  }
 
  const statusCode = checks.status === "ok" ? 200 : 503;
  res.status(statusCode).json(checks);
});

yaml

# docker-compose.dev.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
      args:
        NODE_VERSION: "20"
    ports:
      - "3000:3000"
      - "9229:9229" # Node.js 调试器
    volumes:
      # 挂载源代码以实现热重载
      - .:/app
      # 匿名卷保留镜像中的 node_modules
      # 防止宿主机的 node_modules 覆盖容器中的
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:devpassword@db:5432/myapp_dev
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev
 
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: devpassword
    volumes:
      # 命名卷在容器重启之间持久化数据
      - pgdata:/var/lib/postgresql/data
      # 初始化脚本
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    command: redis-server --appendonly yes
 
  # 可选：数据库管理 UI
  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
 
volumes:
  pgdata:
  redisdata:

dockerfile

# Dockerfile.dev
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
WORKDIR /app
 
# 安装所有依赖（包括 devDependencies）
COPY package*.json ./
RUN npm ci
 
# 源代码通过卷挂载，不是复制
# 但初始构建仍然需要它
COPY . .
 
EXPOSE 3000 9229
 
CMD ["npm", "run", "dev"]

yaml

# docker-compose.prod.yml
services:
  app:
    image: ghcr.io/yourorg/myapp:${TAG:-latest}
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    env_file:
      - .env.production
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
      replicas: 2
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))",
        ]
      interval: 30s
      timeout: 10s
      start_period: 40s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - internal
      - web
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
 
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
 
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: >
      redis-server
      --appendonly yes
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redisdata:/data
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "5m"
        max-file: "3"
 
volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local
 
networks:
  internal:
    driver: bridge
  web:
    external: true

dockerfile

# ============================================
# 阶段 1：安装依赖
# ============================================
FROM node:20-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci
 
# ============================================
# 阶段 2：构建应用
# ============================================
FROM node:20-alpine AS builder
WORKDIR /app
 
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# 构建期间禁用 Next.js 遥测
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN npm run build
 
# ============================================
# 阶段 3：生产运行器
# ============================================
FROM node:20-alpine AS runner
WORKDIR /app
 
RUN apk add --no-cache dumb-init
 
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
 
# 非 root 用户
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# 复制公共资源
COPY --from=builder /app/public ./public
 
# 设置 standalone 输出目录
# 自动利用输出追踪来减小镜像大小
# https://nextjs.org/docs/advanced-features/output-file-tracing
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# 复制 standalone 服务器和静态文件
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
 
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "server.js"]

myapp:latest (alpine 3.19.1)
=============================
Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)

Node.js (node_modules/package-lock.json)
=========================================
Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 1, CRITICAL: 0)

┌──────────────┬────────────────┬──────────┬────────┬───────────────┐
│   Library    │ Vulnerability  │ Severity │ Status │ Fixed Version │
├──────────────┼────────────────┼──────────┼────────┼───────────────┤
│ semver       │ CVE-2022-25883 │ HIGH     │ fixed  │ 7.5.4         │
│ word-wrap    │ CVE-2023-26115 │ MEDIUM   │ fixed  │ 1.2.4         │
└──────────────┴────────────────┴──────────┴────────┴───────────────┘

yaml

# .github/workflows/docker.yml
- name: Build image
  run: docker build -t myapp:${{ github.sha }} .
 
- name: Scan image
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myapp:${{ github.sha }}
    exit-code: 1
    severity: CRITICAL,HIGH
    ignore-unfixed: true

yaml

# .github/workflows/docker.yml
name: Build and Push Docker Image
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      security-events: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Log in to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}
 
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
      - name: Scan image with Trivy
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}
          exit-code: 1
          severity: CRITICAL,HIGH
          ignore-unfixed: true
 
      - name: Upload Trivy results
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: trivy-results.sarif

dockerfile

# 构建时配置
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
# 运行时配置
ENV PORT=3000
 
# 错误：这会使密钥在镜像中可见
ARG API_KEY
ENV API_KEY=${API_KEY}
 
# 正确：在运行时传递密钥
# docker run -e API_KEY=secret myapp

yaml

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - internal
 
  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    networks:
      - internal
 
volumes:
  prometheus_data:
  grafana_data:

javascript

import { collectDefaultMetrics, Registry, Histogram } from "prom-client";
 
const register = new Registry();
collectDefaultMetrics({ register });
 
const httpRequestDuration = new Histogram({
  name: "http_request_duration_seconds",
  help: "Duration of HTTP requests in seconds",
  labelNames: ["method", "route", "status_code"],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
  registers: [register],
});
 
// 中间件
app.use((req, res, next) => {
  const end = httpRequestDuration.startTimer();
  res.on("finish", () => {
    end({ method: req.method, route: req.route?.path || req.path, status_code: res.statusCode });
  });
  next();
});
 
// 指标端点
app.get("/metrics", async (req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

方案	镜像大小
`node:20` + `npm install`	1.1 GB
`node:20-slim` + `npm install`	420 MB
`node:20-alpine` + `npm ci`	280 MB
多阶段 + alpine + 仅生产依赖	150 MB
多阶段 + alpine + 精简后的依赖	95 MB

方案	镜像大小
`node:20` + 完整 `node_modules` + `.next`	1.4 GB
`node:20-alpine` + 完整 `node_modules` + `.next`	600 MB
`node:20-alpine` + standalone 输出	120 MB

为什么你当前的 Dockerfile 大概率是错的

以 root 运行

在生产环境安装 devDependencies

COPY 所有东西

没有健康检查

没有层缓存策略

多阶段构建：最有价值的一步

真实的体积对比

为什么选 Alpine？

完整的生产级 Dockerfile

为什么是三个阶段而不是两个？

为什么要 dumb-init？

.dockerignore 文件

层缓存：别再每次构建等 3 分钟了

错误的顺序

正确的顺序

npm 的缓存挂载

使用 ARG 进行缓存失效

密钥管理：别再把密钥放到 Dockerfile 里了

密钥的三个层级

.env 文件和 Docker

健康检查：让 Docker 知道你的应用是否真正在工作

HEALTHCHECK 指令

为什么不用 curl？

健康端点

为什么健康检查对编排器很重要

开发用的 docker-compose

关键开发模式

开发用 Dockerfile

生产环境的 Docker Compose

与开发环境的区别

Next.js 特有配置：standalone 输出

Next.js 生产 Dockerfile

Next.js 的体积对比

静态文件处理

Sharp 用于图片优化

镜像扫描和安全

Trivy：扫描你的镜像

只读文件系统

丢弃所有能力

锁定基础镜像摘要

CI/CD 集成：整合一切

CI 中的 BuildKit 缓存

常见陷阱及如何避免

镜像内的 node_modules 与宿主机冲突

TypeScript 项目中的 SIGTERM 处理

内存限制和 Node.js

时区问题

构建参数 vs 环境变量

生产环境监控

检查清单

相关文章

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

YAML Validator Guide: Catch Config Errors Before Deploy