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

99 lines
7.7 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
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 携带不同正文必须拒绝。
- Agent 与 Gateway 只接受 `virt-agent-control.v2`;任一侧使用旧控制协议时握手必须失败,不能通过健康检查后再丢弃完成回执。
- 回执传输只有固定次数与绝对截止时间,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 无法回收:任务仍终态失败;VM、磁盘等破坏性操作的执行栅栏继续立即拒绝相同资源的新 mutation。固定存储池配置保留失败证据但不得形成跨任务栅栏。
7. Agent/Gateway/PHP worker 分别重启:任务不重派,数据库租约和浏览器 busy 状态均在固定截止内释放。
8. 完成 endpoint 连续失败:同一个不可变事件最多发送配置中的固定次数,并在绝对截止后停止。
9. 存储配置专用边界:派发 60 秒、helper 120 秒、回执 180 秒;旧记录即使保存了更长通用截止,也按较早的有效截止失败并允许新的独立 operation。
测试必须覆盖不相交资源并行、相同资源拒绝、存储配置运行时串行但终态失败后允许新 operation、旧存储 blocker 派生索引的原子清理、存储配置非阻塞进程锁的 busy/释放行为、角色中途失败后同路径新任务单调补全且不回滚、重 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、卷、过滤器、地址、模板或账单的新冲突请求立即失败,不进入等待队列。固定存储池配置保持同一 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 次数、任务终态、进程残留、资源栅栏、已知跳过项。
未完成真实宿主机验收时只能报告“静态与本机测试通过”,不能宣称生产发布完成。