ocdp-go/QUICK_START.md

OCDP 快速开始指南

🚀 5分钟快速体验

前置要求

• Docker 20.10+
• Docker Compose 2.0+
• (可选) Make 工具

第一步：克隆项目

git clone <repository-url>
cd ocdp-go

第二步：选择运行模式

方式 1: 开发模式（推荐用于日常开发）

特点：

• ✅ 后端 Mock 模式（无需数据库）
• ✅ 热重载（代码修改自动生效）
• ✅ 快速启动
• ✅ 适合快速迭代开发

# 使用 Make
make docker-dev

# 或直接使用 Docker Compose
docker compose --profile dev up

访问服务：

• 前端：http://localhost:5173
• 后端：http://localhost:8080
• API 文档：http://localhost:8080/api/v1

默认账号：

• 用户名：admin
• 密码：admin123

方式 2: 生产模式（用于完整功能测试）

特点：

• ✅ 真实数据库
• ✅ 完整功能
• ✅ 生产环境配置

# 使用 Make
make docker-prod

# 或直接使用 Docker Compose
docker compose up -d

访问服务：

• 前端：http://localhost:3000
• 后端：http://localhost:8080
• 数据库：localhost:5432

方式 3: 独立测试单个服务

测试后端：

make docker-test-backend
# 访问：http://localhost:8080

测试前端：

make docker-test-frontend
# 访问：http://localhost:3000

第三步：验证服务

# 检查后端健康状态
curl http://localhost:8080/health

# 登录获取 token
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

第四步：开始开发

修改后端代码

# 编辑任意 Go 文件
vim backend/cmd/api/main.go

# Air 会自动检测变化并重新编译（开发模式）
# 查看日志确认重载
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f backend

修改前端代码

# 编辑任意 React 组件
vim frontend/src/App.tsx

# Vite HMR 会自动更新浏览器（开发模式）
# 无需手动刷新页面

停止服务

# 停止并删除容器
make docker-down

# 或
docker compose down

# 完全清理（包括数据卷）
docker compose down -v

---

📚 常用命令速查

Docker 命令

命令	说明
make docker-dev	启动开发环境
make docker-prod	启动生产环境
make docker-test-backend	测试后端
make docker-test-frontend	测试前端
make docker-logs	查看所有日志
make docker-down	停止所有服务
make docker-build	重新构建镜像

查看日志

# 所有服务
docker compose logs -f

# 只看后端
docker compose logs -f backend

# 只看前端
docker compose logs -f frontend

# 只看最后 100 行
docker compose logs --tail=100

进入容器

# 进入后端容器
docker compose exec backend sh

# 进入前端容器
docker compose exec frontend sh

# 进入数据库容器
docker compose exec postgres psql -U postgres -d ocdp

重启服务

# 重启所有
docker compose restart

# 重启后端
docker compose restart backend

# 重启前端
docker compose restart frontend

---

🎯 使用场景指南

场景 1: 我要开发新功能

# 1. 启动开发环境
make docker-dev

# 2. 修改代码（自动热重载）

# 3. 查看日志
make docker-logs

# 4. 测试功能
# 访问 http://localhost:5173

# 5. 停止
make docker-down

场景 2: 我要测试完整功能

# 1. 启动生产环境（包含数据库）
make docker-prod

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

# 3. 停止
make docker-down

场景 3: 我只想测试后端 API

# 1. 启动后端 Mock
make docker-test-backend-bg

# 2. 测试 API
curl http://localhost:8080/health
curl http://localhost:8080/api/v1/registries

# 3. 停止
docker compose -f docker-compose.mock.yml down

场景 4: 我只想测试前端界面

# 1. 启动前端 Mock
make docker-test-frontend-bg

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

# 3. 停止
docker compose -f docker-compose.mock.yml down

场景 5: 代码修改不生效

# 1. 停止所有服务
make docker-down

# 2. 重新构建镜像
make docker-build --no-cache

# 3. 重新启动
make docker-dev

---

🔍 常见问题

Q1: 端口被占用怎么办？

问题：启动时报错 "port is already allocated"

解决方案：

# 查看占用端口的进程
sudo lsof -i :8080
sudo lsof -i :5173
sudo lsof -i :3000

# 杀掉进程或修改 docker-compose.yml 中的端口映射

Q2: 容器启动失败

查看详细错误：

docker compose logs backend
docker compose logs frontend

常见原因：

• 端口冲突
• 依赖服务未就绪
• 配置错误

解决方案：

# 清理并重新启动
docker compose down -v
docker compose build --no-cache
docker compose up

Q3: 热重载不工作

后端：

# 确认 Air 是否运行
docker compose logs backend | grep "air"

# 检查文件挂载
docker compose exec backend ls -la /app

前端：

# 确认 Vite 是否运行
docker compose logs frontend | grep "VITE"

# 重启前端
docker compose restart frontend

Q4: 数据库连接失败

检查：

# 数据库是否运行
docker compose ps postgres

# 健康检查
docker compose exec postgres pg_isready

解决方案：

• 确保使用生产模式（docker compose up）
• 等待数据库健康检查通过（约 10-20 秒）
• 检查 DATABASE_URL 环境变量

Q5: 前端无法连接后端

检查：

# 后端是否运行
curl http://localhost:8080/health

# 网络连接
docker network inspect ocdp-network

解决方案：

• 确认后端服务运行正常
• 检查 VITE_API_BASE_URL 环境变量
• 检查浏览器控制台错误

---

📖 进一步学习

详细文档

• Docker 服务架构 - 完整的服务说明
• 开发指南 - 开发规范
• API 文档 - OpenAPI 规范
• 部署指南 - 生产部署

项目结构

ocdp-go/
├── backend/          # Go 后端服务
├── frontend/         # React 前端应用
├── api/              # OpenAPI 规范
├── docs/             # 项目文档
├── docker-compose.yml           # 生产模式
├── docker-compose.dev.yml       # 开发模式
├── docker-compose.mock.yml      # Mock 模式
└── Makefile          # 便捷命令

架构说明

┌─────────────┐     ┌─────────────┐
│  Frontend   │────▶│   Backend   │
│  (React)    │◀────│   (Go API)  │
└─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  PostgreSQL │
                    │   Database  │
                    └─────────────┘

---

🎉 开始使用

现在你已经准备好开始使用 OCDP 了！

推荐的开发流程：

1. ✅ 使用 make docker-dev 启动开发环境
2. ✅ 修改代码（自动热重载）
3. ✅ 使用浏览器测试功能
4. ✅ 使用 make docker-test-backend 测试后端 API
5. ✅ 使用 make docker-prod 进行完整测试

需要帮助？

• 查看 DOCKER_SERVICES.md 了解详细配置
• 查看 GitHub Issues 报告问题
• 查看项目文档获取更多信息

Happy Coding! 🚀