16 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"。面板只接受顶层
仅含 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 |
切换到已配置 selector 及 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 |
本表只描述已注册的 HTTP 路由;对应 libvirt 实现未落地或本机依赖不支持时,features.* 必须为 false 并返回 501,不得假成功。公网池的销售库存仍只在 PHP;Agent 仅在 VM 创建/换网时验证签名的 pool key、CIDR、IP、gateway、DNS 和本机 network selector。
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 索引使 Agent 启动只解码待恢复操作,不遍历永久 tombstone。终态结果和 expected-state 详情保留 90 天后压缩,释放页面供后续事务复用;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-AgentPOST /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 选定 loader、NVRAM template 与目录,并把它们作为 Agent 本地固定配置。域为 x86_64/q35,XML 必须明确:
<loader readonly="yes" secure="no" type="pflash">...</loader>
<firmware>
<feature enabled="no" name="secure-boot"/>
<feature enabled="no" name="enrolled-keys"/>
</firmware>
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 是已排序、最多 64 项且当前探测可用的稳定 selector key 列表,只能包含 Agent 配置的 key,不能暴露 bridge/libvirt network 的本机 source。面板只有在宿主机 default_network 与该列表精确匹配时才允许 Agent 进入 ready 状态。