# Cloudpods 开发环境搭建指南

本指南帮助开发者快速搭建 Cloudpods 本地开发环境。

## 前置要求

### 1. 数据库
- MySQL 5.7+ 或 MariaDB 10.3+
- 确保 MySQL 服务已启动

### 2. Go 环境
- Go 1.19+
- 用于编译后端服务

### 3. Node.js 环境（前端开发）
- Node.js 16+
- pnpm 或 npm

### 4. 操作系统
- macOS / Linux / Windows (推荐使用 WSL)

## 快速开始

### 第一步：配置数据库连接

编辑项目根目录的 `.env.local` 文件：

```bash
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=你的密码
```

**注意：** 如果 MySQL 没有密码，`DB_PASSWORD` 留空即可。

### 第二步：初始化数据库

```bash
# 创建数据库和初始用户
bash backend/dev-scripts/init-database.sh
```

这个脚本会：
- 创建 `yunioncloud` 数据库
- 创建初始管理员用户 `sysadmin`（密码：sysadmin）
- 设置数据库字符集为 utf8mb4

### 第三步：编译后端服务

```bash
cd backend

# 编译所有服务
make

# 或者只编译需要的服务
make cmd/keystone
make cmd/region
make cmd/glance
make cmd/apigateway
make cmd/yunionconf
make cmd/scheduledtask
```

编译后的二进制文件在 `backend/_output/bin/` 目录。

### 第四步：准备 etcd

etcd 二进制文件按平台分目录存放在 `backend/bin/` 下：

- **macOS 用户**：已包含，无需额外操作
- **Linux 用户**：参考 `backend/bin/README.md` 下载 Linux 版本
- **Windows 用户**：建议使用 WSL，然后下载 Linux 版本

### 第五步：启动所有服务

```bash
# 一键启动所有服务
bash backend/dev-scripts/start-services.sh start

# 查看服务状态
bash backend/dev-scripts/start-services.sh status

# 停止所有服务
bash backend/dev-scripts/start-services.sh stop

# 重启所有服务
bash backend/dev-scripts/start-services.sh restart
```

启动脚本会自动：
1. 启动 etcd
2. 启动 keystone（认证服务）
3. 初始化 RBAC 权限策略
4. 注册服务到 Service Catalog
5. 启动其他业务服务（region、glance、yunionconf 等）
6. 启动 API Gateway

### 第六步：启动前端（可选）

```bash
cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm run dev
```

前端默认运行在 http://localhost:8080

## 访问系统

- **前端地址**：http://localhost:8080
- **API Gateway**：http://localhost:30300
- **Keystone**：http://localhost:35357

**默认账号**：
- 用户名：`sysadmin`
- 密码：`sysadmin`
- 域：`Default`

## 常见问题

### 1. 数据库连接失败

检查：
- MySQL 服务是否启动
- `.env.local` 中的数据库配置是否正确
- 数据库用户是否有权限

### 2. 服务启动失败

查看日志：
```bash
tail -f backend/logs/<service>.log
```

常见原因：
- 端口被占用
- 数据库连接失败
- etcd 未启动

### 3. etcd 启动失败

检查：
- 是否下载了对应平台的 etcd
- 端口 2379 和 2380 是否被占用
- 查看日志：`tail -f backend/logs/etcd.log`

### 4. 前端无法访问后端 API

检查：
- API Gateway 是否启动（端口 30300）
- 前端代理配置是否正确
- 浏览器控制台是否有错误

## 开发工作流

### 修改后端代码后

```bash
# 重新编译
cd backend
make cmd/<service-name>

# 重启服务
bash dev-scripts/start-services.sh restart
```

### 修改前端代码后

前端开发服务器会自动热重载，无需手动重启。

### 清理环境

```bash
# 停止所有服务
bash backend/dev-scripts/start-services.sh stop

# 清理数据（可选，会删除所有数据）
rm -rf backend/data/etcd
rm -rf backend/data/glance
mysql -u root -p -e "DROP DATABASE yunioncloud;"
```

## 脚本说明

- `start-services.sh` - 主启动脚本，管理所有服务
- `start-etcd.sh` - 启动 etcd 服务
- `init-database.sh` - 初始化数据库
- `init-admin-policy.sh` - 初始化 RBAC 策略
- `register-services.sh` - 注册服务到 Service Catalog
- `start-mock-monitor.py` - Mock 监控服务（可选）

## 目录结构

```
backend/
├── _output/bin/        # 编译后的二进制文件
├── bin/                # 外部依赖（etcd）
│   ├── darwin/         # macOS 版本
│   ├── linux/          # Linux 版本
│   └── windows/        # Windows 版本
├── data/               # 运行时数据
│   ├── etcd/           # etcd 数据
│   └── glance/         # 镜像存储
├── logs/               # 服务日志
└── dev-scripts/        # 开发脚本
```

## 获取帮助

如有问题，请：
1. 查看服务日志：`backend/logs/<service>.log`
2. 检查服务状态：`bash backend/dev-scripts/start-services.sh status`
3. 联系团队成员