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

296 lines
20 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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,再由用户即时确认一次受控付费创建
```