适用场景:同人多设备 / 单协调器(中央中转架构)
本指南面向使用者,讲解多节点协作部署完成后的具体配置步骤与运维要点。若需了解设计理念与技术依据,请参见《多节点协作架构设计》文档。
TrueAGT 多节点协作采用「中央协调器 + 多个节点」的结构。同一台 TrueAGT 实例可同时承担两种相互独立的角色:
| 角色 | 职责 | 适用场景 |
|---|---|---|
| 协调器(中央) | 长期在线、具备网络可达地址的实例,负责维护节点目录、签发令牌与中转任务。不生成任何 AI 内容。 | 拥有多台设备或多名用户,需在其间委派与分发任务。 |
| 节点 | 普通实例,向指定协调器注册、周期性心跳、拉取并执行任务。 | 存在一台或多台「本地工作站 / 随身设备」需接入中央协调器。 |
单台主机可同时作为协调器与节点(两种角色相互独立,互不冲突)。典型拓扑为:一台云主机承担协调器职责,若干本地实例作为节点接入。
最小可用节点配置仅需两项:协调器地址 coordinator_url 与用户令牌 coordinator_token。填写并重启服务后,该实例即以节点身份上线。
核心要点:
全部配置位于 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
}
}
上述配置项在启动时读取,修改后须重启服务方可生效(不支持运行时动态加载)。通过图形界面保存时,系统将提示「重启后生效」。
| 字段 | 类型 | 说明 |
|---|---|---|
coordinator_url | string | 协调器地址,支持 IP 或域名,可带端口。示例:http://192.168.1.10:8765、https://coord.example.com。协议须为 http:// 或 https://。 |
coordinator_token | string | 协调器上的用户令牌(Bearer)。节点无浏览器登录态,依赖该令牌完成首次注册并获取长期节点凭证。等同于用户身份凭据,须严格保密,不得写入对外共享或公开仓库。 |
node_label | string | 本节点在协调器上的显示名称。留空时由主机名自动填充。建议填写具辨识度的名称,如「家庭工作站」「办公笔记本」。 |
heartbeat_interval | int(秒) | 心跳间隔,最小值 5。间隔过短将增加协调器负载。 |
verify_tls | bool | 是否校验协调器 TLS 证书。当协调器使用自签名证书时,须设为 false,否则注册将因证书校验失败而中断。 |
node_execution_enabled | bool | 是否允许本节点实际执行委派任务(调用本地模型)。关闭时节点仅完成注册、心跳与任务拉取,任务将如实回写「未接入」。 |
node_executor_timeout | int(秒) | 单任务执行超时上限,用于防止本地模型卡死拖垮节点心跳与拉取循环。最小值 5。 |
{
"collab": {
"coordinator_url": "https://coord.example.com",
"coordinator_token": "协调器用户令牌(Bearer)",
"node_label": "家庭工作站"
}
}
保存后重启服务。启动日志应包含:协作节点已启动,协调器=https://coord.example.com。若协调器暂时不可达,日志将提示「注册未成功,将在后台重试」——属预期设计,协调器恢复后节点自动上线,不阻塞主服务运行。
coordinator_token 即协调器实例登录后所获取的个人令牌 / API 令牌字符串(与 Authorization: Bearer <token> 使用同一凭据),可通过「设置 → 多节点协作」图形界面填写。
安全提示:该令牌等同于账户身份凭据,须按密码级标准保管,不得写入对外共享或提交的配置片段。config.json已纳入.gitignore,但提交前仍请通过git diff config.json确认无内容变更。
将某台实例配置为中央协调器,仅需将 collab.enabled 设为 true:
{
"collab": {
"enabled": true
}
}
重启后,该实例即具备节点注册、心跳、令牌签发与任务中转能力,并自动向协作路由注册。协调器不生成任何 AI 内容,仅承担目录维护与中转职责,内容生成始终发生于节点本地。
| 运维参数 | 默认值 | 说明 |
|---|---|---|
grant_ttl | 900(秒) | 短期访问凭证有效期 |
task_timeout | 300(秒) | 任务超时回收阈值 |
max_pending | 50 | 单用户待处理任务上限 |
协调器实例本身无需填写coordinator_url(该字段仅节点使用)。若某台主机需同时作为协调器并接入另一台协调器,可同时配置enabled=true与coordinator_url,两项配置相互独立、互不冲突。
节点实例启动日志应包含 协作节点已启动,协调器=<url>;协调器实例应包含 多节点协作已启用(阶段2:同人多设备 + 中央中转)。
于「设置 → 多节点协作」填写地址与令牌后,点击「测试连接」即可就地校验:
/api/nodes 返回 200)。collab.enabled。collab.enabled=false,协作路由未注册。# 将 <TOKEN> 替换为协调器上的用户令牌,<COORD> 替换为协调器地址
curl -s -o /dev/null -w "%{http_code}\n" \
-H "Authorization: Bearer <TOKEN>" \
https://<COORD>/api/nodes
200:协调器已启用协作且令牌有效;401 / 403:令牌问题;404:协调器未启用 collab.enabled;无需手动修改 config.json,打开「设置 → 多节点协作」即可完成配置:
coordinator_url 自动清空)。令牌输入框留空表示保留已保存值(与「联网搜索」API Key 行为一致),以避免误清空已配置凭据。
| 现象 | 原因 | 处理措施 |
|---|---|---|
启动提示 coordinator_url 不能为空 | 已启用「加入协调器」但未填写地址 | 填写地址,或取消勾选该选项 |
| 注册返回证书错误(自签名证书) | verify_tls=true 但协调器使用自签名证书 | 节点侧将 verify_tls 设为 false |
| 测试连接返回 404 | 目标实例未开启 collab.enabled | 于目标实例启用协调器角色并重启 |
| 测试连接返回 401 / 403 | 令牌错误 / 非该协调器用户 | 使用目标实例上的有效用户令牌 |
| 节点日志「注册未成功,将后台重试」 | 协调器暂时不可达 | 协调器恢复后自动上线,无需人工干预 |
| 心跳持续失败 | 网络抖动 / 协调器重启 | 节点按 heartbeat_interval 自动重试 |
| 任务持续处于「未接入」状态 | node_execution_enabled=false | 启用「允许本节点执行委派任务」并重启 |
trace_id 串联。coordinator_token 等同于账户身份。凭据泄露即等同于账户泄露,须按密码级标准保管并及时轮换。node_execution_enabled=true);关闭时任务如实回写「未接入」状态,不会产生成功假象。