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/INTEGRATION_PLAN.md

109 lines
14 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.

# PHP 面板与 Go Agent 集成架构
本架构是全新实现,不是迁移层。旧 Python 引擎、SSH 宿主机凭据模型、旧引擎密文和旧数据库记录均不属于运行路径;不得增加双写、回退调用或兼容导入。
## 请求路径
```text
浏览器
├─ HTTPS 页面/API ──> PHP 面板 ──> MariaDB/Redis
└─ WSS /engine-console ──> 本机 Go Agent Gateway
└─ 通过已有出站会话要求 Agent 反向建立控制台通道
宿主机 virt-agent ── WSS /agent/connect ──> 面板 Go Agent Gateway
├─ qemu:///system ├─ 本机 HMAC API ──> PHP
└─ WSS /agent/console <─────────────┘
PHP workers ──> 持久 task/operation_id ──一次派发──> 本机 Gateway ──> Agent 隔离 worker
<────────────────────── 有界、不可变的完成回执 ──────────────────────┘
```
外部 `/engine-console` 只是为现有用户界面保留的 WebSocket 路径名,不指向旧引擎。`/agent/connect` 和 `/agent/console` 也由同一个 Gateway 承载。普通 HTTP 页面、管理 API、用户 API 和授权全部由 PHP 提供;`/internal/agent/request` 只在字面 loopback 地址上接受 PHP 签名请求。
## 责任边界
| 数据或行为 | 权威组件 | 持久位置 |
| --- | --- | --- |
| 账户、会话、余额、订单、发票、支付、公钥所有权 | PHP | 业务库 |
| 地区、套餐、容量策略、reservation、公网 IP 账本 | PHP | 业务库 |
| Agent 数字身份、启用状态、配置版本、已测试版本和连接测试状态 | PHP | `cloud_host_agents`;不保存宿主机 endpoint |
| 每宿主机 Agent HMAC 密钥 | PHP | 使用面板 `cloud_data_key` 的用途隔离密钥密封后保存 |
| 云镜像元数据、启动脚本、修订和不可变 generation | PHP | `cloud_templates` |
| 任务状态、操作者、`operation_id`、绝对截止和终态回执 | PHP | 业务库 |
| libvirt、宿主机磁盘、网络、防火墙、快照、救援 | Go Agent | 本机 libvirt 与受管存储 |
| 已派发操作、永久防重放 tombstone 与有界完成 outbox | Go Agent | `journal_path` 指定的本机 bbolt 持久库,以及权限为 `0700` 的隔离 worker 状态目录 |
| 指标样本、持久流量累计、实例 UTC 每日流量和账期基线 | PHP 协调、Agent 采集 | 日志库与业务库 |
PHP 不打开 libvirt 连接,不接收任意宿主机命令,也不把 Agent 密钥返回浏览器。Agent 不连接面板数据库,不处理用户会话、余额或支付。
## Agent API 与认证
基础 API 使用 `/v1`;最低健康与能力接口为 `GET /v1/health`、`GET /v1/capabilities`,VM 资源位于 `/v1/vms`。这些是长连接中的内层 HTTP 语义,Agent 不再对外监听 HTTP/TLS 端口。可选功能必须由 capability 声明;PHP 在能力缺失时返回明确的“不支持”,不能猜测、静默降级或调用旧接口。
每个请求携带:
```text
X-Virt-Timestamp
X-Virt-Nonce
X-Virt-Content-SHA256
X-Virt-Actor
X-Virt-Signature
```
`X-Virt-Actor` 是 URL-safe base64(无填充)的 JSON,包含 `user_id`、`is_admin`、`is_super_admin`、`can_manage`,变更请求还包含稳定的 `operation_id`。签名串逐行拼接:
```text
UPPERCASE_METHOD
原始 path 与 query
小写十六进制 SHA-256(body)
Unix 时间戳
随机 nonce
原始 X-Virt-Actor 值
```
最后用该宿主机独立密钥计算十六进制 HMAC-SHA256。Agent 校验时间窗、正文摘要、常量时间签名和 nonce 防重放。Agent 配置 `panel_url`、数字 `agent_id` 和独立 `agent_secret`,只连接面板 HTTPS/WSS 入口。Gateway 使用 PHP 内部认证接口校验连接;PHP 到 Gateway 另使用面板本机共享密钥签名,两层认证不可关闭。
## 操作一致性
1. PHP 在业务事务中生成不可变 `operation_id`,保存任务、reservation、IP、规范化请求指纹、`dispatch_deadline_at` 和回执截止时间,然后立即向浏览器返回 HTTP `202 Accepted`。这只表示任务已接收,不表示宿主机操作成功。
2. PHP worker 只领取 `dispatch_attempts=0` 且未超过绝对派发截止的任务。领取事务把计数原子改为 1,再向已绑定 Agent 派发一次;任何错误都直接终态失败,不能 requeue。
3. Agent 先取得 `domain`、`volume`、`nwfilter`、`catalog` 或 `storage-config` 资源准入,再原子写入派发边界。每个 mutation 由同一二进制的隐藏 worker 模式在独立子进程中执行,worker 使用自己的 libvirt 连接;主 Agent 不在进程内直接等待不可取消的 CGo 调用。
4. 主 Agent 对 worker 使用绝对截止、进程组 TERM/KILL 和有界 `Wait`。只有确认 worker 已退出后才释放运行时资源锁。重启只读检查隔离 worker 的不可变回执及子 Journal 已提交终态,身份与主 Journal 匹配后导入;缺少可信终态才持久化 `failed/result_unconfirmed`。不续作、不重新调用原 mutation,不能清理未采信的证据目录。
5. Agent 通过完成 outbox 投递不可变回执。相同 `event_id` 在收到精确 ACK 前按固定低频间隔持续投递;PHP 按事件 ID、operation ID、不可变操作身份与正文摘要幂等 ACK。历史 attempts/expires 只是兼容数据,不再淘汰未确认回执;低频退避防止空转,且投递回执永远不重放 mutation。
6. PHP 任务的公开终态只有 `succeeded` 和 `failed`。`receipt_deadline_at` 到期时直接失败;晚到回执不能翻转终态。恢复策略表内的 22 类 Agent 叶子任务可消费精确成功/无副作用失败回执,或同一 Agent operation 的新鲜、种类专用只读证据,幂等收敛 PHP 账本与内部 effect fence,但不会重放 mutation 或改写原任务结果。模板与用户 ISO 的聚合父任务只从这些叶子任务的已知效果持续汇总。
7. 失败且 `effect_may_have_applied=true` 时,任务已经结束,但破坏性操作对应的资源进入安全锁定。冲突请求立即失败而不是等待;在精确效果结论提交前,系统不退款、不释放 reservation、也不再次执行原操作。独立 recovery worker 会按固定低频间隔持续消费不可变回执或执行只读 inspection;Agent 离线、回执/身份冲突、密文损坏和账本状态矛盾都保留队列与具体异常,不受次数或总时长上限影响。管理员可以检查并修复根因,但只有 operation-bound 证据收敛后才解除资源锁。固定存储池配置不删除、不迁移也不改绑数据,因此失败只终止原 operation,不保留跨任务栅栏;后续只能按已定义 pool 的同一路径,或只修正尚未定义的角色后显式创建新任务,并继续由 `storage-config` 运行时准入及宿主机非阻塞文件锁串行。
同一 `operation_id` 和同一指纹只返回已存在的任务或终态;同一标识绑定不同请求必须拒绝。这个防重放规则不构成重试许可。
Agent 在连接前注册并持续运行 libvirt event loop;每个连接 generation 注册 lifecycle、`JOB_COMPLETED` 和 close callback。事件可以帮助当前隔离 worker 判断其一次调用的完成条件。libvirt 重连只恢复连接能力;Agent 启动可只读接管隔离 worker 已落盘的终态证据,但二者都不能续作或重放历史 mutation。
取消尚未派发的 PHP 任务只会阻止唯一一次领取。已经跨过 Agent 派发边界的任务不能通过删除面板记录来假定撤销;只能等待有界回执截止并得到成功或失败终态。
## 虚拟机、镜像与启动脚本
- 域 XML 使用结构化类型生成并验证输入,所有变更按 UUID 定位。创建请求的 `name` 保留为面板/Guest 显示输入并写入 `display-name` metadata;libvirt 内部名称只能由已验签 actor 的 `user_id` 与最终 UUID 派生为 `<user_id>:vm-<前 12 位小写无连字符 UUID>`,不接受请求正文覆盖。部署每台宿主机时先查询 domain capabilities,把该机支持且不启用 Secure Boot 的 Q35/EFI loader 与 NVRAM template 写入本机 Agent 配置;创建请求不能传入任意固件路径。Agent 使用手工 loader/NVRAM XML 并保持 `secure="no"`、`SMM=off`,不混入只适用于固件自动选择的 feature 列表,也不在 PHP 中硬编码单一发行版 OVMF 路径。
- 宿主机网络接入由 PHP 面板按资源池线路独立保存,选择器使用 `bridge:<名称>` 或 `network:<名称>`;Agent 配置不再接受 `network_selectors` 映射。Agent 只发现、验证和使用已存在且活动的 Linux 网桥或 libvirt network,不修改宿主机系统网络。`capabilities.network_selectors` 返回排序去重、最多 64 项的可用接入列表;网络接入必须精确匹配当前 Agent 已测试列表,并在创建、恢复、迁移、重装和换 IP 时根据冻结线路与公网池再次重验。宿主机 `default_network` 仅为兼容展示值,不是运行时网络权威。
- Agent 配置使用 `revision`/`tested_revision` 就绪门闩。保存密钥或启用状态会推进 revision 并将 `tested_revision` 清零;只有同一 revision 经已认证出站会话完成 `/v1/health` 与 `/v1/capabilities`,才记录为就绪。调度、Agent 客户端以及控制台路径均要求 `enabled=1`、`last_test_status=healthy` 且 `tested_revision=revision`;真实网络可用性由绑定资源池线路的接入验证状态单独约束。修改兼容 `default_network` 不推进 Agent revision,也不能让未验证接入进入运行时。全新部署只接受规范的 `bridge:<名称>` 或 `network:<名称>` 接入,不读取旧 alias、旧健康结果或已派发旧任务。
- 云镜像由 PHP 保存目录元数据、启动脚本以及对象存储中不可变主副本的精确身份,宿主机只保存可重建的派生副本。远程 URL 或管理员上传文件必须先由 PHP 校验并发布为主副本;目录不保存旧来源路径,上传暂存也不能再签发 `cloud-template` Agent 拉取能力。创建任务快照镜像 generation、revision 和脚本正文后签名发送给目标 Agent;删除后重新导入的同名镜像不能继承旧脚本。删除采用两阶段收敛:先证明全部宿主机副本已删除,再删除主副本的精确对象版本;主副本清理完成前目录和原聚合任务保持占用。
- 启动脚本仅用于新云镜像实例的首次安装,不用于普通重启、网络设置、重装、救援或用户 ISO。脚本限制 32 KiB UTF-8,拒绝 NUL,CRLF 规范化为 LF,空值表示禁用。
- Agent 将脚本以 root 私有文件写入 cloud-init seed,由一次性 runner 原子记录 started 状态。成功、失败和中断都不自动重放;VM 创建成功不等待脚本结束。
- 镜像下载始终使用独立 HTTPS 请求,WSS 只传递一次性下载 URL/token/摘要等任务元数据,不传镜像字节。救援 ISO 的面板暂存上传会把已捕获文件的精确大小写入签名任务;即使代理改用 chunked 响应,Agent 也按该大小有界读取,并拒绝长度不符、多余字节、短读或摘要不符。云镜像模板的远程 URL 只用于 PHP 形成不可变主副本,不会下发给 Agent;Agent 只读取主副本的精确版本只读地址,并继续校验大小、摘要及 QCOW2 格式,拒绝 backing file、外部 data file、加密或 raw 内容。
## 网络与账期
PHP 的容量策略、reservation 和具体 IP 账本是调度事实源。Agent 仅执行已签名的目标网络配置并做宿主机最终校验,不通过全量扫描改变可售库存。
每个支付周期拥有独立流量额度。RX 与 TX 都计费;额度耗尽或最终到期只持久断开网络,不改变 VM 电源。下一已付费周期开始后更新基线并恢复网络。未支付续费进入三天宽限,结束后才删除域定义及面板管理的磁盘。删除在回执截止前无法取得确定结果时,任务立即终态失败并保留账本占用;recovery worker 会持续核对同一 operation,只有确认效果并完成账本收敛后才释放,期间不得退款、释放或再次删除。
## 控制台
浏览器只向面板侧 `virt-cloud-agent-gateway` 的 `/engine-console` 提交 PHP 签发的短时、一次性票据。Gateway 通过本机 PHP 内省接口验证当前会话与 VM 所有权,再在 Agent 控制长连接上发送 `console_open`。Agent 原子消费本机 console ticket、连接 loopback VNC,然后主动连回 `/agent/console`。Gateway 只在已连接会话内存中暂存该 Agent 握手密钥,用于每次普通请求或控制台打开前向 PHP 复核,不持久化密钥、不接受浏览器指定 Agent 或 endpoint,也不把 VNC 端口暴露公网。
Gateway 固定以 `{"service":"agent-gateway"}` actor 签名 POST `/api/internal/cloud/session-introspection`。首次请求为 `{"ticket":"...","consume":true}`,PHP 原子消费后返回 `active`、`connection_id`、数字 `agent_id`、Agent 一次性票据及 RFC3339 过期时间;不再返回宿主机 WebSocket URL。随后每 15 秒的 `consume:false` 请求带原票据与 `connection_id`,成功响应必须严格为 `{"active":true}`。
当前部署只有在 Gateway 二进制、Agent console capability、一次性消费、会话撤销、Origin、超时和断线关闭测试全部通过后才能启用控制台;否则页面应显示不可用,不能回退到旧引擎。
## 上线边界
生产前必须实测 Agent WSS/HMAC、防重放、断线后对账、Agent 与实际 libvirt daemon 分别重启后的连接恢复和 Journal 扫描、宿主机重启、UEFI、cloud-init、快照/救援/重装、反向控制台撤销、流量跨 QEMU 重启、到期断网、宽限删除、HTTPS 镜像安全和并发购买。测试不得对未明确授权的宿主机做创建、写配置、改网络或修改虚拟机操作。