You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/AGENT_API.md

14 KiB

Virt Host Agent WSS/API v1

本协议只供 PHP 面板经本机 Go Gateway 调用宿主机 Go Agent。浏览器、第三方客户端和其他宿主机不能直接使用;不存在 Python 引擎、SSH 执行或旧数据库兼容路径。

传输

  • Agent 使用数字 agent_id 与独立 agent_secret 主动连接 WSS /agent/connect,子协议固定为 virt-agent-control.v3。v3 的不可变完成回执必须携带操作三元身份;Agent 与 Gateway 不提供 v1/v2 兼容或协商降级,任一侧版本不一致必须在握手阶段失败。Gateway 必须通过 PHP 内部接口认证连接。
  • PHP 把已签名的内层 API 请求发送到 Gateway 字面 loopback 的 POST /internal/agent/request。Gateway 不改写 method、request target、body 或内层认证头。
  • 控制请求帧为 request,即时响应帧为 response;帧 ID 只负责当前连接的配对,不是业务幂等键。
  • mutation 的即时响应只说明 Agent 已接收或已明确拒绝。Agent 在独立 helper 中执行一次,并通过单独的 completion 帧发送不可变终态回执。
  • 断线、超时和进程重启都不得生成新 operation_id、重新发送 mutation,或从历史 Journal 启动 helper。

请求与响应使用 UTF-8 JSON。decoder 拒绝未知字段、多个顶层值、尾随内容、错误类型和超出 max_body_bytes 的正文。ID、UUID、URL、路径、MAC、CIDR、脚本和数组都有明确的格式与长度上限;API 不接受任意 XML、shell 命令或 libvirt flags。

内层 HMAC

每台宿主机使用不同的至少 32 字节密钥。请求头为:

X-Virt-Timestamp: Unix 秒
X-Virt-Nonce: 16-128 个 URL-safe 字符
X-Virt-Content-SHA256: lowercase hex SHA-256(body)
X-Virt-Actor: URL-safe base64 无填充 actor JSON
X-Virt-Signature: lowercase hex HMAC-SHA256

actor 普通字段如下;只读请求可省略 operation_id,mutation 必须携带且与正文一致。普通签名路径拒绝客户端夹带 system_recovery。

{
  "user_id": 42,
  "is_admin": false,
  "is_super_admin": false,
  "can_manage": false,
  "operation_id": "0123456789abcdef0123456789abcdef"
}

面板内部对已派发、已失败但影响未知的允许类型进行恢复核对时,可以使用一个保留 actor。它没有人类管理员权限,并且严格绑定一个 operation:

{
  "user_id": 0,
  "is_admin": false,
  "is_super_admin": false,
  "can_manage": false,
  "system_recovery": true,
  "operation_id": "0123456789abcdef0123456789abcdef"
}

该 actor 只能访问同一 operation_id 的 GET inspect、GET fence-resolution 和 POST resolve-fence,而且 Agent 还会按显式 action allowlist 再次授权;不能访问健康、能力、资源列表、原始 Journal 或任何 libvirt/catalog/storage mutation。inspect、完成回执和 resolve-fence 都必须同时匹配不可变的 action + resource_id + request_fingerprint。resolve-fence 只持久化该 operation 的审计结论并移除其 admission 索引,不调用 libvirt,也不继续或重放原操作。

canonical bytes 为六段原值用一个 LF 连接,末尾没有 LF:

UPPERCASE_METHOD
ESCAPED_PATH_WITH_EXACT_RAW_QUERY
LOWERCASE_BODY_SHA256
TIMESTAMP
NONCE
RAW_X_VIRT_ACTOR

Agent 先验证时间窗、正文摘要、签名与 nonce,再进行路由和授权。nonce 只消费一次,签名和摘要使用常量时间比较;认证错误统一返回 401,不泄露差异。

Mutation 与完成回执

PHP 在提交给 Gateway 前已经持久化任务、请求指纹、唯一 operation_id 和绝对截止时间。Agent 在调用 libvirt 前把同一标识与资源 admission 原子写入当前 Journal,然后最多启动一个隔离 helper。

即时响应:

{
  "operation_id": "0123456789abcdef0123456789abcdef",
  "action": "power-reboot",
  "resource_id": "123e4567-e89b-42d3-a456-426614174000",
  "request_fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "status": "dispatching",
  "replayed": false,
  "retryable": false
}

HTTP 202 仅表示这次 operation 已被 Agent 接收。已存在的相同 operation 和相同指纹只返回现有记录;不同指纹复用标识返回 409,绝不执行第二次。retryable 只保留为错误展示字段,PHP worker 和浏览器不能据此重派 mutation。

helper 结束后 Agent 写入唯一完成记录,并通过 WSS 发送:

{
  "type": "completion",
  "id": "immutable-event-id",
  "operation_id": "0123456789abcdef0123456789abcdef",
  "action": "power-reboot",
  "resource_id": "123e4567-e89b-42d3-a456-426614174000",
  "request_fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "status": "failed",
  "effect_may_have_applied": true,
  "safe_to_resubmit": false,
  "error_code": "result_unconfirmed",
  "result": null
}

Gateway 只接受当前已认证 session 的事件,并自行注入该连接的 agent_id,用 Gateway-PHP 密钥签名后 POST /api/internal/cloud/operation-completion。PHP 按 agent、operation、事件 ID 和正文摘要幂等接收;成功处理后 Gateway 返回 completion_ack。ACK 只删除 Agent outbox,不能删除 Journal tombstone。

Agent 与 Gateway 必须来自同一发布版本。健康检查和 capabilities 只验证经当前控制连接转发的 Agent API,不能替代 v3 握手;旧 Gateway 不允许以“健康但不能处理 completion”的形式继续承载任务。

回执只允许 succeeded|failed。成功必须没有错误码,且两个风险布尔值均为 false;失败必须有稳定错误码,effect_may_have_applied=true 时 safe_to_resubmit 必须为 false。相同事件在获得匹配 ACK 前按低频间隔持续投递;旧 outbox 中的 attempts 和 expires 字段不再淘汰回执。晚到回执不能翻转 PHP 终态或重放 mutation;当且仅当任务类型已登记幂等业务终结器时,精确同源回执才能在保留原 failed 审计记录的同时收敛 PHP 账本与 effect fence。

Go context 无法可靠中止已进入 CGo/libvirt 的调用。父 Agent 到达绝对截止后终止整个 helper 进程组并执行有界 Wait;未确认 helper 已退出时保留 durable execution fence。Agent 重启先检查 helper 回执;若回执文件未发布但子 Journal 已提交终态,则在主/子身份及受信任文件校验通过后导入。既无完整回执也无可信终态证据时才以 result_unconfirmed 失败并保留栅栏,不再次执行。

错误

普通错误 envelope:

{
  "error": {
    "code": "stable_machine_code",
    "message": "bounded public message",
    "retryable": false
  }
}

message 只用于受控管理员诊断,业务分支使用本地白名单中的 code。响应不能包含 Go error chain、libvirt XML、宿主机文件路径、签名、密钥、VNC 地址或凭据。

状态 含义
400/422 JSON 或字段无效
401 HMAC、时间窗、nonce 或 actor 无效
403 actor 权限不足
404 endpoint 或资源不存在
409 operation 指纹冲突、资源被执行栅栏保护或状态冲突
413 正文超过限制
501 capability 未构建,禁止降级
503 libvirt/本地依赖不可用;当前任务仍不会自动重派

端点

以下为 v1 主要契约;所有 mutation 都需要 operation ID,并使用上述单次派发与完成回执模型。

Method Path 用途
GET /v1/health 进程、Journal 和 libvirt 连接健康
GET /v1/capabilities 版本、固件、网络和可选能力
GET/POST /v1/vms 列表 / 创建 VM
GET/DELETE /v1/vms/{uuid} 元数据 / 正常关机后删除
GET /v1/vms/{uuid}/state 当前电源观察
POST /v1/vms/{uuid}/force-delete 单独授权的强制删除任务
POST /v1/vms/{uuid}/actions start/shutdown/reboot/reset/destroy
PATCH/POST /v1/vms/{uuid}/settings 主机名、密码或 SSH 公钥
POST /v1/vms/{uuid}/resources 关机状态下单调扩容 CPU、内存、系统盘与带宽
POST /v1/vms/{uuid}/network 使用签名公网意图换网
POST /v1/vms/{uuid}/network/suspend 断网,不改变电源
POST /v1/vms/{uuid}/network/resume 恢复账期网络策略
POST /v1/vms/{uuid}/service/suspend 到期策略暂停
POST /v1/vms/{uuid}/service/resume 服务策略恢复
POST /v1/vms/{uuid}/reinstall 重装
GET /v1/vms/{uuid}/metrics 当前指标
GET /v1/vms/{uuid}/traffic/daily?days=1..30 按日流量
POST /v1/vms/{uuid}/console-ticket 一次性控制台票据
GET/POST /v1/vms/{uuid}/snapshots 列表 / 创建快照
DELETE /v1/vms/{uuid}/snapshots/{id} 删除快照
POST /v1/vms/{uuid}/snapshots/{id}/restore 恢复快照
GET/PUT /v1/vms/{uuid}/firewall 读取 / 原子应用防火墙
GET /v1/vms/{uuid}/rescue 救援状态
POST /v1/vms/{uuid}/rescue/enter 进入救援
POST /v1/vms/{uuid}/rescue/force-start 明确确认后冷关机启动救援
POST /v1/vms/{uuid}/rescue/exit 确认数据风险后强制停止救援、卸载 ISO 并冷启动原系统
GET /v1/operations/{operation_id} 读取不可变 operation 状态
GET /v1/operations/{operation_id}/inspect 超级管理员只读证据检查
GET /v1/operations/{operation_id}/fence-resolution 读取已持久化的该 operation 栅栏结论
POST /v1/operations/{operation_id}/resolve-fence 只写 Journal 审计元数据并移除该 operation 的准入索引
GET/POST /v1/templates 列出 / 导入云镜像
PATCH/DELETE /v1/templates/{id} 更新 / 删除云镜像
GET/POST /v1/user-isos?owner_id=... 列出 / 导入用户 ISO
DELETE /v1/user-isos/{id}?owner_id=... 删除用户 ISO

面板暂存的云镜像和救援 ISO 导入请求会在签名正文中携带 source_size_bytes。若反向代理把下载响应改为 chunked、使 Agent 无法读取 Content-Length,Agent 使用该不可变预期大小创建有界 stream;若响应仍包含 长度则必须与预期完全一致,最终正文也必须恰好为该字节数并通过 SHA-256 校验。远程 URL 导入不携带该字段,仍必须返回有效的 Content-Length。 任何导入源都不得使用压缩 Content-Encoding。

不存在 mutation reconcile、confirm-inspection、abort-job 或 cleanup endpoint。inspect 不取得 mutation admission,不写 Journal,不继续原目标,也不能调用任何 libvirt 变更。不可变 Journal 成功或明确无副作用失败可以为策略表中的任何类型提供精确结论;其他已失败且影响未知的类型只有在该 action 的专用投影证据完整匹配时才能输出 applied/not_applied,否则保持 partial/inconclusive。例如实例设置只有在 Domain metadata 与 NoCloud seed 都匹配同一 transition ID 时才是 applied,两者都确认未提交时才是 not_applied。电源、网络链路或服务的“当前状态刚好符合目标”不是原 operation 的强证据,必须保持 inconclusive。

关键资源语义

  • VM 内部 libvirt 名称由 actor user ID 和完整 UUID 派生;面板名称只写受控 metadata。客户端不能指定 Domain 名或提交 XML。
  • 新 Domain 固定 x86_64/q35、UEFI、Secure Boot 关闭。loader/VARS 路径来自本机配置与 domcapabilities,请求不能覆盖。
  • 新 Domain 的唯一公网网卡通过专属 virt-<uuid> nwfilter 引用 clean-traffic,并把已分配的纯 IPv4 地址作为显式 IP 参数写入 Domain XML,禁止来宾伪造源 IP。换网操作必须在同一次 seed/Domain 事务中验证旧绑定并替换为新地址;缺少显式绑定的旧 Domain 不自动补齐。
  • 资源升级请求必须携带完整的来源和目标规格并确认实例已关机;CPU、内存、系统盘和带宽均只能增加或保持不变,且至少一项增加。Agent 会拒绝活动实例、快照、救援状态、待清理磁盘和来源规格漂移。系统盘只使用绝对目标容量且不启用 shrink,扩大的虚拟磁盘不会自动扩展来宾分区或文件系统。
  • 正常删除先请求 ACPI 关机。只有同一次执行明确观察到关机请求已接受但等待结束仍活动,才返回 force_required;强删必须使用新的 operation、超级管理员与 ack_data_loss=true。
  • 删除成功必须确认 Domain、全部面板受管磁盘、Seed、专属过滤器、NVRAM 和流量状态均已消失。任何证据不可读都返回失败且可能保留资源栅栏。
  • ShutdownFlags、Reboot 等调用成功只表示 libvirt 接受请求,不统一表示来宾已达到最终电源状态;回执 result 必须准确描述实际被确认的语义。
  • 快照 JOB_COMPLETED 事件只唤醒当前 helper 读取一次新鲜 job 状态,事件本身不是终态。匹配的 backup job 最多中止一次,并且不会由管理员恢复 endpoint 续作。
  • storage stream 使用 non-blocking 模式;callback、abort、finish 与 free 均由 helper 生命周期收口。
  • libvirt 连接重连只恢复新请求能力,不读取 operation 历史或触发 mutation。

控制台与能力

浏览器先从 PHP 获取一次性面板票据;Gateway 再通过已认证 Agent session 使用一次性 Agent ticket 建立反向 binary 通道。票据固定短 TTL、在连接上游前原子消费,重复、过期、跨用户或跨 VM 均拒绝。浏览器永远看不到 Agent ID、endpoint 或 VNC 地址。

features 只能声明当前二进制真正实现并可安全使用的功能。未使用 libvirt build tag、缺少本机固件/目录或反向控制台条件不足时必须返回 false/501,不能提供假成功或旧实现回退。