|
|
|
|
|
# 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、全局 IPv6 及由 MAC 派生的 link-local IPv6 分别作为显式 `IP`、`IPV6`、`IPV6_LINK_LOCAL` 参数写入 Domain XML。专属 nwfilter 与宿主机 `virt_cloud_public_guard` 投影共同拒绝来宾伪造两族源地址和 NDP 身份。换网操作必须在同一次 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,不能提供假成功或旧实现回退。
|