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

175 lines
9.8 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.v2`。v2 包含不可变完成回执;Agent 与 Gateway 不提供 v1 兼容或协商降级,任一侧版本不一致必须在握手阶段失败。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 必须携带且与正文一致。
```json
{
"user_id": 42,
"is_admin": false,
"is_super_admin": false,
"can_manage": false,
"operation_id": "0123456789abcdef0123456789abcdef"
}
```
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",
"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",
"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,不能替代 v2 握手;旧 Gateway 不允许以“健康但不能处理 completion”的形式继续承载任务。
回执只允许 `succeeded|failed`。成功必须没有错误码,且两个风险布尔值均为 false;失败必须有稳定错误码,`effect_may_have_applied=true` 时 `safe_to_resubmit` 必须为 false。相同事件可以在固定次数和绝对截止时间内重复投递,超过任一界限就停止。晚到回执得到 ACK,但不能翻转 PHP 终态。
Go context 无法可靠中止已进入 CGo/libvirt 的调用。父 Agent 到达绝对截止后终止整个 helper 进程组并执行有界 `Wait`;未确认 helper 已退出时保留 durable execution fence。Agent 重启发现“已启动但没有完整回执”的 operation 时直接终态失败并保留栅栏,不再次执行。
## 错误
普通错误 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` | 版本、固件、网络和可选能力 |
| 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}/network` | 使用签名公网意图换网 |
| 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` | 当前指标 |
| GET | `/v1/vms/{uuid}/traffic/daily?days=1..30` | 按日流量 |
| 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` | 恢复快照 |
| 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` | 退出救援 |
| GET | `/v1/operations/{operation_id}` | 读取不可变 operation 状态 |
| GET | `/v1/operations/{operation_id}/inspect` | 超级管理员只读证据检查 |
| 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 |
不存在 mutation `reconcile`、`confirm-inspection`、`abort-job` 或 `cleanup` endpoint。`inspect` 不取得 mutation admission,不写 Journal,不继续原目标,也不能调用任何 libvirt 变更。
## 关键资源语义
- VM 内部 libvirt 名称由 actor user ID 和完整 UUID 派生;面板名称只写受控 metadata。客户端不能指定 Domain 名或提交 XML。
- 新 Domain 固定 x86_64/q35、UEFI、Secure Boot 关闭。loader/VARS 路径来自本机配置与 `domcapabilities`,请求不能覆盖。
- 正常删除先请求 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,不能提供假成功或旧实现回退。