> ## 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.
# 快速开始
> 构建 Arcentra、启动控制平面并连接 Agent。
本指南演示如何从源码构建 Arcentra、启动控制平面，并连接第一个 Agent。
## 前置条件
* **Go** 1.25 及以上（与 `go.mod` 一致）
* **MySQL** 8.x（单机试用可使用 SQLite）
* **Redis** 6.x 或更高版本
* **Kafka**：默认的事件与日志通道
* 可选：**Docker**，用于容器化构建与运行
## 1. 获取源码
```bash theme={null}
git clone https://github.com/arcentrix/arcentra.git
cd arcentra
```
## 2. 构建二进制
`Makefile` 会驱动代码生成（Buf 与 Wire）以及二进制构建。
```bash theme={null}
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. 启动控制平面
```bash theme={null}
./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
打开第二个终端：
```bash theme={null}
./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://:8082/metrics`。
* 在控制平面日志中确认 Agent 已注册。
* 通过 HTTP API 触发一次流水线，参考 [流水线](/zh/pipelines) 与
[API 参考](/zh/api-reference/introduction)。
## 下一步
理解控制平面、Agent 与流水线运行时如何协作。
`config.toml`、`agent.toml`、`plugins.toml` 的字段参考。
通过 DSL 与 HTTP API 编写并运行流水线。
生成代码、Lint、测试与版本发布。