> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcentra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 开发

> 构建、生成、Lint、测试与发布 Arcentra。

本页介绍 Arcentra 仓库的开发流程。下列命令默认在
[`arcentra`](https://github.com/arcentrix/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 deps`                       | `go 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 test`                       | `go 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`。

## 测试

```bash theme={null}
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>` 直接运行。

每个段的字段说明见 [配置](/zh/configuration)。

## 版本与发布

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

```bash theme={null}
# 显式指定
VERSION=25.1.2.3 make build TARGET=arcentra

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

### 打 Tag

```bash theme={null}
export VERSION=25.1.2.3
make version-tag
git push origin v$VERSION
```

Tag 命名约定为 `vYY.Major.Minor.Patch`。

### 在代码中读取版本

```go theme={null}
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`](https://github.com/arcentrix/arcentra/blob/main/CONTRIBUTING.md)
（中文版 `CONTRIBUTING_zh_CN.md`）。简要要求：

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

安全相关问题请按
[`SECURITY.md`](https://github.com/arcentrix/arcentra/blob/main/SECURITY.md)
中的私有渠道反馈。