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