Cloudpods/backend/dev-scripts

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 文件：

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

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

第二步：初始化数据库

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

这个脚本会：

• 创建 yunioncloud 数据库
• 创建初始管理员用户 sysadmin（密码：sysadmin）
• 设置数据库字符集为 utf8mb4

第三步：编译后端服务

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

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

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. 服务启动失败

查看日志：

tail -f backend/logs/<service>.log

常见原因：

• 端口被占用
• 数据库连接失败
• etcd 未启动

3. etcd 启动失败

检查：

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

4. 前端无法访问后端 API

检查：

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

开发工作流

修改后端代码后

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

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

修改前端代码后

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

清理环境

# 停止所有服务
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. 联系团队成员