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

6.9 KiB

PHP/Go Agent 验证门槛

本文件只描述当前全新部署架构。旧数据库、旧 Python 引擎和旧 Agent Journal 不在验证范围内,也没有迁移验收。

1. 静态与单元测试

提交前在仓库根目录执行:

git diff --check

cd agent
go mod verify
go vet ./...
go test ./...
go test -race ./...
go test -tags libvirt ./...
go test -tags 'libvirt libvirt_dlopen' ./...

cd ../gateway
go mod verify
go vet ./...
go test ./...
go test -race ./...

cd ../web
find app config public tests -name '*.php' -print0 | xargs -0 -n1 php -l
for test in tests/*Test.php; do php "$test"; done
for test in tests/*.mjs; do node "$test"; done

cd ..
jq empty deploy/*.json.example

测试产物只能写入临时目录;不能覆盖 release/ 中的用户文件。macOS 没有生产 libvirt 头文件时,必须在与目标宿主机 ABI 一致的 Linux 环境补跑两个 libvirt tag 组合和 race 测试。

2. 单次派发契约

自动测试至少证明:

  • HTTP mutation 在数据库任务提交后立即返回 202、task_id、status_url,不等待宿主机完成。
  • 相同幂等键和相同指纹只返回原任务;不同指纹复用键被拒绝。
  • dispatch_attempts 永远不超过 1;租约过期、worker/Agent/Gateway 重启和 HTTP 超时都不会把 mutation 放回队列。
  • 进行中 DTO 只有 completed:false;完成 DTO 只有 completed:true 与 succeeded|failed。
  • GET 列表、详情、任务观察、管理员检查和健康检查都不会修改任务或联系 mutation 端点。
  • 显式 /tasks/read 只更新可见的已完成任务;读取失败不自动重试。
  • 终态不可变;重复、乱序和晚到回执不能改变任务、资源、退款或账单。
  • Agent 完成事件严格绑定当前 WSS 会话的 agent_id、operation_id 和正文摘要;事件 ID 或 operation ID 携带不同正文必须拒绝。
  • 回执传输只有固定次数与绝对截止时间,ACK 只删除 outbox,不删除主 Journal tombstone。

3. 底层执行与故障注入

对每种 mutation 至少注入以下故障,并统计真实 libvirt/本地变更调用次数:

  1. 写 Journal 前拒绝:任务终态失败,调用次数为 0。
  2. Journal 已提交、helper 未启动时崩溃:重启后终态失败,调用次数为 0,不启动 helper。
  3. helper 已启动、回执前崩溃:重启后终态失败并保留 durable fence,调用次数为 1。
  4. libvirt 返回后丢失响应:任务在回执截止时失败,调用次数为 1,晚到结果不能翻转终态。
  5. helper 超时:父进程 TERM/KILL 整个进程组并执行有界 Wait;确认回收后才释放 admission。
  6. helper 无法回收:任务仍终态失败,但执行栅栏继续立即拒绝相同资源的新 mutation。
  7. Agent/Gateway/PHP worker 分别重启:任务不重派,数据库租约和浏览器 busy 状态均在固定截止内释放。
  8. 完成 endpoint 连续失败:同一个不可变事件最多发送配置中的固定次数,并在绝对截止后停止。

测试必须覆盖不相交资源并行、相同资源拒绝、重 I/O 容量限制、nonce 防重放、operation 指纹冲突、Journal schema 不匹配拒绝启动,以及 .traffic.json 跨 helper 进程的文件锁。

4. libvirt 语义

  • 生产构建必须使用官方 libvirt.org/go/libvirt CGo binding;缺少 tag 时明确返回 capability 不可用,不能回退 shell、SSH 或 Python。
  • event loop 在连接前启动;每个连接 generation 注册并按逆序释放 lifecycle、JOB_COMPLETED 和 close callback。重连只恢复连接能力,不扫描历史 mutation。
  • shutdown/reboot API 返回只代表请求已被 libvirt 接受,不能统一解释为来宾已达到最终状态。删除必须有 Domain 与全部受管工件的明确清理证据。
  • 在线快照的 JOB_COMPLETED 只唤醒当前 helper 做一次新鲜 GetJobStats;事件本身不是成功证据。需要中止匹配的 backup job 时最多调用一次 AbortJob,并受同一个 helper 绝对截止约束。
  • 存储 stream 使用 non-blocking 模式,callback、abort、finish 和 free 都有有界退出路径;helper 结束后不能留下 callback 或 goroutine 持有 admission。

5. 资源、资金与人工处置

  • 派发后失败默认 effect_may_have_applied=true、safe_to_resubmit=false;同 VM、卷、过滤器、地址、模板或账单的新冲突请求立即失败,不进入等待队列。
  • 副作用可能发生时禁止自动退款、释放 reservation/IP、再次删除磁盘或创建替代任务。
  • 管理员 inspect 只能读;不得改变 Journal、任务、Domain、卷、过滤器或 libvirt job。
  • resolve-effect 只对已有种类专用终结器开放:开通任务用新鲜宿主机缺失证据确认 not_applied,先写一次不执行 libvirt 的 Agent 栅栏审计元数据,再原子退款并释放面板资源;支付任务只依据签名回调或管理员已核验的本地渠道账本收敛,绝不重新下单。其他任务类型必须拒绝假解锁。任何路径都不能翻转原任务的 failed 终态;解除栅栏后若需新操作,必须由用户另行显式提交。
  • force-delete 只能来自明确的 force_required 正常删除结果和新的数据丢失确认;超时、断线或只读看到 Domain 活动都不能授予强删。
  • 支付创建、退款、续费、宽限和最终删除分别验证:第三方结果不明确时任务终态失败但资金栅栏保留;不得后台无限查询或再次扣款。

6. 浏览器与 API 回归

  • 所有 mutation 页面收到 202 后立即解除按钮 busy,显示“任务已接收”,然后由共享 observer 只读观察。
  • observer 单飞执行,单次请求有超时,总观察有绝对截止;hidden/pagehide 会停止,恢复可见时只允许继续同一 task GET。
  • 观察停止只提示稍后在任务中心查看,不表示失败,也不取消或重发任务。
  • 任务中心分别查询 active/completed,显示未读数量,并在已完成内容真实渲染后显式标记已读。
  • 全部 UI 不显示“待核对”、uncertain、needs_attention、停止自动核对、自动恢复、任务重试或续作旧 mutation 的控件。
  • Unix 秒必须按秒转换;错误文本来自本地白名单,不显示 Agent 自由文本、路径、密钥或载荷。

7. 非生产宿主机验收

静态测试不能替代真实宿主机验收。经授权后,在非生产 KVM 主机验证创建、启动、关机、重启、重置、重装、快照、救援、网络、防火墙、删除、模板/ISO 与存储注册,并在每类长操作中杀死 helper、Agent、Gateway 和 PHP worker。验收记录至少包含:提交哈希、发行版/libvirt/QEMU/Go/PHP 版本、命令、开始/结束时间、真实 mutation 次数、任务终态、进程残留、资源栅栏、已知跳过项。

未完成真实宿主机验收时只能报告“静态与本机测试通过”,不能宣称生产发布完成。