9.6 KiB
PHP 面板与 Go Agent 集成架构
本架构是全新实现,不是迁移层。旧 Python 引擎、SSH 宿主机凭据模型、旧引擎密文和旧数据库记录均不属于运行路径;不得增加双写、回退调用或兼容导入。
请求路径
浏览器
├─ 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 在能力缺失时返回明确的“不支持”,不能猜测、静默降级或调用旧接口。
每个请求携带:
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。签名串逐行拼接:
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 另使用面板本机共享密钥签名,两层认证不可关闭。
操作一致性
- PHP 在业务事务中生成不可变
operation_id,保存任务、reservation、IP 和请求摘要。 - Worker 取得单实例租约后向已绑定 Agent 派发。Agent 在调用 libvirt 前持久写入派发边界,并按 VM UUID 串行执行变更。
- 同一
operation_id与同一请求可返回既有结果;同一标识对应不同请求必须拒绝。 - Agent 明确失败且确认没有副作用时,PHP 才能执行相应前向补偿。发送后断线、超时或进程中断一律进入
uncertain。 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 镜像安全和并发购买。测试不得对未明确授权的宿主机做创建、写配置、改网络或修改虚拟机操作。