跳转到主要内容
本指南演示如何从源码构建 Arcentra、启动控制平面，并连接第一个 Agent。

​
前置条件

  • Go 1.25 及以上（与 go.mod 一致）
  • MySQL 8.x（单机试用可使用 SQLite）
  • Redis 6.x 或更高版本
  • Kafka：默认的事件与日志通道
  • 可选：Docker，用于容器化构建与运行

​
1. 获取源码

git clone https://github.com/arcentrix/arcentra.git
cd arcentra

​
2. 构建二进制

Makefile 会驱动代码生成（Buf 与 Wire）以及二进制构建。 
make deps
make build TARGET=arcentra
make build TARGET=arcentra-agent
构建成功后，项目根目录会生成两个二进制：arcentra（控制平面）与 arcentra-agent（Agent）。
执行 make help 可以查看全部目标，包括 lint、test、codegen、 docker-build 与 docker-buildx 等。

​
3. 配置控制平面

仓库内 conf.d/ 目录提供了示例配置：
  • conf.d/config.toml：控制平面（HTTP、gRPC、数据库、Redis、Kafka、链路、 JWT 等）。
  • conf.d/agent.toml：Agent（gRPC 客户端、沙箱、标签等）。
  • conf.d/plugins.toml：插件与 builtin 默认配置（Git、SVN、shell 等）。
至少需要根据真实环境调整以下字段：
  • [http]、[grpc] 监听地址（默认 :8080 / :9090）
  • [database.mysql].dsn（或将 driver 切到 sqlite）
  • [redis].address
  • [messageQueue.kafka].bootstrapServers 及 SASL 凭证
  • [http.auth].secretKey（部署到非本地环境前必须更换）

​
4. 启动控制平面

./arcentra -conf conf.d/config.toml -plugin-conf conf.d/plugins.toml
-conf 指向控制平面主配置；-plugin-conf 指向插件与 builtin 默认配置。 两个参数省略时都会回退到 conf.d/ 下的默认文件。 启动后默认对外暴露：HTTP :8080、gRPC :9090、metrics :8082。

​
5. 启动 Agent

打开第二个终端： 
./arcentra-agent -conf conf.d/agent.toml
将 Agent 接入真实集群前需要修改：
  • [grpc].serverAddr 与 [grpc].token，用于连接控制平面。
  • [agent].mode（sandbox / baremetal）以及 [agent.sandbox]，决定执行 方式（containerd 或 Kubernetes）。
  • [agent.labels]，对外暴露 env、team、region 等调度属性。

​
6. 验证部署

  • 访问 metrics：http://<host>:8082/metrics。
  • 在控制平面日志中确认 Agent 已注册。
  • 通过 HTTP API 触发一次流水线，参考 流水线 与 API 参考。

​
下一步

架构

理解控制平面、Agent 与流水线运行时如何协作。

配置

config.toml、agent.toml、plugins.toml 的字段参考。

流水线

通过 DSL 与 HTTP API 编写并运行流水线。

开发

生成代码、Lint、测试与版本发布。
Last modified on April 26, 2026