ocdp-go/docs/archive/DOCKER_SERVICES.md

# 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
```