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

216 lines
17 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"`。面板只接受顶层
仅含 `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 |
### 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 会先用只读 `guest-ping` 检查 QEMU Guest Agent;当 libvirt 明确报告 Guest Agent 未配置、不支持、未响应或探测超时时,自动改用 `crash`。显式请求 `crash` 时不探测也不冻结 Guest。若 QGA 探测成功但后续冻结、解冻或 libvirt 通信失败,不得伪装成安全降级;结果不明确时仍必须保留 `uncertain`。成功响应的 `consistency` 以及宿主机和面板快照元数据必须记录实际采用的模式,协调时只允许 `filesystem` 请求单向降级为 `crash`,绝不允许反向提升。
本表只描述已注册的 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.<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` 是已排序、最多 64 项且当前探测可用的稳定 selector key 列表,只能包含 Agent 配置的 key,不能暴露 bridge/libvirt network 的本机 `source`。面板只有在宿主机 `default_network` 与该列表精确匹配时才允许 Agent 进入 ready 状态。