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

243 lines
30 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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 字节密钥。每个请求包含:
```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"`。这包括进入日志前的拒绝,以及已预留 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}` | 请求正常关机;关机后删除定义及显式列出的受管磁盘,超时只返回 `force_required` |
| POST | `/v1/vms/{uuid}/force-delete` | 超级管理员以新 `operation_id`、原正常关机 operation 和 `ack_data_loss=true` 发起独立强制删除 |
| 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}` | 读取持久操作结果 |
| GET | `/v1/operations/{operation_id}/inspect` | 超级管理员只读核对 Domain/XML/job/卷/filter/存储池证据,不改变宿主机或 Journal |
| POST | `/v1/operations/{operation_id}/confirm-inspection` | 超级管理员提交最新只读核对 token,只在新鲜证据逐字匹配时确认终态并更新 Journal |
| POST | `/v1/operations/{operation_id}/abort-job` | 超级管理员按最新 inspection token 请求中止已确认属于该快照操作的 backup job |
| POST | `/v1/operations/{operation_id}/cleanup` | 超级管理员按最新只读核对生成的 plan 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`。
管理员恢复接口把“看状态”和“改状态”分开。`GET .../inspect` 不进入原 operation 的资源锁,因为正在执行且无法被 context 取消的 backup 会一直持有该锁;接口只能读取 Journal、Domain/XML、`GetJobStats`、卷、filter 和存储池证据,不能调用 destroy、undefine、define、卷删除、filter 删除或写流量状态。响应只包含 `operation_id`、Journal 的 `operation_status`、Unix 秒 `checked_at`、`outcome`、稳定 `summary_code`/可选 `error_code`,以及固定形状的 `confirmation`、`abort_job` 和 `cleanup`;不得包含 XML、路径、libvirt 原始异常或原 operation result。
当只读核对已经得到明确终态,且没有待中止作业或待清理残留时,`GET .../inspect` 返回 `confirmation.available=true` 和小写 64 位十六进制 `inspection_token`。token 绑定 operation 标识、资源、动作、原请求指纹和本次只读核对得到的完整私有 Resolution;私有 result 和错误文本只参与摘要,不进入 inspection 响应。`POST .../confirm-inspection` 的正文只能是 `{"inspection_token":"<token>"}`。Agent 必须在原 operation 的 Journal 资源准入内重新执行一次只读核对,只有新证据仍产生相同 token 和明确终态时才把该 Resolution 写为持久终态并释放 resource blocker;客户端不能提交 outcome、result 或 error 来指定结论。token 过期、证据不完整、核对失败或新旧证据不同均返回 409 `inspection_inconclusive`,同时返回最新安全 inspection,Journal 必须保持原样。成功返回 200,正文同时包含更新后的 `operation` 和最新 `inspection`;整个确认流程不得调用 Hypervisor `Reconcile`、cleanup、abort 或其他宿主机 mutation。
`abort_job.available` 当前只可能用于 `create-snapshot:*`。Agent 必须同时确认同一 VM 上的活动 job 为 `BACKUP`,并读取 `BackupGetXMLDesc`,确认唯一的 push `vda` target 等于该 operation 的确定性 managed snapshot volume;任一证据不可读、不唯一或不匹配就不得返回 token,也不得中止。系统当前没有启动并持久化 block-job target,因此发现任意 block job 都不能推断为本系统 operation,`kind=block` 暂不启用。`inspection_token` 是小写 64 位十六进制摘要;`POST .../abort-job` 必须重新完成上述核对并逐字匹配 token,调用 `AbortJob` 后即使 HTTP 请求取消也要继续读取终态,最多 30 秒,仍没有 `COMPLETED`/`FAILED`/`CANCELLED` 就保持不确定。
只读核对只有在能够完整列出后续每一种 mutation 时才返回 `cleanup.available=true`。`steps` 只允许 `destroy_domain`、`undefine_domain`、`delete_managed_volumes`、`delete_seed_volume`、`undefine_network_filter`、`delete_nvram`、`remove_traffic_state`、`delete_snapshot_volume`、`remove_snapshot_metadata`、`delete_previous_root` 和 `persist_cleanup_metadata`。`plan_id` 是小写 64 位十六进制摘要,并绑定规范化的私有残留证据,包括具体卷集合及卷 XML 摘要、Domain XML 摘要、filter XML 摘要和 NVRAM 文件属性;这些证据本身不进入响应。`POST .../cleanup` 先通过 Journal 正常资源准入,再重新只读核对并逐字匹配当前 plan,计划改变、出现共享引用、活动 job 或证据不可读时必须拒绝。对于仍存在的 Domain,Agent 必须先确认 domain job 为 `NONE`,再从当前 Domain XML 枚举每个磁盘 target 并确认没有 block job;任一查询失败、任一外部 job 活动,或进入 mutation 尾段前的再次检查不再空闲,都不得清理。只有全部匹配后才可调用原 operation 已绑定的幂等 cleanup 尾段。
存储上传和下载使用 `VIR_STREAM_NONBLOCK` 与 libvirt event loop。请求 context 取消、读写失败或校验失败时必须先移除事件回调并 `StreamAbort`;只有完整成功路径才 `StreamFinish`。创建、重装、删除等没有通用 libvirt 取消 API 的操作仍依赖晚到结果与状态核对,不能把 HTTP 超时当作底层操作已中止。
VM 删除分为明确的破坏性边界。普通 `DELETE` 只发送 ACPI 正常关机请求并等待最多 30 秒;来宾仍活动时以 `force_required` 结束,不调用 `DestroyFlags`,自动核对也不得把它升级为强制删除。只有 `ShutdownFlags` 已确认成功且原始 `delete-vm` 或 `service-suspend` 调用实际完成正常关机等待后,才可持久化 `force_required`。正在执行的 `dispatching` 操作即使只读核对发现 Domain 仍活动也不能提前结案;Agent 重启会先把该记录恢复为无 cause 的 `uncertain`,随后只有在原 operation 重新取得 Journal 资源准入并完成新鲜只读核对后,才能把仍活动的旧操作结案为 `graceful_shutdown_unconfirmed`,要求用新的 operation ID 重试正常关机,绝不能据此产生强制授权。若 `ShutdownFlags` 返回错误,Agent 仍完成整个观察窗口:来宾随后停止可继续安全删除,始终活动则以 `graceful_shutdown_request_failed` 结束并要求用新 operation 重新正常关机,活动状态也无法读取才保留 `graceful_shutdown_ambiguous`;这两种错误都不能产生强制授权。只有超级管理员随后提交新的 `operation_id`、同 VM 的原 `delete-vm` 或到期 `service-suspend` operation、`remove_managed_disks=true` 和 `ack_data_loss=true`,Agent 才允许独立 `force-delete-vm` 调用 `DestroyFlags(DEFAULT)`。强制调用一旦派发,HTTP 超时或结果不明只能进入 `uncertain`;自动核对不得重放 `DestroyFlags`,只能在 Domain 已确认 inactive/absent 后继续原 operation 的 undefine 与 UUID 专属清理尾段。若强制 operation 达到 `needs_attention` 后新鲜只读核对仍确认 Domain 活动,管理员可用核对 token 在 Journal 资源准入内把旧强制 operation 结案为 `force_delete_unconfirmed_active`;这只恢复原正常关机 operation 的强制确认入口,不会执行 Destroy。管理员必须再次确认 `ack_data_loss=true`,面板才会以另一个新 operation ID 发起强制删除。
进入 undefine 前,Agent 必须读取 inactive Domain XML,并列举 managed-save、原生 snapshot/checkpoint metadata、实际 NVRAM 路径和 nwfilter 引用证据。其他 Domain 的 live/inactive XML、managed-save XML、原生 snapshot 内嵌的 Domain/InactiveDomain 以及快照磁盘、内存和 `revertDisks` 都参与卷引用检查;过滤器检查还覆盖上述历史 Domain XML和其他 NWFilter 的间接 `filterref`。任一列表、XML 或引用证据不可读都失败关闭。原生外部/手工 snapshot、`revertDisks` 或磁盘下的 `snapshotDeleteInProgress` 存在时,不得仅用 `SNAPSHOTS_METADATA` 删除元数据;operation 保持待处理,管理员先在宿主机完成 libvirt 原生快照删除或回滚,再立即核对。`UndefineFlags` 同时带 `MANAGED_SAVE`、`SNAPSHOTS_METADATA`、`CHECKPOINTS_METADATA` 与 `NVRAM`;调用报错时即使随后查到 Domain absent 也保持 `uncertain`,直至新鲜只读证据分别确认 Domain、全部受管卷、Seed、面板受管且无其他引用的过滤器、NVRAM 与本地流量状态均已消失。首次删除、强制删除及 reconcile 共用这一最终 absence 检查。
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 的请求指纹为:
```text
SHA256(UPPERCASE_METHOD + "\n" + EXACT_TARGET + "\n" + EXACT_BODY_BYTES)
```
Agent 在调用 libvirt 前将 `operation_id`、VM UUID/资源 ID、动作、指纹、是否破坏性和状态原子持久化。状态为 `reserved`、`dispatching`、`succeeded`、`failed`、`uncertain`、`needs_attention`。自动核对有持久化的次数与年龄上限;默认最多 24 次、从首次不确定起最多 6 小时,libvirt 事件的一分钟最小间隔内不会重复扣减次数。任一上限到达后进入 `needs_attention` 并退出自动 recovery index。nonce TTL 至少为签名时钟偏差的两倍,到期边界仍保留,避免未来时间戳签名仍有效时释放 nonce。
持久层是 bbolt 数据库;每次状态变化只更新对应记录,nonce 由独立的到期时间索引清理,不扫描或重写完整 operation 历史。inflight 索引只负责把进程中断时的 `reserved`/`dispatching` 恢复为 `not_dispatched`/`uncertain`;独立 recovery 索引只列出可自动核对记录,resource-blocker 索引则在重启后继续保护未决资源。`dispatching` 本身由进程内资源锁保护,不进入 durable blocker;若请求超时,它先变成 `uncertain` 并写入 blocker,真实 libvirt 调用返回前仍不释放运行时锁。等待者取得锁后必须在写入自身 `dispatching` 前重新检查 blocker,因此前一操作仍未决时不能越过派发边界。`needs_attention` 不再被自动 worker 领取,但 blocker 会一直保留;只允许同一 operation 的人工只读证据确认、匹配作业中止或已确认清理计划取得终态后释放。已完成且不再需要核对的结果和 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 使用手工固件路径:
```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` 核对。