开发

​

工具链

• 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 目标

​

代码生成

• Buf 在 api/<service>/v1 下生成 Go message 与 gRPC 代码。
• Wire 在 cmd/arcentra/ 与 cmd/arcentra-agent/ 下生成 wire_gen.go。

​

测试

make test

​

开发期配置

• conf.d/config.toml：控制平面。
• conf.d/agent.toml：Agent。
• conf.d/plugins.toml：插件与 builtin。

​

版本与发布

• 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 年首个版本

​

构建时选择版本

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

​

在代码中读取版本

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)

​

贡献

1. 从 main 分支拉出特性分支。
2. 提交 PR 前在本地跑 make codegen、make lint、make test。
3. 任何对外可见的改动同步更新本文档站点。
4. 关联 Issue，并遵循项目的 commit 与 PR 约定。