9.2 KiB
9.2 KiB
🐳 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. 生产环境启动
# 启动核心服务（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. 开发环境启动（支持热重载）
# 使用开发配置启动
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
# 或使用 Makefile 命令
make docker-dev
开发模式特性：
- ✅ 后端支持热重载（使用 Air）
- ✅ 前端支持热重载（Vite）
- ✅ 自动挂载源代码
- ✅ 使用 Mock 模式（无需真实数据）
3. 启动可选工具
# 启动 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
📚 常用命令
服务管理
# 启动所有服务
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
日志查看
# 查看所有服务日志
docker compose logs -f
# 查看特定服务日志
docker compose logs -f backend
# 查看最近100行日志
docker compose logs --tail=100 backend
# 实时查看日志（带时间戳）
docker compose logs -f --timestamps backend
服务状态
# 查看服务状态
docker compose ps
# 查看服务详细信息
docker compose ps -a
# 查看服务资源使用
docker stats
进入容器
# 进入后端容器
docker compose exec backend sh
# 进入 PostgreSQL 容器
docker compose exec postgres psql -U postgres -d ocdp
# 进入 Redis 容器
docker compose exec redis redis-cli
构建和更新
# 重新构建镜像
docker compose build
# 重新构建特定服务
docker compose build backend
# 强制重新构建（不使用缓存）
docker compose build --no-cache
# 拉取最新镜像
docker compose pull
🔧 配置说明
环境变量
- 复制环境变量示例文件：
cp env.example .env
- 编辑
.env文件，修改必要的配置：
# 修改 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 日志
查看数据卷：
docker volume ls | grep ocdp
备份数据卷：
# 备份 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 .
恢复数据：
# 恢复 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) │
└─────────┘
🔍 健康检查
所有服务都配置了健康检查：
# 检查所有服务健康状态
docker compose ps
# 检查特定服务
curl http://localhost:8080/health # Backend
curl http://localhost:3000/health # Frontend
健康状态说明：
healthy- 服务正常运行starting- 服务正在启动unhealthy- 服务异常
🐛 故障排查
问题 1: 端口冲突
错误：port is already allocated
解决方案：
# 查看端口占用
lsof -i :8080
# 修改 docker-compose.yml 中的端口映射（如需更改）
ports:
- "8081:8080" # 将主机端口改为 8081
问题 2: 数据库连接失败
错误：connection refused
解决方案：
# 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
解决方案：
# 1. 清理旧的镜像和容器
docker compose down -v
docker system prune -a
# 2. 重新构建（不使用缓存）
docker compose build --no-cache
# 3. 检查 Dockerfile 和 .dockerignore
问题 4: 容器不断重启
解决方案：
# 查看容器日志
docker compose logs --tail=100 [service-name]
# 检查健康检查状态
docker inspect ocdp-backend | grep -A 20 Health
# 禁用健康检查测试
# 在 docker-compose.yml 中注释掉 healthcheck 部分
问题 5: 数据持久化失败
解决方案：
# 检查数据卷
docker volume ls
docker volume inspect ocdp-go_postgres_data
# 检查挂载权限
docker compose exec postgres ls -la /var/lib/postgresql/data
🔒 安全建议
生产环境
- 修改默认密码：
# .env 文件中
DB_PASSWORD=your-secure-password
JWT_SECRET=your-very-secure-secret-key
- 使用 secrets：
# docker-compose.yml
secrets:
db_password:
file: ./secrets/db_password.txt
- 限制容器权限：
services:
backend:
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
- 使用专用网络：
networks:
frontend:
driver: bridge
backend:
driver: bridge
internal: true # 不能访问外网
📊 监控和日志
日志聚合
# 使用 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
性能监控
# 查看资源使用
docker stats
# 限制资源使用
services:
backend:
deploy:
resources:
limits:
cpus: '1'
memory: 512M
reservations:
cpus: '0.5'
memory: 256M
🎯 最佳实践
- 使用多阶段构建 - 减小镜像大小
- 配置健康检查 - 确保服务可用性
- 使用 .dockerignore - 排除不必要的文件
- 使用非 root 用户 - 提高安全性
- 配置日志驱动 - 集中管理日志
- 使用 depends_on 和 healthcheck - 确保启动顺序
- 使用 profiles - 按需启动服务
🔗 相关命令（Makefile）
项目 Makefile 已集成 Docker Compose 命令：
make docker-up # 启动所有服务
make docker-down # 停止所有服务
make docker-logs # 查看日志
make docker-dev # 开发模式启动
make docker-build # 重新构建镜像
📚 更多资源
提示: 首次启动可能需要几分钟来下载镜像和构建容器，请耐心等待！
有问题？查看日志：docker compose logs -f