Kube-Nova 开发指南

环境准备

后端开发环境

Go 语言环境

Kube-Nova 后端基于 Go 语言开发，使用 go-zero 微服务框架。你需要安装 Go 1.22 或更高版本。安装完成后，请确保 $GOPATH/bin 已添加到系统 PATH 环境变量中，这样后续安装的 Go 工具才能在命令行中直接调用。

# 验证 Go 安装
go version

# 确保 GOPATH/bin 在 PATH 中
export PATH=$PATH:$(go env GOPATH)/bin

安装 goctl 工具

goctl 是 go-zero 框架的代码生成工具，用于根据 API 定义文件和 Proto 文件自动生成服务代码骨架。这是开发过程中最核心的工具之一。

go install github.com/zeromicro/go-zero/tools/goctl@latest

安装完成后，可以通过 goctl --version 验证安装是否成功。更多详情请参考官方文档：https://go-zero.dev/docs/tasks/installation/goctl

安装 protoc 及相关插件

protoc 是 Protocol Buffers 的编译器，用于编译 .proto 文件生成 gRPC 服务代码。go-zero 提供了一键安装命令，可以同时安装 protoc、protoc-gen-go 和 protoc-gen-go-grpc 三个组件。

goctl env check --install --verbose --force

这个命令会检查当前环境，并自动下载安装缺失的组件。--force 参数确保即使组件已存在也会重新安装最新版本。更多详情请参考官方文档：https://go-zero.dev/docs/tasks/installation/protoc

前端开发环境

Node.js 环境

前端项目要求 Node.js 版本 >= 20.19.0，包管理器使用 pnpm >= 8.8.0。建议使用 nvm 管理 Node.js 版本，便于在不同项目间切换。

# 验证 Node.js 版本
node --version

# 安装 pnpm（如果尚未安装）
npm install -g pnpm

# 验证 pnpm 版本
pnpm --version

---

代码仓库

后端仓库

平台	仓库地址
GitHub	https://github.com/yanshicheng/kube-nova
Gitee	https://gitee.com/ikubeops/kube-nova

# 克隆仓库（选择其一）
git clone https://github.com/yanshicheng/kube-nova.git
# 或
git clone https://gitee.com/ikubeops/kube-nova.git

# 进入项目目录并下载依赖
cd kube-nova
go mod tidy

前端仓库

平台	仓库地址
GitHub	https://github.com/yanshicheng/kube-nova-web
Gitee	https://gitee.com/ikubeops/kube-nova-web

# 克隆仓库（选择其一）
git clone https://github.com/yanshicheng/kube-nova-web.git
# 或
git clone https://gitee.com/ikubeops/kube-nova-web.git

# 进入项目目录并安装依赖
cd kube-nova-web
pnpm install

---

后端项目结构

理解项目结构对于高效开发至关重要。Kube-Nova 后端采用典型的 go-zero 微服务架构，核心目录说明如下：

kube-nova/
├── application/          # 应用服务目录（核心开发区域）
│   ├── console-api/      # 控制台 API 服务
│   ├── console-rpc/      # 控制台 RPC 服务
│   ├── manager-api/      # 管理端 API 服务
│   ├── manager-rpc/      # 管理端 RPC 服务
│   ├── portal-api/       # 门户 API 服务
│   ├── portal-rpc/       # 门户 RPC 服务
│   └── workload-api/     # 工作负载 API 服务
├── common/               # 公共模块
│   ├── handler/          # 通用处理器
│   ├── interceptors/     # gRPC 拦截器
│   ├── k8smanager/       # Kubernetes 客户端管理
│   ├── middleware/       # HTTP 中间件
│   └── utils/            # 工具函数
├── pkg/                  # 可复用的包
│   ├── casbinadapter/    # Casbin 权限适配器
│   ├── jwt/              # JWT 认证
│   └── storage/          # 存储相关
├── template/             # goctl 代码生成模板
└── sql/                  # 数据库脚本

在 go-zero 的设计理念中，API 服务负责处理 HTTP 请求，而 RPC 服务则提供内部的 gRPC 调用。API 服务通常会调用一个或多个 RPC 服务来完成业务逻辑，这种分层设计使得服务之间的职责更加清晰。

---

Makefile 指令详解

项目提供了丰富的 Makefile 指令来简化开发流程。这些指令可以分为三类：通用指令、代码生成指令（gen-xxx）和服务运行指令（run-xxx）。

通用指令

指令	说明
make tidy	执行 go mod tidy，自动更新和清理依赖
make fmt	格式化所有 Go 代码
make vet	静态分析代码，检测潜在错误
make lint	使用 golangci-lint 进行代码质量检查
make test	运行单元测试
make build	构建当前平台的二进制文件，输出到 dist/ 目录
make linux	交叉编译 Linux amd64 版本
make docker	构建 Docker 镜像并推送到 Harbor 仓库
make clean	清理构建产物
make help	显示所有可用指令的帮助信息

代码生成指令（gen-xxx）

代码生成指令是开发过程中的核心工具。当你修改了 .api 文件或 .proto 文件后，需要运行相应的生成指令来更新代码骨架。

API 服务代码生成

API 服务使用 .api 文件定义 HTTP 接口。goctl 会根据这个定义文件生成路由、handler、types 等代码。

指令	作用
make gen-portal-api	根据 portal.api 生成门户 API 服务代码
make gen-manager-api	根据 manager.api 生成管理端 API 服务代码
make gen-workload-api	根据 workload.api 生成工作负载 API 服务代码
make gen-console-api	根据 console.api 生成控制台 API 服务代码

以 gen-portal-api 为例，它实际执行的命令是：

goctl api go \
  --api=application/portal-api/portal.api \
  --dir=application/portal-api/ \
  --style=goZero \
  --home=./template

这里的 --home=./template 参数指定了自定义模板目录，使生成的代码符合项目规范。--style=goZero 表示使用驼峰命名风格。

RPC 服务代码生成

RPC 服务使用 .proto 文件定义 gRPC 接口。生成过程会同时产生 protobuf 消息定义和 gRPC 服务代码。

指令	作用
make gen-portal-rpc	根据 portal.proto 生成门户 RPC 服务代码
make gen-manager-rpc	根据 manager.proto 生成管理端 RPC 服务代码
make gen-console-rpc	根据 console.proto 生成控制台 RPC 服务代码

以 gen-portal-rpc 为例，它实际执行的命令是：

goctl rpc protoc --style=goZero --home=./template \
  -I=application/portal-rpc/ \
  --go_out=application/portal-rpc/pb/ \
  --go_opt=module="github.com/yanshicheng/kube-nova/application/portal-rpc/pb" \
  --go-grpc_out=application/portal-rpc/pb/ \
  --go-grpc_opt=module="github.com/yanshicheng/kube-nova/application/portal-rpc/pb" \
  --zrpc_out=application/portal-rpc/ -m \
  application/portal-rpc/portal.proto

命令参数说明：-I 指定 proto 文件的搜索路径；--go_out 和 --go-grpc_out 指定生成的 Go 代码输出目录；--zrpc_out 指定 go-zero 服务代码输出目录；-m 表示支持多个 proto 文件。

服务运行指令（run-xxx）

开发阶段使用这些指令可以快速启动单个服务进行调试，无需每次都完整构建。

指令	作用
make run-portal-api	启动门户 API 服务（端口见配置文件）
make run-portal-rpc	启动门户 RPC 服务
make run-manager-api	启动管理端 API 服务
make run-manager-rpc	启动管理端 RPC 服务
make run-workload-api	启动工作负载 API 服务
make run-console-api	启动控制台 API 服务
make run-console-rpc	启动控制台 RPC 服务

以 run-portal-api 为例，它实际执行的命令是：

go run application/portal-api/portal.go -f application/portal-api/etc/portal-api.yaml

每个服务的配置文件位于对应目录的 etc/ 子目录中，包含服务端口、数据库连接、Redis 配置等信息。启动服务前请确保配置文件已正确设置。

---

开发工作流

新增 API 接口的典型流程

当你需要为某个服务新增 HTTP 接口时，应该遵循以下步骤。这里以在 portal-api 服务中新增接口为例：

第一步，编辑 API 定义文件。打开 application/portal-api/portal.api 文件，按照 go-zero 的 API 语法添加新的接口定义，包括请求路径、方法、请求参数和响应结构。

第二步，生成代码骨架。运行 make gen-portal-api 命令，goctl 会根据更新后的 API 定义自动生成或更新路由注册、handler 函数签名和类型定义。

第三步，实现业务逻辑。在生成的 handler 文件中编写具体的业务逻辑。如果需要调用 RPC 服务，可以在 svc/servicecontext.go 中注入 RPC 客户端。

第四步，测试验证。运行 make run-portal-api 启动服务，使用 Postman 或 curl 测试新增的接口。

新增 RPC 方法的典型流程

当你需要新增内部 gRPC 调用方法时：

第一步，编辑 Proto 定义文件。打开对应服务的 .proto 文件（如 application/portal-rpc/portal.proto），添加新的 message 定义和 service 方法。

第二步，生成代码骨架。运行 make gen-portal-rpc 命令，生成 protobuf 序列化代码和 gRPC 服务骨架。

第三步，实现服务逻辑。在 internal/logic/ 目录下找到对应的 logic 文件，实现具体的业务逻辑。

第四步，测试验证。运行 make run-portal-rpc 启动 RPC 服务，可以使用 grpcurl 或编写测试用例进行验证。

---

前端开发

启动开发服务器

cd kube-nova-web
pnpm install    # 首次运行或依赖更新后执行
pnpm run dev    # 启动开发服务器，支持热更新

开发服务器启动后，默认会在本地开启一个端口（通常是 5173 或 3000），浏览器访问该地址即可预览前端界面。开发模式下支持热模块替换（HMR），修改代码后页面会自动刷新。

构建生产版本

pnpm build:prod

构建完成后，产物会输出到 dist/ 目录，可以直接部署到 Nginx 或其他静态文件服务器。

---

常见问题

goctl 命令未找到

如果运行 make gen-xxx 时提示 goctl: command not found，说明 $GOPATH/bin 未加入 PATH 环境变量。请执行 export PATH=$PATH:$(go env GOPATH)/bin 并将此行添加到你的 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）中。

protoc 相关错误

如果生成 RPC 代码时出现 protoc 相关错误，请重新运行 goctl env check --install --verbose --force 确保所有组件正确安装。

依赖下载缓慢

国内用户可以设置 Go 模块代理加速依赖下载：

go env -w GOPROXY=https://goproxy.cn,direct

服务启动失败

请检查对应服务的配置文件（位于 etc/ 目录）中的数据库、Redis、Etcd 等连接信息是否正确，以及相关基础服务是否已启动。