# 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 派生为 `: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 镜像安全和并发购买。测试不得对未明确授权的宿主机做创建、写配置、改网络或修改虚拟机操作。