源码编译
从源码编译和运行 KubePolaris，适合开发者和有定制需求的用户。
开发环境要求
| 工具 | 版本要求 | 用途 |
|---|---|---|
| Go | 1.22+ | 后端编译 |
| Node.js | 18+ | 前端编译 |
| npm | 8+ / 9+ | 包管理 |
| MySQL | 8.0+ | 数据库 |
| Git | 2.0+ | 代码管理 |
| Make | 3.8+ | 构建工具（可选） |
获取源码
# 克隆仓库
git clone https://github.com/clay-wangzhi/KubePolaris.git
cd kubepolaris
# 查看目录结构
ls -la
后端编译
1. 安装依赖
# 进入项目根目录（Go 模块根目录）
cd kubepolaris
# 下载依赖
go mod download
# 验证依赖
go mod verify
2. 编译
# 编译后端
go build -o bin/kubepolaris-backend .
# 或使用 Makefile
make build-backend
# 交叉编译（Linux）
GOOS=linux GOARCH=amd64 go build -o bin/kubepolaris-backend-linux .
# 交叉编译（Windows）
GOOS=windows GOARCH=amd64 go build -o bin/kubepolaris-backend.exe .
3. 运行
# 复制环境变量模板（可选，按需修改）
cp .env.example .env
# 运行（默认使用 SQLite，零配置启动）
./bin/kubepolaris-backend
# 或开发模式（热重载）
go run main.go
前端编译
1. 安装依赖
# 进入前端目录
cd ui
# 使用 npm
npm install
2. 开发模式
# 启动开发服务器
npm run dev
# 默认访问 http://localhost:5173
3. 生产构建
# 构建生产版本
npm run build
# 构建产物在 dist/ 目录
ls -la dist/
4. 预览构建
# 预览生产构建
npm preview
数据库准备
1. 安装 MySQL
# macOS
brew install mysql
brew services start mysql
# Ubuntu/Debian
sudo apt-get install mysql-server
sudo systemctl start mysql
# Docker
docker run -d \
--name kubepolaris-mysql \
-e MYSQL_ROOT_PASSWORD=root \
-e MYSQL_DATABASE=kubepolaris \
-p 3306:3306 \
mysql:8.0
2. 创建数据库
# 连接 MySQL
mysql -u root -p
# 创建数据库
CREATE DATABASE kubepolaris CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# 创建用户（可选）
CREATE USER 'kubepolaris'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON kubepolaris.* TO 'kubepolaris'@'%';
FLUSH PRIVILEGES;
3. 表结构
应用会在启动时自动迁移表结构（使用 GORM AutoMigrate）。
配置
KubePolaris 通过环境变量进行配置，支持 .env 文件自动加载。默认使用 SQLite，零配置即可启动。
# 从模板创建 .env 文件，按需修改
cp .env.example .env
vim .env
如需使用 MySQL，在 .env 中设置：
DB_DRIVER=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=kubepolaris
完整环境变量参考请查看项目根目录的 .env.example 文件。
完整开发流程
1. 启动数据库
# 使用 Docker 启动 MySQL
docker-compose up -d mysql
2. 启动后端
# 终端 1
cd kubepolaris
go run main.go
3. 启动前端
# 终端 2
cd kubepolaris/ui
pnpm dev
4. 访问应用
- 前端开发服务器: http://localhost:5173
- 后端 API: http://localhost:8080
使用 Makefile
项目提供了 Makefile 简化常用操作：
# 查看所有命令
make help
# 开发环境启动
make dev
# 构建
make build
# 运行测试
make test
# 代码检查
make lint
# 生成 Swagger 文档
make swagger
# 构建 Docker 镜像
make docker-build
# 清理
make clean
代码结构
kubepolaris/
├── cmd/
│ └── main.go # 主入口
├── internal/
│ ├── config/ # 配置管理
│ ├── database/ # 数据库连接
│ ├── handlers/ # HTTP 处理器
│ ├── middleware/ # 中间件
│ ├── models/ # 数据模型
│ ├── router/ # 路由定义
│ └── services/ # 业务逻辑
├── pkg/
│ └── logger/ # 日志工具
├── .env.example # 环境变量配置模板
├── ui/ # 前端代码
│ ├── src/
│ │ ├── components/ # 通用组件
│ │ ├── pages/ # 页面组件
│ │ ├── services/ # API 服务
│ │ ├── types/ # TypeScript 类型
│ │ └── utils/ # 工具函数
│ ├── package.json
│ └── vite.config.ts
├── go.mod
├── go.sum
└── Makefile
调试技巧
后端调试
使用 VS Code 或 GoLand 的调试功能：
.vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch Backend",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/main.go",
"env": {
"KUBEPOLARIS_SERVER_MODE": "debug"
}
}
]
}
前端调试
- 使用浏览器开发者工具
- 安装 React Developer Tools 扩展
- 使用 VS Code 的 JavaScript 调试
运行测试
后端测试
# 运行所有测试
go test ./...
# 运行特定包的测试
go test ./internal/handlers/...
# 显示详细输出
go test -v ./...
# 生成覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
前端测试
cd ui
# 运行测试
pnpm test
# 运行测试并生成覆盖率
pnpm test:coverage
常见问题
Go 模块下载慢
# 设置代理
go env -w GOPROXY=https://goproxy.cn,direct
npm 安装慢
# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com
# 或使用 pnpm
pnpm config set registry https://registry.npmmirror.com
端口被占用
# 查看端口占用
lsof -i :8080
lsof -i :5173
# 杀死进程
kill -9 <PID>