ocdp v1
This commit is contained in:
mangomqy
435
docs/archive/DOCKER_SERVICES.md
Normal file
435
docs/archive/DOCKER_SERVICES.md
Normal file
@ -0,0 +1,435 @@
|
||||
# OCDP Docker 服务架构
|
||||
|
||||
## 📋 项目概述
|
||||
|
||||
OCDP 采用微服务架构，包含以下核心服务：
|
||||
|
||||
### 核心服务
|
||||
1. **Backend API** - Go 后端服务（支持 Mock/Production 模式）
|
||||
2. **Frontend** - React + TypeScript 前端应用
|
||||
3. **PostgreSQL** - 主数据库（生产模式）
|
||||
4. **Redis** - 缓存服务（生产模式）
|
||||
|
||||
### 可选服务
|
||||
- **pgAdmin** - PostgreSQL 管理工具
|
||||
- **Swagger UI** - API 文档查看器
|
||||
|
||||
---
|
||||
|
||||
## 🎯 运行模式说明
|
||||
|
||||
### 1. **生产模式（Real Mode）**
|
||||
- 所有服务连接真实的数据库和外部依赖
|
||||
- 适用于：生产环境、集成测试
|
||||
- 使用配置：`docker-compose.yml`
|
||||
|
||||
### 2. **开发模式（Dev Mode）**
|
||||
- 支持热重载（后端使用 Air，前端使用 Vite HMR）
|
||||
- 后端使用 Mock 适配器，不依赖数据库
|
||||
- 前端连接后端 Mock 数据
|
||||
- 适用于：日常开发、快速迭代
|
||||
- 使用配置：`docker-compose.yml` + `docker-compose.dev.yml`
|
||||
|
||||
### 3. **Mock 模式（独立测试）**
|
||||
- 每个服务完全独立，Mock 所有外部依赖
|
||||
- 适用于：单独测试某个服务
|
||||
- 使用配置：`docker-compose.mock.yml`
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Dockerfile 说明
|
||||
|
||||
### Backend Dockerfiles
|
||||
|
||||
| 文件 | 用途 | 特点 |
|
||||
|------|------|------|
|
||||
| `backend/Dockerfile` | 生产环境 | 多阶段构建，连接真实数据库 |
|
||||
| `backend/Dockerfile.dev` | 开发环境 | 使用 Air 热重载，挂载源代码 |
|
||||
| `backend/Dockerfile.mock` | Mock 测试 | Mock 所有外部依赖，独立运行 |
|
||||
|
||||
### Frontend Dockerfiles
|
||||
|
||||
| 文件 | 用途 | 特点 |
|
||||
|------|------|------|
|
||||
| `frontend/Dockerfile` | 生产环境 | Nginx 静态文件服务 |
|
||||
| `frontend/Dockerfile.dev` | 开发环境 | Vite Dev Server + HMR |
|
||||
| `frontend/Dockerfile.mock` | Mock 测试 | 使用前端 Mock 数据 |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 场景 1: 生产环境部署（Real Mode）
|
||||
|
||||
```bash
|
||||
# 启动所有服务（包含数据库）
|
||||
docker compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker compose logs -f
|
||||
|
||||
# 访问服务
|
||||
# - Frontend: http://localhost:3000
|
||||
# - Backend: http://localhost:8080
|
||||
# - pgAdmin: http://localhost:5050 (需要 --profile tools)
|
||||
```
|
||||
|
||||
**环境变量**：
|
||||
```bash
|
||||
export JWT_SECRET="your-production-secret"
|
||||
export ENCRYPTION_KEY="your-production-encryption-key-32-bytes"
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 场景 2: 开发环境（Dev Mode）
|
||||
|
||||
```bash
|
||||
# 启动开发环境（不需要数据库，使用 Mock）
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
|
||||
|
||||
# 或后台运行
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
|
||||
|
||||
# 访问服务
|
||||
# - Frontend: http://localhost:5173 (Vite Dev Server)
|
||||
# - Backend: http://localhost:8080 (Mock Mode)
|
||||
```
|
||||
|
||||
**特点**：
|
||||
- ✅ 后端自动重载（Air）
|
||||
- ✅ 前端 HMR（Vite）
|
||||
- ✅ 不需要数据库（Mock 模式）
|
||||
- ✅ 快速启动，适合日常开发
|
||||
|
||||
### 场景 3: 独立测试后端（Backend Mock）
|
||||
|
||||
```bash
|
||||
# 只启动后端 Mock 服务
|
||||
docker compose -f docker-compose.mock.yml up backend
|
||||
|
||||
# 测试 API
|
||||
curl http://localhost:8080/health
|
||||
curl http://localhost:8080/api/v1/registries
|
||||
```
|
||||
|
||||
### 场景 4: 独立测试前端（Frontend Mock）
|
||||
|
||||
```bash
|
||||
# 只启动前端 Mock 服务
|
||||
docker compose -f docker-compose.mock.yml up frontend
|
||||
|
||||
# 访问前端
|
||||
# http://localhost:3000
|
||||
```
|
||||
|
||||
### 场景 5: 开发模式 + 真实数据库（可选）
|
||||
|
||||
```bash
|
||||
# 如果需要真实数据库进行开发
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile with-db up
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
ocdp-go/
|
||||
├── backend/ # 后端服务
|
||||
│ ├── Dockerfile # 生产环境
|
||||
│ ├── Dockerfile.dev # 开发环境（热重载）
|
||||
│ ├── Dockerfile.mock # Mock 测试
|
||||
│ ├── .air.toml # Air 配置（热重载）
|
||||
│ ├── cmd/api/main.go # 入口文件
|
||||
│ ├── internal/ # 内部代码
|
||||
│ ├── config/ # 配置文件
|
||||
│ └── data/ # Mock 数据
|
||||
│
|
||||
├── frontend/ # 前端服务
|
||||
│ ├── Dockerfile # 生产环境
|
||||
│ ├── Dockerfile.dev # 开发环境（Vite Dev Server）
|
||||
│ ├── Dockerfile.mock # Mock 测试
|
||||
│ ├── nginx.conf # Nginx 配置
|
||||
│ ├── src/ # 源代码
|
||||
│ └── package.json # 依赖配置
|
||||
│
|
||||
├── api/ # API 规范
|
||||
│ └── openapi.yaml # OpenAPI 定义
|
||||
│
|
||||
├── docs/ # 文档
|
||||
│ ├── features/ # 功能文档
|
||||
│ ├── deployment/ # 部署文档
|
||||
│ └── development/ # 开发文档
|
||||
│
|
||||
├── docker-compose.yml # 生产模式配置
|
||||
├── docker-compose.dev.yml # 开发模式覆盖
|
||||
├── docker-compose.mock.yml # Mock 模式配置
|
||||
└── Makefile # 便捷命令
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 开发工作流
|
||||
|
||||
### 日常开发流程
|
||||
|
||||
```bash
|
||||
# 1. 启动开发环境
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
|
||||
|
||||
# 2. 修改代码（自动重载）
|
||||
# - 后端代码修改后自动重新编译
|
||||
# - 前端代码修改后 HMR 立即生效
|
||||
|
||||
# 3. 查看日志
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f backend
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f frontend
|
||||
|
||||
# 4. 停止服务
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml down
|
||||
```
|
||||
|
||||
### 测试后端 API
|
||||
|
||||
```bash
|
||||
# 启动后端 Mock
|
||||
docker compose -f docker-compose.mock.yml up backend -d
|
||||
|
||||
# 测试登录
|
||||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}'
|
||||
|
||||
# 测试获取 registries
|
||||
curl http://localhost:8080/api/v1/registries
|
||||
|
||||
# 停止
|
||||
docker compose -f docker-compose.mock.yml down
|
||||
```
|
||||
|
||||
### 构建生产镜像
|
||||
|
||||
```bash
|
||||
# 构建所有镜像
|
||||
docker compose build
|
||||
|
||||
# 只构建后端
|
||||
docker compose build backend
|
||||
|
||||
# 只构建前端
|
||||
docker compose build frontend
|
||||
|
||||
# 无缓存构建
|
||||
docker compose build --no-cache
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 服务详细说明
|
||||
|
||||
### Backend Service
|
||||
|
||||
**环境变量**：
|
||||
|
||||
| 变量 | 说明 | Mock 模式 | Production 模式 |
|
||||
|------|------|-----------|-----------------|
|
||||
| `ADAPTER_MODE` | 适配器模式 | `mock` | `production` |
|
||||
| `PORT` | 服务端口 | `8080` | `8080` |
|
||||
| `DATABASE_URL` | 数据库连接 | 不需要 | 必需 |
|
||||
| `JWT_SECRET` | JWT 密钥 | 任意值 | 强密钥 |
|
||||
| `ENCRYPTION_KEY` | 加密密钥 | 任意值（32字节） | 强密钥（32字节） |
|
||||
|
||||
**健康检查**：
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
# 返回: {"status":"healthy"}
|
||||
```
|
||||
|
||||
**Mock 数据位置**：
|
||||
- `backend/data/` - Mock 数据文件
|
||||
- `backend/internal/adapter/output/persistence/mock/` - Mock 实现
|
||||
|
||||
### Frontend Service
|
||||
|
||||
**环境变量**：
|
||||
|
||||
| 变量 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `VITE_API_BASE_URL` | 后端 API 地址 | `http://localhost:8080/api/v1` |
|
||||
| `VITE_USE_MOCK` | 使用前端 Mock | `false` |
|
||||
|
||||
**端口**：
|
||||
- 开发模式：`5173`（Vite Dev Server）
|
||||
- 生产模式：`80`（Nginx）
|
||||
|
||||
### PostgreSQL Service
|
||||
|
||||
**连接信息**：
|
||||
```
|
||||
Host: localhost
|
||||
Port: 5432
|
||||
Database: ocdp
|
||||
User: postgres
|
||||
Password: postgres
|
||||
```
|
||||
|
||||
**管理工具**：
|
||||
```bash
|
||||
# 启动 pgAdmin
|
||||
docker compose --profile tools up -d pgadmin
|
||||
|
||||
# 访问: http://localhost:5050
|
||||
# Email: admin@ocdp.local
|
||||
# Password: admin
|
||||
```
|
||||
|
||||
### Redis Service
|
||||
|
||||
**连接信息**：
|
||||
```
|
||||
Host: localhost
|
||||
Port: 6379
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 故障排查
|
||||
|
||||
### 问题 1: 后端无法连接数据库
|
||||
|
||||
**检查**：
|
||||
```bash
|
||||
# 确认数据库是否运行
|
||||
docker compose ps postgres
|
||||
|
||||
# 查看数据库日志
|
||||
docker compose logs postgres
|
||||
|
||||
# 测试连接
|
||||
docker compose exec postgres psql -U postgres -d ocdp -c "SELECT 1;"
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
- 确保使用生产模式：`ADAPTER_MODE=production`
|
||||
- 检查 `DATABASE_URL` 环境变量
|
||||
- 等待数据库健康检查通过
|
||||
|
||||
### 问题 2: 前端无法访问后端
|
||||
|
||||
**检查**：
|
||||
```bash
|
||||
# 查看后端状态
|
||||
curl http://localhost:8080/health
|
||||
|
||||
# 查看网络
|
||||
docker compose ps
|
||||
docker network inspect ocdp-network
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
- 确认后端服务运行正常
|
||||
- 检查 `VITE_API_BASE_URL` 环境变量
|
||||
- 检查 CORS 配置
|
||||
|
||||
### 问题 3: 开发模式热重载不工作
|
||||
|
||||
**后端**：
|
||||
```bash
|
||||
# 确认 Air 正在运行
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs backend | grep air
|
||||
|
||||
# 检查文件挂载
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec backend ls -la
|
||||
```
|
||||
|
||||
**前端**：
|
||||
```bash
|
||||
# 确认 Vite 正在运行
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs frontend | grep VITE
|
||||
|
||||
# 检查 HMR
|
||||
# 浏览器控制台应该显示 [vite] connected
|
||||
```
|
||||
|
||||
### 问题 4: 容器启动失败
|
||||
|
||||
```bash
|
||||
# 查看详细日志
|
||||
docker compose logs --tail=100
|
||||
|
||||
# 重新构建镜像
|
||||
docker compose build --no-cache
|
||||
|
||||
# 清理并重启
|
||||
docker compose down -v
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 性能建议
|
||||
|
||||
### 开发环境优化
|
||||
|
||||
1. **使用 Mock 模式**：避免数据库依赖，加快启动速度
|
||||
2. **关闭不需要的服务**：只启动正在开发的服务
|
||||
3. **使用 Docker volumes**：提高文件 I/O 性能
|
||||
|
||||
### 生产环境优化
|
||||
|
||||
1. **使用多阶段构建**：减小镜像体积
|
||||
2. **启用健康检查**：自动重启失败的服务
|
||||
3. **配置资源限制**：防止服务占用过多资源
|
||||
4. **使用 Redis 缓存**：减少数据库查询
|
||||
|
||||
---
|
||||
|
||||
## 📖 相关文档
|
||||
|
||||
- [开发指南](./docs/development/specification.md)
|
||||
- [部署指南](./docs/deployment/docker-guide.md)
|
||||
- [API 文档](../../backend/docs/openapi.yaml)
|
||||
- [Artifact Filter 功能](./docs/features/ARTIFACT_MEDIATYPE_FILTER.md)
|
||||
|
||||
---
|
||||
|
||||
## 🎓 总结
|
||||
|
||||
### 各模式对比
|
||||
|
||||
| 特性 | 生产模式 | 开发模式 | Mock 模式 |
|
||||
|------|---------|---------|----------|
|
||||
| 数据库 | ✅ PostgreSQL | ❌ Mock | ❌ Mock |
|
||||
| 热重载 | ❌ | ✅ Air + Vite | ❌ |
|
||||
| 启动速度 | 慢 | 中 | 快 |
|
||||
| 适用场景 | 生产/集成测试 | 日常开发 | 独立测试 |
|
||||
| 资源占用 | 高 | 中 | 低 |
|
||||
|
||||
### 推荐使用场景
|
||||
|
||||
- 🚀 **日常开发**：使用开发模式
|
||||
- 🧪 **单元测试**：使用 Mock 模式
|
||||
- 🔗 **集成测试**：使用生产模式
|
||||
- 📦 **部署上线**：使用生产模式
|
||||
|
||||
### 快速命令参考
|
||||
|
||||
```bash
|
||||
# 开发（推荐）
|
||||
make dev
|
||||
# 或
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
|
||||
|
||||
# 测试后端
|
||||
docker compose -f docker-compose.mock.yml up backend
|
||||
|
||||
# 测试前端
|
||||
docker compose -f docker-compose.mock.yml up frontend
|
||||
|
||||
# 生产部署
|
||||
docker compose up -d
|
||||
|
||||
# 停止所有
|
||||
docker compose down
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user