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

# 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,不能提供假成功或旧实现回退。