NestJS容器化部署实战

NestJS vs Nuxt3 容器化对比：
│
├── 构建产物
│   ├── Nuxt3：.output 目录（自包含 node_modules）
│   └── NestJS：dist 目录（需要外部 node_modules）
│
├── 依赖管理
│   ├── Nuxt3：bundleDependencies 自动打包依赖
│   └── NestJS：需要手动安装生产依赖
│
├── Prisma 集成 
│   ├── Nuxt3：通常无数据库操作
│   └── NestJS：需要 prisma generate 生成 client
│
├── 启动方式
│   ├── Nuxt3：node .output/server/index.mjs
│   └── NestJS：node dist/main.js
│
└── 环境变量
    ├── Nuxt3：BASE_URL 等 API 地址
    └── NestJS：DATABASE_URL、JWT_SECRET 等

NestJS 容器化关键点：
│
├── 1. Prisma Client 生成 
│   ├── 执行 prisma generate
│   ├── 生成 node_modules/.prisma/client
│   └── 数据库操作必需文件
│
├── 2. 生产依赖安装 
│   ├── npm install --production
│   ├── 或 npm install --omit=dev
│   └── 不包含开发依赖
│
├── 3. 文件拷贝顺序 
│   ├── 先拷贝 package.json
│   ├── 安装生产依赖
│   ├── 拷贝 prisma client
│   └── 最后拷贝 dist 目录
│
└── 4. 数据库连接 
    ├── DATABASE_URL 环境变量
    ├── 数据库服务运行
    └── 网络连通性

//  原始 package.json
{
  "scripts": {
    "preinstall": "prisma generate"
  }
}

//  调整后的 package.json
{
  "scripts": {
    "generate": "prisma generate"
  }
}

# ==================== 构建阶段 ====================
FROM node:18-alpine AS builder

# 使用 node 用户（安全配置）
USER node
WORKDIR /home/node/app

# 设置淘宝源（国内加速）
RUN npm config set registry https://registry.npmmirror.com

# 复制依赖配置文件
COPY --chown=node:node package*.json ./
COPY --chown=node:node prisma ./prisma/

# 安装所有依赖（包括开发依赖）
RUN npm install

# 生成 Prisma Client
RUN npm run generate
# 或直接执行：npx prisma generate

# 复制源码
COPY --chown=node:node . .

# 构建应用
RUN npm run build

# ==================== 生产阶段 ====================
FROM node:18-alpine AS production

USER node
WORKDIR /home/node/app

# 复制 package.json
COPY --from=builder --chown=node:node /home/node/app/package*.json ./

# 安装生产依赖
RUN npm install --production
# 或使用：npm install --omit=dev

# 拷贝 Prisma Client（关键步骤）
COPY --from=builder --chown=node:node /home/node/app/node_modules/.prisma ./node_modules/.prisma
COPY --from=builder --chown=node:node /home/node/app/node_modules/@prisma ./node_modules/@prisma

# 拷贝构建产物
COPY --from=builder --chown=node:node /home/node/app/dist ./dist

# 拷贝 Prisma schema（运行迁移时需要）
COPY --from=builder --chown=node:node /home/node/app/prisma ./prisma

# 暴露端口
EXPOSE 3000

# 设置环境变量
ENV NODE_ENV=production

# 启动应用
CMD ["node", "dist/main.js"]

Prisma Client 文件结构：
│
├── node_modules/.prisma/client/
│   ├── index.js           # 入口文件
│   ├── schema.prisma      # Schema 副本
│   ├── runtime/           # 运行时库
│   └── default.js         # 默认导出
│
└── node_modules/@prisma/client/
    ├── index.js
    └── ...（符号链接）

# 两种方式等价
npm install --production
npm install --omit=dev

# 区别
# --production：npm 6+ 支持
# --omit=dev：npm 8.10+ 支持，更语义化

文件拷贝顺序（关键）：
│
├── 1. package.json
│   └── 定义依赖版本
│
├── 2. npm install --production
│   └── 安装生产依赖到 node_modules
│
├── 3. 拷贝 Prisma Client 
│   └── 覆盖/添加到 node_modules
│
└── 4. 拷贝 dist 目录
    └── 最后拷贝构建产物

为什么这个顺序很重要？
├── 如果先拷贝 dist，再安装依赖
│   └── 可能覆盖某些文件（极少见）
│
└── 正确顺序确保依赖完整
    └── Prisma Client 正确集成

# .dockerignore
node_modules
dist
.git
.github
.env*
*.log
.DS_Store
logs

# 停止并删除旧容器
docker stop test
docker rm test

# 使用环境变量运行
docker run \
  -d \
  --name nest-app \
  -p 8000:3000 \
  -e DATABASE_URL="postgresql://user:password@host:5432/db" \
  nest-app:1.0

# .env
DATABASE_URL="postgresql://postgres:password@postgres:5432/mydb"
JWT_SECRET="your-secret-key"
PORT=3000
NODE_ENV=production

version: '3.8'

services:
  # 数据库服务
  postgres:
    image: postgres:15-alpine
    container_name: postgres-db
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - app-network

  # NestJS 应用
  nest-app:
    image: nest-app:1.0
    container_name: nest-app-prod
    restart: always
    ports:
      - "8000:3000"
    env_file:
      - .env  # 引用环境变量文件
    depends_on:
      - postgres
    networks:
      - app-network

volumes:
  postgres-data:

networks:
  app-network:
    driver: bridge

日志映射的必要性：
│
├── 1. 问题排查 
│   ├── 容器删除后日志丢失
│   ├── 需要保留历史日志
│   └── 便于回溯问题
│
├── 2. 日志分析 
│   ├── 统一日志收集
│   ├── ELK 集成
│   └── 监控告警
│
├── 3. 合规要求 
│   ├── 审计日志保留
│   ├── 安全合规
│   └── 数据备份
│
└── 4. 便捷查看 
    ├── 无需进入容器
    ├── 宿主机直接查看
    └── 使用熟悉的工具

version: '3.8'

services:
  nest-app:
    image: nest-app:1.0
    container_name: nest-app-prod
    restart: always
    ports:
      - "8000:3000"
    env_file:
      - .env
    volumes:
      # 日志映射：容器路径 → 宿主机路径
      - ./logs:/home/node/app/logs
      # 其他可能的映射
      - ./uploads:/home/node/app/uploads
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import * as fs from 'fs';
import * as path from 'path';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: ['error', 'warn', 'log'],
  });

  // 确保日志目录存在
  const logDir = path.join(__dirname, '..', 'logs');
  if (!fs.existsSync(logDir)) {
    fs.mkdirSync(logDir, { recursive: true });
  }

  await app.listen(3000);
}
bootstrap();

#  不推荐（Windows 可能失败）
volumes:
  - ./logs:/home/node/app/logs

#  推荐（使用绝对路径）
volumes:
  - /c/Users/YourName/project/logs:/home/node/app/logs
  # 或 Windows 路径格式
  - C:\Users\YourName\project\logs:/home/node/app/logs

# 进入容器查看
docker exec -it nest-app-prod sh
ls /home/node/app/logs

# 在宿主机查看
ls ./logs

# 两者应该内容一致

# ==================== 第一步：构建镜像 ====================
docker build -t nest-app:1.0 .

# 查看构建结果
docker images | grep nest-app

# ==================== 第二步：运行容器（测试） ====================
docker run -d --name test -p 8000:3000 nest-app:1.0

# 查看运行状态
docker ps

# 查看日志
docker logs -f test

# ==================== 第三步：测试接口 ====================
# 访问健康检查接口
curl http://localhost:8000/api

# 预期错误（未配置数据库）
# PrismaClientInitializationError: Can't reach database server

# ==================== 第四步：配置环境变量 ====================
# 停止并删除测试容器
docker stop test
docker rm test

# 创建 .env 文件
cat > .env << EOF
DATABASE_URL="postgresql://postgres:password@postgres:5432/mydb"
JWT_SECRET="your-secret-key"
EOF

# ==================== 第五步：使用 Docker Compose 启动 ====================
docker compose up -d

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f nest-app

# ==================== 第六步：验证服务 ====================
curl http://localhost:8000/api

# 预期输出：正常响应数据

# ==================== 服务管理 ====================
# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 重新构建并启动
docker compose up -d --build

# ==================== 日志查看 ====================
# 查看所有服务日志
docker compose logs

# 查看特定服务日志
docker compose logs nest-app

# 实时查看日志
docker compose logs -f nest-app

# 查看最后 100 行
docker compose logs --tail 100 nest-app

# ==================== 进入容器 ====================
# 进入应用容器
docker compose exec nest-app sh

# 进入数据库容器
docker compose exec postgres sh

# 以 root 用户进入
docker compose exec -u root nest-app sh

# ==================== 数据库操作 ====================
# 运行 Prisma 迁移
docker compose exec nest-app npx prisma migrate deploy

# 打开 Prisma Studio
docker compose exec nest-app npx prisma studio

# 查看数据库
docker compose exec postgres psql -U postgres -d mydb

NestJS 容器问题排查：
│
├── 1. 构建失败
│   ├── 检查 Dockerfile 语法
│   ├── 查看构建日志定位错误步骤
│   ├── 验证 .dockerignore 配置
│   └── 检查 prisma generate 是否执行
│
├── 2. 启动失败
│   ├── docker logs 查看容器日志
│   ├── 检查环境变量是否正确
│   ├── 验证数据库连接
│   └── 检查端口映射
│
├── 3. 数据库连接失败 
│   ├── DATABASE_URL 配置错误
│   ├── 数据库服务未启动
│   ├── 网络不通（容器间通信）
│   └── 防火墙阻止
│
└── 4. Prisma 错误
    ├── Prisma Client 未生成
    ├── 未拷贝 .prisma 目录
    └── Schema 文件缺失

#  错误示例（使用 localhost）
DATABASE_URL="postgresql://postgres:password@localhost:5432/mydb"

# 问题：
# - localhost 在容器内指向容器自身
# - 数据库在另一个容器中
# - 网络不通

#  正确示例（使用服务名）
DATABASE_URL="postgresql://postgres:password@postgres:5432/mydb"

# 说明：
# - postgres 是 docker-compose.yml 中定义的服务名
# - Docker Compose 自动创建 DNS 解析
# - 容器间通过服务名通信

# 进入应用容器
docker compose exec nest-app sh

# 测试数据库连通性
ping postgres

# 使用 nc 测试端口
nc -zv postgres 5432

# 预期输出：Connection to postgres 5432 port [tcp/postgresql] succeeded!

version: '3.8'

services:
  # PostgreSQL 数据库
  postgres:
    image: postgres:15-alpine
    container_name: postgres-prod
    restart: always
    environment:
      POSTGRES_USER: ${DB_USER:-postgres}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-password}
      POSTGRES_DB: ${DB_NAME:-mydb}
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - app-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  # NestJS 应用
  nest-app:
    image: nest-app:1.0
    container_name: nest-app-prod
    restart: always
    ports:
      - "8000:3000"
    env_file:
      - .env
    volumes:
      - ./logs:/home/node/app/logs
      - ./uploads:/home/node/app/uploads
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - app-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  # Nginx 反向代理（可选）
  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - nest-app
    networks:
      - app-network

volumes:
  postgres-data:
    driver: local

networks:
  app-network:
    driver: bridge

# 方式一：简单依赖（不等待启动完成）
depends_on:
  - postgres

# 方式二：条件依赖（等待健康检查通过）
depends_on:
  postgres:
    condition: service_healthy

# 说明：
# - service_healthy：等待健康检查通过
# - service_started：等待容器启动（默认）
# - service_completed_successfully：等待容器执行完成

# PostgreSQL 健康检查
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres"]
  interval: 10s      # 检查间隔
  timeout: 5s        # 超时时间
  retries: 5         # 重试次数
  start_period: 10s  # 启动等待时间

# NestJS 应用健康检查
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s  # 给应用足够的启动时间

生产环境安全配置：
│
├── 1. 非 root 用户运行 
│   ├── USER node
│   ├── WORKDIR /home/node/app
│   └── COPY --chown=node:node
│
├── 2. 环境变量安全 
│   ├── .env 文件不入 Git
│   ├── 使用 Docker Secrets（Kubernetes）
│   └── 敏感信息加密存储
│
├── 3. 网络隔离 
│   ├── 用户定义网络
│   ├── 不暴露不必要的端口
│   └── 数据库端口仅内网访问
│
├── 4. 镜像安全 
│   ├── 使用官方基础镜像
│   ├── 定期更新基础镜像
│   ├── 镜像漏洞扫描
│   └── 使用特定版本标签（不用 latest）
│
└── 5. 日志管理 
    ├── 日志映射到宿主机
    ├── 日志轮转配置
    └── 统一日志收集系统

# ==================== 构建缓存优化 ====================
# 先复制依赖文件，利用 Docker 缓存
COPY package*.json ./
COPY prisma ./prisma/
RUN npm install

# 再复制源码（源码变化频繁）
COPY . .
RUN npm run build

# ==================== 层合并优化 ====================
# 合并多个 RUN 命令
RUN npm install && \
    npm run build && \
    npm cache clean --force

# ==================== 基础镜像选择 ====================
# 生产环境推荐
FROM node:18-alpine  # 体积小（~170MB）

# 开发环境可用
FROM node:18-slim    # 兼容性好（~240MB）
FROM node:18         # 功能全（~900MB）

# docker-compose.yml 添加监控
services:
  # 应用监控（可选）
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana
    ports:
      - "3001:3000"
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  grafana-data:

推荐学习路径：
│
├── 1. CI/CD 自动化
│   ├── GitHub Actions
│   ├── 自动化测试
│   └── 自动化部署
│
├── 2. Kubernetes 部署
│   ├── Deployment 配置
│   ├── Service 配置
│   ├── Ingress 配置
│   └── ConfigMap 和 Secrets
│
├── 3. 数据库迁移
│   ├── Prisma Migrate
│   ├── 自动化迁移脚本
│   └── 多环境管理
│
├── 4. 监控与日志
│   ├── ELK Stack
│   ├── Prometheus + Grafana
│   └── 日志收集与分析
│
└── 5. 性能优化
    ├── 连接池配置
    ├── 缓存策略
    └── 负载均衡

# 多阶段构建
FROM node:18-alpine AS builder
FROM node:18-alpine AS production

# 安全配置
USER node
WORKDIR /home/node/app
COPY --chown=node:node . .

# Prisma 相关
COPY prisma ./prisma/
RUN npm run generate
COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma
COPY --from=builder /app/node_modules/@prisma ./node_modules/@prisma

# 生产依赖
RUN npm install --production
# 或
RUN npm install --omit=dev

# 构建镜像
docker build -t nest-app:1.0 .

# 运行容器
docker run -d --name nest-app -p 8000:3000 -e DATABASE_URL="xxx" nest-app:1.0

# Docker Compose
docker compose up -d          # 启动
docker compose down           # 停止
docker compose logs -f        # 查看日志
docker compose restart        # 重启
docker compose ps             # 查看状态

# 数据库操作
docker compose exec nest-app npx prisma migrate deploy  # 运行迁移
docker compose exec nest-app npx prisma studio          # 打开 Studio

# 调试命令
docker compose exec nest-app sh              # 进入容器
docker compose exec postgres psql -U postgres # 进入数据库
docker logs -f nest-app                      # 查看日志

# .env
DATABASE_URL="postgresql://postgres:password@postgres:5432/mydb"
JWT_SECRET="your-jwt-secret-key"
PORT=3000
NODE_ENV=production

# 可选
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=mydb