Andy Daemon Admin

管理员 Token

系统资源

尚未刷新

CPU--

实时使用率

内存--

磁盘--

定时任务

Supervisor / APScheduler

等待连接

Daemon 控制面

0 个节点

状态	Daemon	主机	版本	能力	运行命令	最近心跳
等待连接

命令状态

状态	命令	Daemon	耗时	退出码	完成时间	结果
暂无记录

下发任务

命令由目标 Client 的受限用户执行

网关统计

请求性能与错误记录

接口	请求	平均耗时	最大耗时	错误
等待连接

调用方身份与 Token

上游系统对接控制面的身份，Token 仅在颁发时展示一次

已有调用方

状态	名称	Caller ID	归属	创建时间	操作
等待连接

任务监控中心

按 Goal / Session 还原持续交互全过程

Goal

Session

Agent

外部任务 ID

Daemon

状态

状态	命令	Daemon	调用方	Goal	Session	耗时	创建时间	操作
等待连接

Client 身份与 Token

Token 仅在颁发时展示一次

已有 Client 身份

状态	Client ID	主机	版本	创建时间	最近心跳	操作
等待连接

使用指引

按实际使用场景组织操作说明。每个场景独立描述目标、前置条件、步骤和验收结果；后续相关场景可以继续添加到本页。

场景 01

创建 Client 身份并颁发 Token

适用于新增一台执行节点，或为已有 Client 补发访问凭证。Token 只在颁发成功时展示一次，请立即保存到目标 Client。

前置条件已使用管理员 Token 连接控制面，并明确目标 Client ID。

完成标志Client 使用身份配置启动后，在身份列表中显示“在线”。

进入 Client 身份页
点击顶部“Client 身份”Tab，打开身份和 Token 管理界面。
填写身份信息
输入唯一 Client ID 和 Token 有效期。新 ID 会创建身份；已有 ID 会颁发新 Token。
颁发并保存凭证
点击“创建身份并颁发 Token”，随后复制“身份配置 JSON”。Token 不会再次显示，也不要粘贴到日志或代码仓库。
写入 Client 配置
在目标机器保存为仅当前用户可读的身份文件。
mkdir -p ~/.andy-daemon chmod 700 ~/.andy-daemon $EDITOR ~/.andy-daemon/config.json chmod 600 ~/.andy-daemon/config.json
启动 Client
使用刚保存的身份文件启动执行 Client。
python -m andy_daemon.cli run \ --identity ~/.andy-daemon/config.json \ --home ~/.andy-daemon
确认上线
回到“Client 身份”页，确认对应 Client 的状态变为“在线”，主机、版本和最近心跳已有数据。

场景 02

在远端一键安装 Client

用户只需准备 Client ID 和对应 Token，即可在远端完成安装。Web 会自动带入控制面地址，安装器默认选择最新版，并使用 uv 管理独立的 Python 3.12 环境、自动选择可用的 Python 包源、配置 systemd 和启动 Client。

用户提供Client ID、该身份刚颁发或仍有效的 Token。

目标机要求Linux + systemd、具备 sudo 权限，能访问控制面及 uv 官方下载源。

默认行为控制面地址由 Web 自动生成；不指定版本时安装最新版。

可选版本需要固定或回切版本时，选择版本或追加 --version v0.1.2。

准备 Client ID 和 Token
在“Client 身份”页创建身份并颁发 Token。除此之外，不需要手工准备其他业务参数。
选择安装版本
保持“最新版”，或从版本列表选择明确版本。复制生成的命令。
在目标主机执行一次
使用具备 sudo 权限的账号执行命令，并在安全提示中粘贴 Token。安装过程不会把 Token 放入 URL。
curl -fsSL 'http://HOST:24645/install.sh' | sudo bash -s -- \ --server-url 'http://HOST:24645' \ --daemon-id 'CLIENT_ID'
验证服务
安装成功后检查 systemd 状态，并回到身份页确认心跳上线。
systemctl status andy-daemon journalctl -u andy-daemon -f

场景 03

首次远程执行：系统体检

向已在线的 Client 下发一个无副作用的只读命令，体验“控制面排队 → Client 领取 → 受限用户执行 → 结果回传”的完整链路。

前置条件Client 状态为“在线”，并已使用管理员 Token 连接控制面。

安全范围只读取主机、时间、用户、系统、磁盘和内存信息，不修改目标机。

预期用户命令应由受限的 andy-daemon 用户执行，而不是 root。

完成标志任务状态为“成功”、退出码为 0，并返回完整标准输出。

确认 Client 在线
在“Client 身份”页确认目标 Client 的状态、版本和最近心跳正常。
下发只读体检命令
在“运行概览 → 下发任务”选择目标 Client，粘贴下面的命令并点击“执行任务”。
printf '主机: '; hostname printf '时间: '; date printf '运行时长: '; uptime -p printf '用户: '; id printf '系统: '; uname -a printf '磁盘:\n'; df -h / printf '内存:\n'; free -h
观察状态流转
任务会依次经历排队、领取、启动、运行，并最终进入成功或失败状态。
检查执行结果
提交后详情面板会自动刷新；也可在“运行概览 → 最近执行”点击“查看结果”，检查退出码及完整 stdout/stderr。
完成安全验收
确认输出中的用户为 andy-daemon、命令没有写入文件或改变系统配置，并且 Client 心跳持续在线。

场景 04

轮换、吊销 Token 与停用 Client

用于凭证定期轮换、Token 疑似泄露或节点退出服务。吊销只影响选中的 Token；停用 Client 会立即拒绝该身份的全部 Token，同时保留历史任务和结果。

轮换原则先颁发新 Token 并更新 Client，确认重新上线后再吊销旧 Token。

紧急处置疑似泄露时可立即停用 Client，阻止心跳、领取任务和结果上报。

打开凭证管理
进入“Client 身份”，在目标 Client 行点击“管理凭证”。
轮换 Token
点击“颁发 Token”创建新凭证，更新目标 Client 配置并确认心跳恢复。
吊销旧 Token
在凭证列表核对 Token ID 和创建时间，只吊销已被替换的凭证。
必要时停用身份
点击“停用”会立即拒绝该 Client 的全部 Token；问题处理完成后可重新启用。

场景 05

升级、诊断、回滚与安全卸载 Client

用于 Client 的日常版本维护和故障恢复。升级默认使用最新版并保留现有 Token；安装器会等待身份真正上线，服务启动失败或无法连接控制面时自动恢复旧版本，配置和执行状态不会被删除。

升级策略记录上一版本后切换，并以控制面确认身份在线作为成功标准；可通过 --version 固定目标版本。

卸载策略只移除 systemd 服务和版本指针，默认保留配置、状态库及已下载版本。

升级 Client
沿用现有身份配置和 Token，默认升级到最新版。
curl -fsSL 'http://HOST:24645/install.sh' | sudo bash -s -- \ --action upgrade --server-url 'http://HOST:24645' --daemon-id 'CLIENT_ID'
运行诊断
检查当前版本、服务状态、配置权限和控制面连通性；不会打印 Token。
curl -fsSL 'http://HOST:24645/install.sh' | sudo bash -s -- \ --action diagnose --server-url 'http://HOST:24645'
手动回滚
将 current 与 previous 交换并重启；如果回滚版本不能启动，会恢复原版本。
curl -fsSL 'http://HOST:24645/install.sh' | sudo bash -s -- --action rollback
安全卸载
停止并移除服务，但保留配置、状态和下载版本，方便审计或重新安装。
curl -fsSL 'http://HOST:24645/install.sh' | sudo bash -s -- --action uninstall

场景 06

用 Goal / Session 绑定持续交互

适用于与上层目标关联的多轮任务。goal_id 代表上层目标（例如“开发一个网站”），session_id 代表工具会话（例如 opencode 的会话）；提交命令时带上两者，即可在任务监控页按 Goal 分组，还原同一目标下的全部交互过程。

前置条件已连接管理员 Token，并有在线 Client。

完成标志在“任务监控”页按 Goal 分组，能看到该目标下的全部命令、会话与执行结果。

填写任务关联
在“运行概览 → 下发任务”，可选填写 Goal / Session / Agent / 外部任务 ID。Goal 与 Session 可跨多轮复用，用于把同一目标的多次执行串成一条链路。
执行多轮任务
同一 Goal / Session 下可以反复提交命令；重复提交同一幂等键（idempotency_key）不会重复下发，而是返回原命令，方便上游安全重试。
按 Goal 查看全过程
打开“任务监控”Tab，输入 Goal 或 Session 过滤；或点击“按 Goal 分组”，按目标聚合查看会话链与执行结果。
核对执行详情
点击任意命令的“查看结果”，详情面板会显示调用方、Goal / Session 与完整执行输出。

场景 07

构建容器 Runtime（含 opencode 持久化）

每个 Runtime 一个容器：承载 daemon 执行层与 opencode 会话。Runtime 级数据（opencode 会话库、daemon 本地状态）必须挂独立持久卷，不随项目工作区走——项目可以重建，Runtime 数据不丢。

数据分层Runtime 级（opencode.db、daemon 状态）→ 独立持久卷；项目级（代码、dev_plans、场景库）→ 项目工作区；Server 级（andy-server.db、审计）→ /workspace/app/shared。

完成标志容器重建后 opencode 会话不丢，daemon 心跳恢复，服务健康检查通过。

规划 Runtime 目录
在宿主机为每个 Runtime 建立独立持久目录，不放在任何项目目录下。
mkdir -p /opt/andy_runtime/<runtime-id>/opencode-data
构建容器
基于 andy_deamon 镜像启动，把 opencode 数据目录挂到容器默认数据路径，项目工作区与凭据照常挂载。
docker run -d --name <runtime-id> \ -v /opt/andy_runtime/<runtime-id>/opencode-data:/root/.local/share/opencode \ -v /opt/andy_deamon_24645/workspace:/workspace \ -v /root/credentials:/credentials:ro \ -p 24645:24625 andy_deamon:20260813181346
部署 opencode（Runtime 工具）
硬件门槛：CPU 必须支持 AVX（老 CPU 会 SIGILL）。二进制放公共位置，配置与数据走 XDG 环境变量并归 daemon 受限用户。
grep avx /proc/cpuinfo # 硬件门槛（无输出则不可用） cp -a /root/.opencode /opt/opencode && chmod -R a+rX /opt/opencode mkdir -p /opt/opencode/config/opencode # 执行时环境: XDG_DATA_HOME=<持久目录> XDG_CONFIG_HOME=/opt/opencode/config # 数据目录属主: chown -R andy-daemon:andy-daemon <持久目录>
验证 Runtime 健康
确认服务就绪，且 opencode 会话库可从容器内读取。
curl -s http://127.0.0.1:24645/health/ready sqlite3 /root/.local/share/opencode/opencode.db "SELECT COUNT(*) FROM session;"
备份与恢复
opencode 会话是单 SQLite 文件，备份即拷库；恢复即挂回。
sqlite3 /root/.local/share/opencode/opencode.db ".backup '/opt/andy_runtime/<runtime-id>/opencode-backup.db'"
后续补充
本场景会随 Runtime 运维实践持续补充：凭据注入、资源配额、会话监控、多 Runtime 端口规划等。

场景 08

用户侧 Agent 接入：通过 Server 驱动 Daemon 任务

本机 Agent 持调用方 Token 与 Server 对话：发需求 → Server 发布任务 → Daemon 执行（含 opencode）→ Agent 轮询获取状态与结果。用户只需向 Agent 提供调用方 Token，即可让 Agent 通过 Server 驱动任意 runtime 上的任务。

前置条件管理员已在「调用方」页颁发 caller Token（Bearer JWT，一次性展示）；Token 通过环境变量注入 Agent（如 ANDY_CALLER_TOKEN），不进命令参数。

完成标志Agent 凭 Token 独立完成一次任务：提交 → 轮询 → 终态取结果；opencode 任务可指定模型/续会话。

Agent 验证身份
用 Token 访问控制面确认有效（200 即通过）。
curl -H "Authorization: Bearer $ANDY_CALLER_TOKEN" \ https://deamon.ty.orbitx.cn/api/control/daemons
Agent 发需求（提交任务）
带 goal_id（用户目标）与 session_id（opencode 会话），幂等键防重。
curl -X POST -H "Authorization: Bearer $ANDY_CALLER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"daemon_id":"tom5r","command":"...","timeout_seconds":180, "goal_id":"goal-xxx","session_id":"ses_xxx", "idempotency_key":"$(uuidgen)"}' \ https://deamon.ty.orbitx.cn/api/control/commands
Agent 轮询进度
queued/claimed/starting/running = 进行中；succeeded/failed/timeout = 终态（reaper 保证不会无限卡住）。
curl -H "Authorization: Bearer $ANDY_CALLER_TOKEN" \ https://deamon.ty.orbitx.cn/api/control/commands/<command_id>
Agent 取结果
成功：读取 execution.stdout/stderr/exit_code；失败：按 stderr 定位原因，可用同一幂等键重试。
opencode 任务模板
模型可指定、会话可续、完全授权已配置、异步询问可续答（详见场景 S08）。
XDG_DATA_HOME=/data/management XDG_CONFIG_HOME=/opt/opencode/config \ /opt/opencode/bin/opencode run --model opencode/deepseek-v4-flash-free \ [--session ses_xxx] "任务内容"

后续场景预留

场景 09 · 待补充已预留独立场景位置，可继续扩展调用方管理与上游对接体验。

场景 10 · 待补充已预留独立场景位置，可继续添加相关运维流程。

场景 11 · 待补充已预留独立场景位置，用于后续相关操作指引。

Andy Daemon