# 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 `;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 字节密钥。每个请求包含: ```text 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 的固定字段: ```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: ```text 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: ```json { "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 的请求指纹为: ```text 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-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.`;反向通道只转发 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 使用手工固件路径: ```xml ... ... ``` 手工指定 loader/NVRAM 时不得再生成仅适用于 `os firmware='efi'` 自动选择模式的 `` 列表;两种模式混用会被 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` 是已排序、最多 64 项且当前探测可用的稳定 selector key 列表,只能包含 Agent 配置的 key,不能暴露 bridge/libvirt network 的本机 `source`。面板只有在宿主机 `default_network` 与该列表精确匹配时才允许 Agent 进入 ready 状态。