Skip to content

USAGE.md

Latest commit

 

History

History
155 lines (114 loc) · 12.7 KB

USAGE.md

File metadata and controls

155 lines (114 loc) · 12.7 KB
Raw

使用手册

面向日常使用：App 各页面按钮含义、典型操作流程、CLI 参考与常见问题。 首次部署请先阅读 DEPLOY.md。

1. 界面总览

首次安装启动时会自动弹出「快速配置」向导（节点名 / Hub 地址 / 加入密钥 / opencode 端口与密码 / agent 端口 →「保存并启动节点」即完成入网注册）；密码为必填且不会自动生成——加入既有网络时须与全网统一密码一致；三样信息（Hub 地址 / 加入密钥 / 密码）的获取方式见 部署与运维指南 §4.1。若剪贴板中存在其他设备生成的有效快速配置，首次加载会自动校验并预填；也可在向导内点「从剪贴板读取」。向导可点「稍后配置」暂缓，之后在「设置」页完成并维护全部配置；入网后即具备全部控制能力。

App 有三个页签：本机 / 主控 / 设置。

1.1 本机

区域 说明
状态卡 远程连接（Telegram Bot）、opencode 服务、代理、开机自启的运行状态
一键诊断 生成诊断报告（结果卡可随时「收起」）
查看日志 本机 opencode 日志尾部；支持刷新 / 打开目录 / 收起
重启连接 停止并重新启动远程连接（Bot 与控制端通道）

1.2 设置

下表中每个可填写字段的含义、获取步骤与示例，详见 部署与运维指南 的「配置字段详解」一节；遵循该节逐步操作即可完成入网。

区域 说明
Hub 连接 Hub 地址/端口，保存并同步会同时写入本机节点配置与主控配置
节点配置 节点名（显示名，可随时修改）、加入密钥（TLS 组网时为 密钥.指纹 组合串，整串粘贴即自动钉扎）、opencode 端口（首次密码由向导设置且必填；修改密码 走「opencode」行右侧 ⚙ 齿轮，需验证原密码）、agent 端口、frpc 路径
注册 id 首次注册时确定（如 node-a），全网唯一、不可修改；以固定灰字展示，改名只改显示名
└ 按钮 保存配置 / 启动节点 / 停止节点 / 刷新状态 / 重置身份
节点状态 显示 agent 运行状态与注册结果；节点名与注册身份不一致时提示「启动节点后自动迁移」
agent 日志 查看/刷新/收起 agent 运行日志，排障首选
节点隧道（visitor） 全自动运行：同步节点或启动 App 时按需自动生成/更新/启动；仅保留「停用/启用」开关（停用会持久保持，直到手动启用）与日志
MCP 集成（本机 opencode） 主控必备、纯节点无需：一键写入/更新 node-ctl MCP（保格式、自动备份、自动移除 fleet 明文条目）、路径失效一键修复、移除；写入后重启 opencode 生效。手动路径兜底见卡片输入框。详见 DEPLOY §5.5
控制端配置备份 导出到剪贴板 / 从剪贴板导入：备份或迁移控制端配置（含凭据，请勿外发；导入后自动同步节点）
Bot Token 轮换 更新 Telegram Bot token 并重启远程连接（BotFather /revoke 后粘贴新 token →「更新并重启」）
版本与更新 检查更新 / 立即更新：从 GitHub 拉取最新源码（运行时 + 界面）覆盖本机，数据文件不受影响；随后自动重启节点并重载界面。开发版（git 仓库）请改用 git pull。详见 DEPLOY §9
会话管理 两个勾选项（默认关）：占用达 80% 时派发前自动压缩（本机作为主控）；App 退出时清理入站会话（本机作为节点，仅保留关键日志）。详见 PROTOCOL §8

1.3 主控

区域 说明
节点管理 同步节点（自动配置）：从注册中心拉取最新节点列表，自动清理已失效节点、自动更新隧道并在隧道运行中时自动重启；节点以卡片显示（名称、在线徽标、opencode 运行状态徽标（自动刷新，含 PID）、目标节点会话上下文占用徽标 ctx NN%（目标节点上与该主控绑定的会话，非本机占用；≥60% 黄、≥80% 红）、注册 id、端口与隧道信息、启动/停止/重启/压缩/清空/移除按钮）；刷新列表：重新计算在线/可达状态与占用；清理失效节点：仅清理本机主控配置中注册表已不存在的条目（不触碰 Hub）
新设备接入 生成并复制配置：在 Hub 创建一次性加入密钥，把 Hub 地址、端口、指纹、加入密钥与端口默认值写入剪贴板；新设备首次启动会自动读取并预填。可选包含网络统一密码（敏感）
压缩 / 清空（节点卡片） 压缩：对本机×该目标的对话上下文做结构化结转（digest → 新会话接续 → 换绑），占用回落、旧会话归档；清空：删除目标节点上的绑定会话（不可恢复，下次派发自动新建）；目标离线或拒绝删除时直接失败，本机绑定与占用缓存保持不变。占用含会话固定前缀（系统提示 + 工具/MCP 定义），压缩回收的是对话历史部分
移除（节点卡片） 从 Hub 与本机彻底移除该节点：删除注册身份、token、stcp 密钥与已用加入密钥，释放端口；同时删除本机节点配置、会话绑定并重建/清理 visitors 配置。不可恢复；本机节点不显示「移除」按钮
编排（opencode-fleet） 生成 fleet 配置片段（备选路径；推荐使用「设置」页「MCP 集成」一键写入 node-ctl）

2. 典型操作

托盘与退出（App 即总开关）

  • 打开 App = 自动启动本机节点与隧道（已配置时；每次打开都会确保在线，无"暂停"记忆）
  • 关闭窗口（×）= 最小化到系统托盘：一切继续运行；双击托盘图标恢复窗口（首次会气泡提示一次）
  • 退出应用（侧栏底部「退出应用」或托盘右键 →「退出应用」）= 停止本机节点与隧道：本节点变为离线（注册 id / 密钥 / 端口全部保留，下次打开原样回来），其他节点照常运行
  • 只临时下线、保持 App 运行：用「停止节点」；手机经 Bot 遥控其他节点时请保持 App 运行（托盘常驻），不要退出
  • 重复启动 App 不会产生多个实例：会自动唤起已运行的窗口

快速接入新设备

  1. 控制端「主控」→「新设备接入」→ 按需勾选「包含网络统一密码（敏感）」→「生成并复制配置」
  2. 通过可信渠道把剪贴板内容发送到新设备（或在可信设备间直接同步剪贴板）
  3. 新设备首次启动会读取剪贴板，校验标记、版本、时效与 TLS 指纹后自动预填向导；也可在向导内点「从剪贴板读取」
  4. 填写全网唯一的节点名 →「保存并启动节点」
  5. 一次性加入密钥使用后即绑定；未使用的密钥到期自动清理。使用后请清除剪贴板

剪贴板配置包含一次性加入密钥；勾选后还会包含网络统一密码。不要发送到公开群聊或不可信设备。

移除节点（撤销接入与 Hub 权限）

  1. 控制端「主控」→ 目标节点卡片 →「移除」→ 确认
  2. Hub 侧删除该节点的注册身份、token、stcp 密钥与已用加入密钥，并释放隧道端口
  3. 本机主控删除 nodes.json 中的节点条目、会话绑定与历史缓存，并重建 visitors 配置；无剩余节点时停止隧道并删除含密钥的 visitors 配置
  4. 被移除节点无法再用旧 token、stcp 密钥或旧加入密钥接入
  5. 本机节点不显示「移除」按钮；请在其他主控上操作，或使用本机「重置身份」

Hub 审计日志只记录节点 id、端口与清理的密钥数量，不记录 token、stcp 密钥或密码。旧版 Hub 不支持新端点时会自动回退到既有 /admin/revoke。

被移除设备本地可能仍缓存其曾同步过的其他节点凭据；服务器无法远程清除。需要彻底隔离时，请轮换网络统一密码或重建网络凭据。

修改某节点 opencode 密码

  1. 节点设备 →「设置」页 →「opencode」行右侧点 修改密码
  2. 弹窗内先输入原密码（当前网络共用密码，用于验证确认），再输入新密码 + 确认新密码（至少 8 位），点「验证并保存」
  3. 验证通过后写入本机配置；agent 运行中会立即用新密码重启本机 opencode（约 1 秒生效）
  4. 远程节点：到控制端「主控」页重启对应节点即可
  5. 各节点密码需统一：请逐节点依次修改保持一致；控制端派发密码自动跟随本机节点密码，无需单独更新

验证发生在节点本机（与本地配置现值比对）：Hub 只做注册与中继，不存储、不比对任何密码或指纹。

修改节点名（显示名）

注册 id 不可变，节点名是自由修改的标签：

  1. 「设置」页修改「节点名」并保存（「注册 id」行始终显示固定的注册 id 供对照）
  2. 点「启动节点」：agent 自动把新显示名同步到 Hub；注册 id、token、隧道密钥与端口均不变，无需新密钥
  3. 控制端「同步节点」后，节点列表即显示新名称（id 标签不变）

（名称需全网唯一；若与其他节点重名会提示更换）

迁移控制端配置

控制端 A：「设置」页 →「导出到剪贴板」；控制端 B →「从剪贴板导入」，即完成 Hub 连接与节点凭据迁移。导出内容含凭据，请勿外发。

手机远程下发

手机向 Bot 发消息 → Bot 所在控制端的 opencode 处理 → 经 MCP/fleet 或 CLI 下发到目标节点 → 回执摘要返回。确保控制端 opencode（如 4096）与 Bot 进程在运行。

3. CLI 参考（node-ctl）

无需图形环境，node node-ctl/cli.js <命令>：

list                        列出节点（本地配置 + 注册表在线状态）
status <node>               查询节点 opencode 状态
start|stop|restart <node>   远程启停/重启节点 opencode
fleet-config                输出主控 opencode 的 fleet MCP 配置片段
visitors-config [--out p]   生成主控侧 frpc visitors 配置（stcp 接入）
dispatch <node> "<任务>"    按消息协议派发任务（信封+回执解析，复用会话）
                            选项：--new 强制新会话；--mode one-shot|session；
                                  --timeout 秒（默认300）；--raw 附原始回复
usage <node>                查看与该节点的会话上下文占用（tokens 与百分比）
compact <node>              压缩与该节点的对话上下文（digest 结转 + 换新会话）
clear <node>                清空与该节点的对话上下文（删除目标会话，不可恢复）

示例：

node node-ctl/cli.js dispatch node-a "查看根分区占用并汇报"
node node-ctl/cli.js dispatch node-a --new "换一个全新会话，执行 uname -a"

4. 消息协议要点

设备间任务统一使用 opencode-mesh 消息协议 v1（完整规范见 PROTOCOL.md）：

  • 发送方将任务包装为信封（[opencode-mesh v1]，含 from / task / mode / reply）
  • 接收方执行后返回回执块（[opencode-mesh-result v1]，含 task / status / summary / artifacts）
  • 信息不足时可回澄清块（question），发送方补充后继续
  • 解析器带宽松回退：小模型未严格按格式回复时仍可提取有效信息；旧式 [aoi-mesh ...] 标记兼容

5. 常见问题

问题 处理
修改密码提示「原密码不正确」 原密码 = 当前网络统一密码；各节点应保持一致，可与任一已入网设备的密码核对
改密后派发任务 401 各节点密码需统一：请逐节点依次修改一致（控制端派发密码自动跟随本机节点密码）
提示「certificate fingerprint mismatch」 Hub 证书变更或遭遇中间人：核对 Hub 指纹后，用 密钥.新指纹 重新保存（详见部署文档「启用 TLS 的安全升级顺序」与故障排查）
修改节点名后列表未更新 保存后点「启动节点」，再在控制端「同步节点」；注册 id 始终不变
节点在线但访问不通 「设置」页看 agent 日志；「主控」页确认隧道未被手动停用
同步后看不到某节点 该节点可能离线或被吊销；先确认节点在线，再「刷新列表」
隧道端口冲突 「主控」页停止隧道后重新启动，按当前节点列表重新分配回环端口
想给其他设备开新名额 用任一已入网设备向 Hub 生成加入密钥（部署文档 §3），无需固定管理员