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

316 lines
24 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。浏览器、第三方客户端和其他宿主机不能直接使用;不存在 Python 引擎、SSH 执行或旧数据库兼容路径。
## 传输
- Agent 使用数字 `agent_id` 与独立 `agent_secret` 主动连接 `WSS /agent/connect`,子协议固定为 `virt-agent-control.v3`。v3 的不可变完成回执必须携带操作三元身份;Agent 与 Gateway 不提供 v1/v2 兼容或协商降级,任一侧版本不一致必须在握手阶段失败。Gateway 必须通过 PHP 内部接口认证连接。
- PHP 把已签名的内层 API 请求发送到 Gateway 字面 loopback 的 `POST /internal/agent/request`。Gateway 不改写 method、request target、body 或内层认证头。
- 控制请求帧为 `request`,即时响应帧为 `response`;帧 ID 只负责当前连接的配对,不是业务幂等键。
- mutation 的即时响应只说明 Agent 已接收或已明确拒绝。Agent 在独立 helper 中执行一次,并通过单独的 `completion` 帧发送不可变终态回执。
- 断线、超时和进程重启都不得生成新 `operation_id`、重新发送 mutation,或从历史 Journal 启动 helper。
请求与响应使用 UTF-8 JSON。decoder 拒绝未知字段、多个顶层值、尾随内容、错误类型和超出 `max_body_bytes` 的正文。ID、UUID、URL、路径、MAC、CIDR、脚本和数组都有明确的格式与长度上限;API 不接受任意 XML、shell 命令或 libvirt flags。
## 内层 HMAC
每台宿主机使用不同的至少 32 字节密钥。请求头为:
```text
X-Virt-Timestamp: Unix 秒
X-Virt-Nonce: 16-128 个 URL-safe 字符
X-Virt-Content-SHA256: lowercase hex SHA-256(body)
X-Virt-Actor: URL-safe base64 无填充 actor JSON
X-Virt-Signature: lowercase hex HMAC-SHA256
```
actor 普通字段如下;只读请求可省略 `operation_id`,mutation 必须携带且与正文一致。普通签名路径拒绝客户端夹带 `system_recovery`。
```json
{
"user_id": 42,
"is_admin": false,
"is_super_admin": false,
"can_manage": false,
"operation_id": "0123456789abcdef0123456789abcdef"
}
```
面板内部对已派发、已失败但影响未知的允许类型进行恢复核对时,可以使用一个保留 actor。它没有人类管理员权限,并且严格绑定一个 operation:
```json
{
"user_id": 0,
"is_admin": false,
"is_super_admin": false,
"can_manage": false,
"system_recovery": true,
"operation_id": "0123456789abcdef0123456789abcdef"
}
```
该 actor 只能访问同一 `operation_id` 的 `GET inspect`、`GET fence-resolution` 和 `POST resolve-fence`,而且 Agent 还会按显式 action allowlist 再次授权;不能访问健康、能力、资源列表、原始 Journal 或任何 libvirt/catalog/storage mutation。`inspect`、完成回执和 `resolve-fence` 都必须同时匹配不可变的 `action + resource_id + request_fingerprint`。`resolve-fence` 只持久化该 operation 的审计结论并移除其 admission 索引,不调用 libvirt,也不继续或重放原操作。
canonical bytes 为六段原值用一个 LF 连接,末尾没有 LF:
```text
UPPERCASE_METHOD
ESCAPED_PATH_WITH_EXACT_RAW_QUERY
LOWERCASE_BODY_SHA256
TIMESTAMP
NONCE
RAW_X_VIRT_ACTOR
```
Agent 先验证时间窗、正文摘要、签名与 nonce,再进行路由和授权。nonce 只消费一次,签名和摘要使用常量时间比较;认证错误统一返回 401,不泄露差异。
## Mutation 与完成回执
PHP 在提交给 Gateway 前已经持久化任务、请求指纹、唯一 `operation_id` 和绝对截止时间。Agent 在调用 libvirt 前把同一标识与资源 admission 原子写入当前 Journal,然后最多启动一个隔离 helper。
即时响应:
```json
{
"operation_id": "0123456789abcdef0123456789abcdef",
"action": "power-reboot",
"resource_id": "123e4567-e89b-42d3-a456-426614174000",
"request_fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"status": "dispatching",
"replayed": false,
"retryable": false
}
```
HTTP `202` 仅表示这次 operation 已被 Agent 接收。已存在的相同 operation 和相同指纹只返回现有记录;不同指纹复用标识返回 409,绝不执行第二次。`retryable` 只保留为错误展示字段,PHP worker 和浏览器不能据此重派 mutation。
helper 结束后 Agent 写入唯一完成记录,并通过 WSS 发送:
```json
{
"type": "completion",
"id": "immutable-event-id",
"operation_id": "0123456789abcdef0123456789abcdef",
"action": "power-reboot",
"resource_id": "123e4567-e89b-42d3-a456-426614174000",
"request_fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"status": "failed",
"effect_may_have_applied": true,
"safe_to_resubmit": false,
"error_code": "result_unconfirmed",
"result": null
}
```
Gateway 只接受当前已认证 session 的事件,并自行注入该连接的 `agent_id`,用 Gateway-PHP 密钥签名后 POST `/api/internal/cloud/operation-completion`。PHP 按 agent、operation、事件 ID 和正文摘要幂等接收;成功处理后 Gateway 返回 `completion_ack`。ACK 只删除 Agent outbox,不能删除 Journal tombstone。
Agent 与 Gateway 必须来自同一发布版本。健康检查和 capabilities 只验证经当前控制连接转发的 Agent API,不能替代 v3 握手;旧 Gateway 不允许以“健康但不能处理 completion”的形式继续承载任务。
回执只允许 `succeeded|failed`。成功必须没有错误码,且两个风险布尔值均为 false;失败必须有稳定错误码,`effect_may_have_applied=true` 时 `safe_to_resubmit` 必须为 false。相同事件在获得匹配 ACK 前按低频间隔持续投递;旧 outbox 中的 attempts 和 expires 字段不再淘汰回执。晚到回执不能翻转 PHP 终态或重放 mutation;当且仅当任务类型已登记幂等业务终结器时,精确同源回执才能在保留原 `failed` 审计记录的同时收敛 PHP 账本与 effect fence。
Go context 无法可靠中止已进入 CGo/libvirt 的调用。父 Agent 到达绝对截止后终止整个 helper 进程组并执行有界 `Wait`;未确认 helper 已退出时保留 durable execution fence。Agent 重启先检查 helper 回执;若回执文件未发布但子 Journal 已提交终态,则在主/子身份及受信任文件校验通过后导入。既无完整回执也无可信终态证据时才以 `result_unconfirmed` 失败并保留栅栏,不再次执行。
## 错误
普通错误 envelope:
```json
{
"error": {
"code": "stable_machine_code",
"message": "bounded public message",
"retryable": false
}
}
```
`message` 只用于受控管理员诊断,业务分支使用本地白名单中的 `code`。响应不能包含 Go error chain、libvirt XML、宿主机文件路径、签名、密钥、VNC 地址或凭据。
| 状态 | 含义 |
| --- | --- |
| 400/422 | JSON 或字段无效 |
| 401 | HMAC、时间窗、nonce 或 actor 无效 |
| 403 | actor 权限不足 |
| 404 | endpoint 或资源不存在 |
| 409 | operation 指纹冲突、资源被执行栅栏保护或状态冲突 |
| 413 | 正文超过限制 |
| 501 | capability 未构建,禁止降级 |
| 503 | libvirt/本地依赖不可用;当前任务仍不会自动重派 |
## 端点
以下为 v1 主要契约;所有 mutation 都需要 operation ID,并使用上述单次派发与完成回执模型。
| Method | Path | 用途 |
| --- | --- | --- |
| GET | `/v1/health` | 进程、Journal 和 libvirt 连接健康 |
| GET | `/v1/capabilities` | 版本、固件、网络、VPC L3 前置条件和可选能力 |
| POST | `/v1/vpc/networks/{vpc_key}/apply` | 超级管理员按完整期望快照原子收敛宿主机 VPC bridge、/32 peer routes 与隔离规则 |
| POST | `/v1/vpc/networks/{vpc_key}/remove` | 超级管理员按已应用 revision/digest 前置条件移除宿主机 VPC 状态 |
| GET/POST | `/v1/vms` | 列表 / 创建 VM |
| GET/DELETE | `/v1/vms/{uuid}` | 元数据 / 正常关机后删除 |
| GET | `/v1/vms/{uuid}/state` | 当前电源观察 |
| POST | `/v1/vms/{uuid}/force-delete` | 单独授权的强制删除任务 |
| POST | `/v1/vms/{uuid}/actions` | start/shutdown/reboot/reset/destroy |
| PATCH/POST | `/v1/vms/{uuid}/settings` | 主机名、密码或 SSH 公钥 |
| POST | `/v1/vms/{uuid}/resources` | 单调扩容 CPU、内存、系统盘与带宽;运行中实例先正常关机,完成后冷启动恢复,绝不自动强制断电 |
| POST | `/v1/vms/{uuid}/network` | 使用签名公网意图换网 |
| POST | `/v1/vms/{uuid}/network/suspend` | 断网,不改变电源 |
| POST | `/v1/vms/{uuid}/network/resume` | 恢复账期网络策略 |
| POST | `/v1/vms/{uuid}/vpc-port` | 在宿主机路由投影已包含端口后,冷重启挂载一张 VPC 私网网卡 |
| DELETE | `/v1/vms/{uuid}/vpc-port` | 冷重启卸载精确匹配的 VPC 私网网卡;调用后才能从宿主机路由投影移除端口 |
| POST | `/v1/vms/{uuid}/service/suspend` | 到期策略暂停 |
| POST | `/v1/vms/{uuid}/service/resume` | 服务策略恢复 |
| POST | `/v1/vms/{uuid}/reinstall` | 重装 |
| GET | `/v1/vms/{uuid}/metrics` | 当前指标 |
| POST | `/v1/vms/{uuid}/console-ticket` | 一次性控制台票据 |
| GET/POST | `/v1/vms/{uuid}/snapshots` | 列表 / 创建快照 |
| DELETE | `/v1/vms/{uuid}/snapshots/{id}` | 删除快照 |
| POST | `/v1/vms/{uuid}/snapshots/{id}/restore` | 恢复快照 |
| POST | `/v1/vms/{uuid}/backups` | 把可移植的完整系统盘备份上传到预签名对象存储 multipart 目标 |
| POST | `/v1/vms/{new_uuid}/restore-backup` | 从预签名对象下载完整备份,并以新 UUID、MAC、公网地址和固件状态创建 VM |
| GET/PUT | `/v1/vms/{uuid}/firewall` | 读取 / 原子应用防火墙 |
| GET | `/v1/vms/{uuid}/rescue` | 救援状态 |
| POST | `/v1/vms/{uuid}/rescue/enter` | 进入救援 |
| POST | `/v1/vms/{uuid}/rescue/force-start` | 明确确认后冷关机启动救援 |
| POST | `/v1/vms/{uuid}/rescue/exit` | 确认数据风险后强制停止救援、卸载 ISO 并冷启动原系统 |
| GET | `/v1/operations/{operation_id}` | 读取不可变 operation 状态 |
| GET | `/v1/operations/{operation_id}/inspect` | 超级管理员只读证据检查 |
| GET | `/v1/operations/{operation_id}/fence-resolution` | 读取已持久化的该 operation 栅栏结论 |
| POST | `/v1/operations/{operation_id}/resolve-fence` | 只写 Journal 审计元数据并移除该 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 |
云镜像和救援 ISO 的 Agent 导入请求只携带对象存储中不可变主副本的短期
只读地址、`source_size_bytes` 与 SHA-256;管理员填写的原始官方地址和浏览器
本地文件不会下发到 Agent。若对象存储响应使用 chunked、使 Agent 无法读取
`Content-Length`,Agent 使用不可变预期大小创建有界 stream;若响应仍包含
长度则必须与预期完全一致,最终正文也必须恰好为该字节数并通过 SHA-256
校验。任何导入源都不得使用压缩 `Content-Encoding`。
不存在通用 mutation `reconcile`、`confirm-inspection`、`abort-job` 或任意资源 `cleanup` endpoint。`inspect` 不取得 mutation admission,不写 Journal,不继续原目标,也不能调用任何 libvirt 变更。唯一的备份工作区清理接口在下节说明:它只能消费原成功备份返回的最新 evidence-bound plan,不能接受路径、卷名或任意清理步骤。不可变 Journal 成功或明确无副作用失败可以为策略表中的任何类型提供精确结论;其他已失败且影响未知的类型只有在该 action 的专用投影证据完整匹配时才能输出 `applied/not_applied`,否则保持 `partial/inconclusive`。例如实例设置只有在 Domain metadata 与 NoCloud seed 都匹配同一 transition ID 时才是 `applied`,两者都确认未提交时才是 `not_applied`。电源、网络链路或服务的“当前状态刚好符合目标”不是原 operation 的强证据,必须保持 `inconclusive`。
VPC capability envelope 当前为 version 3;除 `apply_supported` 外必须明确返回
`vm_port_supported`,并在 checks 中分别提供 `vpc_l3_apply` 与 `vpc_vm_port`。
面板只把二者均可用、IPv4 forwarding 已开启且 transport candidate 精确匹配的
宿主机视为 VPC 就绪,因而不会把低于 version 3、只支持 host routing 或缺少 VM
网卡/迁移合同的旧 Agent 加入调度。若 firewalld 正在运行,能力探测还会只读核验
runtime/permanent 保留对象与 Agent 已提交的完整 host projection;查询失败、同名
对象被外部规则占用或出现未记录接口时,`vpc_l3_apply` 会返回对应的 fail-closed
原因且 capability 不再报告 VPC 就绪。能力探测本身不创建、修改或 reload firewalld。
version 3 在 PeerMigration V3 接收正文中增加
可选 `vpc_port`;未连接 VPC 的实例仍使用原有 public-only 合同。
VPC mutation 不接受逐条宿主机命令。`apply` 正文包含一个规范化的完整 host projection:VPC key/revision/CIDR/gateway、面板已经验证的 underlay 地址与接口、本机端口和远端 `/32` 路由;`desired_digest` 必须与 Agent 对该投影计算的 SHA-256 完全相同。Agent 为整台宿主机串行化这些 mutation,按完整集合重算专属 bridge、protocol 186 路由和 `inet virt_cloud_vpc` nftables 表。任一步失败都会尝试恢复操作前的完整集合;恢复确认成功时任务明确为未应用且可安全重新提交,恢复无法确认时保留原 operation 执行栅栏。成功应用或删除后,Agent 在 `journal_path + ".vpc-l3-v1.json"` 持久化绑定 operation ID 的应用标记,断线后的只读 `inspect` 只能使用这一精确标记确认原操作已经应用。
VM VPC port mutation 只接受面板/IPAM 已确定的完整身份:port/VPC key、私网
CIDR、首个可用 gateway、实例 `/32` 地址、MAC,以及当前宿主机路由投影的
revision/digest。挂载前,Agent 必须在已持久化 host projection 中找到完全一致的
本机端口;卸载时也必须先保留该端口,成功卸载网卡后面板才可提交新的 host
projection 删除它。Agent 正常关机、同时原子更新持久 Domain XML 和 NoCloud
network-config,再恢复原电源状态;运行中实例不会热插拔或强制断电。私网只获得
到本 VPC CIDR 的 on-link 路由,不获得默认路由或 DNS。公网 nwfilter 和流量账单
只绑定公网网卡;断网、到期暂停、带宽扩容、救援退出和重装会按各自语义同时保留
或控制已登记的私网网卡。Domain 与 seed 的 transition marker 必须同时匹配,未知
效果才可被只读核对为 applied/not_applied;半提交保持执行栅栏,绝不重放。
维护迁移携带不可变的 `vpc_port` 身份。面板必须先把端口 host projection 收敛到
目标宿主机,目标 Agent 才能接受 PeerMigration;目标返回的端口身份必须与请求完全
一致。切换完成后面板再撤销源宿主机路由。回滚按相反顺序先恢复源路由,之后才恢复
源实例。任何 VPC 路由 mutation 的未知效果都会阻止继续迁移,不能以当前连通性猜测
原 operation 已执行,也不能自动换发新 operation。
### 可移植备份与异地恢复
`POST /v1/vms/{uuid}/backups` 正文包含 `backup_key`、`name`、
`consistency_mode=filesystem|crash` 及 `object_upload`。`object_upload` 只有
短期预签名的 `part_urls`、`complete_url`、`abort_url`、只读 `verify_url`、part 大小及
总大小上限;Agent 永远不接收或保存 S3 access key。运行中 VM 使用 libvirt 完整 push backup,
关机 VM 使用稳定的独立克隆。两者都写入独立 `vbackup-*` 工作区卷,不注册到
Domain 的正式 `Snapshots` 目录;文件系统冻结不可用时 `filesystem` 会保守降级并在
结果中报告 `crash`。首版只接受一个可写 `vda`,拒绝额外可写盘、救援挂载、
原生/外部快照或带 backing file 的系统盘。multipart 完成得到确定成功后删除本地
临时工作区。若完成响应丢失,Agent 只通过 `verify_url` 重新读取并核对对象大小及
SHA-256;完全匹配才继续成功清理,不匹配或暂不可读时保留本地快照和 effect fence,
绝不自动重放、Abort 或误判为未执行。普通上传失败或取消在远端 Abort 已确认后,
使用独立的两分钟本地清理上下文删除临时卷;只有进程硬崩溃、远端完成不明确或
清理失败才可能留下本地副本。read-only operation inspection 可输出只覆盖该
operation 工作区卷(以及旧版本遗留的同 key 快照 metadata)的 evidence-bound cleanup plan。
成功结果只返回 `backup_key`、对象 `size_bytes`、qcow2
`virtual_size_bytes`、`sha256`、multipart 完成响应中的可选 `object_etag` 与
`object_version_id`、实际 `consistency`,以及本地临时副本未能清理时的
可选 `cleanup_pending=true`,不返回预签名 URL 或本机路径。本地清理失败不会丢弃
已经验证成功的远端对象身份,也不会把可恢复的备份错误降级为远端效果不明。
后续只读 inspection 在残留仍精确归属于该 operation 且没有活跃 libvirt/block job 时,
会同时保留 `applied` 对象投影并附带 cleanup plan。超级管理员可为一个新的 operation ID
调用 `POST /v1/operations/{cleanup_operation_id}/cleanup-backup-workspace`,正文只含
`prior_operation_id` 与刚读取的 `cleanup_plan_id`。Agent 在 mutation admission 内重新读取
原 Journal、活动 block job、精确卷摘要、引用关系和 metadata;计划变化即拒绝。成功结果必须
同时返回 `cleaned=true`、`workspace_absent=true`、`metadata_absent=true`。原备份成功回执不会
被改写;清理 operation 通过 `supersedes_operation_id` 保留审计关系。若第一次响应丢失,管理员
必须重新 inspect 后创建新的清理 operation,不能盲目重放旧删除请求。
action 为 `create-backup:{backup_key}:{consistency}`。
维护迁移不复用备份 endpoint。`POST /v1/vms/{uuid}/peer-migration/prepare`
接收版本 3 的迁移 ID、最长七天有效的随机票据、到期时间,以及一个根盘加全部当前
快照的路径无关工件目录。Agent 先持久化原电源/autostart 恢复意图,再正常关机并
禁用 autostart;完全停机后对每个稳定 qcow2 计算实际大小、虚拟容量和 SHA-256,
发布只读清单。prepare 结果只返回清单摘要、源状态和不含本机路径的工件回执。
每台 Agent 另外在 `peer_migration_port` 提供自动身份锁定的 TLS 1.3 数据面:
`GET /v3/peer-migrations/{migration_id}/manifest` 与
`GET /v3/peer-migrations/{migration_id}/artifacts/{artifact_id}`。请求必须使用
`Authorization: Bearer`,票据不得出现在 query;错误身份统一返回 404。工件只接受
HTTP Range 读取,公开 JSON、Header 和错误均不得泄露主机路径。Agent 自动生成并
持久化 TLS 身份、发现本机非 loopback 单播地址;能力响应中的 `peer_migration` 固定
声明 `version=3`、HTTPS 地址目录、身份 SHA-256 锁定值、`pinned_tls=true` 和
`chunk_size_bytes=8388608`。目标优先选择与本机同网段的地址,再回退公网地址。
`POST /v1/vms/{new_uuid}/restore-backup` 使用与新建 VM 相同的 CPU、内存、系统盘、
带宽、主机名及完整公网意图,并额外携带 `backup_key`、一次性 `source_url`、
`source_size_bytes`、`source_sha256`。Agent 严格核对实际字节数、SHA-256、独立
qcow2 格式和虚拟容量,并要求备份时冻结的严格布尔字段
`debian_12_network_fix`;`disk_gib` 不得小于备份磁盘。恢复不会复制原 Domain XML,
而是重新生成 seed、MAC、nwfilter、NVRAM、流量基线及 Domain;seed 只更新新网络
和实例身份,不覆盖备份磁盘内已有密码或 SSH 公钥。action 为
`restore-backup:{backup_key}`,使用 create-like 恢复:系统身份只能在新 VM 和全部
受管创建工件均确认不存在后提交 `not_applied`,不能根据当前状态推断并提交
`applied`。备份和恢复均为 HeavyIO,helper 上限为 24 小时。
`POST /v1/vms/{new_uuid}/peer-migration/receive` 只用于维护迁移。目标 Agent 从源
HTTPS 地址目录拉取路径无关清单,以固定 8 MiB Range 分块写入第一个
`storage_path_roots` 下自动创建的 `.peer-migration-staging` 目录,重试复用已验证
偏移;完整文件必须
通过大小和 SHA-256 后才改名为 `.ready` 并导入。Agent 为每个快照创建独立 qcow2
卷、重建 Domain 快照 metadata,并只定义 autostart=false 的关机目标;网络受限时
持久 interface XML 同时写入 `link state=down`。成功回执必须证明目标仍关机且每个
工件身份完全匹配,随后删除本次暂存目录。
PHP 在 receive 回执之后才应用用户防火墙,然后用
`POST /v1/vms/{uuid}/peer-migration/activate` 精确恢复原 running 与 autostart 两个
独立布尔状态。切换前的确定失败可用源端 `rollback` 恢复原状态;切换后的源副本用
`cleanup` 删除,且必须返回 Domain 与全部托管工件均不存在。每个阶段使用独立
operation ID;派发后效果不明只允许 read-only inspection 收敛,不能自动重放。
## 关键资源语义
- VM 内部 libvirt 名称由 actor user ID 和完整 UUID 派生;面板名称只写受控 metadata。客户端不能指定 Domain 名或提交 XML。
- 新 Domain 固定 x86_64/q35、UEFI、Secure Boot 关闭。loader/VARS 路径来自本机配置与 `domcapabilities`,请求不能覆盖。
- 新 Domain 的唯一公网网卡通过专属 `virt-<uuid>` nwfilter 引用 `clean-traffic`,并把已分配的纯 IPv4 地址作为显式 `IP` 参数写入 Domain XML,禁止来宾伪造源 IP。换网操作必须在同一次 seed/Domain 事务中验证旧绑定并替换为新地址;缺少显式绑定的旧 Domain 不自动补齐。
- 资源升级请求必须携带完整的来源和目标规格,并通过 `confirm_shutdown=true` 明确授权自动正常关机与冷启动;不要求用户提前关机。CPU、内存、系统盘和带宽均只能增加或保持不变,且至少一项增加。Agent 接受正常运行或已关机的实例,拒绝暂停态、快照、救援状态、待清理磁盘和来源规格漂移;运行中实例先请求 ACPI 正常关机,最多等待 10 分钟并确认完全停机后才离线扩容并冷启动,已关机实例保持关机,等待超时也不会强制断电。系统盘只使用绝对目标容量且不启用 shrink,扩大的虚拟磁盘不会自动扩展来宾分区或文件系统。
- 正常删除先请求 ACPI 关机。只有同一次执行明确观察到关机请求已接受但等待结束仍活动,才返回 `force_required`;强删必须使用新的 operation、超级管理员与 `ack_data_loss=true`。
- 删除成功必须确认 Domain、全部面板受管磁盘、Seed、专属过滤器、NVRAM 和流量状态均已消失。任何证据不可读都返回失败且可能保留资源栅栏。
- `ShutdownFlags`、`Reboot` 等调用成功只表示 libvirt 接受请求,不统一表示来宾已达到最终电源状态;回执 result 必须准确描述实际被确认的语义。
- 快照 `JOB_COMPLETED` 事件只唤醒当前 helper 读取一次新鲜 job 状态,事件本身不是终态。匹配的 backup job 最多中止一次,并且不会由管理员恢复 endpoint 续作。
- storage stream 使用 non-blocking 模式;callback、abort、finish 与 free 均由 helper 生命周期收口。
- libvirt 连接重连只恢复新请求能力,不读取 operation 历史或触发 mutation。
## 控制台与能力
浏览器先从 PHP 获取一次性面板票据;Gateway 再通过已认证 Agent session 使用一次性 Agent ticket 建立反向 binary 通道。票据固定短 TTL、在连接上游前原子消费,重复、过期、跨用户或跨 VM 均拒绝。浏览器永远看不到 Agent ID、endpoint 或 VNC 地址。
`features` 只能声明当前二进制真正实现并可安全使用的功能。未使用 `libvirt` build tag、缺少本机固件/目录或反向控制台条件不足时必须返回 false/501,不能提供假成功或旧实现回退。