|
|
# 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 生命周期验收
|
|
|
```
|