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

130 lines
14 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 验证门槛
本文件只描述当前全新部署架构。旧数据库、旧 Python 引擎和旧 Agent Journal 不在验证范围内,也没有迁移验收。
## 1. 静态与单元测试
提交前在仓库根目录执行:
```bash
git diff --check
php tools/generate-recovery-contract.php --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 测试。
### 恢复类型契约
`agent/operation/recovery_contract.json` 是恢复种类、身份范围、Agent action 和 system actor 可提交结论的唯一清单。Go 将它嵌入二进制;PHP 使用 `tools/generate-recovery-contract.php` 生成的 `CloudOperationRecoveryContract.php`,生产面板不读取 Agent 源码目录,也不在启动时生成文件。
新增或调整操作时:
1. 修改清单,明确普通叶子、开通、存储、支付或汇总模式;不能为了通过测试把特殊任务加入普通恢复。
2. 实现该类型的请求身份、业务终结器和种类专用证据校验;清单只定义能力边界,不替代这些安全检查。
3. 执行 `php tools/generate-recovery-contract.php` 并一起提交生成物。`--check` 和 PHP 契约测试必须在清单/生成物不一致时失败。
4. 补齐 `CloudOperationRecoveryMatrixTest.php` 的真实请求/账本 fixture,以及 Agent 契约测试。新增种类没有覆盖、动作映射遗漏、权限方向冲突、快照参数越界,都必须让测试失败。
开通的 system fence 只允许 `not_applied`,仍需专用清理与资金证据;支付、固定存储和汇总任务不得获得普通 system recovery 权限。两种普通效果结论共享一个 PHP 提交事务:保留各自证据校验,先处理账本/父任务,再在同一事务确认晚到回执。现有幂等、冲突证据、prepared crash-resume 和失败不 ACK 的回归不可删除。
## 2. 单次派发契约
自动测试至少证明:
- HTTP mutation 在数据库任务提交后立即返回 `202`、`task_id`、`status_url`,不等待宿主机完成。
- 相同幂等键和相同指纹只返回原任务;不同指纹复用键被拒绝。
- `dispatch_attempts` 永远不超过 1;租约过期、worker/Agent/Gateway 重启和 HTTP 超时都不会把 mutation 放回队列。
- 运行时故障注入 `dispatch_attempts=-1/2`(以及可模拟时的 NULL/非整数)必须 fail-closed:任务和聚合父任务继续阻断,回执保持 `received` 且不 ACK,Agent 调用次数为 0,恢复密文不清除,用户与管理员页面显示 `recovery_dispatch_ledger_conflict`。修回 `1` 后同一回执或只读证据可继续收敛;修复前不得手工解栅栏、退款、强制删除或提交重叠模板/ISO/救援目录操作。
- 进行中 DTO 只有 `completed:false`;完成 DTO 只有 `completed:true` 与 `succeeded|failed`。
- GET 列表、详情、任务观察、管理员检查和健康检查都不会修改任务或联系 mutation 端点。
- 显式 `/tasks/read` 只更新可见的已完成任务;读取失败不自动重试。
- 终态不可变;重复、乱序和晚到回执不能改变任务或触发 mutation。策略表中所有 Agent 叶子任务的精确晚到成功/无副作用失败回执只允许幂等收敛账本和 effect fence;不同 event、operation 或正文必须拒绝,并保留任务供后续只读恢复。
- Agent 完成事件严格绑定当前 WSS 会话的 `agent_id`、`operation_id` 和正文摘要;事件 ID 或 operation ID 携带不同正文必须拒绝。
- Agent 与 Gateway 只接受 `virt-agent-control.v3`;任一侧使用旧 v1/v2 控制协议时握手必须失败,不能通过健康检查后再丢弃完成回执。
- 回执传输在收到 ACK 前持续进行;旧 attempts/expires 元数据不能淘汰 outbox。ACK 只删除 outbox,不删除主 Journal tombstone。
## 3. 底层执行与故障注入
对每种 mutation 至少注入以下故障,并统计真实 libvirt/本地变更调用次数:
1. 写 Journal 前拒绝:任务终态失败,调用次数为 0。
2. Journal 已提交、helper 未启动时崩溃:重启后终态失败,调用次数为 0,不启动 helper。
3. helper 已启动、回执前崩溃:子 Journal 未提交终态时,重启后终态失败并保留 durable fence,调用次数为 1;若子 Journal 已提交终态而 `completion.json` 未发布,重启须导入匹配的原终态且不再次执行。覆盖新旧 worker 目录、成功与无副作用失败、身份冲突/损坏目录不被清理、暂时不可读时不抢先写 `result_unconfirmed`。
4. libvirt 返回后丢失响应:任务在回执截止时失败,调用次数为 1,晚到结果不能翻转终态。
5. helper 超时:父进程 TERM/KILL 整个进程组并执行有界 `Wait`;确认回收后才释放 admission。
6. helper 无法回收:任务仍终态失败;VM、磁盘等破坏性操作的执行栅栏继续立即拒绝相同资源的新 mutation。固定存储池配置保留失败证据但不得形成跨任务栅栏。
7. Agent/Gateway/PHP worker 分别重启:任务不重派,数据库租约和浏览器 busy 状态均在固定截止内释放。
8. 完成 endpoint 连续失败:同一个不可变事件持续低频重投;Agent 重启后仍保留,只有收到匹配 ACK 才删除 outbox。
9. 存储配置专用边界:派发 60 秒、helper 120 秒、回执 180 秒;旧记录即使保存了更长通用截止,也按较早的有效截止失败并允许新的独立 operation。
10. 策略种类恢复(实例电源、重装、救援、网络/设置、快照、防火墙、删除、生命周期网络控制、模板、救援模板和用户 ISO):
- 晚到成功与明确无副作用失败回执分别收敛 `applied/not_applied`;无回执时用新鲜、种类专用、operation-bound 的 Agent inspection 做同样收敛。任务必须保持原 `failed`、原错误、结果、终态时间和 `completion_event_id`。
- 精确持久回执可以在接收入口同步做纯 PHP 收敛;只有需联系 Agent 的 inspection/fence 恢复才能由独立 `--recovery-only` worker 执行。普通/策略 worker 不得联系恢复目标;recovery worker 每轮最多公平处理一项。
- PHP 先预提交账本并继续保持 blocker。活动失败栅栏的 Agent 审计写入必须和 PHP effect commit 在同一 job-row 锁下串行,且写前重验租约、incident 和 `received` 事件;原 mutation 调用次数仍只能为 0 或 1。
- `partial/inconclusive`、Agent 离线、认证失败、operation/ID 冲突、无效回执、密文损坏、账本或实例状态矛盾都必须持久低频退避;不得因 6 小时、12 次、历史 attempts/expires 或任何累计预算停止领取。
- 测试必须覆盖超过 12 次和超过 21600 秒后继续 inspection、fence POST 响应丢失后 GET 恢复、prepared crash-resume、精确晚到回执覆盖匹配且无活栅栏的 prepared intent,以及 event 持久化后/prepare 后崩溃且无 Agent 重投时的续跑。任务 effect commit 与事件 `applied` ACK 必须同事务提交。
- received event 必须从 terminal job 做 `(host_id,operation_id)` 相关索引查询并重算 `payload_sha256`。无效摘要直接拒绝;方向、完整 operation hash 或 fence 语义冲突时原子落为 `recovery_evidence_conflict`,保留 blocker/escrow/prepared 证据;隔离该异常事件后,job 仍必须按退避再次领取,不能覆盖冲突证据。
- kind-specific 成功证明缺失时记录 `recovery_receipt_invalid`;加密请求、本地账本、数据库或资源状态异常记录对应 `recovery_*` 代码。所有异常都必须在任务中心/管理页面显示具体中文说明,并在根因修复后继续同一 operation 的安全收敛。
测试必须覆盖不相交资源并行、相同资源拒绝、存储配置运行时串行但终态失败后允许新 operation、旧存储 blocker 派生索引的原子清理、存储配置非阻塞进程锁的 busy/释放行为、角色中途失败后同路径新任务单调补全且不回滚、重 I/O 容量限制、nonce 防重放、operation 指纹冲突、Journal schema 不匹配拒绝启动,以及 `.traffic.json` 跨 helper 进程的文件锁。
六类恢复回归还必须覆盖:
- 模板/ISO 导入与删除 A 宿主已应用、B 明确未应用:保留失败审计,显示部分结果,清除父任务占用;新的显式删除仅派发至仍有副本的宿主。未知叶子、错绑副本和伪造投影仍拒绝解锁。
- 持续填充回执、叶子与聚合队列:三个通道均在有界 tick 内获得处理机会,空通道不能浪费整轮。
- Gateway 未监听及连接阶段超时且零字节发送:明确未执行并原子收尾;已发送后超时、连接复用、缺统计、多个传输中任一可能发送均不能当作未派发。开通任务只退款一次,不重复派发。
- 快照占用及各变更入口写入前校验失败:Journal 记录无副作用失败,同资源新 operation 可以进入;写调用之后及显式 uncertain 错误继续保留保护。
- `dispatch_attempts=0` 的 create 因缺密钥、临时数据库或账本异常而收尾失败:保留恢复入口;根因修复后自动完成退款/库存/IP/预留收尾,原终态不翻转、不联系 Agent、不重复退款。
## 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、卷、过滤器、地址、模板或账单的新冲突请求立即失败,不进入等待队列。固定存储池配置保持同一 operation 不重放,但失败后不以旧任务阻断具有新 operation ID 的显式请求。
- 副作用可能发生时禁止自动退款、释放 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 次数、任务终态、进程残留、资源栅栏、已知跳过项。
未完成真实宿主机验收时只能报告“静态与本机测试通过”,不能宣称生产发布完成。