ocdp-go/docs/deployment/docker-guide.md

# 🐳 Docker Compose 使用指南

完整的 Docker Compose 配置，一键启动所有服务！

## 📋 服务列表

### 核心服务（默认启动）

| 服务 | 端口 | 说明 |
|------|------|------|
| **postgres** | 5432 | PostgreSQL 16 数据库 |
| **redis** | 6379 | Redis 缓存（可选） |
| **backend** | 8080 | Go 后端 API 服务 |
| **frontend** | 3000 | React 前端应用 |

### 可选服务

| 服务 | 端口 | 说明 | Profile |
|------|------|------|---------|
| **nginx** | 80, 443 | 反向代理 | `production` |
| **pgadmin** | 5050 | PostgreSQL 管理工具 | `tools` |
| **swagger-ui** | 8081 | API 文档查看器 | `tools` |

## 🚀 快速开始

### 1. 生产环境启动

```bash
# 启动核心服务（PostgreSQL + Redis + Backend + Frontend）
docker compose up -d

# 查看日志
docker compose logs -f

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

访问：
- 🎨 前端：http://localhost:3000
- 🔧 后端 API：http://localhost:8080
- 📊 健康检查：http://localhost:8080/health

### 2. 开发环境启动（支持热重载）

```bash
# 使用开发配置启动
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# 或使用 Makefile 命令
make docker-dev
```

开发模式特性：
- ✅ 后端支持热重载（使用 Air）
- ✅ 前端支持热重载（Vite）
- ✅ 自动挂载源代码
- ✅ 使用 Mock 模式（无需真实数据）

### 3. 启动可选工具

```bash
# 启动 pgAdmin
docker compose --profile tools up -d pgadmin

# 启动 Swagger UI
docker compose --profile tools up -d swagger-ui

# 启动所有工具
docker compose --profile tools up -d

# 启动生产环境（包含 Nginx）
docker compose --profile production up -d
```

访问工具：
- 📊 pgAdmin：http://localhost:5050
  - 邮箱：`admin@ocdp.local`
  - 密码：`admin`
- 📖 Swagger UI：http://localhost:8081

## 📚 常用命令

### 服务管理

```bash
# 启动所有服务
docker compose up -d

# 启动特定服务
docker compose up -d postgres redis backend

# 停止所有服务
docker compose down

# 停止并删除数据卷
docker compose down -v

# 重启服务
docker compose restart

# 重启特定服务
docker compose restart backend
```

### 日志查看

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

# 查看特定服务日志
docker compose logs -f backend

# 查看最近100行日志
docker compose logs --tail=100 backend

# 实时查看日志（带时间戳）
docker compose logs -f --timestamps backend
```

### 服务状态

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

# 查看服务详细信息
docker compose ps -a

# 查看服务资源使用
docker stats
```

### 进入容器

```bash
# 进入后端容器
docker compose exec backend sh

# 进入 PostgreSQL 容器
docker compose exec postgres psql -U postgres -d ocdp

# 进入 Redis 容器
docker compose exec redis redis-cli
```

### 构建和更新

```bash
# 重新构建镜像
docker compose build

# 重新构建特定服务
docker compose build backend

# 强制重新构建（不使用缓存）
docker compose build --no-cache

# 拉取最新镜像
docker compose pull
```

## 🔧 配置说明

### 环境变量

1. 复制环境变量示例文件：
```bash
cp env.example .env
```

2. 编辑 `.env` 文件，修改必要的配置：
```bash
# 修改 JWT 密钥（生产环境必须修改）
JWT_SECRET=your-very-secure-secret-key

# 修改数据库密码（生产环境建议修改）
DB_PASSWORD=your-secure-password
```

### 数据持久化

数据卷：
- `postgres_data` - PostgreSQL 数据
- `redis_data` - Redis 数据
- `backend_data` - 后端应用数据
- `pgadmin_data` - pgAdmin 配置
- `nginx_logs` - Nginx 日志

查看数据卷：
```bash
docker volume ls | grep ocdp
```

备份数据卷：
```bash
# 备份 PostgreSQL
docker compose exec postgres pg_dump -U postgres ocdp > backup.sql

# 或使用 Docker 卷备份
docker run --rm -v ocdp-go_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz -C /data .
```

恢复数据：
```bash
# 恢复 PostgreSQL
docker compose exec -T postgres psql -U postgres ocdp < backup.sql

# 或恢复卷
docker run --rm -v ocdp-go_postgres_data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres-backup.tar.gz -C /data
```

## 🏗️ 服务架构

```
┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ↓
┌─────────────┐      ┌─────────────┐
│   Nginx     │      │  Swagger UI │
│   (80)      │      │   (8081)    │
└──────┬──────┘      └─────────────┘
       │
       ↓
┌─────────────┐
│  Frontend   │
│   (3000)    │
└──────┬──────┘
       │
       ↓
┌─────────────┐
│   Backend   │
│   (8080)    │
└──┬────┬─────┘
   │    │
   │    └─────────┐
   ↓              ↓
┌─────────┐  ┌─────────┐
│Postgres │  │  Redis  │
│ (5432)  │  │ (6379)  │
└────┬────┘  └─────────┘
     │
     ↓
┌─────────┐
│pgAdmin  │
│ (5050)  │
└─────────┘
```

## 🔍 健康检查

所有服务都配置了健康检查：

```bash
# 检查所有服务健康状态
docker compose ps

# 检查特定服务
curl http://localhost:8080/health  # Backend
curl http://localhost:3000/health  # Frontend
```

健康状态说明：
- `healthy` - 服务正常运行
- `starting` - 服务正在启动
- `unhealthy` - 服务异常

## 🐛 故障排查

### 问题 1: 端口冲突

**错误**：`port is already allocated`

**解决方案**：
```bash
# 查看端口占用
lsof -i :8080

# 修改 docker-compose.yml 中的端口映射（如需更改）
ports:
  - "8081:8080"  # 将主机端口改为 8081
```

### 问题 2: 数据库连接失败

**错误**：`connection refused`

**解决方案**：
```bash
# 1. 检查 PostgreSQL 是否启动
docker compose ps postgres

# 2. 查看 PostgreSQL 日志
docker compose logs postgres

# 3. 等待健康检查通过
docker compose ps | grep healthy

# 4. 手动测试连接
docker compose exec postgres psql -U postgres -d ocdp
```

### 问题 3: 构建失败

**错误**：`build failed`

**解决方案**：
```bash
# 1. 清理旧的镜像和容器
docker compose down -v
docker system prune -a

# 2. 重新构建（不使用缓存）
docker compose build --no-cache

# 3. 检查 Dockerfile 和 .dockerignore
```

### 问题 4: 容器不断重启

**解决方案**：
```bash
# 查看容器日志
docker compose logs --tail=100 [service-name]

# 检查健康检查状态
docker inspect ocdp-backend | grep -A 20 Health

# 禁用健康检查测试
# 在 docker-compose.yml 中注释掉 healthcheck 部分
```

### 问题 5: 数据持久化失败

**解决方案**：
```bash
# 检查数据卷
docker volume ls
docker volume inspect ocdp-go_postgres_data

# 检查挂载权限
docker compose exec postgres ls -la /var/lib/postgresql/data
```

## 🔒 安全建议

### 生产环境

1. **修改默认密码**：
```bash
# .env 文件中
DB_PASSWORD=your-secure-password
JWT_SECRET=your-very-secure-secret-key
```

2. **使用 secrets**：
```yaml
# docker-compose.yml
secrets:
  db_password:
    file: ./secrets/db_password.txt
```

3. **限制容器权限**：
```yaml
services:
  backend:
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
```

4. **使用专用网络**：
```yaml
networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # 不能访问外网
```

## 📊 监控和日志

### 日志聚合

```bash
# 使用 ELK Stack
docker compose -f docker-compose.yml -f docker-compose.logging.yml up -d

# 或使用 Loki
docker compose -f docker-compose.yml -f docker-compose.loki.yml up -d
```

### 性能监控

```bash
# 查看资源使用
docker stats

# 限制资源使用
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
```

## 🎯 最佳实践

1. **使用多阶段构建** - 减小镜像大小
2. **配置健康检查** - 确保服务可用性
3. **使用 .dockerignore** - 排除不必要的文件
4. **使用非 root 用户** - 提高安全性
5. **配置日志驱动** - 集中管理日志
6. **使用 depends_on 和 healthcheck** - 确保启动顺序
7. **使用 profiles** - 按需启动服务

## 🔗 相关命令（Makefile）

项目 Makefile 已集成 Docker Compose 命令：

```bash
make docker-up        # 启动所有服务
make docker-down      # 停止所有服务
make docker-logs      # 查看日志
make docker-dev       # 开发模式启动
make docker-build     # 重新构建镜像
```

## 📚 更多资源

- [Docker Compose 文档](https://docs.docker.com/compose/)
- [Docker 最佳实践](https://docs.docker.com/develop/dev-best-practices/)
- [项目 README](README.md)

---

**提示**: 首次启动可能需要几分钟来下载镜像和构建容器，请耐心等待！

有问题？查看日志：`docker compose logs -f`