节点管理员手册

将 Ai Lubricant 的执行能力安全延伸到客户自己的机器与网络。节点主动连接平台，日常终端、文件与代理无需 SSH。

本页目录工作原理三种角色准备控制面Onboard审批/状态终端文件/代理升级/撤销排错安全

1. 为什么可以不准备 SSH

Ai Lubricant 不是替用户托管 SSH，而是让节点主动出站连接平台，从根本上避免中心服务反向拨入客户机器。

1

Server Hello

节点发起 NodeConnect 双向流；服务端先发送当前时间，避免节点本地时钟偏差直接影响首次认证。

2

TOTP 注册

节点用 onboard 时签发的 secret 和服务端时间生成 TOTP，提交 node_id、角色和能力信息。

3

长期主动连接

认证成功后保持 NodeConnect；心跳携带活跃会话，断线以 1–30 秒退避主动重连。

4

受控命令帧

创建会话、PTY、host exec、文件/工作区配置和节点 HTTP 代理通过现有流下发并回传结果。

准确边界平台日常链路不使用 22 端口、SSH Key 或 SFTP。节点机器仍需安装客户端、赋予合适的 OS 权限，并允许其主动访问 node_server_public_url。

2. 三种节点角色

角色运行客户端凭据用途
execution是TOTP secret执行 provider CLI 会话、任务、工作区、终端、文件与节点代理。默认 standalone 启动。
management是TOTP secret管理 execution 节点并在宿主机创建/删除它们；自身也支持 host terminal/exec。默认 docker 启动。
passive_management否无纯分组与授权容器；创建后直接 approved，不连接、不执行、不提供终端。
角色不能混淆execution 与 management 是两个独立 Go 二进制，没有 --role 参数；passive_management 没有二进制。只有 execution 节点可移动到管理分组下。

3. 准备控制面

前置条件：数据服务已启用兼容层；节点控制服务可运行；二者共享数据库和内部 token。

[monkeycode]
compat_enabled = true
agent_compose_base_url = http://127.0.0.1:8003
node_control_token = <高强度随机值>
node_server_public_url = https://nodes.example.com
node_server_master_key = <持久化 AES-256 主密钥>
# 单独进程启动；Hypercorn 提供 h2/h2c
python -m node_server

# 健康检查
curl http://127.0.0.1:8003/health
  • agent_compose_base_url：数据服务访问控制服务的内部地址。
  • node_server_public_url：目标节点实际能访问的公开地址，含端口与协议。
  • node_control_token：数据服务调用控制服务内部 API 的共享 Bearer token。
  • node_server_master_key：加密所有节点 TOTP secret；丢失或更换会使既有凭据不可解密。
.env 必须可写且持久化控制服务在缺少 token/主密钥时会自动生成并写回 .env；写入失败会拒绝启动。容器场景必须挂载持久化文件或 Secret，不能只烘焙进一次性镜像。

4. Onboard 节点

4.1 创建管理分组

  1. 进入 /manager/nodes，新增角色为 passive_management 的节点。
  2. 填写分组名称与标签。该记录创建后直接 approved，不生成 secret 或安装命令。
  3. 后续可把 execution 节点归到该分组，用于授权与资源组织。

4.2 创建有客户端的节点

  1. 在节点页面点击 Onboard，选择 execution 或 management。
  2. 填写节点名、启动方式和标签。execution 必须选择一个 management/passive_management 父节点。
  3. 系统生成 node_id、TOTP secret、安装脚本 URL、install command 和 otpauth URI。
  4. 立即把 secret 保存到受控 Secret 管理系统；平台不会把明文 secret 长期显示。
  5. 在目标机器执行安装命令，或使用 30 分钟有效的一键 bootstrap 脚本自动识别 OS/arch、下载二进制并启动。
安装命令不可外传命令中含完整 node_id 和 secret，等价于节点身份凭据。不要贴到文档、工单、聊天或截图；泄露后应 revoke 并重新 onboard。

4.3 二进制与参数

仓库可构建 Linux/macOS/Windows × amd64/arm64 的两类二进制：

  • execution：node-execution-<os>-<arch>
  • management：agent-compose-node-management-<os>-<arch>

共同必需参数/环境变量：

参数环境变量说明
--serverAGENT_COMPOSE_SERVER控制服务公开 URL。
--node-idAGENT_COMPOSE_NODE_IDonboard 生成的 durable ID。
--secretAGENT_COMPOSE_NODE_SECRETbase32 TOTP secret。
--nameAGENT_COMPOSE_NODE_NAME显示名称；默认主机名。
--labelsAGENT_COMPOSE_NODE_LABELSk=v,k=v 能力标签。
--tls-insecureAGENT_COMPOSE_NODE_TLS_INSECURE=1跳过 TLS 验证，仅限本地调试。

5. 审批、在线与容量

  1. 节点第一次成功注册后会显示在线，但 credentialed 节点初始状态为 pending。
  2. 管理员确认节点 ID、角色、名称、OS/arch、IP/标签和客户端版本，点击 Approve。
  3. 只有 approved、在线、具备能力且满足 CPU/内存/会话容量的 execution 节点参与调度。
  4. 按业务需要设置节点 capacity，避免单节点过载。
  5. 查看心跳和活跃会话；超过 60 秒无心跳，控制服务 reaper 会移除该连接。
节点详情
截图加载失败
审批、角色、能力、版本、容量与会话
nodes/node-detail.png
审批后才能调度：在线不等于可执行，管理员先核对身份和能力，再开放生产任务。

6. 浏览器节点终端

  1. 从节点详情点击“终端”，进入 /manager/nodes/:nodeId/terminal。
  2. 浏览器以 WebSocket 连接数据服务；数据服务带内部 token 代理到控制服务。
  3. 控制服务创建 terminal_id，通过 NodeConnect 下发 open 帧。
  4. 节点在本机创建 PTY（Unix 使用 pty，Windows 使用 ConPTY），流式回传输出。
  5. 键盘输入与窗口 resize 通过帧下发；关闭页面/终端后节点结束 shell 并释放 PTY。

终端默认从节点用户 home 目录启动；可指定 shell/cwd。节点断开时会 CloseAll，避免遗留 orphan shell。

7. 文件、Host Exec 与节点代理

文件/工作区

用户通过 /console/files 或项目编辑器浏览工作区文件。数据服务将请求代理到控制面，再通过节点连接操作目标环境。限制可访问根目录，不要给 Agent 无关的系统路径。

Host Exec

  • 仅 approved、在线且声明 host_exec=true 的节点可执行。
  • Unix 使用 /bin/sh -c，Windows 使用 cmd.exe /D /S /C。
  • 默认超时 2 分钟、最大 10 分钟；默认输出上限 1 MiB、最大 16 MiB；超出会标记 truncated。
  • 适合管理动作和诊断，不应替代长期任务会话。

节点 HTTP 代理

数据服务可通过控制服务把 HTTP 请求下发给 execution 节点，由节点使用自身网络出口访问上游，再把响应流式回传。适用于需要使用节点 IP、NAT 后网络或内网资源的 Provider。

不是任意 SSRF 通道节点代理应受节点权限、渠道配置和调用身份控制；不要把控制面内部代理端点暴露给普通公网用户。

8. 升级、移动与撤销

  • 自升级：控制服务可向在线节点下发升级，节点下载对应 OS/arch 二进制并校验版本/校验和。
  • 管理节点启动 execution：connected management 可通过 Docker 或 standalone child process 创建 execution 节点。
  • 移动分组：仅 execution 节点可移动到 management/passive_management 父节点下。
  • Revoke：发现泄露、未知主机或离职资产时立即撤销；节点后续注册将失败。
  • Delete：删除拥有子节点的 management 时需要先迁移/删除子节点；在线节点需谨慎强制删除。
控制面切换铁律先停止旧控制进程，再启动新进程。绝不能让两个 Registry 同时对同一批节点下发命令。迁移时同步数据库、node_control_token、node_server_master_key 和公开 URL。

9. 常见故障

现象检查处理
节点无法连接public URL、DNS/TLS、出站防火墙、控制服务健康从节点 curl 公开地址；核对协议/端口；不要用 uvicorn 启控制服务。
permission_deniednode_id、secret、状态、TOTP/时间确认使用正确凭据；同步系统时间；泄露时 revoke 后重新 onboard。
在线但不参与调度是否 approved、角色是否 execution、容量、能力标签Approve 节点；释放会话/调整容量；检查 provider 能力。
终端打开失败节点在线、terminal 能力、shell/cwd、WebSocket 代理先看节点状态，再看控制服务日志和前端 WS；验证反向代理支持 Upgrade。
终端有窗口但无输出PTY 是否创建、窗口是否 0×0、输出帧当前实现会把 0×0 clamp 到 80×24；检查节点日志与 terminal output 帧。
控制服务启动失败.env 是否可写、主密钥/token 是否有效修复持久化权限；从备份恢复原主密钥，不要随意生成新值。
重连后命令混乱是否同时运行两个控制 Registry立即停掉旧控制面，只保留一个；检查节点连接到哪个公开地址。

10. 节点安全基线

  • 控制服务只向节点或数据服务开放；内部 unary/terminal/proxy 端点必须验证 node_control_token。
  • 节点使用专用 OS 用户或容器，限制文件、网络、Docker socket 与 sudo 权限。
  • management 节点可创建/删除 execution 并执行 host exec，按高权限基础设施管理。
  • 不把 TOTP secret、安装命令、master key、control token 写入 Git/文档/日志。
  • 生产 TLS 不使用 --tls-insecure；定期检查证书、节点版本与异常连接。
  • 定期审计 approved 节点、角色、分组、容量、活跃会话和最后心跳；撤销闲置节点。
  • 节点代理只允许访问业务所需目标；限制内网敏感地址和 metadata endpoints。