ocdp v1

2025-11-13 02:54:06 +00:00
commit c5e51ed069
254 changed files with 54901 additions and 0 deletions
--- a/docs/deployment/docker-guide.md
+++ b/docs/deployment/docker-guide.md
@ -0,0 +1,453 @@
+# 🐳 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`
+