Docker 部署 Node.js：Express / Nest.js 后端服务的容器化实战

# ===== 构建阶段：安装依赖 =====
FROM node:20-alpine AS builder
WORKDIR /app

# 先复制 lock 文件以利用缓存层
COPY package*.json ./
RUN npm ci --only=production --ignore-scripts

# 再复制源代码
COPY . .

# ===== 运行阶段：仅保留产物 =====
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production

# 安装 dumb-init 作为 PID 1，正确处理信号转发与僵尸进程
RUN apk add --no-cache dumb-init \
    && addgroup -g 1001 -S nodejs \
    && adduser -S nodejs -u 1001

# 仅从 builder 阶段复制必要文件
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/src ./src
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./

USER nodejs
EXPOSE 3000

# dumb-init 作为 PID 1，确保 SIGTERM 正常传递到 node 进程
ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "src/index.js"]

version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/api
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
      PORT: 3000
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: api
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru

volumes:
  postgres_data:
    driver: local
  redis_data:
    driver: local

# ===== 构建阶段 =====
FROM node:20-alpine AS builder
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# ===== 生产依赖阶段：仅安装 production 依赖 =====
FROM node:20-alpine AS prod-deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production --ignore-scripts

# ===== 运行阶段 =====
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production

RUN addgroup -g 1001 -S nodejs \
    && adduser -S nodejs -u 1001

# 从 builder 复制编译产物
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
# 从 prod-deps 复制生产依赖
COPY --from=prod-deps --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./

USER nodejs
EXPOSE 3000
CMD ["node", "dist/main.js"]

FROM node:20-alpine
RUN npm install -g pm2@latest
WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production --ignore-scripts

COPY . .

EXPOSE 3000
USER node
CMD ["pm2-runtime", "start", "ecosystem.config.js", "--env", "production"]

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'api',
    script: './src/index.js',
    // instances: 'max' 表示使用容器可见的全部 CPU 核心
    instances: 'max',
    exec_mode: 'cluster',
    // 内存超限自动重启，防止 OOM 导致容器被整体杀掉
    max_memory_restart: '512M',
    // 优雅关闭超时
    kill_timeout: 5000,
    // 监听文件变化自动重启（开发环境用，生产建议关闭）
    watch: false,
    env: {
      NODE_ENV: 'development'
    },
    env_production: {
      NODE_ENV: 'production'
    },
    // 日志输出到 stdout/stderr，由 Docker 收集
    log_file: '/dev/null',
    out_file: '/dev/stdout',
    error_file: '/dev/stderr',
    // 合并日志
    merge_logs: true
  }]
};

# nginx.conf
upstream api {
    least_conn;                     # 最少连接负载均衡策略
    server api:3000 max_fails=3 fail_timeout=30s;
    server api_backup:3000 backup;  # 热备节点
}

server {
    listen 80;
    server_name api.example.com;

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Gzip 压缩响应
    gzip on;
    gzip_types application/json application/javascript text/css;
    gzip_min_length 1024;

    # 静态文件直接由 Nginx 服务
    location /static/ {
        alias /var/www/static/;
        expires 30d;
        access_log off;
    }

    # API 转发
    location / {
        proxy_pass http://api;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
        proxy_connect_timeout 60s;
        proxy_buffering off;
    }

    # 健康检查端点（可选，配合 nginx_upstream_check_module）
    location /nginx-health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }
}

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./static:/var/www/static:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - api
    restart: unless-stopped

# ===== 构建阶段 =====
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# ===== 生产依赖阶段 =====
FROM node:20 AS prod-deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production --ignore-scripts

# ===== Distroless 运行阶段 =====
FROM gcr.io/distroless/nodejs20-debian12:nonroot
WORKDIR /app
ENV NODE_ENV=production

# Distroless nonroot 的 UID 为 65532
COPY --from=builder --chown=nonroot:nonroot /app/dist ./dist
COPY --from=prod-deps --chown=nonroot:nonroot /app/node_modules ./node_modules
COPY --from=builder --chown=nonroot:nonroot /app/package.json ./

EXPOSE 3000
# Distroless 镜像的入口即为 node 二进制，CMD 只需传脚本路径
CMD ["dist/main.js"]

# Chiseled Ubuntu + Node.js 运行时（需确保基础镜像已安装 node）
FROM mcr.microsoft.com/dotnet/runtime-deps:8.0-jammy-chiseled AS runtime
# 注：若需 Node.js 在 Chiseled 中运行，可基于自定义 Chiseled Node 镜像
# 或直接使用 Azure 提供的 mcr.microsoft.com/oss/node/node:20-jammy-chiseled

FROM node:20-alpine
# ... 构建指令 ...

EXPOSE 3000
# 每 30 秒探测一次，超时 5 秒，连续 3 次失败标记为 unhealthy
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => r.statusCode === 200 ? process.exit(0) : process.exit(1))"

CMD ["node", "src/index.js"]

// Express /health 端点示例
app.get('/health', (req, res) => {
  // 若需检查数据库连通性，建议增加短路超时（如 2 秒）
  res.status(200).json({ status: 'ok', uptime: process.uptime() });
});

// graceful-shutdown.js
const http = require('http');

function setupGracefulShutdown(server, options = {}) {
  const timeout = options.timeout || 30000;

  const shutdown = (signal) => {
    console.log(`Received ${signal}. Starting graceful shutdown...`);

    server.close(() => {
      console.log('HTTP server closed.');
      // 关闭 DB / Redis 连接
      // await db.end(); await redis.quit();
      process.exit(0);
    });

    // 超时强制退出
    setTimeout(() => {
      console.error('Shutdown timeout exceeded. Forcing exit.');
      process.exit(1);
    }, timeout);
  };

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

module.exports = { setupGracefulShutdown };

services:
  api:
    build: .
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    environment:
      # 显式限制 V8 堆内存，避免 OOM
      NODE_OPTIONS: "--max-old-space-size=384"

services:
  api:
    build: .
    secrets:
      - db_password
      - jwt_secret
    environment:
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/api
    # 应用内读取：fs.readFileSync('/run/secrets/db_password', 'utf8').trim()

secrets:
  db_password:
    file: ./secrets/db_password.txt
  jwt_secret:
    file: ./secrets/jwt_secret.txt

// config/secrets.js
const fs = require('fs');
const path = require('path');

function loadSecret(name, fallbackEnv) {
  const secretPath = path.join('/run/secrets', name);
  if (fs.existsSync(secretPath)) {
    return fs.readFileSync(secretPath, 'utf8').trim();
  }
  return process.env[fallbackEnv];
}

module.exports = {
  dbPassword: loadSecret('db_password', 'DB_PASSWORD'),
  jwtSecret: loadSecret('jwt_secret', 'JWT_SECRET'),
};

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./

# 挂载 npm 缓存目录，key 为 lock 文件内容
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
    npm ci

COPY . .
RUN npm run build

# Docker Scout（需 Docker Desktop 或登录 Docker Hub）
docker scout cves my-api:latest

# Trivy（开源，可集成 CI）
trivy image --severity HIGH,CRITICAL my-api:latest

# Snyk
snyk container test my-api:latest

# ===== 构建阶段 =====
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

# ===== 运行阶段 =====
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production

RUN addgroup -g 1001 -S fastify && adduser -S fastify -u 1001

COPY --from=builder --chown=fastify:fastify /app/node_modules ./node_modules
COPY --from=builder --chown=fastify:fastify /app/app.js ./
COPY --from=builder --chown=fastify:fastify /app/package.json ./

USER fastify
EXPOSE 3000
CMD ["node", "app.js"]

// app.js — Fastify 入口
const fastify = require('fastify')({
  logger: true,
  // 信任代理头，用于获取真实客户端 IP
  trustProxy: true,
});

fastify.get('/health', async () => ({ status: 'ok' }));

fastify.get('/users/:id', async (request, reply) => {
  // 业务逻辑
  return { id: request.params.id, name: 'Alice' };
});

const start = async () => {
  try {
    await fastify.listen({ port: 3000, host: '0.0.0.0' });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};
start();

version: '3.8'

services:
  api:
    image: my-api:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
        failure_action: rollback
        order: start-first
      rollback_config:
        parallelism: 1
        delay: 5s
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 256M
        reservations:
          cpus: '0.1'
          memory: 64M
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://postgres:secret@db:5432/api
    secrets:
      - jwt_secret
    networks:
      - backend
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        constraints:
          - node.role == manager

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    configs:
      - source: nginx_conf
        target: /etc/nginx/nginx.conf
    networks:
      - backend
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.labels.nginx == true

networks:
  backend:
    driver: overlay

volumes:
  postgres_data:

secrets:
  db_password:
    external: true
  jwt_secret:
    external: true

configs:
  nginx_conf:
    external: true

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nodejs-api
  labels:
    app: nodejs-api
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: nodejs-api
  template:
    metadata:
      labels:
        app: nodejs-api
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001
      containers:
        - name: api
          image: my-api:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 3000
              name: http
          env:
            - name: NODE_ENV
              value: "production"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: api-secrets
                  key: database-url
            - name: JWT_SECRET
              valueFrom:
                secretKeyRef:
                  name: api-secrets
                  key: jwt-secret
          resources:
            limits:
              cpu: "500m"
              memory: "512Mi"
            requests:
              cpu: "100m"
              memory: "128Mi"
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 30
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "sleep 15"]
---
apiVersion: v1
kind: Service
metadata:
  name: nodejs-api-service
spec:
  selector:
    app: nodejs-api
  ports:
    - port: 80
      targetPort: 3000
  type: ClusterIP

# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: api-secrets
type: Opaque
stringData:
  database-url: "postgres://postgres:secret@db:5432/api"
  jwt-secret: "your-256-bit-secret"