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/VALIDATION.md

11 KiB

PHP/Go Agent 验证门槛

本文件定义 go 分支的交付门槛。历史旧引擎测试结果不代表本实现通过;每次发布必须记录实际提交、环境、命令、通过/失败/跳过数量和未完成的真实环境验收。

1. 静态与单元测试

Go Agent 与本机 helper:

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:

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 不自动重放/退款。

浏览器脚本与部署文件:

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 测试机另运行:

systemd-analyze verify /home/virt-cloud/deploy/*.service

最终仓库不得再跟踪 Python 源码、依赖清单或旧引擎 service:

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 与宿主机

先做只读能力检查:

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. 发布记录

发布提交前把实际结果追加到本节;未执行项写“未执行”及原因,不能写成通过。

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 分支提交前验收

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 提交前验收

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 链接测试仅有重复库警告