224 lines
4.5 KiB
Markdown
224 lines
4.5 KiB
Markdown
# 开发环境快速指南
|
||
|
||
## 📋 前置要求
|
||
|
||
- Go 1.21+
|
||
- Docker & Docker Compose
|
||
- Air（热加载工具）: `go install github.com/cosmtrek/air@latest`
|
||
|
||
## 🎯 设计理念
|
||
|
||
本项目使用 **Docker Compose Profile** 机制，通过单一的 `docker-compose.yml` 文件支持三种运行模式，避免配置文件重复。
|
||
|
||
## 🚀 三种运行模式
|
||
|
||
### 模式 0: Mock 模式（最快）
|
||
|
||
纯本地运行，无需任何外部依赖，所有服务都是 Mock。
|
||
|
||
```bash
|
||
make run-0
|
||
```
|
||
|
||
**特点:**
|
||
- ✅ 启动最快（秒启动）
|
||
- ✅ 无需 Docker
|
||
- ✅ 支持热加载
|
||
- ✅ 适合快速功能开发
|
||
|
||
**停止:** `Ctrl+C`
|
||
|
||
---
|
||
|
||
### 模式 1: 开发模式（推荐）
|
||
|
||
Docker 提供真实的 PostgreSQL，后端在本地运行并支持热加载。
|
||
|
||
```bash
|
||
make run-1
|
||
```
|
||
|
||
**特点:**
|
||
- ✅ 真实的数据库
|
||
- ✅ 支持热加载
|
||
- ✅ 代码修改实时生效
|
||
- ✅ 适合日常开发
|
||
|
||
**停止:** `Ctrl+C` 停止后端（数据库容器继续运行）
|
||
|
||
**清理:** `make clean-1` 清理数据库和临时文件
|
||
|
||
---
|
||
|
||
### 模式 2: 生产模式
|
||
|
||
所有服务完全容器化，模拟生产环境。
|
||
|
||
```bash
|
||
make run-2
|
||
```
|
||
|
||
**特点:**
|
||
- ✅ 完全容器化
|
||
- ✅ 接近生产环境
|
||
- ✅ 后台运行
|
||
- ❌ 无热加载
|
||
|
||
**查看日志:**
|
||
```bash
|
||
docker compose --profile backend logs -f
|
||
```
|
||
|
||
**停止:**
|
||
```bash
|
||
docker compose --profile backend down
|
||
```
|
||
|
||
**清理:** `make clean-2` 清理所有容器和构建产物
|
||
|
||
---
|
||
|
||
## 🧹 清理命令
|
||
|
||
```bash
|
||
# 清理模式 1 的产物（依赖容器 + 临时文件）
|
||
make clean-1
|
||
|
||
# 清理模式 2 的产物（所有容器 + 构建产物）
|
||
make clean-2
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 常用工作流
|
||
|
||
### 日常开发
|
||
|
||
```bash
|
||
# 启动开发环境
|
||
make run-1
|
||
|
||
# ... 编码、测试 ...
|
||
# 代码修改会自动重新编译
|
||
|
||
# 下班停止（Ctrl+C）
|
||
# 第二天继续（依赖容器还在运行，直接启动）
|
||
make run-1
|
||
```
|
||
|
||
### 重置数据库
|
||
|
||
```bash
|
||
# 清理并重新开始
|
||
make clean-1
|
||
make run-1
|
||
```
|
||
|
||
### 测试生产部署
|
||
|
||
```bash
|
||
# 启动生产模式
|
||
make run-2
|
||
|
||
# 查看日志
|
||
docker compose -f docker-compose.prod.yml logs -f
|
||
|
||
# 测试完成后清理
|
||
make clean-2
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 环境变量配置
|
||
|
||
复制并修改环境变量配置：
|
||
|
||
```bash
|
||
cp env.example .env
|
||
```
|
||
|
||
主要配置项：
|
||
|
||
- `ADAPTER_MODE`: 设置为 `mock` 启用 Mock 模式（模式 0）
|
||
- `POSTGRES_*`: 数据库配置（模式 1、2）
|
||
- `JWT_SECRET`: JWT 密钥（生产环境必须修改）
|
||
- `ENCRYPTION_KEY`: 加密密钥（必须 32 字节）
|
||
|
||
---
|
||
|
||
## 📂 文件说明
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `Makefile` | 开发命令入口（5个核心命令） |
|
||
| `.air.toml` | 热加载配置 |
|
||
| `docker-compose.yml` | 统一配置文件（使用 profile 区分模式） |
|
||
| `Dockerfile` | 生产镜像构建配置 |
|
||
| `DEVELOPMENT.md` | 本文档 |
|
||
|
||
### Docker Compose Profile 说明
|
||
|
||
- **无 profile**: 只启动 postgres（用于模式 1）
|
||
- **--profile backend**: 启动 postgres + backend（用于模式 2）
|
||
- **--profile mock**: 启动 backend-mock（独立的 mock 模式容器）
|
||
|
||
---
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q: 模式 1 启动失败，提示端口被占用？
|
||
|
||
A: 检查是否有其他 PostgreSQL 实例在运行：
|
||
```bash
|
||
docker ps | grep postgres
|
||
# 或者修改 .env 中的 POSTGRES_PORT
|
||
```
|
||
|
||
### Q: 如何查看依赖服务状态？
|
||
|
||
A:
|
||
```bash
|
||
docker compose ps # 模式 1（只有 postgres）
|
||
docker compose --profile backend ps # 模式 2（postgres + backend）
|
||
```
|
||
|
||
### Q: 模式 1 和模式 2 的数据库数据会互相影响吗？
|
||
|
||
A: 会共享同一个数据库容器和数据卷 `ocdp-postgres-data`。
|
||
- 模式 1: 使用本地 air 连接到 postgres 容器
|
||
- 模式 2: 使用 backend 容器连接到 postgres 容器
|
||
- 数据是持久化的，切换模式不会丢失数据
|
||
|
||
### Q: 如何完全清理所有 Docker 资源？
|
||
|
||
A:
|
||
```bash
|
||
make clean-1
|
||
make clean-2
|
||
docker system prune -a --volumes
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 提示
|
||
|
||
- **首次使用**: 推荐从 `make run-0` 开始，快速验证环境
|
||
- **日常开发**: 使用 `make run-1`，享受热加载和真实数据库
|
||
- **部署前测试**: 使用 `make run-2`，确保容器化部署没问题
|
||
- **数据持久化**: 模式 1 和 2 的数据库数据都会持久化，`Ctrl+C` 不会丢失数据
|
||
- **完全重置**: 使用 `clean-*` 命令会删除数据卷，数据会丢失
|
||
|
||
---
|
||
|
||
## 🎯 快速参考
|
||
|
||
```bash
|
||
make # 显示帮助
|
||
make run-0 # Mock 模式
|
||
make run-1 # 开发模式
|
||
make run-2 # 生产模式
|
||
make clean-1 # 清理开发环境
|
||
make clean-2 # 清理生产环境
|
||
```
|
||
|