跳转到主要内容
本页介绍 Arcentra 仓库的开发流程。下列命令默认在 arcentra 仓库根目录执行。

​
工具链

  • Go 1.25 及以上（与 go.mod 一致）。
  • Buf：Protobuf / gRPC 代码生成。make buf-install 会按需安装。
  • Wire：编译期依赖注入。make wire-install 会按需安装。
  • golangci-lint v2：make lint 会自动安装到 bin/。
  • staticcheck（可选）：make staticcheck 会安装并执行。
  • addlicense（可选）：make addlicense 为 Go 文件添加 Apache 2.0 头。
  • Docker（可选）：make docker-build、make docker-buildx 必备。

​
常用 Make 目标

make help 会列出全部目标，最常用的是：
目标作用
make depsgo mod tidy 与 go mod verify
make codegen跑全部代码生成（Buf + 两个二进制的 Wire）
make buf生成 gRPC / protobuf 代码
make wire TARGET=arcentra生成控制平面的 Wire 绑定
make wire TARGET=arcentra-agent生成 Agent 的 Wire 绑定
make build TARGET=<name>编译 cmd/<name> 下的二进制
make build-target TARGET=<name>加 -trimpath -s -w 的发布构建（CI/Docker）
make run本地运行控制平面
make lint安装 golangci-lint v2 并执行
make fmt-check校验格式（排除生成代码）
make testgo test -race -count=1 ./...
make staticcheck跑 staticcheck
make docker-build通过 BuildKit 构建镜像
make docker-buildx多架构（linux/arm64,linux/amd64）构建并推送
make addlicense为 Go 文件添加 license header
make version输出版本号、分支、commit、构建时间
make version-tag创建带注释的 vX.Y.Z.W git tag
仓库默认包含两个二进制：arcentra（控制平面）与 arcentra-agent。cmd/ 下的任何子目录都可通过 make build TARGET=<dirname> 编译。

​
代码生成

构建系统串联两个生成器：
  • Buf 在 api/<service>/v1 下生成 Go message 与 gRPC 代码。
  • Wire 在 cmd/arcentra/ 与 cmd/arcentra-agent/ 下生成 wire_gen.go。
修改任何 .proto 或 wire.go 后请执行 make codegen。

​
测试

make test
会以开启 race detector 的方式运行全部 Go 测试。需要单独跑某个包时，可以直接 go test -race ./internal/path/...。

​
开发期配置

conf.d/ 下的示例配置面向本地开发场景：
  • conf.d/config.toml：控制平面。
  • conf.d/agent.toml：Agent。
  • conf.d/plugins.toml：插件与 builtin。
make run 会基于这些默认配置启动控制平面，也可以使用 go run ./cmd/arcentra -conf <path> 与 go run ./cmd/arcentra-agent -conf <path> 直接运行。 每个段的字段说明见 配置。

​
版本与发布

Arcentra 使用 YY.Major.Minor.Patch 四段式版本号：
  • YY：2 位年份（25 代表 2025，26 代表 2026）。
  • Major：架构变更或破坏式 API 升级。
  • Minor：向后兼容的新功能。
  • Patch：Bug 修复或小改动。
示例： 
25.0.0.0  -> 2025 年初始版本
25.0.0.1  -> Bug 修复
25.0.1.0  -> 新功能（向后兼容）
25.1.0.0  -> 重大更新
26.0.0.0  -> 2026 年首个版本

​
构建时选择版本

Makefile 按以下优先级解析版本：
  1. 环境变量 VERSION。
  2. 仓库根目录的 VERSION 文件。
  3. 精确匹配的 git tag（去掉前缀 v）。
  4. 缺省值：当前 2 位年份 + .0.0.0。
# 显式指定
VERSION=25.1.2.3 make build TARGET=arcentra

# 通过 VERSION 文件
echo -n "25.1.2.3" > VERSION
make build TARGET=arcentra

​
打 Tag

export VERSION=25.1.2.3
make version-tag
git push origin v$VERSION
Tag 命名约定为 vYY.Major.Minor.Patch。

​
在代码中读取版本

import "github.com/arcentrix/arcentra/pkg/version"

v := version.GetVersion()
fmt.Println(v.Version)

parsed, err := version.GetParsedVersion()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("year=20%02d major=%d minor=%d patch=%d\n",
    parsed.Year, parsed.Major, parsed.Minor, parsed.Patch)

​
贡献

完整流程参见 CONTRIBUTING.md （中文版 CONTRIBUTING_zh_CN.md）。简要要求：
  1. 从 main 分支拉出特性分支。
  2. 提交 PR 前在本地跑 make codegen、make lint、make test。
  3. 任何对外可见的改动同步更新本文档站点。
  4. 关联 Issue，并遵循项目的 commit 与 PR 约定。
安全相关问题请按 SECURITY.md 中的私有渠道反馈。
Last modified on April 26, 2026