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

24 KiB

单次派发任务架构

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 才是结果来源。

单次派发状态机

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。

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 的成功判定来自明确证据而非仅观察“仍在运行”。

设计依据