ocdp v1

USAGE_GUIDE.md

@@ -0,0 +1,355 @@
+# OCDP 使用指南
+
+## 🎯 统一的 docker-compose.yml
+
+现在所有配置都整合在一个文件中，使用 **profiles** 区分不同运行模式。
+
+---
+
+## 🚀 快速开始
+
+### 方式 1: 使用 Make（推荐）
+
+```bash
+# 开发模式
+make docker-dev
+
+# 生产模式
+make docker-prod
+
+# 测试后端
+make docker-test-backend
+
+# 测试前端
+make docker-test-frontend
+```
+
+### 方式 2: 使用 Docker Compose
+
+```bash
+# 开发模式
+docker compose --profile dev up
+
+# 生产模式
+docker compose --profile production up
+
+# Mock 测试模式（后端）
+docker compose --profile mock up backend-mock
+
+# Mock 测试模式（前端）
+docker compose --profile mock up frontend-mock
+```
+
+---
+
+## 📋 三种运行模式
+
+### 1. 开发模式（Dev Profile）
+
+**特点**：
+- ✅ 后端 Mock 模式（无需数据库）
+- ✅ 热重载（Air + Vite HMR）
+- ✅ 快速启动
+
+**启动命令**：
+```bash
+# 前台运行
+docker compose --profile dev up
+
+# 后台运行
+docker compose --profile dev up -d
+
+# 或使用 Make
+make docker-dev
+make docker-dev-bg
+```
+
+**访问地址**：
+- 前端：http://localhost:5173
+- 后端：http://localhost:8080
+
+**服务列表**：
+- `backend-dev` - 后端开发服务
+- `frontend-dev` - 前端开发服务
+
+### 2. 生产模式（Production Profile）
+
+**特点**：
+- ✅ 真实数据库（PostgreSQL + Redis）
+- ✅ 完整功能
+- ✅ 生产环境配置
+
+**启动命令**：
+```bash
+# 后台运行
+docker compose --profile production up -d
+
+# 或使用 Make
+make docker-prod
+make docker-up
+```
+
+**访问地址**：
+- 前端：http://localhost:3000
+- 后端：http://localhost:8080
+- 数据库：localhost:5432
+
+**服务列表**：
+- `postgres` - PostgreSQL 数据库
+- `redis` - Redis 缓存
+- `backend-prod` - 后端生产服务
+- `frontend-prod` - 前端生产服务
+
+### 3. Mock 测试模式（Mock Profile）
+
+**特点**：
+- ✅ 独立测试单个服务
+- ✅ 无外部依赖
+- ✅ 快速启动
+
+**测试后端**：
+```bash
+# 前台运行
+docker compose --profile mock up backend-mock
+
+# 后台运行
+docker compose --profile mock up -d backend-mock
+
+# 或使用 Make
+make docker-test-backend
+make docker-test-backend-bg
+```
+
+**测试前端**：
+```bash
+# 前台运行
+docker compose --profile mock up frontend-mock
+
+# 后台运行
+docker compose --profile mock up -d frontend-mock
+
+# 或使用 Make
+make docker-test-frontend
+make docker-test-frontend-bg
+```
+
+---
+
+## 🛠️ 常用操作
+
+### 查看日志
+
+```bash
+# 查看所有日志
+docker compose logs -f
+
+# 查看特定服务日志
+docker compose logs -f backend-dev
+docker compose logs -f frontend-dev
+docker compose logs -f backend-prod
+docker compose logs -f backend-mock
+
+# 或使用 Make
+make docker-logs
+make docker-logs-backend
+make docker-logs-frontend
+```
+
+### 停止服务
+
+```bash
+# 停止所有服务
+docker compose down
+
+# 停止特定 profile 的服务
+docker compose --profile dev down
+docker compose --profile production down
+docker compose --profile mock down
+
+# 或使用 Make
+make docker-down
+```
+
+### 重启服务
+
+```bash
+# 重启所有运行的服务
+docker compose restart
+
+# 重启特定服务
+docker compose restart backend-dev
+docker compose restart frontend-dev
+
+# 或使用 Make
+make docker-restart
+make docker-restart-backend
+make docker-restart-frontend
+```
+
+### 构建镜像
+
+```bash
+# 构建所有镜像
+docker compose build
+
+# 无缓存构建
+docker compose build --no-cache
+
+# 或使用 Make
+make docker-build
+make docker-build-no-cache
+```
+
+### 查看状态
+
+```bash
+# 查看运行的服务
+docker compose ps
+
+# 查看详细状态
+make docker-status
+```
+
+---
+
+## 🔧 开发工具
+
+### 启动 pgAdmin 和 Swagger UI
+
+```bash
+# 需要先启动生产模式
+docker compose --profile production --profile tools up -d
+
+# 或使用 Make
+make docker-tools
+```
+
+**访问地址**：
+- pgAdmin：http://localhost:5050
+- Swagger UI：http://localhost:8081
+
+---
+
+## 📊 服务对比表
+
+| 特性 | 开发模式 | 生产模式 | Mock 模式 |
+|------|---------|---------|----------|
+| **Profile** | `dev` | `production` | `mock` |
+| **后端服务** | `backend-dev` | `backend-prod` | `backend-mock` |
+| **前端服务** | `frontend-dev` | `frontend-prod` | `frontend-mock` |
+| **数据库** | ❌ Mock | ✅ PostgreSQL | ❌ Mock |
+| **前端端口** | 5173 | 3000 | 3000 |
+| **热重载** | ✅ | ❌ | ❌ |
+| **启动时间** | ~15秒 | ~30秒 | ~5秒 |
+
+---
+
+## 💡 使用场景示例
+
+### 场景 1: 日常开发
+
+```bash
+# 1. 启动开发环境
+make docker-dev
+
+# 2. 修改代码（自动热重载）
+
+# 3. 查看日志
+make docker-logs
+
+# 4. 停止
+make docker-down
+```
+
+### 场景 2: 测试后端 API
+
+```bash
+# 1. 启动后端 Mock
+make docker-test-backend-bg
+
+# 2. 测试 API
+curl http://localhost:8080/health
+curl http://localhost:8080/api/v1/registries
+
+# 3. 停止
+docker compose --profile mock down
+```
+
+### 场景 3: 生产环境部署
+
+```bash
+# 1. 配置环境变量
+export JWT_SECRET="your-secret"
+export ENCRYPTION_KEY="your-32-byte-key"
+
+# 2. 启动生产环境
+make docker-prod
+
+# 3. 检查状态
+make docker-status
+
+# 4. 启动管理工具
+make docker-tools
+```
+
+### 场景 4: 完全重置
+
+```bash
+# 1. 停止并删除所有容器和数据
+docker compose down -v
+
+# 2. 删除镜像
+docker rmi $(docker images | grep ocdp | awk '{print $3}')
+
+# 3. 重新构建
+make docker-build
+
+# 4. 重新启动
+make docker-dev
+```
+
+---
+
+## 🎓 环境变量
+
+### 开发模式环境变量
+
+后端自动使用：
+- `ADAPTER_MODE=mock`
+- `JWT_SECRET=dev-secret-key`
+
+### 生产模式环境变量
+
+可通过 `.env` 文件或导出环境变量设置：
+```bash
+export JWT_SECRET="your-production-secret"
+export ENCRYPTION_KEY="your-production-encryption-key-32-bytes"
+```
+
+---
+
+## 📚 相关文档
+
+- [README.md](./README.md) - 项目概述
+- [DOCKER_SERVICES.md](./DOCKER_SERVICES.md) - 详细架构说明
+- [COMMANDS_CHEATSHEET.md](./COMMANDS_CHEATSHEET.md) - 命令速查表
+- [QUICK_START.md](./QUICK_START.md) - 快速开始指南
+
+---
+
+## ✨ 优势
+
+通过整合到单个 `docker-compose.yml` 文件：
+
+- ✅ **更简洁**：只需维护一个配置文件
+- ✅ **更清晰**：所有服务定义在同一处
+- ✅ **更灵活**：通过 profiles 轻松切换模式
+- ✅ **更易维护**：减少配置重复
+- ✅ **向后兼容**：Make 命令保持不变
+
+---
+
+<div align="center">
+  <sub>简化配置，提升效率！🚀</sub>
+</div>
+