部署指南

涵盖单机部署、多机部署（TCP + TLS）、网络与防火墙、备份恢复、日志管理 —— 从开发机到生产环境的完整运维参考。

§ 1 单机部署（Mac / Linux）

单机部署是最常见的起步形态：一个 agent-center server + 一个或多个 agent-center worker 运行在同一台机器上，通过 Unix socket 通信。

1.1 文件布局

使用 install center 安装后，默认目录结构：

~/.agent-center/
├── current → versions/v2.15.0/     # 当前版本 symlink
├── versions/v2.15.0/bin/
│   └── agent-center                # 单一二进制（含嵌入 SPA）
├── etc/config.yaml                 # 主配置文件
├── var/
│   ├── agent-center.db             # SQLite 数据库
│   ├── agent-center.db-wal
│   ├── admin.sock                  # 本机 admin Unix socket
│   ├── bootstrap_token             # 首次启动 bootstrap token（mode 0600）
│   ├── admin-tls.crt               # TCP TLS 证书（开启 TCP 时自动生成）
│   ├── admin-tls.key
│   ├── admin-tls.fingerprint
│   └── master.key                  # SecretManagement 主密钥（mode 0600）
├── logs/
│   ├── stdout.log
│   └── stderr.log
└── workers/                        # 各 worker 子树
    └── worker-f3c04c1d/
        ├── current → versions/v2.15.0/
        ├── var/{worker.db, worker-token}
        └── logs/{stdout.log, stderr.log}

Linux 系统模式（--user-mode=false）则部署到 /opt/agent-center/，配置放 /etc/agent-center/，数据放 /var/lib/agent-center/。

1.2 最小配置

# ~/.agent-center/etc/config.yaml
server:
  listen_addr: ":7050"
  sqlite_path: "~/.agent-center/var/agent-center.db"
  admin_socket_path: "~/.agent-center/var/admin.sock"

identity:
  default_user: hayang

web_console:
  enabled: true
  listen_addr: "127.0.0.1:7100"     # loopback only (ADR-0037)

1.3 launchd / systemd 服务

macOS (launchd) -- install center 自动生成 plist 并加载：

# 查看状态
launchctl list | grep agent-center

# 手动重启
launchctl kickstart -k gui/$(id -u)/com.agent-center.server

Linux (systemd) -- 系统级 unit 示例：

# /etc/systemd/system/agent-center.service
[Unit]
Description=agent-center server
After=network-online.target

[Service]
Type=simple
User=agent-center
ExecStart=/usr/local/bin/agent-center server --config=/etc/agent-center/config.yaml
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/agent-center /run/agent-center /var/log/agent-center

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now agent-center
sudo systemctl restart agent-center
sudo journalctl -u agent-center -f

Worker daemon (user systemd)：

# ~/.config/systemd/user/agent-center-worker.service
[Unit]
Description=agent-center worker daemon
After=network-online.target

[Service]
Type=simple
ExecStart=%h/.local/bin/agent-center worker --config=%h/.agent-center-worker/config.yaml
Restart=on-failure
RestartSec=5s
KillMode=process    # 必须：shim 进程需脱离 daemon 生命周期

[Install]
WantedBy=default.target

systemctl --user enable --now agent-center-worker
systemctl --user restart agent-center-worker

KillMode=process 是必须的 -- 默认的 control-group 模式会在 daemon 重启时杀掉正在运行的 agent 子进程。Worker daemon 重启后会自动 reconcile 存活的 shim 进程。

1.4 启动 server

$ agent-center server --config=~/.agent-center/etc/config.yaml
agent-center server: db=~/.agent-center/var/agent-center.db listen=:7050 web=127.0.0.1:7100 admin=~/.agent-center/var/admin.sock (escalator running)

启动后打开浏览器 http://127.0.0.1:7100 即可访问 Web Console。

1.5 安装 worker（同机）

在 Web Console Fleet 页面点击 + Add Worker，输入名称后复制生成的安装命令：

$ ./install worker \
    --bootstrap=unix://~/.agent-center/var/admin.sock \
    --worker-id=worker-f3c04c1d \
    --worker-name='my-mac' \
    --token=acat_xxxxxxxxx
[worker] starting: worker_id=worker-f3c04c1d socket=~/.agent-center/var/admin.sock poll=1s
[worker] enrolled as worker_id=worker-f3c04c1d

Worker 注册后在 Fleet 页面状态变为 online。

§ 2 多机部署

多机部署在 server 端启用 Admin TCP TLS 监听，worker 通过 TCP + 自签 TLS 连接 server，信任模型使用 SSH 风格的指纹固定（fingerprint pinning） -- 无 CA、无 mTLS。

2.1 架构

┌──────────────────────┐              ┌─────────────────────────┐
│ Host A: CENTER       │              │ Host B: WORKER          │
│                      │              │                         │
│ agent-center server  │   TCP + TLS  │ agent-center worker     │
│   admin unix sock    │◄─────────────│   dials tcp://A:7300    │
│   admin tcp :7300    │              │   + server_fingerprint  │
│   Web Console :7100  │              │   + bearer token        │
│       (loopback)     │              │                         │
└──────────────────────┘              └─────────────────────────┘

2.2 Server 端配置

# /etc/agent-center/config.yaml
server:
  listen_addr: ":7050"
  sqlite_path: "/var/lib/agent-center/agent-center.db"
  admin_socket_path: "/run/agent-center/admin.sock"    # 本机 CLI 用
  admin_tcp_listen: "0.0.0.0:7300"                     # 跨机 worker 用

identity:
  default_user: hayang

web_console:
  enabled: true
  listen_addr: "127.0.0.1:7100"

2.3 启动 server 并获取 fingerprint

$ agent-center server --config=/etc/agent-center/config.yaml
agent-center server: db=... listen=:7050 web=127.0.0.1:7100 admin=...
  admin tcp:  0.0.0.0:7300 (TLS, auto-generated)
              cert valid until 2027-06-26 (364 days)
              fingerprint: sha256:7F:4A:8C:9B:...:6F:2C

首次启动自动生成自签证书，fingerprint 写入 /var/lib/agent-center/admin-tls.fingerprint。同时生成 bootstrap admin token 写入 /var/lib/agent-center/bootstrap_token（mode 0600）。

2.4 Worker 跨机注册

方式一：通过 Web Console + Add Worker Modal 获取完整安装命令（推荐）：

$ ./install worker \
    --bootstrap=tcp://host-a.example.com:7300 \
    --server-fingerprint="sha256:7F:4A:8C:9B:...:6F:2C" \
    --worker-id=worker-de6b92eb \
    --worker-name='vps-worker-1' \
    --token=acat_xxxxxxxxx \
    --capabilities=claudecode,fakeagent
[worker] starting: worker_id=worker-de6b92eb target=tcp://host-a.example.com:7300 poll=1s
[worker] enrolled as worker_id=worker-de6b92eb

方式二：通过 CLI 手动 mint token + 构造命令：

# Host A 上 mint enroll token
$ agent-center admintoken mint-enroll --ttl=30m
{"id":"...","plaintext":"acat_...","expires_at":"2026-06-26T13:00:00Z"}

# 复制 fingerprint
$ cat /var/lib/agent-center/admin-tls.fingerprint

# Host B 上运行
$ ./install worker \
    --bootstrap=tcp://host-a:7300 \
    --server-fingerprint="sha256:..." \
    --token=acat_... \
    --capabilities=claudecode

2.5 Token 管理

Bootstrap token 拥有 * scope（全权限），生产环境应为每个 worker mint 独立的 scoped token：

$ agent-center admintoken create \
    --owner=worker:W-vps-1 \
    --scopes='dispatch:pull,secret:resolve,blob:put,task:*'
{"id":"...","plaintext":"acat_...","owner":"worker:W-vps-1"}

Plaintext 仅展示一次，不会持久化。部署到 worker 后立即 revoke bootstrap token。

Token 轮换：mint 新 token → 部署到 worker → 重启 worker → 验证 → revoke 旧 token：

$ agent-center admintoken revoke --id=<old-token-id> --reason="rotation"

2.6 证书轮换

证书轮换是破坏性操作 -- 所有 worker 会立即报 fingerprint mismatch：

停止 server
删除 admin-tls.{crt,key,fingerprint}
重启 server（自动生成新证书）
更新所有 worker 的 --server-fingerprint，逐一重启

证书过期 30 天前会触发 admin.tcp_cert_expiring 事件。用 agent-center events query --type=admin.tcp_cert_expiring 查询。

2.7 验证

# Host A 上查看所有 worker
$ agent-center worker list
WORKER_ID         STATUS    CAPABILITIES
worker-de6b92eb   online    claudecode, fakeagent

或在 Web Console /fleet 页面查看。

§ 3 网络与防火墙

3.1 端口规划

端口	协议	方向	暴露给
`7100/tcp`	HTTP	入站 (loopback only)	本机 -- Web Console 浏览器 / SSH tunnel
`7300/tcp`	Admin TCP TLS	入站	Worker 机器（跨机部署时开放）
`22/tcp`	SSH	入站	运维人员（白名单 IP）

3.2 Web Console 网络安全

Web Console 仅绑定 loopback（127.0.0.1:7100），server 会主动拒绝任何非 127.0.0.1 / localhost 的 bind 地址。API、SSE、SPA 全在同一端口：

/api/* -- JSON endpoint（conversation / agent / secret / fleet / trace 等）
/api/sse -- 单连接 Server-Sent Events
/, /assets/*, /<任意路径> -- 嵌入的 React SPA + client-routing fallback

远程访问请使用 SSH 隧道：

ssh -L 7100:127.0.0.1:7100 user@center-host
# 然后浏览器打开 http://127.0.0.1:7100/

不要在防火墙开放 7100 端口 -- Web Console 的安全前提是 loopback-only，无认证机制。

3.3 Admin TCP TLS 端口

端口 7300 是 worker 跨机连接 server 的唯一入口。建议在防火墙层做 worker IP 白名单，叠加 bearer token + 内置 rate limit（burst=200, refill=10/sec）。

# firewalld 示例
sudo firewall-cmd --permanent --add-port=7300/tcp --zone=public
sudo firewall-cmd --permanent --add-source=<worker-ip> --zone=trusted
sudo firewall-cmd --reload

3.4 Rate limit

Per-token rate limit 默认 burst=200, refill=10/sec。正常 worker daemon（1 poll/sec + 每次 task 约 3 次调用）远低于限额。异常触发会产生 admin.rate_limit_hit 事件：

$ agent-center query events --type=admin.rate_limit_hit --limit=20

事件包含 token_id、client_ip、method、path，可据此 revoke 可疑 token。

§ 4 备份与恢复

4.1 备份对象

对象	路径	体量	频次
SQLite 数据库	`/var/lib/agent-center/agent-center.db`	数百 MB	每日
BlobStore	`/var/lib/agent-center/blobs/`	GB 级	每周（增量 rsync）
Memory git	`/var/lib/agent-center/memory/`	KB - MB	每日（push 远端 git）
master.key	`/etc/agent-center/master.key`	32 bytes	配置变更时

4.2 SQLite 备份脚本

#!/bin/bash
# /usr/local/bin/agent-center-backup
set -euo pipefail
DEST=/var/backups/agent-center/$(date +%Y%m%d-%H%M%S)
mkdir -p "$DEST"

# WAL checkpoint 后再拷贝，保证一致性
sqlite3 /var/lib/agent-center/agent-center.db "PRAGMA wal_checkpoint(FULL);"
cp /var/lib/agent-center/agent-center.db "$DEST/agent-center.db"

# 保留 30 天
find /var/backups/agent-center -mindepth 1 -maxdepth 1 -type d -mtime +30 -exec rm -rf {} +

用 systemd timer 自动执行：

# /etc/systemd/system/agent-center-backup.timer
[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

4.3 恢复

sudo systemctl stop agent-center
sudo cp /var/backups/agent-center/<date>/agent-center.db /var/lib/agent-center/
sudo chown agent-center:agent-center /var/lib/agent-center/agent-center.db
sudo systemctl start agent-center

BlobStore 用 rsync -a 恢复；blob 路径自描述，可部分恢复。

4.4 master.key 运维

master.key 用于加密 SecretManagement 的 UserSecret at-rest 值。丢失不可恢复 -- 必须在首个 secret 创建前备份到离线安全位置（password manager / hardware token）。禁止放入 git 或未加密云盘。

生成方式：

head -c 32 /dev/urandom | base64 > master.key && chmod 0600 master.key

§ 5 日志

5.1 systemd journal

agent-center server 和 worker daemon 的标准输出走 journald：

# 实时跟踪 server 日志
sudo journalctl -u agent-center -f

# 查看最近 1 小时
sudo journalctl -u agent-center --since="1 hour ago"

# worker daemon（user systemd）
journalctl --user -u agent-center-worker -f

5.2 journal rotation 配置

# /etc/systemd/journald.conf
SystemMaxUse=2G
SystemKeepFree=10G
MaxRetentionSec=30day

5.3 macOS 日志

launchd 模式下日志写入 ~/.agent-center/logs/stdout.log 和 stderr.log。可用标准工具查看：

tail -f ~/.agent-center/logs/stderr.log

5.4 Worker per-execution 日志

Worker 的 per-execution 日志不走 logrotate，由 agent-center daemon 自管理：

Execution 结束后，events.jsonl / agent.log 上传 BlobStore + 保留 24h 本地副本
24h 后整目录删除

5.5 BlobStore 归档

Blob 默认 retention 90 天（可通过 blob_store.retention_days 配置），server 周期 GC 自动删除过期 blob。

5.6 事件查询

除日志外，agent-center 内置 event-driven 可观测性，覆盖 worker 离线、execution 失败等场景：

# 查最近 1 小时的失败事件
agent-center query events --since=1h --type=*.failed

# 查看系统统计
agent-center stats

更多排障参考见快速开始。部署架构图见架构 / 部署架构。