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

154 lines
22 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 明确未应用:保留失败审计,显示部分结果,清除父任务占用;新的显式删除仅派发至仍有副本的宿主。未知叶子、错绑副本和伪造投影仍拒绝解锁。
- 云镜像全部宿主机副本已删除但主副本仍存在:父任务不得提前发布成功,副本账本不得提前删除。对象 DELETE 明确成功或精确版本 HEAD 返回不存在后才原子退休目录;DELETE 结果不明确时原 operation 不重放,需两次间隔 HEAD 证明相同大小、ETag 和 version ID 后才生成新代次。连续三代仍不明确、对象身份变化或明确拒绝必须进入管理员核对;管理员重试只处理对象存储,不得再次调用 Agent。晚到宿主机成功回执也必须进入同一两阶段边界。
- 全新 schema 的 `cloud_templates` 不得包含 `source_type`、`sealed_source_url` 或其他旧来源路径;不得存在 `cloud_rescue_template_imports`、`cloud_rescue_template_deletions`、`cloud_upload_staging`、旧云镜像上传/导入路由、浏览器救援 ISO 上传路由或宿主机级目录接口。本地 QCOW2 只允许由浏览器对同一持久导入意图执行受控 multipart 直传,不能进入 PHP 请求正文;救援 ISO 仅允许 HTTPS 远程源进入隔离区,校验通过后发布不可变对象。后续所有宿主机补齐和修复只能使用主副本生成的精确版本只读地址。
- 云镜像导入必须覆盖同一幂等键重放、不同指纹冲突、刷新后跳过服务端已确认分片、完成/Abort 响应丢失核对、24 小时过期清理及 Bucket lifecycle 兜底。官方地址下载失败必须保留同一可恢复意图;不可变 PUT 结果不明且 HEAD 暂不可用时保持 `source_unknown`,后续 HEAD 证明对象存在只能接纳原对象,证明不存在才允许在原对象键上重新下载和发布,任何路径都不得分配第二个模板或任务代次。PHP 硬中止遗留的 `virt-cloud-template-*` 普通临时文件只能在超过 24 小时后由普通 worker 逐个删除。
- 持续填充回执、叶子与聚合队列:三个通道均在有界 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 自由文本、路径、密钥或载荷。
- 服务条款和隐私政策的公开页面只读取最近一次已发布版本;保存草稿、预览草稿和发布失败都不能改变公开内容。
- 中文与英文法律内容分别维护草稿和发布历史;切换语言不能串用另一语言的版本。不同访问域名必须读取同一份全局发布内容,只允许 `{{site_name}}` 按当前站点名称安全替换。
- 两个管理员同时编辑同一法律页面时,旧 `draft_version` 的保存或发布必须返回冲突,不能覆盖新草稿;发布成功必须新增不可变历史版本。
- 法律内容在保存、预览和公开读取时都必须经过服务端清洗;脚本、事件属性、表单、外链资源和未知标签不能进入预览或公开页面。
- 落地页、服务条款、隐私政策和后台法律编辑页必须分别在桌面与窄屏视口验收,导航、目录、编辑控件和正文不得横向溢出。
- 对象存储配置页面不得回显 Access Key ID、Secret Access Key 或数据库密文;普通管理员只能查看,保存、连接验证和停用必须同时经过超级管理员与 CSRF 校验。
- 对象存储页面必须在桌面与窄屏视口验收运行概览、编辑抽屉和清理异常工作区;编辑抽屉默认保持现有凭据,只有明确启用“替换凭据”才显示空白凭据输入框。停用和重新核对必须使用站内确认对话框,不使用浏览器原生 `confirm()`。
- 对象存储保存后必须处于未启用状态;只有当前配置版本的签名 `HeadBucket` 成功后才能就绪。修改或停用时旧验证立即失效;失败响应只显示稳定的本地错误,不泄露 Endpoint 响应正文、凭据或服务器路径。
- 使用受控的 S3/MinIO 测试 Bucket 分别验收路径寻址和虚拟主机寻址、错误 Region、错误凭据、缺少 `s3:ListBucket`、无效证书和连接超时;验证过程中 Bucket 对象数与内容不得变化。
- 可移植备份必须拒绝额外可写盘、backing chain、LUN 和活动 pivot/mirror;运行实例分别验证文件系统一致性与 Guest Agent 不可用时的崩溃一致性路径,关机实例验证稳定完整副本。
- `PeerMigration V3` 必须验证当前全部快照都进入同一不可变清单、任一快照缺失或回执漂移即拒绝切换、目标恢复后快照目录整体改绑。源 Agent 自动生成持久 TLS 1.3 身份并发布本机地址目录,目标必须精确锁定源证书 SHA-256 并携带一次性 Bearer 票据;公开清单、任务结果和浏览器响应均不得出现宿主机路径、私钥或票据。目标必须优先尝试同网段地址并可回退公网地址,按固定 8 MiB Range 分块续传、复用合法 `.partial` 并在导入前核对每个完整 SHA-256。
- 目标分块暂存必须由 Agent 派生到第一个 `storage_path_roots` 下的 `.peer-migration-staging`,不能落在 Journal 系统盘。故障注入分块断连后应从已有偏移继续;成功导入删除暂存,过期中断会话只能由有界本地清理回收,不能删除不匹配目录。
- 目标在恢复和用户防火墙收敛期间必须保持关机;源机的运行/关机、autostart、断网状态与修改后主机名必须在独立激活步骤后保持一致。传输确定失败须同时提供续传和安全回滚,防火墙、激活、回滚、源清理的确定失败均有显式恢复出口。若源准备已存在精确成功回执但 PHP 最终化失败,只能将原准备效果收敛为 `applied` 后创建新的补偿回滚任务;Agent 明确确认源机恢复前不得释放目标预留或 IP。未知效果只能核对原 operation,不能重放。普通云备份仍只能产生单系统盘 S3 对象,PeerMigration 不得创建 S3 迁移对象。
- 维护迁移阶段注册表必须通过完整性测试:每个 Agent 任务种类只能对应一个账本字段、完成处理和不确定结果核对动作,每个人工恢复动作只能对应一个执行入口。页面必须直接使用后端返回的恢复选项和阶段进度;接口在加锁后使用同一判定重新授权。资源结算模块只能在源删除或目标接管得到明确证明后移动订单预留和公网 IP。没有持久化字节遥测时只能显示阶段进度,不能合成传输百分比。
- 独立恢复可选择原宿主机或其他合格宿主机;无论目标是否为原宿主机,都必须单独校验并预留容量与全新公网 IP。目标使用 `bridge:br0`;校验下载对象字节数与 SHA-256,新实例 UUID、MAC、seed、NVRAM、网络过滤器和流量状态均不得复用源实例,且不得继承订单、账单、服务期、到期时间或流量周期。
- 对备份/恢复断连、超时和回执丢失执行故障注入:同一 Agent operation ID 只能查询收敛,不能再次派发。恢复失败只有在全部托管产物明确不存在时才能释放容量与 IP。对象删除响应未知时不得重放原 DELETE;必须用两次间隔 HEAD 证明同一大小、ETag 和 `version_id` 仍存在,才允许创建新的删除代次。验证每轮最多三次、超限转人工、手动重试重新建立稳定证据、精确版本删除、清理债务不占保留份数,并确认大量异常债务不会饿死新的保留清理。
- 清理异常工作区不得显示对象键或 `version_id`。`delete_uncertain` 必须显示下一次自动核对时间且没有人工重试按钮;`delete_attention` 必须显示停止时间,只有超级管理员可点击“重新核对”,该动作必须先执行精确对象身份检查并返回稳定核对流程,不能直接调用 DELETE。
## 7. 非生产宿主机验收
静态测试不能替代真实宿主机验收。经授权后,在非生产 KVM 主机验证创建、启动、关机、重启、重置、重装、快照、救援、网络、防火墙、删除、模板/ISO 与存储注册,并在每类长操作中杀死 helper、Agent、Gateway 和 PHP worker。验收记录至少包含:提交哈希、发行版/libvirt/QEMU/Go/PHP 版本、命令、开始/结束时间、真实 mutation 次数、任务终态、进程残留、资源栅栏、已知跳过项。
VPC 还必须在至少两台同地区非生产宿主机上保持 firewalld 运行并验收:专用 guest/transport zone 与双向 policy 的 runtime、permanent 定义完全一致;VPC bridge 和所选传输接口只绑定到各自专用 zone;同一 VPC 的同机与跨宿主机实例可进行任意 IP 协议双向通信;伪造源地址、跨 VPC、VPC 到其他宿主机出口以及 VPC 到宿主机 INPUT 仍被拒绝。测试期间不得通过停用 firewalld、加入 `trusted`、打开全局 forward 或添加宽泛 direct/rich rule 获得假通过。删除最后一个本地 VPC 投影后,Agent 必须只解除受管接口绑定,不删除或覆盖宿主机其他 firewalld 配置;永久配置应能在后续 firewalld reload 后恢复同一边界。
管理员 VPC 控制面还要分别在桌面和窄屏视口验收概览、全站网络、地址池抽屉和详情抽屉。首屏必须由服务端直接提供摘要、地区就绪状态和网络目录,不能用全页等待替代;浏览器只在后台重新核对一次。地区“可创建”必须与用户创建接口复用同一个资格判定。地址池创建使用稳定 `request_key`,编辑使用 `expected_revision`,已有占用时 CIDR 与分配前缀保持锁定。VPC 详情只展示实例端口、宿主机投影、批次和原任务链接;失败或未知效果只能进入原 operation 的任务详情核对,不能在控制面直接重发、强制收敛或解除资源栅栏。只读管理员不得获得地址池 mutation 控件。
未完成真实宿主机验收时只能报告“静态与本机测试通过”,不能宣称生产发布完成。