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