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）

# 启动所有服务（包含数据库）
docker compose up -d

# 查看日志
docker compose logs -f

# 访问服务
# - Frontend: http://localhost:3000
# - Backend:  http://localhost:8080
# - pgAdmin:  http://localhost:5050 (需要 --profile tools)

环境变量：

export JWT_SECRET="your-production-secret"
export ENCRYPTION_KEY="your-production-encryption-key-32-bytes"
docker compose up -d

场景 2: 开发环境（Dev Mode）

# 启动开发环境（不需要数据库，使用 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）

# 只启动后端 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）

# 只启动前端 Mock 服务
docker compose -f docker-compose.mock.yml up frontend

# 访问前端
# http://localhost:3000

场景 5: 开发模式 + 真实数据库（可选）

# 如果需要真实数据库进行开发
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                     # 便捷命令

---

🔧 开发工作流

日常开发流程

# 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

# 启动后端 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

构建生产镜像

# 构建所有镜像
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字节）

健康检查：

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

管理工具：

# 启动 pgAdmin
docker compose --profile tools up -d pgadmin

# 访问: http://localhost:5050
# Email: admin@ocdp.local
# Password: admin

Redis Service

连接信息：

Host: localhost
Port: 6379

---

🛠️ 故障排查

问题 1: 后端无法连接数据库

检查：

# 确认数据库是否运行
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: 前端无法访问后端

检查：

# 查看后端状态
curl http://localhost:8080/health

# 查看网络
docker compose ps
docker network inspect ocdp-network

解决方案：

• 确认后端服务运行正常
• 检查 VITE_API_BASE_URL 环境变量
• 检查 CORS 配置

问题 3: 开发模式热重载不工作

后端：

# 确认 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

前端：

# 确认 Vite 正在运行
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs frontend | grep VITE

# 检查 HMR
# 浏览器控制台应该显示 [vite] connected

问题 4: 容器启动失败

# 查看详细日志
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 缓存：减少数据库查询

---

📖 相关文档

• 开发指南
• 部署指南
• API 文档
• Artifact Filter 功能

---

🎓 总结

各模式对比

特性	生产模式	开发模式	Mock 模式
数据库	✅ PostgreSQL	❌ Mock	❌ Mock
热重载	❌	✅ Air + Vite	❌
启动速度	慢	中	快
适用场景	生产/集成测试	日常开发	独立测试
资源占用	高	中	低

推荐使用场景

• 🚀 日常开发：使用开发模式
• 🧪 单元测试：使用 Mock 模式
• 🔗 集成测试：使用生产模式
• 📦 部署上线：使用生产模式

快速命令参考

# 开发（推荐）
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