Docker部署

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: Docker, 容器, 容器化, docker-compose, 容器部署
---

# Docker 部署指南

## &#128051; 使用 Docker 快速部署

Docker 部署可以简化环境配置，确保开发、测试、生产环境的一致性。

---

## &#128203; 前置要求

### 必需软件
- Docker 20.10 或更高版本
- Docker Compose 2.0 或更高版本

### 安装 Docker

**Ubuntu/Debian:**
```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
```

**CentOS/RHEL:**
```bash
sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker
```

**安装 Docker Compose:**
```bash
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 或使用 Docker 插件
sudo apt install -y docker-compose-plugin
```

### 验证安装
```bash
docker --version
docker-compose --version
# 或
docker compose version
```

---

## &#128221; 创建 Docker 配置文件

### 1. Dockerfile
创建 `Dockerfile`：

```dockerfile
# 使用官方 Node.js 镜像
FROM node:20-slim

# 设置工作目录
WORKDIR /app

# 安装 pnpm
RUN npm install -g pnpm

# 复制依赖文件
COPY package.json pnpm-lock.yaml ./

# 安装依赖
RUN pnpm install --frozen-lockfile

# 复制源代码
COPY . .

# 构建应用
RUN pnpm build

# 暴露端口
EXPOSE 5000

# 启动应用
CMD ["pnpm", "start"]
```

### 2. docker-compose.yml
创建 `docker-compose.yml`：

```yaml
version: '3.8'

services:
  # PostgreSQL 数据库
  postgres:
    image: postgres:15-alpine
    container_name: payroll-postgres
    environment:
      POSTGRES_USER: payroll_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: payroll
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - payroll-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U payroll_user -d payroll"]
      interval: 10s
      timeout: 5s
      retries: 5

# Redis 缓存（可选）
  redis:
    image: redis:7-alpine
    container_name: payroll-redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    networks:
      - payroll-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

# 应用服务
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: payroll-app
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://payroll_user:${DB_PASSWORD}@postgres:5432/payroll?sslmode=disable
      NEXT_PUBLIC_APP_URL: ${APP_URL}
      JWT_SECRET: ${JWT_SECRET}
      ADMIN_USERNAME: ${ADMIN_USERNAME}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      ADMIN_EMAIL: ${ADMIN_EMAIL}
      OSS_ENDPOINT: ${OSS_ENDPOINT}
      OSS_ACCESS_KEY_ID: ${OSS_ACCESS_KEY_ID}
      OSS_SECRET_KEY: ${OSS_SECRET_KEY}
      OSS_BUCKET: ${OSS_BUCKET}
      SMS_ACCESS_KEY_ID: ${SMS_ACCESS_KEY_ID}
      SMS_SECRET_KEY: ${SMS_SECRET_KEY}
      SMS_SIGN_NAME: ${SMS_SIGN_NAME}
      SMS_TEMPLATE_CODE: ${SMS_TEMPLATE_CODE}
      WECHAT_APP_ID: ${WECHAT_APP_ID}
      WECHAT_APP_SECRET: ${WECHAT_APP_SECRET}
    ports:
      - "5000:5000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - payroll-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

# Nginx 反向代理
  nginx:
    image: nginx:alpine
    container_name: payroll-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - app
    networks:
      - payroll-network
    restart: unless-stopped

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

networks:
  payroll-network:
    driver: bridge
```

### 3. .env.docker
创建 `.env.docker`：

```bash
# 数据库配置
DB_PASSWORD=your_strong_db_password_here

# 应用配置
APP_URL=http://localhost:5000

# JWT密钥
JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters-long-change-this

# 管理员账号
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-very-strong-password-here
ADMIN_EMAIL=admin@yourdomain.com

# 对象存储（可选）
OSS_ENDPOINT=
OSS_ACCESS_KEY_ID=
OSS_SECRET_KEY=
OSS_BUCKET=

# 短信服务（可选）
SMS_ACCESS_KEY_ID=
SMS_SECRET_KEY=
SMS_SIGN_NAME=
SMS_TEMPLATE_CODE=

# 微信集成（可选）
WECHAT_APP_ID=
WECHAT_APP_SECRET=
```

### 4. nginx.conf
创建 `nginx.conf`：

```nginx
events {
    worker_connections 1024;
}

http {
    upstream app {
        server app:5000;
    }

server {
        listen 80;
        server_name localhost;

client_max_body_size 20M;

location / {
            proxy_pass http://app;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            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_cache_bypass $http_upgrade;
        }
    }
}
```

### 5. .dockerignore
创建 `.dockerignore`：

```
node_modules
.next
.git
.gitignore
.env
.env.local
.env.*.local
README.md
docs
data-export
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
*.md
```

---

## &#128640; 部署步骤

### 1. 克隆代码
```bash
git clone <your-repository-url> /var/www/payroll
cd /var/www/payroll
```

### 2. 配置环境变量
```bash
cp .env.docker .env
nano .env
```

### 3. 构建并启动服务
```bash
# 使用 docker-compose（旧版本）
docker-compose up -d

# 或使用 Docker 插件（新版本）
docker compose up -d
```

### 4. 初始化数据库
```bash
# 进入应用容器
docker exec -it payroll-app bash

# 运行数据库迁移
pnpm db:migrate

# 导入初始数据
pnpm db:seed

# 退出容器
exit
```

### 5. 查看服务状态
```bash
# 查看所有容器
docker ps

# 查看应用日志
docker logs -f payroll-app

# 查看数据库日志
docker logs -f payroll-postgres
```

---

## &#128260; 常用操作

### 查看服务状态
```bash
docker ps
docker compose ps
```

### 查看日志
```bash
# 查看应用日志
docker logs -f payroll-app

# 查看最近 100 行日志
docker logs --tail 100 payroll-app

# 查看所有服务日志
docker compose logs -f
```

### 重启服务
```bash
# 重启所有服务
docker compose restart

# 重启特定服务
docker compose restart app
docker compose restart postgres
```

### 停止服务
```bash
docker compose stop
```

### 启动服务
```bash
docker compose start
```

### 删除服务（包括数据）
```bash
docker compose down -v
```

### 更新应用
```bash
# 拉取最新代码
git pull

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

# 清理旧镜像
docker image prune -a
```

### 进入容器
```bash
# 进入应用容器
docker exec -it payroll-app bash

# 进入数据库容器
docker exec -it payroll-postgres psql -U payroll_user -d payroll
```

---

## &#128190; 数据备份

### 备份数据库
```bash
# 创建备份目录
mkdir -p backups

# 备份数据库
docker exec payroll-postgres pg_dump -U payroll_user payroll > backups/payroll_$(date +%Y%m%d).sql

# 压缩备份
gzip backups/payroll_$(date +%Y%m%d).sql
```

### 恢复数据库
```bash
# 解压备份
gunzip backups/payroll_20240101.sql.gz

# 恢复数据库
cat backups/payroll_20240101.sql | docker exec -i payroll-postgres psql -U payroll_user -d payroll
```

### 备份卷
```bash
# 备份所有卷
docker run --rm -v postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_data.tar.gz /data

# 恢复卷
docker run --rm -v postgres_data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres_data.tar.gz
```

---

## &#128202; 性能优化

### 1. 限制资源使用
在 `docker-compose.yml` 中添加：

```yaml
app:
  # ... 其他配置
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 2G
      reservations:
        cpus: '1'
        memory: 1G
```

### 2. 启用多阶段构建
优化 `Dockerfile`：

```dockerfile
# 构建阶段
FROM node:20-slim AS builder
WORKDIR /app
RUN npm install -g pnpm
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

# 运行阶段
FROM node:20-slim AS runner
WORKDIR /app
RUN npm install -g pnpm
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --prod --frozen-lockfile
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma
EXPOSE 5000
CMD ["pnpm", "start"]
```

### 3. 使用缓存层
在 `docker-compose.yml` 中添加 Redis 缓存：

```yaml
redis:
  image: redis:7-alpine
  # ... 配置
```

---

## &#128274; 安全配置

### 1. 使用 secrets
创建 `.env.production`（不提交到 git）：

```bash
cp .env.docker .env.production
nano .env.production
```

在 `.gitignore` 中添加：

```
.env.production
.env
.env.local
```

### 2. 配置 SSL
在 `nginx.conf` 中添加 HTTPS 配置：

```nginx
server {
    listen 443 ssl http2;
    server_name yourdomain.com;

ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

# ... 其他配置
}
```

挂载 SSL 证书：

```yaml
nginx:
  # ... 其他配置
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro
    - ./ssl:/etc/nginx/ssl:ro
```

---

## &#128027; 故障排查

### 问题 1：容器无法启动
```bash
# 查看容器日志
docker logs payroll-app

# 查看容器详细信息
docker inspect payroll-app

# 重新构建
docker compose up -d --build
```

### 问题 2：数据库连接失败
```bash
# 测试数据库连接
docker exec -it payroll-postgres psql -U payroll_user -d payroll

# 检查数据库状态
docker exec payroll-postgres pg_isready -U payroll_user

# 查看数据库日志
docker logs payroll-postgres
```

### 问题 3：端口冲突
```bash
# 检查端口占用
sudo netstat -tlnp | grep 5000

# 修改 docker-compose.yml 中的端口映射
ports:
  - "8080:5000"  # 使用 8080 端口
```

### 问题 4：权限问题
```bash
# 修复文件权限
sudo chown -R $USER:$USER .

# 或在 Docker Compose 中指定用户
app:
  user: node
  # ... 其他配置
```

---

## &#128218; 参考资源

- [Docker 官方文档](https://docs.docker.com/)
- [Docker Compose 文档](https://docs.docker.com/compose/)
- [Node.js 最佳实践](https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md)

---

## ✅ 部署检查清单

部署完成后，请确认以下项目：

- [ ] Docker 和 Docker Compose 已安装
- [ ] 环境变量已配置
- [ ] 所有容器正常运行
- [ ] 数据库已初始化
- [ ] 初始数据已导入
- [ ] 应用可以正常访问
- [ ] SSL 证书已配置（如需要）
- [ ] 日志记录正常
- [ ] 备份策略已配置

---

## &#127881; 部署完成！

你的企业管理数字化中台已成功使用 Docker 部署。

Docker 部署的优势：
- ✅ 环境隔离
- ✅ 快速部署
- ✅ 易于扩展
- ✅ 便于迁移

如有问题，请查看 Docker 日志或联系技术支持。