454 lines
9.2 KiB
Markdown
454 lines
9.2 KiB
Markdown
# 🐳 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`
|
||
|