13 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 ──> 持久 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 状态目录 |
| 指标样本、持久流量累计和账期基线 | 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、规范化请求指纹、dispatch_deadline_at和回执截止时间,然后立即向浏览器返回 HTTP202 Accepted。这只表示任务已接收,不表示宿主机操作成功。 - PHP worker 只领取
dispatch_attempts=0且未超过绝对派发截止的任务。领取事务把计数原子改为 1,再向已绑定 Agent 派发一次;任何错误都直接终态失败,不能 requeue。 - Agent 先取得
domain、volume、nwfilter、catalog或storage-config资源准入,再原子写入派发边界。每个 mutation 由同一二进制的隐藏 worker 模式在独立子进程中执行,worker 使用自己的 libvirt 连接;主 Agent 不在进程内直接等待不可取消的 CGo 调用。 - 主 Agent 对 worker 使用绝对截止、进程组 TERM/KILL 和有界
Wait。只有确认 worker 已退出后才释放运行时资源锁。重启只读检查隔离 worker 的不可变回执及子 Journal 已提交终态,身份与主 Journal 匹配后导入;缺少可信终态才持久化failed/result_unconfirmed。不续作、不重新调用原 mutation,不能清理未采信的证据目录。 - Agent 通过完成 outbox 投递不可变回执。相同
event_id在收到精确 ACK 前按固定低频间隔持续投递;PHP 按事件 ID、operation ID、不可变操作身份与正文摘要幂等 ACK。历史 attempts/expires 只是兼容数据,不再淘汰未确认回执;低频退避防止空转,且投递回执永远不重放 mutation。 - PHP 任务的公开终态只有
succeeded和failed。receipt_deadline_at到期时直接失败;晚到回执不能翻转终态。恢复策略表内的 22 类 Agent 叶子任务可消费精确成功/无副作用失败回执,或同一 Agent operation 的新鲜、种类专用只读证据,幂等收敛 PHP 账本与内部 effect fence,但不会重放 mutation 或改写原任务结果。模板与用户 ISO 的聚合父任务只从这些叶子任务的已知效果持续汇总。 - 失败且
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-namemetadata;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 面板统一保存:网页默认 Linux 网桥
br0,default_network使用bridge:<名称>或network:<名称>;Agent 配置不再接受network_selectors映射。Agent 只发现、验证和使用已存在且活动的 Linux 网桥或 libvirt network,不修改宿主机系统网络。capabilities.network_selectors返回排序去重、最多 64 项的可用接入列表;面板所选值必须精确匹配,创建/换网时再次重验。 - Agent 配置使用
revision/tested_revision就绪门闩。保存密钥、启用状态或宿主机default_network会推进 revision 并将tested_revision清零;只有同一 revision 经已认证出站会话完成/v1/health与/v1/capabilities且网络匹配,才记录为就绪。调度、Agent 客户端以及控制台路径均要求enabled=1、last_test_status=healthy且tested_revision=revision。全新部署只接受规范的bridge:<名称>或network:<名称>,不读取旧 alias、旧健康结果或已派发旧任务。 - 云镜像由 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 电源。下一已付费周期开始后更新基线并恢复网络。未支付续费进入三天宽限,结束后才删除域定义及面板管理的磁盘。删除在回执截止前无法取得确定结果时,任务立即终态失败并保留账本占用;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 镜像安全和并发购买。测试不得对未明确授权的宿主机做创建、写配置、改网络或修改虚拟机操作。