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

21 KiB

Virt Host Agent WSS/API v1

本协议只供 PHP 面板通过本机 Go Gateway 调用宿主机 Go Agent。浏览器、第三方客户端和另一台宿主机不得直接使用;不提供旧引擎 API 兼容。

传输与编码

  • Agent 配置面板 HTTPS origin、数字 agent_id 和独立 agent_secret,主动连接 WSS /agent/connect,子协议固定为 virt-agent-control.v1。请求头携带 X-Virt-Agent-ID 与 Authorization: Bearer <agent_secret>;Gateway 必须通过 PHP 内部接口校验后才接管会话。Agent 不启动入站 HTTP/TLS listener,不需要部署宿主机证书或开放管理端口。
  • 基础 API 语义仍使用 /v1。PHP 先用每宿主机密钥对内层 method/target/body 签名,再用 Gateway 本机共享密钥向字面 loopback 的 POST /internal/agent/request 提交转发 envelope。Gateway 不改写内层字节,Agent 在进程内将其交给同一 API handler 校验与执行。
  • 请求和响应使用 UTF-8 JSON,Content-Type: application/json。无正文 GET 的摘要按空字节串计算。
  • JSON decoder 拒绝未知字段、多个顶层值、尾随非空内容、错误类型和超过 max_body_bytes 的正文。
  • ID、UUID、路径、URL、网桥名、MAC、CIDR、脚本和数组数量都必须有显式格式/长度上限;不能把任意 XML、shell 命令或 libvirt flags 作为 API 输入。
  • 时间使用 UTC RFC 3339;字节数使用整数,不用浮点;响应禁止包含密钥、宿主机文件内容、VNC 地址或底层凭据。

控制帧是严格 JSON:Gateway 发送 {"type":"request","id":"...","method":"GET","request_target":"/v1/...","body":"...","headers":{...}},Agent 返回 {"type":"response","id":"...","status":200,"body":"{...}"}。id 只用于连接内匹配响应;业务幂等和防重放仍以内层 HMAC、nonce 和 operation_id 为准。任一方断线或超时只能返回不确定运输结果,不得为此生成新 operation_id 或自动重放变更。

HMAC 认证

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

X-Virt-Timestamp: Unix 秒数字符串
X-Virt-Nonce: 16-128 个 URL-safe 字符
X-Virt-Content-SHA256: 小写十六进制 SHA-256(body)
X-Virt-Actor: URL-safe base64(无填充)的 actor JSON
X-Virt-Signature: 小写十六进制 HMAC-SHA256

actor JSON 的固定字段:

{
  "user_id": 42,
  "is_admin": false,
  "is_super_admin": false,
  "can_manage": false,
  "operation_id": "01J_OPERATION_ID"
}

只读请求可省略 operation_id;变更请求必须携带,并与正文中的值一致。actor 不接受未知字段。

canonical 字节串为六段原值以单个 LF 连接,末尾不追加 LF:

UPPERCASE_METHOD + "\n" +
ESCAPED_PATH_WITH_EXACT_RAW_QUERY + "\n" +
LOWERCASE_BODY_SHA256 + "\n" +
TIMESTAMP + "\n" +
NONCE + "\n" +
RAW_X_VIRT_ACTOR

X-Virt-Signature = hex(HMAC-SHA256(host_secret, canonical))。Agent 先验证时间窗、格式、正文摘要和签名,再原子消费 nonce;签名与摘要用常量时间比较。失败统一返回 401,不透露具体签名差异。

响应与错误

成功响应是单个 JSON object;列表放在具名字段中,不直接返回顶层数组。错误使用稳定 envelope:

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

message 只用于管理员诊断,业务分支必须使用 code。不得回传 Go error chain、libvirt XML、文件路径、请求签名或密钥。HTTP 状态约定:

状态 含义
400/422 JSON 或字段无效;修正请求后再提交
401 HMAC、时间窗、nonce 或 actor 无效
403 actor 没有所需权限
404 指定 UUID/资源不存在
409 operation_id 指纹冲突、状态冲突或资源忙
413 请求体超过限制
501 capability 未实现,禁止静默降级
503 libvirt/本地依赖暂不可用;变更是否可重试仍取决于派发边界

持久操作响应包含 operation_id、status、replayed、retryable,并可按状态包含 result、error 和可选 cause_code。已越过派发边界的错误 envelope 在 error.operation 中携带同一持久记录,其可选 cause_code 规则相同。 cause_code 是 1~64 字符的稳定 lower_snake_case 诊断标识;只保留首个有效根因, 后续 uncertain/reconcile 不得覆盖,操作最终成功时必须清除。它只用于管理员诊断, 不是业务分支或用户展示的公开错误码。

只有在请求明确尚未越过持久派发边界时,Gateway/Agent 才能在上述严格 error 对象中增加 "dispatch_state":"not_dispatched"。这包括进入日志前的拒绝,以及已预留 operation 但在等待资源锁或容量槽时失败;后一种记录必须允许同一指纹和同一 operation_id 安全地重新准入。面板只接受顶层 仅含 error,且该对象恰好由 code、message、retryable、 dispatch_state 四个字段组成的 envelope: 不可重试的 400/413/422/501、普通 unauthorized 401、所有 403,以及 路由契约的 404/405 作为终态请求错误;operation_not_found 等资源 404 不属于该捷径。可重试的 5xx 才把同一 operation_id 放回持久队列。 没有该标记、字段多余或形状错误都必须按不确定处理。

replayed_request 与 Gateway 的 gateway_replayed_request 绝不能带 not_dispatched:相同 nonce 的首次请求可能已经越过派发边界。若操作已 越过派发边界,错误 envelope 还应返回同一 operation_id 和 status: "uncertain";retryable 不能覆盖 no-replay 规则。

基础端点

以下路由为 v1 契约;最终路径必须与 agent/server 路由测试保持逐字一致。尚未在当前 Go 路由注册的功能必须返回 capability false/501,不得提供假成功。

Method Path 用途
GET /v1/health 进程、操作日志和 libvirt 连接健康
GET /v1/capabilities 版本、固件和可选能力
GET /v1/vms 面板授权范围内的 VM 元数据
POST /v1/vms 创建 VM
GET /v1/vms/{uuid} VM 元数据
GET /v1/vms/{uuid}/state 当前电源状态
DELETE /v1/vms/{uuid} 删除定义及显式列出的受管磁盘
POST /v1/vms/{uuid}/actions start/shutdown/reboot/reset/destroy
PATCH/POST /v1/vms/{uuid}/settings 主机名、root 密码或 SSH 公钥;必须明确确认重启
POST /v1/vms/{uuid}/network 切换到面板指定的现有网桥 / libvirt network 及 PHP 签名的公网 IP intent
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 CPU/内存/磁盘/网络累计指标
GET /v1/vms/{uuid}/traffic/daily?days=1..30 最多 30 天按日流量
POST /v1/vms/{uuid}/console-ticket 签发 60 秒、一次性 Agent console ticket
GET /v1/vms/{uuid}/snapshots 快照列表
POST /v1/vms/{uuid}/snapshots 创建快照
DELETE /v1/vms/{uuid}/snapshots/{id} 删除快照
POST /v1/vms/{uuid}/snapshots/{id}/restore 恢复快照
GET/PUT /v1/vms/{uuid}/firewall 读取/原子应用防火墙 revision
GET /v1/vms/{uuid}/rescue 救援状态
POST /v1/vms/{uuid}/rescue/enter 进入救援,不自动强制关机
POST /v1/vms/{uuid}/rescue/force-start 仅对已核验的 staged rescue 冷关机并启动;必须 ack_data_loss: true
POST /v1/vms/{uuid}/rescue/exit 退出救援并保持账期网络策略
GET /v1/operations/{operation_id} 读取持久操作结果
POST /v1/operations/{operation_id}/reconcile 核对宿主机证据;只允许同一 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

VM 名称边界

POST /v1/vms 请求中的 name 仍是面板显示名称,也是首次生成 Guest 配置时使用的名称输入;它不再直接写入 libvirt 域的 <name>。Agent 在得到最终 VM UUID 后,只能使用已验签 X-Virt-Actor 中的 user_id 与该 UUID 派生宿主机内部名称:<user_id>:vm-<UUID 去掉连字符并转为小写后的前 12 位>,例如用户 3 与 UUID 83472897-3274-... 得到 3:vm-834728973274。内部名称字段不是请求正文契约,客户端提交 domain_name 或其他自定义 libvirt 名称必须按未知字段拒绝;后续查询、变更和对账仍以完整 UUID 定位,不能依赖名称。

Agent 把原始 name 保存为 Virt Cloud 的 display-name 域 metadata,并在 VM 元数据响应中优先返回它。既有 VM 若没有 display-name metadata,则只在读取时回退到原有 libvirt domain name,不能因此自动重命名、重定义或迁移旧域。该内部命名规则仅用于规则启用后新建的 VM。

创建快照请求的 consistency_mode=filesystem 表示“优先文件系统一致”:Agent 先确认本地 libvirt 客户端和守护进程均支持 5.10.0 引入的 Guest Agent 响应上限;版本较旧时直接改用 crash,版本查询失败则返回基础设施错误。确认支持后,Agent 用只读 guest-ping 检查 QEMU Guest Agent,再在冻结前通过 libvirt 把冻结和解冻命令的响应上限设置为 guest_agent_timeout_seconds(默认 15 秒)。当 libvirt 明确报告 Guest Agent 未配置、未响应、探测超时,或驱动不支持设置响应上限时,也自动改用 crash。显式请求 crash 时不探测也不冻结 Guest。若 QGA 探测和超时设置均成功,但后续冻结、解冻或 libvirt 通信失败,不得伪装成安全降级;结果不明确时仍必须保留 uncertain。该响应上限只约束 Guest Agent 命令,不是后续 push backup 的超时。成功响应的 consistency 以及宿主机和面板快照元数据必须记录实际采用的模式,协调时只允许 filesystem 请求单向降级为 crash,绝不允许反向提升。

在线快照继续使用 libvirt push backup:BackupBegin 启动后以 GetJobStats 等待终态。JOB_COMPLETED 事件只会唤醒一次新的 GetJobStats 核对,事件本身不构成成功或失败证据;固定间隔轮询仍作为事件丢失时的兜底。请求超时时,只有当前活动任务仍明确标识为该 backup 时才调用一次 AbortJob,随后继续等待最多 30 秒,直到观察到 COMPLETED、FAILED 或 CANCELLED;无法确认终态时保持 uncertain。已经终态、任务类型不明或出现其他 libvirt job 时不得调用 AbortJob。快照恢复、快照删除、创建、重装和删除虚机均不使用 AbortJob。

存储上传和下载使用 VIR_STREAM_NONBLOCK 与 libvirt event loop。请求 context 取消、读写失败或校验失败时必须先移除事件回调并 StreamAbort;只有完整成功路径才 StreamFinish。创建、重装、删除等没有通用 libvirt 取消 API 的操作仍依赖晚到结果与状态核对,不能把 HTTP 超时当作底层操作已中止。

Agent 在打开 qemu:///system 前注册并持续运行 libvirt 默认 event loop。每个连接 generation 都注册全域 lifecycle、JOB_COMPLETED 和 connection close callback;stream readable/writable 使用同一个 event loop。回调只发送有界、合并的核对唤醒,不保存回调中的临时 domain/connection 句柄,也不在事件线程中调用 libvirt 做核对或重连。

连接异常关闭后,Agent 在后台按有界退避建立新 generation 并重新注册全部回调;新连接完整就绪并发布后,才允许新请求使用并扫描 Journal 的全部可核对记录。旧 generation 会等其在途调用返回后再释放。Agent 启动执行同一扫描,并以低频周期扫描作为事件丢失的兜底。事件、completed job stats 和连接内存状态都不替代 Journal;Agent 或 libvirt daemon 重启导致事件缺失时,仍按原 operation_id 与宿主机状态核对,绝不重放原变更。

本表只描述已注册的 HTTP 路由;对应 libvirt 实现未落地或本机依赖不支持时,features.* 必须为 false 并返回 501,不得假成功。公网池的销售库存仍只在 PHP;Agent 仅在 VM 创建/换网时验证签名的 pool key、CIDR、IP、gateway、DNS 和面板指定的网络接入。网络值只接受 bridge:<名称> 或 network:<名称>;名称以字母或数字开头,后续仅允许字母、数字、点、下划线和短横线,bridge 为 1~15 字符,network 为 1~64 字符。Agent 验证并使用宿主机已存在且活动的网络,不创建或修改系统网络。

operation_id、指纹与串行

operation_id 为 8~80 个 URL-safe 字符,由 PHP 创建后在所有重试中保持不变。Agent 的请求指纹为:

SHA256(UPPERCASE_METHOD + "\n" + EXACT_TARGET + "\n" + EXACT_BODY_BYTES)

Agent 在调用 libvirt 前将 operation_id、VM UUID/资源 ID、动作、指纹、是否破坏性和状态原子持久化。状态为 reserved、dispatching、succeeded、failed、uncertain。nonce TTL 至少为签名时钟偏差的两倍,到期边界仍保留,避免未来时间戳签名仍有效时释放 nonce。

持久层是 bbolt 数据库;每次状态变化只更新对应记录,nonce 由独立的到期时间索引清理,不扫描或重写完整 operation 历史。inflight 索引只负责把进程中断时的 reserved/dispatching 恢复为 not_dispatched/uncertain;独立 recovery 索引只列出可核对记录,因此启动、重连和事件唤醒都不遍历永久 tombstone。已完成且不再需要核对的结果和 expected-state 详情保留 90 天后压缩,释放页面供后续事务复用;仍可核对的记录必须保留 expected-state、结果和资源租约元数据,直到取得终态。operation_id、请求指纹、资源、动作和终态永久保留为 tombstone,任何清理都不得让旧的破坏性标识重新可用。update-settings、change-network、网络 suspend/resume、服务 suspend/resume 与 apply-firewall 在同一派发事务中额外保存无密钥 expected-state(只含 transition id、公开网络意图、解析后的本机网络 source、布尔状态或防火墙摘要;绝不保存密码、SSH key、token 或原始正文)。设置/网络/防火墙写入相同的宿主机 transition marker;重启后的 reconcile 只读比较 marker 与实际状态,换网还必须匹配持久化的 bridge/libvirt-network source,完整匹配才成功,明确未提交或半提交则失败并要求前向处置,绝不自动重放。

  • 首次请求保留标识并写盘;同标识同指纹返回已有或进行中的记录。
  • 同标识不同指纹返回 409,绝不执行第二个请求。
  • 每个 VM UUID 使用独立串行锁;同 VM 变更不得并发,不同 VM 可并行。
  • 进程启动时遗留 dispatching 必须转为 uncertain,不能自动继续调用。
  • CGo/libvirt 调用通常不能被 Go context 真正取消。HTTP 超时后 Agent 仍必须记录晚到结果,不能丢弃唯一证据。

reconcile 不重新提交原 API 变更。通常只读取操作日志和宿主机现状;证据不足就保持 uncertain。只有目标可由同一 operation 和 VM UUID 唯一推出时,才允许续作幂等尾段:例如已提交的 reinstall/snapshot 旧卷清理,或 delete-vm 在重新核验 managed ownership、全部磁盘交叉引用后继续收敛到“域与专属工件均不存在”。delete 的 destroy/undefine 即使返回错误也必须复查实际活动/存在状态;没有观察到目标状态就继续保持 uncertain。VM 仍在运行不证明之前的 shutdown/reboot 未执行;持久域暂时查不到也不自动证明磁盘已安全删除。

救援进入先持久化救援 XML,再请求正常关机。若来宾没有在等待窗口内关机,操作以 succeeded 返回 staged: true 和 pending_manual_restart: true,不会隐式 destroy。只有随后显式提交同名的 force-start API、确认 ack_data_loss,且 Agent 重新核验持久救援定义、模板与 live 原系统状态后,才允许冷关机并启动救援环境。

控制台票据

浏览器先从 PHP 获取一次性面板票据,再连接面板 virt-cloud-agent-gateway 的 /engine-console。Gateway 通过 PHP 内省得到数字 Agent ID 和一个 Agent console ticket;浏览器不能提供 Agent ID、endpoint 或 VNC 目标。

Agent console ticket 的当前边界:

  • 只能由通过 HMAC 且具有 can_manage 的 panel-to-Agent POST /v1/vms/{uuid}/console-ticket 签发,TTL 固定 60 秒。
  • Agent 仅在内存中将随机票据映射到该 VM 的本地 loopback VNC 目标;进程重启会使未用票据全部失效。
  • 票据在尝试建立上游连接前就被原子消费;过期、重复或已消费一律拒绝,连接失败也不退回票据。
  • 面板浏览器票据另行绑定会话、用户和 VM;Gateway 每 15 秒向 PHP 重新内省,负责在登出、撤销或权限变更后断开会话。
  • 只把 VNC 绑定地址留在 Agent 内部,API 和浏览器都不能看到宿主机 VNC 地址/端口。

Gateway 在已认证控制通道发送 console_open,其中包含一次性 Agent ticket、会话 ID 和随机反向通道 token。Agent 在尝试 VNC 前原子消费票据,然后主动连接 WSS /agent/console,子协议为 virt-agent-console.<token>;反向通道只转发 binary frame。features.console 只有在完整 broker、本地 VNC 与反向 Gateway 连接可用时才能为 true。

UEFI 与 Secure Boot

POST /v1/vms 不接受 firmware mode、loader、NVRAM 路径或 Secure Boot 开关;所有新域固定为 UEFI 且 Secure Boot 关闭。运维在部署时依据本机 domain capabilities 选定不启用 Secure Boot 的 loader、NVRAM template 与目录,并把它们作为 Agent 本地固定配置。域为 x86_64/q35,XML 使用手工固件路径:

<loader readonly="yes" secure="no" type="pflash">...</loader>
<nvram template="...">...</nvram>

手工指定 loader/NVRAM 时不得再生成仅适用于 os firmware='efi' 自动选择模式的 <firmware><feature/></firmware> 列表;两种模式混用会被 libvirt 拒绝。loader secure="no" 表示所选固件不具备 Secure Boot 能力,实际路径还必须由宿主机配置固定为非 Secure Boot 固件。SMM 不得为了 Secure Boot 被隐式开启。宿主机不支持所选组合时明确拒绝,不能回退 BIOS 或硬编码另一个发行版的 OVMF 路径。

云镜像首次启动脚本

PHP 拥有镜像目录和脚本正文。创建请求携带已快照的 template generation/revision 与 startup_script;Agent 不从旧模板记录补取。

  • 脚本最大 32 KiB UTF-8,拒绝 NUL;CRLF 规范化为 LF,不 trim,空内容表示禁用。
  • 只在新云镜像 VM 首次安装时注入,不用于普通重启、settings、network、reinstall、rescue 或用户 ISO。
  • cloud-init seed 内脚本保存为 /var/lib/virt-cloud/startup.sh(0600),runner 为 /var/lib/virt-cloud/startup-runner.sh(0700)。
  • runner 在执行前原子创建 /var/lib/virt-cloud/startup/started,用 /bin/bash 执行,并写入 output.log 和 exit-code;日志轮转或容量限制由镜像/宿主机运维策略负责。
  • started 一旦建立,成功、失败、VM 重启、Agent 重启或控制面断线都不得自动重放。VM 创建 API 不等待脚本完成。
  • 请求、操作记录、域 metadata、普通用户 DTO 和日志不得保存或回显脚本正文。

权限与能力

Agent 不能只相信 is_admin 布尔值;路由先验证 HMAC,再按动作验证 can_manage/管理员级别和资源范围。普通用户动作必须由 PHP 确认所有权后签名,Agent 仍按最小 capability 执行。

GET /v1/capabilities 不接受网络探测参数,是运行时事实,不是承诺清单。某项未实现、宿主机版本不支持或依赖缺失时对应 feature 为 false;PHP 保持既有页面布局,但把动作显示为明确不可用。响应中的 network_selectors 是 Agent 自动发现的当前可用 bridge:<名称> / network:<名称> 列表,排序去重且最多 64 项:Linux 网桥须有 sysfs bridge 目录且接口为 UP,libvirt network 须为 active。该字段不再读取 Agent 配置映射;旧配置文件的 network_selectors 必须删除。

PHP 拥有宿主机 default_network,新建默认为 bridge:br0,只有该值与上述列表精确匹配时才允许 Agent 进入 ready 状态。旧 alias 和旧 healthy 结果不能继续作为就绪依据;网络变更须重新测试,创建和换网还会重新验证实际目标。更新协议不会自动改写已派发或 uncertain 操作的请求、指纹和 expected-state;这些操作仍按原 operation_id 核对。