356 lines
6.2 KiB
Markdown
356 lines
6.2 KiB
Markdown
# 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>
|
||
|