# 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"`。这包括进入日志前的拒绝,以及已预留 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 域的 ``。Agent 在得到最终 VM UUID 后,只能使用已验签 `X-Virt-Actor` 中的 `user_id` 与该 UUID 派生宿主机内部名称:`:vm-`,例如用户 `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":""}`。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.`;反向通道只转发 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` 是 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` 核对。