# PHP/Go Agent 验证门槛 本文件定义 `go` 分支的交付门槛。历史旧引擎测试结果不代表本实现通过;每次发布必须记录实际提交、环境、命令、通过/失败/跳过数量和未完成的真实环境验收。 ## 1. 静态与单元测试 Go Agent 与本机 helper: ```bash cd /home/virt-cloud/agent test -z "$(gofmt -l .)" go mod verify go vet ./... go test ./... go vet -tags libvirt ./... go test -tags libvirt ./... go test -race -tags libvirt ./... cd /home/virt-cloud/gateway test -z "$(gofmt -l .)" go mod verify go vet ./... go test ./... go test -race ./... ``` Go 测试至少覆盖:配置内容校验但不检查 owner/mode、HTTPS `panel_url`、数字 Agent ID、旧 listener/TLS 字段被拒绝、WSS 子协议与认证、严格控制帧、HMAC 正文摘要、完整时间窗(含未来偏差与到期边界)、nonce 防重放、不同请求复用 `operation_id`、按 VM 串行、派发前/后故障注入、仅按 inflight 索引重启恢复、超过 16 MiB 的长期 journal 重启、nonce 到期索引清理、operation tombstone 保留、五类 expected-state/transition marker 只读核对、换网 source 反例、libvirt typed error、UEFI XML、启动脚本一次性 runner 和反向控制台。不带 tag 的 portable 测试只能验证缺失 adapter 时的明确失败;生产交付必须通过 `-tags libvirt` 的编译和测试。PHP 契约测试还必须证明 PHP→Gateway 只使用字面 loopback 固定路径,不再存储或请求宿主机 endpoint。 PHP: ```bash cd /home/virt-cloud/web find app config public tests -name '*.php' -print0 | xargs -0 -n1 php -l for test_file in tests/*Test.php; do php "$test_file" || exit $?; done ``` PHP 测试至少覆盖:Agent Gateway loopback 约束、Gateway 外层 HMAC、每宿主机内层密钥加密与签名 golden vector、Agent 握手认证、管理员权限、普通用户路由隔离、模板脚本读取/写入权限、32 KiB/UTF-8/NUL 边界、revision/generation、持久任务快照、账单与资源 reservation、`uncertain` 不自动重放/退款。 浏览器脚本与部署文件: ```bash cd /home/virt-cloud for test_file in web/tests/*.mjs; do node "$test_file" || exit $?; done jq empty deploy/*.json.example git diff --check ``` 在 systemd Linux 测试机另运行: ```bash systemd-analyze verify /home/virt-cloud/deploy/*.service ``` 最终仓库不得再跟踪 Python 源码、依赖清单或旧引擎 service: ```bash cd /home/virt-cloud test -z "$(git ls-files '*.py' '*.pyi' '*requirements*.txt' 'pyproject.toml')" test ! -e deploy/virt-cloud-engine.service test ! -e deploy/virt-cloud-console-relay.service test ! -e deploy/virt-cloud-console-relay.json.example test ! -e gateway/cmd/virt-cloud-console-relay ! rg -n 'virt-cloud-engine\.service|/home/virt-cloud/engine|CLOUD_ENGINE_CONFIG' \ deploy README.md docs --glob '!VALIDATION.md' ! rg -n 'virt-cloud-console-relay|cloud_console_relay_secret|agent_websocket_url' \ deploy gateway web/app web/config README.md docs --glob '!VALIDATION.md' ``` 上述 `requirements*.txt` 只是对已退役文件类型的残留检查,不是当前部署依赖;产品运行路径中不存在 Python 或 pip 安装步骤。 ## 2. API 契约 使用 PHP 客户端与 Go 服务共享的固定向量校验以下字节级契约: - method 必须转大写;path 与原始 query 不重排。 - body SHA-256 和 HMAC 为小写十六进制。 - actor JSON 为 URL-safe base64 且无填充。 - canonical 值为 method、target、digest、timestamp、nonce、actor 六行,以 `\n` 连接且末尾无额外换行。 - 缺少任一签名头、摘要不符、过期/未来时间、nonce 重放、actor 字段未知或签名错误全部拒绝。 - 认证错误不回显密钥、canonical 内容、内部路径或 libvirt 原始敏感信息。 每个 Agent 的 `/v1/health` 和 `/v1/capabilities` 都要从面板 `/admin/agents` 经当前已认证 WSS 会话测试;一个宿主机失败不得污染另一个宿主机的配置或状态。 ## 3. 操作与故障注入 所有变更使用非生产测试 VM。为创建、关机、重启、强制断电、删除、重装、快照、救援、换 IP、断网/恢复分别覆盖: 1. Agent 收到请求前失败:PHP 可按同一标识安全重试。 2. Agent 持久写入派发边界后、调用 libvirt 前失败:恢复后仍使用原 `operation_id`,不得新建操作。 3. libvirt 调用已返回但响应丢失:任务进入 `uncertain`,通过 UUID 和本地操作日志核对。 4. Agent 或面板 worker 重启:操作日志、PHP 租约和 reservation 不丢失。 5. 同一 `operation_id` + 相同摘要:返回既有结果;同一标识 + 不同摘要:409 拒绝。 6. 同一 VM 并发变更:严格串行;不同 VM 可在资源上限内并行。 运行中状态不能证明关机/重启未发生;持久域消失不能在未核对磁盘清单时自动视为完整删除。任何未知删除都不得释放 IP、库存或退款。 ## 4. libvirt 与宿主机 先做只读能力检查: ```bash virsh -c qemu:///system version virsh -c qemu:///system capabilities >/dev/null virsh -c qemu:///system domcapabilities >/dev/null virsh -c qemu:///system list --all virsh -c qemu:///system net-list --all virsh -c qemu:///system pool-list --all ``` 只读检查不得安装软件、修改服务、网络、存储池、域 XML 或主机配置。只有明确授权的非生产宿主机才可运行变更测试。 生成的 XML 应使用宿主机的 `virt-xml-validate` 验证。至少检查:Q35、EFI loader/NVRAM 来自 domain capabilities、Secure Boot 明确关闭、MAC/网桥/带宽正确、磁盘与 cloud-init seed 路径位于受管目录、用户输入经过 XML 转义。 ## 5. 镜像与首次启动脚本 - 远程导入验证 HTTPS、DNS 解析后的公网地址、每次跳转、超时、大小和 SHA-256;拒绝内网/环回/链路本地/元数据地址。 - 本地上传验证独立 QCOW2;拒绝 raw、ISO、加密、backing file、外部 data file、截断和超限文件。 - 每个镜像分别测试无脚本、空脚本、最大脚本、CRLF、非 UTF-8、NUL 和修订并发。 - 新 VM 第一次启动只运行一次。退出 0、非零、执行中重启、Agent 重启和控制面断线后均不能自动重放。 - 重装、救援、用户 ISO、普通重启、改密码、改主机名、改网络不得意外触发该首次安装脚本。 ## 6. 业务与 UI 回归 管理员页面保持 venix,用户/登录页保持原虚拟机面板样式。逐项验收: - 注册、登录、密码重置、充值、支付、公告、工单、管理员账户。 - `/admin/agents` 新增/修改密钥/禁用/出站连接测试;普通用户不可见且 API 返回拒绝。 - 地区、资源池、套餐、库存、多公网池、镜像、救援 ISO、系统日志和异常任务。 - 购买只扣款一次并只创建一台 VM;明确创建失败才退款,未知结果不退款。 - 控制台短票据一次消费、到期、登出撤销、跨用户拒绝和上游断线。 - CPU、内存、磁盘 I/O、网络图表持续采样;无人登录时仍采集。 - RX+TX 用尽只断网;下一账期恢复;最终到期只断网;三天宽限内续费恢复,宽限后删除定义与面板受管磁盘。 用桌面和手机宽度检查页面,确认后端切换没有改变用户可见信息架构,也没有向普通用户暴露宿主机或 Agent 管理入口。 ## 7. 更新与恢复 在测试副本验证固定 `go` 分支 fast-forward、脏工作树拒绝、签名 API、令牌不回显、依赖变更人工门槛、service 停启顺序、`cloudInit` 失败、PHP-FPM 启动失败和健康检查失败。进入 `cloudInit` 后中断必须保留维护锁;不得因回退 Git 提交自动判定数据库安全。本项是对当前全新 schema 初始化/重放的保守处理,不是旧库兼容迁移。 ## 8. 发布记录 发布提交前把实际结果追加到本节;未执行项写“未执行”及原因,不能写成通过。 ```text commit: Go version / libvirt version / PHP version / MariaDB version: go vet: go test: go test -race: PHP tests: Node tests: systemd-analyze: read-only host capability check: authorized host mutation test: browser/payment/SMTP test: known skips or risks: ``` ### 2026-10-15 `go` 分支提交前验收 ```text commit: 本记录所在 go 分支提交(基线 887072a) Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / libvirt 12.8.0 / PHP 8.5.11 / MariaDB 未在本机运行 go vet: Agent 默认、libvirt+dlopen、libvirt 静态 tag 与 Gateway 均通过 go test: Agent 默认、libvirt+dlopen、libvirt 静态 tag 与 Gateway 均通过;go mod verify 与 tidy -diff 通过 go test -race: Agent 默认、libvirt+dlopen、libvirt 静态 tag 与 Gateway 均通过 PHP tests: 383 个 PHP 文件 lint 通过,113 个测试文件通过 Node tests: 93 个 JavaScript 文件语法检查通过,4 个行为测试通过;3 个部署 JSON 示例有效 systemd-analyze: 未执行;验收机为 macOS,不提供 systemd-analyze read-only host capability check: 已对指定 103 宿主机只读检查;AlmaLinux 10.2、libvirt 11.10、qemu:///system、Q35 EFI 与 secureBoot yes/no 能力可用 authorized host mutation test: 未执行;用户明确禁止修改指定宿主机的任何配置 browser/payment/SMTP test: 自动化 PHP/Node 契约测试通过;真实支付、SMTP 和浏览器人工验收未执行 known skips or risks: 生产 Linux 上的 systemd-analyze、MariaDB 全新建库、真实 libvirt 破坏性生命周期与外部服务联调仍须在获授权测试环境验收;macOS 静态 libvirt 链接仅有重复库警告 ``` ### 2026-10-16 出站 WSS Agent Gateway 提交前验收 ```text commit: 本记录所在 go 分支提交(基线 97a17ed) Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / libvirt 12.8.0 / PHP 8.5.11 / MariaDB 未在本机运行 go vet: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过 go test: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过;go mod verify 与 tidy -diff 通过;反向控制台目标测试分别连续运行 50 次和 30 次通过 go test -race: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过 Linux AMD64 build: linux/amd64 CGo + libvirt_dlopen 交叉编译通过;提交后按实际提交 SHA 重建发布包 PHP tests: SourceSyntax 检查 391 个 PHP 文件通过,115 个测试文件通过;现有测试依赖仅输出已知弃用/警告信息,退出码为 0 Node tests: 93 个 JavaScript 文件语法检查通过,4 个行为测试通过;3 个部署 JSON 示例有效 systemd-analyze: 未执行;验收机为 macOS,不提供 systemd-analyze read-only host capability check: 本轮未完成;当前 Mac 的 SSH 别名 103 解析为 0.0.0.103,网络不可达 authorized host mutation test: 未执行;用户明确禁止修改指定宿主机的任何配置 browser/payment/SMTP test: 自动化 PHP/Node 契约测试通过;真实支付、SMTP 和浏览器人工验收未执行 known skips or risks: 生产 Linux 上的 systemd-analyze、MariaDB 全新建库、真实 libvirt 生命周期与外部服务联调仍须在获授权测试环境验收;macOS libvirt 链接测试仅有重复库警告 ``` ### 2026-10-16 创建/回执一致性加固提交前验收 ```text commit: 本记录所在 go 分支提交(基线 177fa24) Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / 本机动态链接测试沿用已安装 libvirt / PHP 8.5.11 / MariaDB 未在本机运行 go vet: Agent 默认及 libvirt+dlopen、Gateway 均通过 go test: Agent 默认、libvirt、libvirt+dlopen 与 Gateway 均通过;两个 Go 模块的 mod verify 与 tidy -diff 均通过 go test -race: Agent libvirt+dlopen 与 Gateway 均通过 Linux AMD64 build: 提交后按实际提交源码交叉编译 Agent(CGo + libvirt_dlopen)和静态 Gateway 直运行二进制 PHP tests: 389 个 PHP 文件 lint 通过,116 个测试文件通过;仅输出既有 TicketAttachmentService warning 与 Predis deprecation,退出码为 0 Node tests: 89 个 JavaScript 文件语法检查通过,4 个行为测试通过;部署 JSON 示例有效 systemd-analyze: 待在 Linux 面板/宿主机部署时执行 read-only host capability check: 待对指定 103 宿主机部署前复核 authorized host mutation test: 待部署后在用户指定的测试环境按 operation_id 串行验收 browser/payment/SMTP test: 自动化 PHP/Node 契约测试通过;真实创建付款需在最终提交动作前取得用户即时确认 known skips or risks: libvirt 调用已执行但结果不可证明时会安全保留 uncertain,必须复用原 operation_id 核对,禁止自动重放;macOS libvirt 链接仅有重复库警告 ``` ### 2026-10-16 持久化目录任务收敛验收 ```text commit: 本记录所在 go 分支提交(基线 e7fa625) Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / 本机动态链接测试沿用已安装 libvirt / PHP 8.5.11 / MariaDB 未在本机运行 go vet: Agent 默认及 libvirt tag、Gateway 均通过 go test: Agent 默认及 libvirt tag、Gateway 均通过;两个 Go 模块的 mod verify 均通过 go test -race: Agent libvirt tag 与 Gateway 均通过;Gateway race 测试获准绑定本机临时回环端口 Linux AMD64 build: 本提交未修改 Go 源码,继续使用 e7fa625 对应的已验证 Agent 与 Gateway 二进制 PHP tests: 392 个 PHP 文件逐文件 lint 通过,119 个测试文件通过;SourceSyntax 独立检查 396 个文件通过;仅输出既有测试 warning 与第三方依赖 deprecation,退出码为 0 Node tests: 89 个 JavaScript 文件语法检查通过,4 个行为测试通过;部署 JSON 示例有效 systemd-analyze: 本提交未修改 service 文件,未重复执行 read-only host capability check: HKG-A 出站 WSS 已稳定连接;Agent 报告 14 项必要能力、UEFI 可用且 Secure Boot 关闭 authorized host mutation test: HTTPS Debian 13 云镜像导入在 Agent 端确定成功,436207616 字节,SHA-256 为 1010eb3215be632548cfb6793b53bd8243064d8820b5106f2becfcd179099b2f;本提交新增后台同 operation_id 收敛,禁止重放原始导入 POST browser/payment/SMTP test: 管理端网络选择器已由错误的 bridge:br0 修正为 Agent 声明的 public;旧创建任务已按原 operation_id 核对并明确失败退款;新的真实 10 USD 创建提交仍等待用户即时确认 known skips or risks: worker 每 tick 最多处理一个普通任务和一个目录核对;真实创建、重装、快照恢复和删除属于外部或破坏性操作,必须在动作前取得确认后再完成联调 ``` ### 2026-10-16 Linux AMD64 直运行二进制发布验收 ```text source commit: fbe8498deb9405a9e13396212eab43d1e490a8f3(Agent/Gateway Go 源码与 e7fa625 一致) Go version: Go 1.27.1 Agent build: linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen、trimpath、vcs.modified=false Agent artifact: release/virt-agent-linux-amd64 Agent SHA-256: ea70ee891a2b85793407a1d7a66679bc8d9822117daeb8e9a6b87da4e5570046 Gateway build: linux/amd64、CGO_ENABLED=0、静态链接、trimpath、vcs.modified=false Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64 Gateway SHA-256: e612c35eabae27d5afc483b9430404f9f9d73f92529dcd583ea1ba8ff17628e9 go mod verify: Agent 与 Gateway 均通过 go vet / go test: Agent 默认及 libvirt+libvirt_dlopen 均通过;Gateway 均通过 go test -race: Gateway 通过;Agent 沿用同一 source commit 的前置 race 验收 artifact inspection: 两个文件均为 ELF 64-bit x86-64,未嵌入本机路径或部署端点 known skips or risks: Agent 使用 libvirt_dlopen,宿主机运行时仍必须提供 libvirt.so.0;新产物未在本轮重复执行真实 VM 破坏性生命周期操作 ``` ### 2026-10-16 创建失败根因保留与阶段诊断验收 ```text commit: 本记录所在 go 分支源码提交(基线 93781a2) Go version / libvirt version / PHP version / MariaDB version: Go 1.27.1 / 本机 libvirt 12.8.0 / PHP 8.5.11 / MariaDB 未在本机运行 go vet: Agent 默认及 libvirt+libvirt_dlopen 均通过 go test: Agent 默认及 libvirt+libvirt_dlopen、Gateway 均通过;Gateway Agent 包连续 20 次通过;Agent go mod verify 通过 go test -race: Agent libvirt+libvirt_dlopen 与 Gateway 均通过 PHP tests: 119 个测试文件通过,app/config/public 下 272 个 PHP 文件逐文件 lint 通过;SourceSyntax 独立通过;仅输出既有测试 warning 与第三方依赖 deprecation,退出码为 0 Node tests: 4 个行为测试及 admin-operations.js 语法检查通过 libvirt XML: 当前 create 请求形态生成的 q35/UEFI、Secure Boot 关闭、br0 bridge 域 XML 通过 virt-xml-validate domain schema read-only host capability check: 面板快照确认 Agent、public->br0、/29 地址池及模板副本均就绪;本轮桌面 SSH 自动化两次超时,未取得宿主机原始 libvirt 日志 authorized host mutation test: 未重新提交真实付费创建;现有失败任务已完成退款且受管工件确认不存在 known skips or risks: 旧 Agent 将最初错误覆盖为 creation_absent,历史任务无法恢复唯一根因;部署本提交后,新失败会保留首个 Agent cause_code 并区分模板、克隆、seed、NWFilter、domain define/autostart/start 阶段;卷缺失退款证据要求 dir pool 的刷新清单与目标文件 ENOENT 同时成立,其他池型保守保持 uncertain;随后须用一次受控创建完成宿主机实测 ``` ### 2026-10-16 创建诊断 Linux AMD64 二进制发布验收 ```text source commit: 59dff015355b93800d024e097dfc949584165536 Go version: Go 1.27.1 Agent build: linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen、trimpath、vcs.modified=false;外部链接器剥离调试符号并移除本机构建路径 Agent artifact: release/virt-agent-linux-amd64 Agent SHA-256: 3ba35c544f563354fbeab2f0f99e02acb0be917a45b16e58a7e4fdc1fbe0666f Gateway build: linux/amd64、CGO_ENABLED=0、静态链接、trimpath、vcs.modified=false;运行时代码未改变,仅同步本次源码提交标识 Gateway artifact: release/virt-cloud-agent-gateway-linux-amd64 Gateway SHA-256: f59a96840b735c1560260830681b038a41e692c8623db3b820b9177b34f23361 go vet / go test: Agent libvirt+libvirt_dlopen 的 hypervisor、operation、api 通过;Gateway 全量及 race 通过 PHP tests: CloudAdminOperationsService、CloudAgentProtocol、CloudFinancialWorkflow、CloudOperationErrorCatalog、CloudProtocol 通过 artifact inspection: 两个文件均为 ELF 64-bit x86-64,未嵌入本机路径或部署端点;Agent 最低检测到 GLIBC_2.14,运行时需要 libvirt.so.0 known skips or risks: 二进制需部署到面板与宿主机后,再以一次受控创建取得新的 cause_code 并完成真实 libvirt 生命周期验收 ``` ### 2026-10-16 手工 UEFI 固件模式修复验收 ```text commit: 本记录所在 go 分支源码提交(基线 6461eb3) Go version / libvirt version: Go 1.27.1 / 本机 libvirt 12.8.0 go vet: Agent 默认构建通过 go test: Agent 默认及 libvirt+libvirt_dlopen 全量通过;hypervisor 定向回归通过 go test -race: Agent libvirt+libvirt_dlopen 全量通过 go mod verify / tidy -diff: 均通过且无变更 Linux AMD64 build: Zig 交叉编译预检通过;linux/amd64、CGO_ENABLED=1、tags=libvirt,libvirt_dlopen,最低 GLIBC 符号版本 2.14 read-only host diagnosis: 103 宿主机 libvirt 日志对失败创建明确报告 `cannot use feature-based firmware autoselection when firmware autoselection is disabled` XML contract: 手工 loader/NVRAM 模式不再生成仅适用于 `os firmware='efi'` 自动选择的 firmware feature;测试精确锁定配置 loader、readonly=yes、pflash、secure=no、NVRAM template/path、SMM=off authorized host mutation test: 未重放旧 operation_id,未重新提交付费创建,未注册测试域 known skips or risks: schema 校验不能捕获本次 libvirt 语义互斥;发布后二进制仍须先在 103 执行只读 domxml-to-native,再由用户即时确认一次受控付费创建 ```