多节点协作配置指南

适用场景:同人多设备 / 单协调器(中央中转架构)

本指南面向使用者,讲解多节点协作部署完成后的具体配置步骤与运维要点。若需了解设计理念与技术依据,请参见《多节点协作架构设计》文档。

1. 概述

TrueAGT 多节点协作采用「中央协调器 + 多个节点」的结构。同一台 TrueAGT 实例可同时承担两种相互独立的角色:

角色职责适用场景
协调器(中央) 长期在线、具备网络可达地址的实例,负责维护节点目录、签发令牌与中转任务。不生成任何 AI 内容。 拥有多台设备或多名用户,需在其间委派与分发任务。
节点 普通实例,向指定协调器注册、周期性心跳、拉取并执行任务。 存在一台或多台「本地工作站 / 随身设备」需接入中央协调器。

单台主机可同时作为协调器与节点(两种角色相互独立,互不冲突)。典型拓扑为:一台云主机承担协调器职责,若干本地实例作为节点接入。

最小可用节点配置仅需两项:协调器地址 coordinator_url 与用户令牌 coordinator_token。填写并重启服务后,该实例即以节点身份上线。

2. 角色关系与系统架构

协调器(中央 · 控制平面) 节点目录 · 令牌签发 · 任务中转 不存储业务数据 · 不生成 AI 内容 满足审计可发现、可处置的合规要求 节点主动发起连接(无需公网地址 / 入站端口) 节点 A(桌面) 数据 · 模型 · 会话 本地完成,不出本机 节点 B(服务器) 数据 · 模型 · 会话 本地完成,不出本机 节点 C(笔记本) 数据 · 模型 · 会话 本地完成,不出本机

核心要点:

3. 配置位置与生效方式

全部配置位于 config.json 的顶层 collab 段,也可通过「设置 → 多节点协作」图形界面完成(见第 7 章)。图形界面写入的内容即对应本段配置。

{
  "collab": {
    "enabled": false,
    "coordinator_url": "",
    "coordinator_token": "",
    "node_label": "",
    "heartbeat_interval": 60,
    "verify_tls": true,
    "node_execution_enabled": false,
    "node_executor_timeout": 300
  }
}
上述配置项在启动时读取,修改后须重启服务方可生效(不支持运行时动态加载)。通过图形界面保存时,系统将提示「重启后生效」。

4. 以节点身份接入协调器

4.1 配置字段说明(节点侧)

字段类型说明
coordinator_urlstring协调器地址,支持 IP 或域名,可带端口。示例:http://192.168.1.10:8765、https://coord.example.com。协议须为 http:// 或 https://。
coordinator_tokenstring协调器上的用户令牌(Bearer)。节点无浏览器登录态,依赖该令牌完成首次注册并获取长期节点凭证。等同于用户身份凭据,须严格保密,不得写入对外共享或公开仓库。
node_labelstring本节点在协调器上的显示名称。留空时由主机名自动填充。建议填写具辨识度的名称,如「家庭工作站」「办公笔记本」。
heartbeat_intervalint(秒)心跳间隔,最小值 5。间隔过短将增加协调器负载。
verify_tlsbool是否校验协调器 TLS 证书。当协调器使用自签名证书时,须设为 false,否则注册将因证书校验失败而中断。
node_execution_enabledbool是否允许本节点实际执行委派任务(调用本地模型)。关闭时节点仅完成注册、心跳与任务拉取,任务将如实回写「未接入」。
node_executor_timeoutint(秒)单任务执行超时上限,用于防止本地模型卡死拖垮节点心跳与拉取循环。最小值 5。

4.2 最小可用节点配置

{
  "collab": {
    "coordinator_url": "https://coord.example.com",
    "coordinator_token": "协调器用户令牌(Bearer)",
    "node_label": "家庭工作站"
  }
}

保存后重启服务。启动日志应包含:协作节点已启动,协调器=https://coord.example.com。若协调器暂时不可达,日志将提示「注册未成功,将在后台重试」——属预期设计,协调器恢复后节点自动上线,不阻塞主服务运行。

4.3 节点令牌获取方式

coordinator_token 即协调器实例登录后所获取的个人令牌 / API 令牌字符串(与 Authorization: Bearer <token> 使用同一凭据),可通过「设置 → 多节点协作」图形界面填写。

安全提示:该令牌等同于账户身份凭据,须按密码级标准保管,不得写入对外共享或提交的配置片段。config.json 已纳入 .gitignore,但提交前仍请通过 git diff config.json 确认无内容变更。

5. 以协调器(中央)身份运行

将某台实例配置为中央协调器,仅需将 collab.enabled 设为 true:

{
  "collab": {
    "enabled": true
  }
}

重启后,该实例即具备节点注册、心跳、令牌签发与任务中转能力,并自动向协作路由注册。协调器不生成任何 AI 内容,仅承担目录维护与中转职责,内容生成始终发生于节点本地。

运维参数默认值说明
grant_ttl900(秒)短期访问凭证有效期
task_timeout300(秒)任务超时回收阈值
max_pending50单用户待处理任务上限
协调器实例本身无需填写 coordinator_url(该字段仅节点使用)。若某台主机需同时作为协调器并接入另一台协调器,可同时配置 enabled=true 与 coordinator_url,两项配置相互独立、互不冲突。

6. 配置验证

6.1 启动日志核查

节点实例启动日志应包含 协作节点已启动,协调器=<url>;协调器实例应包含 多节点协作已启用(阶段2:同人多设备 + 中央中转)。

6.2 图形界面连通性测试

于「设置 → 多节点协作」填写地址与令牌后,点击「测试连接」即可就地校验:

6.3 命令行连通性测试

# 将 <TOKEN> 替换为协调器上的用户令牌,<COORD> 替换为协调器地址
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer <TOKEN>" \
  https://<COORD>/api/nodes

7. 图形配置界面(设置 → 多节点协作)

无需手动修改 config.json,打开「设置 → 多节点协作」即可完成配置:

  1. 担任协调器(中央中转):勾选后本实例作为协调器运行(重启生效)。
  2. 加入协调器(作为节点):勾选后下方字段生效;取消勾选即退出节点身份(coordinator_url 自动清空)。
  3. 依次填写:协调器地址、协调器令牌、节点显示名、心跳间隔、TLS 校验开关、本节点执行委派任务开关、单任务执行超时。
  4. 点击「测试连接」进行就地校验(见第 6.2 节)。
  5. 点击「保存并重启生效」写入配置;随后重启 TrueAGT 使角色配置生效。
  6. 页面内「查看配置指南」按钮可随时打开本文档(全局「帮助」入口亦提供同一链接)。
令牌输入框留空表示保留已保存值(与「联网搜索」API Key 行为一致),以避免误清空已配置凭据。

8. 故障排查

现象原因处理措施
启动提示 coordinator_url 不能为空已启用「加入协调器」但未填写地址填写地址,或取消勾选该选项
注册返回证书错误(自签名证书)verify_tls=true 但协调器使用自签名证书节点侧将 verify_tls 设为 false
测试连接返回 404目标实例未开启 collab.enabled于目标实例启用协调器角色并重启
测试连接返回 401 / 403令牌错误 / 非该协调器用户使用目标实例上的有效用户令牌
节点日志「注册未成功,将后台重试」协调器暂时不可达协调器恢复后自动上线,无需人工干预
心跳持续失败网络抖动 / 协调器重启节点按 heartbeat_interval 自动重试
任务持续处于「未接入」状态node_execution_enabled=false启用「允许本节点执行委派任务」并重启

9. 安全与合规

10. 适用范围与限制

11. 相关文档

本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。