跳到主要内容

控制面契约

本文档描述 miner-agent 与 main-api 之间的控制面通信契约。

备注

Agent 向 main-api 发送签名 JSON payload。

出站路径​

当前客户端为矿工路由添加 /api/v1 前缀：

方法路径用途
POST/api/v1/miner/register注册节点身份、钱包地址、公网入口、运行时类型和 GPU inventory
POST/api/v1/miner/heartbeat上报签名后的主机、GPU、运行时和模型状态
POST/api/v1/miner/challenge为注册或重新验证请求挑战
POST/api/v1/miner/challenge/verify提交签名后的挑战答案
危险

源 README 提到的是不带 /api/v1 前缀的 V1 route layout；当前实现使用上表中的前缀路径。

注册 Payload​

注册 payload 包含：

  • node_id
  • node_public_key（base64 形式发送）
  • node_key_type
  • wallet_address
  • name
  • public_ip
  • agent_version
  • runtime_type
  • gpus
  • timestamp
  • nonce
  • sign_result

sign_result 由节点 Ed25519 私钥对规范 digest 签名得到。

心跳 Payload​

心跳 payload 包含：

  • node_id
  • timestamp
  • 主机指标
  • gpus
  • vllm
  • nonce
  • sign_result

vllm 对象包含：

  • 运行时健康
  • 服务中的模型
  • 模型就绪
  • 可选 load 数据
  • 探测失败时的错误信息

错误行为​

  • 注册和心跳的 HTTP 失败会写入 agent 状态，并通过 /v1/miner/status 和 /readyz 暴露
  • 如果注册返回 HTTP 409，客户端会把节点视为已注册但未验证，并进入挑战路径

相关文档​