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/TASK_EXECUTION.md

123 lines
24 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.

# 单次派发任务架构
Virt Cloud 采用全新部署的单次派发模型,不迁移旧任务,不兼容旧状态,也不保留 mutation 自动重试队列。这里的“请求成功”只表示面板已经持久接收任务;宿主机操作是否成功由同一 operation 的不可变回执或只读恢复证据决定。
## 对外契约
1. PHP 在一个业务事务中保存任务、不可变 `operation_id`、请求指纹、资源占用和绝对截止时间。
2. 提交接口立即返回 HTTP `202 Accepted`、`task_id` 和 `status_url`。浏览器解除按钮占用并提示“任务已接收”,不等待宿主机执行完成。
3. 未完成任务只返回 `completed: false`,不公开内部阶段、尝试次数或“待核对”状态。
4. 完成任务只返回 `completed: true`,且 `status` 只能是 `succeeded` 或 `failed`。
5. 失败回执同时返回 `effect_may_have_applied` 与 `safe_to_resubmit`。界面只报告失败和风险,不提供自动或手动“重试”按钮。
6. 所有浏览器观察请求均为只读 GET、单飞执行,并受单次请求超时和总观察截止时间约束。观察停止不会取消或重新提交任务。
这里的“提交接口”指所有采用任务协议的 Agent 或支付渠道操作。即使目标已经完全收敛、无需再次写宿主机,也要在同一事务创建一个 `dispatch_attempts=0` 的终态成功任务,并返回精确的 `202 {task_id,status_url}`;这份回执表达“本次请求已由既有持久证据满足”,不会伪造一次 Agent 派发。未采用任务协议的纯数据库配置写入仍可同步返回 `200/201`。
任务查询不会联系 Agent。为防止 PHP worker 守护进程整体退出后数据库记录永久显示执行中,查询自己的任务时可以只在本地收敛已经越过绝对截止时间的记录:先消费已持久化的终态回执,否则写入终态失败。该兜底不派发请求,也不延长截止时间。
HTTP `202` 不是宿主机操作成功。它表示请求已经进入异步处理,`status_url` 才是结果来源。
## 单次派发状态机
```text
accepted ──单次领取──> dispatching ──Agent 已接收──> awaiting_receipt
│ │ │
└──截止/拒绝──> failed └──截止/断线──> failed ├──> succeeded
└──> failed
```
每个任务最多跨越一次派发边界。`dispatch_attempts` 的数据库约束为 `0..1`;运行时只把 `0` 视为确定未派发、只把 `1` 视为合法已派发。若旧数据库、人工修库或损坏数据产生其他值,面板必须以 `recovery_dispatch_ledger_conflict` fail-closed:不采信或 ACK 回执、不访问 Agent 栅栏、不退款、不释放资源、不授权后续破坏性操作,并保留恢复密文和资源锁。页面显示具体异常,恢复 worker 按低频持续保留该任务。管理员必须依据真实派发记录把计数修复为 `1` 或 `0`;修改计数不会立即解锁,sticky repair incident 仍由后台重新验证不可变终态。修为 `1` 时,同一 operation 和同一不可变回执/只读证据继续收敛;修为 `0` 时只重跑 PHP 本地未派发终结器,绝不联系 Agent;若既有成功终态却被修为 `0`,系统将明确报告状态矛盾并继续锁定。任何路径都不重放 mutation。worker、进程重启、租约过期、Gateway 断线和 HTTP 超时都不得把任务重新放回派发队列。绝对截止时间在任何层都不能因重新读取、页面刷新或服务重启而重置。
面板跨过本地派发边界,并不证明 HTTP 已送达 Gateway。对于固定回环地址,PHP 仅在 libcurl 明确连接失败或连接阶段超时,且完整统计证明连接未建立、HTTP 请求和上传/下载字节均为零、没有响应或重定向时,将该次失败记为 `not_applied`;如果存在多个底层传输尝试,每次都必须具有未发送证明。创建任务通过既有原子终结器退款并释放预留,其他类型通过各自终结器收尾,原任务均不重发。请求已发送后的超时、空响应、缺失统计和 Agent 查不到 operation 均不等于未执行,仍保留未知影响。该证明无法追溯补回历史任务未保存的传输证据。
任务一旦终态即不可变。晚到的宿主机回执不能把 `failed` 改成 `succeeded`,派发账本异常也不能把既有 `succeeded` 改成 `failed`;两者都不能重写原任务的错误、结果、终态时间或完成事件编号。恢复异常通过独立的 `finalization_incident`、效果结论和资源锁表达,页面不能仅因原终态为成功就显示普通成功。只有列入种类策略表、且具备幂等业务账本终结器的精确同源回执,才可以在不重放 mutation 的前提下收敛其副作用账本。策略表覆盖实例电源、重装、救援、更换网络、实例设置、实例升级、快照、备份、防火墙、维护迁移目标状态恢复、删除/强制删除、生命周期网络控制,以及模板、救援镜像和用户 ISO 的 Agent 叶子任务;聚合父任务只根据子任务重新汇总。精确成功回执收敛为 `applied`,明确 `effect_may_have_applied=false` 的精确失败回执收敛为 `not_applied`。两者都不会重放,且原任务终态保持不变。
## PHP 本地服务补偿
实例可用时间补偿不跨越 Agent 派发边界。管理员先冻结范围和受众摘要,普通 worker 再用独立补偿明细租约处理 PHP 数据库投影;成功时在同一事务延长实例、尾服务周期和已经存在的流量/备份权益窗口,并创建一个 `dispatch_attempts=0` 的终态本地审计任务。该审计任务只为实例操作记录和任务中心提供统一证据,不表示发生过 Agent 调用。
支付创建中或可安全等待的条件进入原明细的 `deferred`,账本矛盾进入 `attention`;两者都不创建新的 Agent operation。相同事故和实例具有唯一约束,worker 租约恢复只能继续原明细,不能通过重复批次再次加时。补偿不改余额、流量字节或套餐,也不生成账单。详细业务不变量和通知边界见 [`SERVICE_COMPENSATION.md`](SERVICE_COMPENSATION.md)。
## Agent 执行边界
Go context 不能可靠中止已经进入 CGo/libvirt 的调用,因此每个宿主机变更在独立 worker 子进程中执行。主 Agent 负责认证、持久日志、资源准入和回执;worker 负责打开自己的 libvirt 连接并执行一次变更。
- worker 从受限标准输入读取一次性请求,不从命令行或日志暴露密钥。
- 父进程使用绝对截止时间;到期先终止、再强制回收整个 worker 进程组,并等待有界的 `Wait`。
- worker 目录和持久标记表明该 `operation_id` 已经启动时,主进程绝不再次启动同一变更。
- worker 启动前持久化不含密钥的请求身份;正常结束后原子写入唯一回执。若断电发生在子 Journal 已提交终态、但 `completion.json` 尚未发布的窗口,重启可只读导入该终态。必须验证目录/文件的所有者和权限,以及主/子 Journal 的 operation、action、resource、fingerprint;新目录还验证请求身份摘要。升级前没有身份文件的目录仍须通过完整的主/子 Journal 身份匹配。
- worker 已结束但主 Journal 无法持久化终态或执行栅栏时,Agent 必须停止控制通道并以失败退出,不得吞掉错误继续接单。重启先导入有效回执或子 Journal 终态;没有可信终态时写入 `failed/result_unconfirmed` 并保留安全栅栏,绝不再次执行 mutation。暂时无法读取子 Journal 时先退出而不毁掉证据;只有匹配并提交成功的证据目录才可清理,损坏或身份冲突的目录保留供核查。
- 宿主机重连只恢复连接能力,不扫描并重放历史变更。
部分 libvirt 操作在客户端被杀死后仍可能已经由守护进程执行。因此底层硬截止解决的是进程、锁和任务无限占用,不会把未知副作用伪造成“确定未执行”。
各变更入口必须显式标出第一次宿主机写操作。参数校验、资源读取及快照/模板/ISO 占用检查在该边界前的明确拒绝,记录为无副作用失败,可释放本次操作的持久栅栏;镜像源下载在创建卷前返回的普通错误也属于这一类。进入 libvirt 写调用后的错误仍按原有不确定语义处理;显式 uncertain 以及取消/截止错误保留保守语义,不得被前置校验包装降级。该规则不改变创建 VM 的专用资源清理与资金证明要求,也不自动重发失败操作。
## 回执传输
完成回执是不可变事件,不是新的变更请求。Agent 持续投递同一 `event_id`,直到 PHP 返回 ACK;重启、旧 outbox 中保存的尝试次数或历史过期时间都不能淘汰未确认回执。PHP 以 `event_id`、`operation_id` 和正文摘要幂等接收。ACK 只删除投递 outbox,不删除主 Journal 记录。
PHP 的 `receipt_deadline_at` 到期时直接把任务终态化为失败。之后收到相同回执不能更新原任务终态;不支持恢复的类型只返回晚到 ACK。对策略表允许的任务,精确匹配 `agent_id + operation_id + event_id + 正文摘要` 的成功回执会先以原加密请求收敛对应 PHP 业务账本,再提交 `effect_resolution=applied`;明确无副作用的失败回执则收敛为 `not_applied`。回执路径只使用 PHP 已持久化事件,不联系 Agent;任务效果结论与事件 ACK 在同一事务提交,结论提交后立即清除恢复密文。如果进程在事件提交后或预提交后崩溃,专用 recovery worker 会从 terminal job 出发,以已有 `(host_id,operation_id)` 唯一索引精确读取 `received` 事件,重算正文摘要后继续 PHP 提交。它只有在既有 prepared 证据同方向、同完整 operation hash 且栅栏语义一致时才可继续收敛;方向、哈希、ID、栅栏语义、密文或账本状态冲突时,必须记录具体 `recovery_*` 异常并保留 blocker/escrow。异常事件可以被隔离,但任务仍按固定低频退避留在恢复队列,修复数据、身份、网络或 Agent 后继续核对;不存在 6 小时、12 次或其他永久退出上限。它不扫描事件全表,也不依赖 Agent 再次投递。相同回执重传只返回幂等 ACK;不同正文复用事件 ID 或 operation ID 必须拒绝并记录安全日志。
开通任务使用独立的资金恢复终结器,不加入通用效果物化策略,也不重放创建请求。精确成功回执在重新验证未退款订单、已支付开通发票、库存、IP、placement、服务周期和凭据 escrow 后原子补完实例账本。晚到失败回执必须同时证明 `creation_absent=true`、`managed_artifacts_absent=true` 且没有未知副作用,才能原子退款、释放库存/IP/预留并 ACK;仅有失败状态或 `safe_to_resubmit` 不足以退款。没有完整失败回执时,恢复 worker 仍会领取该订单,使用绑定原 operation 的 system-recovery 身份只读检查;只有新鲜、身份一致且明确的 `creation_absent` 证据才进入专用预提交。预提交持久化证据但不提前退款,确认必要的 Agent 栅栏审计后再原子提交资金和资源账本。Agent 已提交栅栏但 PHP 提交失败时,后续轮次可依据同一预提交读取既有栅栏结论并继续,不会重新开通或重复退款。系统身份对开通只允许 `not_applied` 栅栏结论,不能凭只读状态推断成功并物化实例;残留资源、运行中操作、身份冲突、无效证据和矛盾成功回执继续保留保护。此能力需更新面板和 Agent,并保持 recovery worker 运行;不需要数据库迁移或新增 systemd 服务。
任何回执或 inspection 改变 PHP 账本前,都必须重新验证加密请求、任务/宿主机/资源身份,以及该种类终结器会消费的请求与结果字段;可解密但不完整的 escrow 不得以空账本假收敛。prepared 证据绑定规范化后的完整 operation;重试次数只属于调度状态,不参与 immutable operation hash,也不能破坏 prepare 后的崩溃续跑。如果恢复必须写 Agent 栅栏审计结论,该有界网络写入与随后的 PHP effect commit 必须在同一 job-row 锁下串行,写前再次验证租约、incident 和优先回执,防止陈旧 worker 在冲突证据落盘后解除 Agent fence。
`host_storage_configure` 使用更短且固定的专用边界:60 秒内必须跨越派发边界,Agent helper 最多执行 120 秒,PHP 最多等待终态回执 180 秒,浏览器 GET 观察最多 300 秒并在停止前做一次本地状态刷新。存储配置读取本身会先收敛已经越过绝对截止的关联任务;该过程只消费已持久化回执或写失败终态,不联系 Agent、不发送 PUT,也不重放 mutation。为使升级时已经存在的任务同样有界,存储任务的有效截止取数据库旧值与这些专用期限中的较早值。
## 资源与资金安全
普通 `applied/not_applied` 恢复保留各自的证据检查,但共用准备与提交实现,避免资源锁、恢复 escrow、父任务汇总和回执 ACK 在两个方向上漂移。公开入口不变;共同提交事务仍按父任务、目录、子任务、回执的既定顺序加锁,账本及效果结论提交后才确认回执。开通、支付和固定存储的专用收尾不进入这个通用入口。
付费实例升级在派发前原子扣除余额、占用目标套餐库存,并把原 reservation 提升到目标容量。已确认 `applied` 后才更新实例、当前账期流量上限和后续续费快照;已确认 `not_applied` 才恢复来源 reservation、库存与余额。派发后结果未知或宿主机只证明部分扩容时保留目标容量、资金和两侧库存栅栏,继续使用原 `operation_id` 核对,绝不缩盘回滚或自动重放。升级期间旧价格续费被拒绝;成功后旧的未支付续费账单作废并由新快照重新生成。
实例升级的同一个 `resize-vm` operation 覆盖只读预检、原电源状态记录、ACPI 正常关机、停机确认、离线扩容和运行态恢复。原本运行的实例只有在资源与持久定义均确认生效后才执行冷启动,并核对运行态定义;原本关机的实例继续保持关机。正常关机最多等待 10 分钟,超时后停止变更且绝不升级为强制断电;任务保留未知效果栅栏,再由同一 operation 的只读资源证据收敛。若资源已完整生效但冷启动失败,不退款、不回滚,也不误报升级成功;实例与升级账本保持锁定,等待管理员核对并恢复目标运行态后再解除。
跨端恢复能力由 `agent/operation/recovery_contract.json` 定义:Agent 嵌入读取,PHP 使用随源码发布的生成常量。清单区分普通叶子、开通、存储、支付及汇总任务,记录身份范围、动作及 system actor 可提交的结论;未知类型默认拒绝。请求身份重建、业务账本终结器和新鲜证据校验仍是必需条件,登记类型本身不等于可以解锁。维护步骤和跨端契约测试见 `docs/VALIDATION.md`。
任务终态不等于副作用已被证明。当失败回执表明操作效果可能已经发生时:
- 任务本身立即结束,不再轮询、不再自动重试;内部恢复协调器只能低频读取允许种类的同一 Agent operation 证据;
- 同一 VM、卷、网络过滤器、地址或账单的冲突变更立即返回明确错误,不进入等待队列;
- 在可信清理证据确认前不自动退款、不释放 reservation、不再次删除磁盘;
- 管理员可以执行独立的只读检查,但检查不会翻转原任务终态,也不会续作原 mutation;
- 策略表中的 Agent 叶子任务可以自动消费同一 operation 的不可变证据:晚到终态回执是纯 PHP 收敛;没有回执时,由独立的 `cloudWorker --recovery-only` 进程每轮最多领取一项。常驻进程在精确 `received` 事件、普通叶子任务、聚合任务三个通道间轮转,空通道同轮跳过;持续有任务时,每三个完成的 tick 给每个通道一次机会,避免回执或叶子队列持续非空导致聚合任务饥饿。普通/策略 worker 从不联系恢复目标,因此离线宿主的核对不会阻塞正常派发。恢复使用绑定 operation ID 的 system-recovery actor 调用 Agent 只读 `inspect`,且只接受新鲜、种类专用、资源身份一致的 `applied/not_applied` 证据。它先预提交 PHP 账本并继续保留 blocker;只有活动失败栅栏才写入一次 operation-bound Journal 审计结论,再提交 `effect_resolution`。原 mutation 永不调用。`partial/inconclusive`、Agent 离线、ID 冲突、无效回执、密文损坏或账本/实例状态矛盾都会保留 blocker,向页面公开具体异常,并按固定低频退避持续重检;没有次数和总时长上限。修复根因后,同一 operation 可继续自动收敛并清除 incident;相互矛盾的持久证据不得被覆盖或猜测解锁;
- 超级管理员只能对已有种类专用原子终结器的任务提交审计结论。开通任务仅支持由新鲜宿主机缺失证据确认 `not_applied`,并在同一事务退款、释放库存/IP/预留后再解栅栏;支付任务只根据签名回调或外部支付平台审计证据收敛本地账本,不重新下单;
- 没有专用终结器的类型必须拒绝“只改任务字段”的假解锁。它们的原任务仍已终态失败,但资金或资源保持 fenced,直到实现并验收对应的业务账本终结器;
- 需要修复时创建一个经过人工判断的新操作,而不是复用或重放原任务。
固定存储池配置是非破坏性的窄例外:失败回执仍如实保留 `effect_may_have_applied`,原 operation ID 仍永久终止且不能重放,但它不形成跨任务资源栅栏。存储配置只做单调补全,已定义的固定 pool 不因后续失败而被 destroy、undefine 或回滚。管理员可以按已定义的同一路径,或只修正尚未定义的角色后显式创建新任务;新 operation 仍通过 `storage-config` 运行时准入和宿主机非阻塞文件锁串行,并且只核验或补全固定池,不改绑、迁移或删除数据。旧 helper 尚未退出时,新任务必须立即失败而不是等待,且不得自动重试或留下新的永久栅栏。
如果业务账本终结器本身因损坏数据或数据库异常失败,公开任务仍必须落为 `failed`,并写入 `finalization_incident`。所有已注册自动终结器的策略种类在 incident 未清除期间都保留原始密封请求作为隐藏恢复 escrow;这既包括已派发且效果仍为 `unknown` 的任务,也包括 `dispatch_attempts=0`、宿主机效果已确定为 `not_applied`、但 PHP 业务账本回滚尚未提交的任务。后者由 recovery-only worker 只重跑同一种类的 PHP 终结器,不进行 Agent 检查或 mutation;成功后原子清除 incident、将 escrow 改写为脱敏审计载荷,并保留原终态审计字段。失败时按固定低频继续尝试,不能热循环。无法验证或不完整的密文不能假收敛、清空原密文或把任务永久移出恢复队列,而应显示 `recovery_payload_unavailable` 并等待密钥/数据修复。除上述固定存储池配置例外外,资金与资源栅栏继续保留。恢复器绝不会为了让任务看起来成功而猜测退款、释放或重放 mutation。
这一区分同时满足可用性和安全性:用户不会看到永久运行的任务,worker 不会永久占用槽位,而未知破坏性副作用也不会被自动重复执行。
未派发的订单开通任务同样具备 PHP 本地终结器恢复入口:`dispatch_attempts=0` 且退款、库存/IP/预留收尾失败时保留 escrow 和 incident,以固定退避持续尝试原子收尾;历史上落为 `unknown` 的此类任务也可领取。恢复不联系 Agent、不创建 VM、不重放开通,退款和资源释放只提交一次;缺密钥或账本矛盾时保留异常,修复后继续。
模板/用户 ISO 导入和删除的多宿主结果可以合法地部分成功。所有叶子均有确定效果、且副本身份与投影一致时,父任务保留原失败审计,并以 `effect_resolution=applied` 加 `effect_scope=partial` 表示“部分宿主机已应用,全部效果已知”,清除 incident 与目录 `active_job_id`。这不等于全量成功,也不把不完整镜像发布为可用;用户可显式创建新的删除任务,仅处理确认仍存在的副本,已不存在的副本不会重发删除。原父/子任务不会自动补偿或重放,仍有未知叶子或投影矛盾时继续保锁。
云镜像全量删除额外包含对象存储逐副本阶段。全部 Agent 叶子明确删除后,汇总父任务仍不能发布成功,也不能移除副本账本;PHP 对每个存储副本分别冻结 `backend + object_key + version_id + size + ETag` 删除意图。每个 DELETE 返回明确成功或同一精确版本 HEAD 明确不存在后,才在一个事务中退休对象制品和宿主机副本账本、将目录置为 `retired` 并完成父任务。DELETE 超时、断线或 5xx 不得重放原请求;必须间隔至少五分钟得到两次同一对象身份仍存在的 HEAD 证据,才沿用原制品创建新的受控删除代次。身份变化、明确拒绝或超限进入 `delete_attention`,管理员入口只重开对应对象副本的只读核对,不重新派发已经完成的 Agent 删除。
## 非任务循环
服务守护循环、健康采集和只读指标刷新可以长期运行,但每一轮必须有独立超时、允许失败后返回主循环,且不能持有某个 mutation 的数据库租约、资源锁或浏览器忙状态。它们不属于任务重试,不得借此重新提交宿主机变更。
## 验收门槛
- 同一个任务在并发、进程重启和断线注入下,宿主机 mutation 调用次数只能是 0 或 1。
- 在派发前失败、派发后超时、worker 崩溃、Agent 崩溃、Gateway 断线和 PHP 重启场景中,任务都在固定截止内进入终态。
- 截止后执行槽、资源锁、WSS pending map、数据库租约和浏览器 busy 状态全部释放。
- 终态回执重复、乱序或晚到不能改变已终态任务,也不能触发 mutation;允许类型的精确晚到回执只能幂等收敛副作用账本与 effect fence。
- 非法派发计数及其修复后的 sticky incident 在后台复核完成前始终阻断同资源操作;既有成功终态保持成功审计,但 UI 必须显示恢复异常而不能触发普通成功回调。
- `dispatch_attempts=0` 的本地终结器异常只重试 PHP 业务账本,第二次 tick 不重复已提交副作用;无效回执、密文或身份冲突的 receipt-priority 路径必须遵守低频退避,不能形成 hot loop。
- 公共任务 API 和任务中心不把 `partial/inconclusive` 暴露为新任务状态,也不存在自动重试 mutation 语义;资源账本可以保留内部安全栅栏状态,任务始终显示原来的失败终态。策略种类的证据驱动收敛不是任务重试,也不会重新执行宿主机变更;页面必须同时说明正在持续核对及当前具体异常。
- 真实非生产 libvirt 宿主机必须验证:被终止 worker 不残留、后续独立任务仍可执行,以及 reboot/reset/shutdown 的成功判定来自明确证据而非仅观察“仍在运行”。
## 设计依据
- [RFC 9110 - 202 Accepted](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.3.3):接收处理不代表处理已完成,响应应说明当前状态并指向状态监视。
- [RFC 9110 - Retrying Requests](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2):客户端不应自动重试非幂等请求,除非能证明请求未被应用或能够检测并恢复部分失败。
- [Google AIP-151 - Long-running operations](https://google.aip.dev/151):长任务先返回操作资源,随后以明确的完成状态携带结果或错误。
- [libvirt domain API](https://libvirt.org/html/libvirt-libvirt-domain.html):关机、重启及作业中止调用具有不同的完成语义,API 返回不能被统一解释为来宾最终状态。
- [libcurl error codes](https://curl.se/libcurl/c/libcurl-errors.html) 与 [HTTP request size](https://curl.se/libcurl/c/CURLINFO_REQUEST_SIZE.html):区分连接失败与一般超时,并使用实际发送统计限定未派发证明。