安装指南

Center + Worker 的完整安装、Bootstrap、升级与卸载流程。

§ 1 安装 Center

agent-center 是单一 Go binary（Web Console React SPA 通过 go:embed 内嵌），无额外依赖。

1.1 从发行包安装

下载对应平台的 release tarball（命名格式 agent-center-<os>-<arch>-<version>-<sha>），解压后运行：

tar xzf agent-center-v2.15.0-darwin-arm64.tar.gz
cd agent-center-v2.15.0-darwin-arm64/
./install center

默认 prefix：~/.agent-center（macOS / Linux user mode）或 /opt/agent-center（Linux system mode）。可用 --prefix=<dir> 覆盖。

1.2 从源码构建

git clone https://github.com/oopslink/agent-center.git
cd agent-center
make build                  # = build-frontend + build-backend
                            # 产物 → ./bin/agent-center (~17-18 MB)

构建完成后手动安装：

./bin/agent-center install center

1.3 Source guided installer

# 交互式向导（询问 mode、version、prefix）
curl -fsSL https://raw.githubusercontent.com/oopslink/agent-center/main/install.sh | bash

# 固定版本安装（推荐生产使用）
curl -fsSL https://raw.githubusercontent.com/oopslink/agent-center/v2.15.0/install.sh \
  | bash -s -- center --version v2.15.0

1.4 前台 vs 后台服务

install center 默认只部署文件与配置，打印前台启动命令：

agent-center server --config=<prefix>/etc/config.yaml   # 日志输出到 stdout

如需注册后台服务（开机自启动），加 --service：

./install center --service   # macOS → LaunchAgent，Linux → systemd unit

install center 是幂等且 upgrade-aware 的：重复运行相同版本会跳过；新版本会执行升级。

默认端口	地址	用途
Web Console	`127.0.0.1:7100`	浏览器打开
Center server	`:7050`	内部服务端口
Admin TCP	`0.0.0.0:7300`	Worker enroll / 连接

macOS AirPlay 注意：macOS Ventura+ 的 AirPlay Receiver 占用端口 7000，因此 center 默认使用 :7050。如遇端口冲突，请关闭 System Settings → General → AirDrop & Handoff → AirPlay Receiver。

§ 2 安装 Worker

Worker 可以部署在与 center 同一台机器，也可以部署在任意其他开发机上。

2.1 通过 Web Console 生成安装命令

在 Web Console 点击 "+ Add Worker"，输入名称，复制生成的命令（含 bootstrap URL、enroll token、server fingerprint）：

./install worker \
  --bootstrap=tcp://HOST:7300 \
  --server-fingerprint=sha256:... \
  --token=enroll_... \
  --worker-id=worker-... --worker-name="my box"

2.2 平台自动检测

install worker 自动检测当前平台：

macOS → 生成 LaunchAgent plist（加 --service 时）
Linux → 生成 user systemd unit（加 --service 时）

默认前台模式，打印启动命令：

agent-center worker run --config=<prefix>/etc/config.yaml

2.3 多 worker 共存

同一台机器可安装多个 worker，每个使用独立子目录（<prefix>/workers/<worker-id>/）。加 --service 时各自获得独立的 service label（com.agent-center.worker.<worker-id>），互不冲突。

2.4 Worker 文件布局

~/.agent-center-worker/
├── config.yaml             # mode=worker 配置（v2.7.1 起为 single source of truth）
├── session-token           # 长期 session token（enroll 后写入）
├── daemon.sock             # worker daemon unix socket
├── exec/                   # per-execution 目录
│   └── <execution_id>/
│       ├── envelope.json
│       ├── status.json
│       ├── events.jsonl
│       └── agent.log
└── blobs-staging/          # BlobStore 上传暂存

§ 3 Bootstrap & Enroll

3.1 Bootstrap token

Center 首次启动时在 <sqlite_dir>/bootstrap_token 写入一个 * scope 的 system bootstrap token（mode 0600）。应尽快用它 mint 长期 scoped token 后 revoke：

# 用 bootstrap token mint worker daemon 的长期 token
export AGENT_CENTER_ADMIN_TOKEN=$(cat /var/lib/agent-center/bootstrap_token)
agent-center admin token create \
  --owner=worker:mac-w-1 \
  --scopes=dispatch:pull,secret:resolve,blob:put,task:*

3.2 Worker enroll 流程

在 Web Console 点 "+ Add Worker"，系统生成一次性 enroll token
在 worker 机器执行生成的 install worker 命令
Worker 启动后自动用 token 完成握手，token 用完即删
握手成功后写入长期 session-token，后续通信使用此 token

--server-fingerprint 在 tcp:// 模式下必须提供（SSH-style fingerprint pinning），防止中间人攻击。

§ 4 升级

4.1 升级 center

从源码：

git pull
make build
./bin/agent-center upgrade center

从发行包：重新解压新版本并运行 ./install center，自动检测已有安装并执行升级。

升级流程：复制新 binary → 原子 symlink 切换（current → 新版本）→ health probe → 失败自动回滚。配置文件（端口、blob store、keys）跨版本保留。

启动时自动执行 DB migration。Downtime 约 2-5 秒，worker 自动重连。

4.2 升级 worker

指定 --worker-id 以定位正确的 worker subtree（多 worker 主机场景）：

git pull && make build
./bin/agent-center upgrade worker --worker-id=worker-...

升级不中断正在运行的 agent：daemon 重启后 reconcile 扫描活跃 shim 进程并续接。

4.3 手动回滚

# Center 回滚到上一版本
sudo ln -sfn /opt/agent-center/releases/<previous-sha> /opt/agent-center/current
sudo systemctl restart agent-center

含不可逆 schema migration 时，需先恢复 SQLite snapshot。建议升级前备份。

§ 5 卸载

5.1 卸载 center

agent-center uninstall center

默认保留数据目录（SQLite、blobs、memory）。如需彻底清除：

agent-center uninstall center --purge

5.2 卸载 worker

agent-center uninstall worker --worker-id=worker-...

移除对应 worker 的子目录与 service 注册（LaunchAgent / systemd unit）。

§ 6 Test Instance（沙箱）

v2.8 起支持 install test-instance，创建隔离的测试环境（独立 center + N workers），适用于功能验证与 CI：

agent-center install test-instance

Test instance 特性：

独立 install prefix、service label、SQLite、admin socket
与生产 center 实例完全隔离，互不影响
可在同一台机器上运行多个 test instance

单机多 center 实例（v2.7.1）：install center --instance <name> 可部署第二个 center，各自使用独立 DB / socket / service。list-local-centers 列出本机所有 center 部署。

命令速查

命令	说明
`agent-center install center`	安装 center（幂等，upgrade-aware）
`agent-center install worker`	安装 worker daemon（enroll 到运行中的 center）
`agent-center upgrade center`	升级 center（原子切换 + 自动回滚）
`agent-center upgrade worker --worker-id=<id>`	升级 worker
`agent-center uninstall center`	移除 center（数据保留，`--purge` 彻底清除）
`agent-center uninstall worker --worker-id=<id>`	移除单个 worker
`agent-center install test-instance`	创建隔离测试沙箱
`agent-center server`	前台运行 center（开发用）
`agent-center help`	完整命令树

快速上手见 5 分钟快速开始。