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

9.8 KiB

单次派发任务架构

Virt Cloud 采用全新部署的单次派发模型,不迁移旧任务,不兼容旧状态,也不保留自动重试或自动核对队列。这里的“请求成功”只表示面板已经持久接收任务;宿主机操作是否成功只能由终态回执决定。

对外契约

  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;worker、进程重启、租约过期、Gateway 断线和 HTTP 超时都不得把任务重新放回派发队列。绝对截止时间在任何层都不能因重新读取、页面刷新或服务重启而重置。

任务一旦终态即不可变。晚到的宿主机回执可以按事件 ID 幂等确认和清理传输 outbox,但不能把 failed 改成 succeeded,也不能改变账单、退款或资源释放结论。

Agent 执行边界

Go context 不能可靠中止已经进入 CGo/libvirt 的调用,因此每个宿主机变更在独立 worker 子进程中执行。主 Agent 负责认证、持久日志、资源准入和回执;worker 负责打开自己的 libvirt 连接并执行一次变更。

  • worker 从受限标准输入读取一次性请求,不从命令行或日志暴露密钥。
  • 父进程使用绝对截止时间;到期先终止、再强制回收整个 worker 进程组,并等待有界的 Wait。
  • worker 目录和持久标记表明该 operation_id 已经启动时,主进程绝不再次启动同一变更。
  • worker 正常结束后原子写入唯一回执;worker 崩溃、Agent 重启或回执丢失时直接终态失败,标记 effect_may_have_applied=true、safe_to_resubmit=false。
  • worker 已结束但主 Journal 无法持久化终态或执行栅栏时,Agent 必须停止控制通道并以失败退出,不得吞掉错误继续接单。重启只导入 helper 已写的不可变回执;没有回执则写入 result_unconfirmed,绝不再次执行 mutation。
  • 宿主机重连只恢复连接能力,不扫描并重放历史变更。

部分 libvirt 操作在客户端被杀死后仍可能已经由守护进程执行。因此底层硬截止解决的是进程、锁和任务无限占用,不会把未知副作用伪造成“确定未执行”。

回执传输

完成回执是不可变事件,不是新的变更请求。Agent 可以在有界次数和绝对截止时间内重复投递同一 event_id;PHP 以 event_id、operation_id 和正文摘要幂等接收。回执到达或超过投递截止后,Agent 必须停止发送。

PHP 的 receipt_deadline_at 到期时直接把任务终态化为失败。之后收到相同回执只返回幂等 ACK,不能更新任务结果。不同正文复用事件 ID 或 operation ID 必须拒绝并记录安全日志。

host_storage_configure 使用更短且固定的专用边界:60 秒内必须跨越派发边界,Agent helper 最多执行 120 秒,PHP 最多等待终态回执 180 秒,浏览器 GET 观察最多 300 秒并在停止前做一次本地状态刷新。存储配置读取本身会先收敛已经越过绝对截止的关联任务;该过程只消费已持久化回执或写失败终态,不联系 Agent、不发送 PUT,也不重放 mutation。为使升级时已经存在的任务同样有界,存储任务的有效截止取数据库旧值与这些专用期限中的较早值。

资源与资金安全

任务终态不等于副作用已被证明。当失败回执表明操作效果可能已经发生时:

  • 任务本身立即结束,不再轮询、不再自动核对、不再自动重试;
  • 同一 VM、卷、网络过滤器、地址或账单的冲突变更立即返回明确错误,不进入等待队列;
  • 不自动退款、不释放 reservation、不再次删除磁盘;
  • 管理员可以执行独立的只读检查,但检查不会翻转原任务终态,也不会续作原 mutation;
  • 超级管理员只能对已有种类专用原子终结器的任务提交审计结论。开通任务仅支持由新鲜宿主机缺失证据确认 not_applied,并在同一事务退款、释放库存/IP/预留后再解栅栏;支付任务只根据签名回调或外部支付平台审计证据收敛本地账本,不重新下单;
  • 没有专用终结器的类型必须拒绝“只改任务字段”的假解锁。它们的原任务仍已终态失败,但资金或资源保持 fenced,直到实现并验收对应的业务账本终结器;
  • 需要修复时创建一个经过人工判断的新操作,而不是复用或重放原任务。

固定存储池配置是非破坏性的窄例外:失败回执仍如实保留 effect_may_have_applied,原 operation ID 仍永久终止且不能重放,但它不形成跨任务资源栅栏。存储配置只做单调补全,已定义的固定 pool 不因后续失败而被 destroy、undefine 或回滚。管理员可以按已定义的同一路径,或只修正尚未定义的角色后显式创建新任务;新 operation 仍通过 storage-config 运行时准入和宿主机非阻塞文件锁串行,并且只核验或补全固定池,不改绑、迁移或删除数据。旧 helper 尚未退出时,新任务必须立即失败而不是等待,且不得自动重试或留下新的永久栅栏。

如果业务账本终结器本身因损坏数据或数据库异常失败,公开任务仍必须落为 failed,并写入 finalization_incident。该不可失败的最终路径清除密封请求载荷、将副作用标记为 unknown;除上述固定存储池配置例外外,资金与资源栅栏继续保留,并向管理端显示需要修复账本的事件。它绝不会为了让任务看起来成功而猜测退款、释放或重放 mutation。

这一区分同时满足可用性和安全性:用户不会看到永久运行的任务,worker 不会永久占用槽位,而未知破坏性副作用也不会被自动重复执行。

非任务循环

服务守护循环、健康采集和只读指标刷新可以长期运行,但每一轮必须有独立超时、允许失败后返回主循环,且不能持有某个 mutation 的数据库租约、资源锁或浏览器忙状态。它们不属于任务重试,不得借此重新提交宿主机变更。

验收门槛

  • 同一个任务在并发、进程重启和断线注入下,宿主机 mutation 调用次数只能是 0 或 1。
  • 在派发前失败、派发后超时、worker 崩溃、Agent 崩溃、Gateway 断线和 PHP 重启场景中,任务都在固定截止内进入终态。
  • 截止后执行槽、资源锁、WSS pending map、数据库租约和浏览器 busy 状态全部释放。
  • 终态回执重复、乱序或晚到不能改变已终态任务,也不能触发 mutation。
  • 公共任务 API、任务中心和当前部署文档中不存在 uncertain、needs_attention、自动 reconcile 或自动重试语义;资源账本可以保留内部安全栅栏状态,但只能向用户解释为原任务已失败且资源已锁定,不能把任务重新显示为运行中。
  • 真实非生产 libvirt 宿主机必须验证:被终止 worker 不残留、后续独立任务仍可执行,以及 reboot/reset/shutdown 的成功判定来自明确证据而非仅观察“仍在运行”。

设计依据