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

# 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 次数、任务终态、进程残留、资源栅栏、已知跳过项。
未完成真实宿主机验收时只能报告“静态与本机测试通过”,不能宣称生产发布完成。