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

107 lines
9.6 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 ──> 持久 cloud job/operation_id ──> 本机 Gateway ──> Agent 本地操作日志 ──> 对账
```
外部 `/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 与受管存储 |
| 已派发操作及确定/不确定结果 | Go Agent | `journal_path` 指定的本机 bbolt 持久库;终态详情保留 90 天,operation_id tombstone 永久保留,nonce 使用独立 TTL 索引 |
| 指标样本、持久流量累计和账期基线 | 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 和请求摘要。
2. Worker 取得单实例租约后向已绑定 Agent 派发。Agent 在调用 libvirt 前持久写入派发边界,并按 VM UUID 串行执行变更。
3. 同一 `operation_id` 与同一请求可返回既有结果;同一标识对应不同请求必须拒绝。
4. Agent 明确失败且确认没有副作用时,PHP 才能执行相应前向补偿。发送后断线、超时或进程中断一律进入 `uncertain`。
5. `uncertain` 只能结合 Agent 操作记录和按 UUID 观察到的宿主机状态对账。运行中状态不证明先前关机/重启未执行;破坏性操作不得自动重放或直接退款。
取消尚未派发的 PHP 任务只会阻止后续领取。已经跨过 Agent 派发边界的任务不能通过删除面板记录来假定撤销。
## 虚拟机、镜像与启动脚本
- 域 XML 使用结构化类型生成并验证输入,所有变更按 UUID 定位。部署每台宿主机时先查询 domain capabilities,把该机支持且不启用 Secure Boot 的 Q35/EFI loader 与 NVRAM template 写入本机 Agent 配置;创建请求不能传入任意固件路径。Agent 使用手工 loader/NVRAM XML 并保持 `secure="no"`、`SMM=off`,不混入只适用于固件自动选择的 feature 列表,也不在 PHP 中硬编码单一发行版 OVMF 路径。
- Agent 配置使用 `revision`/`tested_revision` 就绪门闩。保存密钥、启用状态或宿主机 `default_network` 会推进 revision 并将 `tested_revision` 清零;只有同一 revision 经已认证出站会话完成 `/v1/health` 与 `/v1/capabilities`,且 `default_network` 精确存在于 Agent 上报的可用 `network_selectors`,才记录为就绪。调度、Agent 客户端以及控制台路径均要求 `enabled=1`、`last_test_status=healthy` 且 `tested_revision=revision`。
- 云镜像由 PHP 保存目录元数据和启动脚本。创建任务快照镜像 generation、revision 和脚本正文后签名发送给目标 Agent;删除后重新导入的同名镜像不能继承旧脚本。
- 启动脚本仅用于新云镜像实例的首次安装,不用于普通重启、网络设置、重装、救援或用户 ISO。脚本限制 32 KiB UTF-8,拒绝 NUL,CRLF 规范化为 LF,空值表示禁用。
- Agent 将脚本以 root 私有文件写入 cloud-init seed,由一次性 runner 原子记录 started 状态。成功、失败和中断都不自动重放;VM 创建成功不等待脚本结束。
- 镜像下载始终使用独立 HTTPS 请求,WSS 只传递一次性下载 URL/token/摘要等任务元数据,不传镜像字节。Agent 限制来源、解析后的公网地址、全部跳转、大小、超时和摘要;校验 QCOW2 格式,拒绝 backing file、外部 data file、加密或 raw 内容。
## 网络与账期
PHP 的容量策略、reservation 和具体 IP 账本是调度事实源。Agent 仅执行已签名的目标网络配置并做宿主机最终校验,不通过全量扫描改变可售库存。
每个支付周期拥有独立流量额度。RX 与 TX 都计费;额度耗尽或最终到期只持久断开网络,不改变 VM 电源。下一已付费周期开始后更新基线并恢复网络。未支付续费进入三天宽限,结束后才删除域定义及面板管理的磁盘。任何删除响应不确定时都保留账本占用,直到对账确认清理。
## 控制台
浏览器只向面板侧 `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、超时和断线关闭测试全部通过后才能启用控制台;否则页面应显示不可用,不能回退到旧引擎。
## 在线更新
PHP 只做超级管理员授权、CSRF 和固定 Unix socket API 调用。本机 root Go helper `virt-cloud-update` 固定仓库 `https://g.luoli.live/root/virt.git` 与 `go` 分支,通过 `/run/virt-cloud/update.sock` 提供 settings/check/apply/jobs。访问令牌由 helper 保存到私有状态目录,不进入 URL、命令行或日志。
helper 只允许干净工作树 fast-forward,按持久检查点停止服务、更新源码、运行 `php xcat cloudInit` 并重启/健康检查。它不在线安装或改写依赖;修改 `deploy/**`、Go modules、Composer/JavaScript/Cargo 依赖声明或 lock 的版本必须在人工维护窗口升级与复测。对于历史文件类型,任何 `requirements*.txt` 变更也会被拒绝;这是变更面检查,不表示当前运行需要 Python。数据库初始化结果不确定时保持维护锁并要求 SSH 人工核对,不能仅回退源码。
## 上线边界
生产前必须实测 Agent WSS/HMAC、防重放、断线后对账、宿主机重启、UEFI、cloud-init、快照/救援/重装、反向控制台撤销、流量跨 QEMU 重启、到期断网、宽限删除、HTTPS 镜像安全和并发购买。测试不得对未明确授权的宿主机做创建、写配置、改网络或修改虚拟机操作。