9.8 KiB
单次派发任务架构
Virt Cloud 采用全新部署的单次派发模型,不迁移旧任务,不兼容旧状态,也不保留自动重试或自动核对队列。这里的“请求成功”只表示面板已经持久接收任务;宿主机操作是否成功只能由终态回执决定。
对外契约
- PHP 在一个业务事务中保存任务、不可变
operation_id、请求指纹、资源占用和绝对截止时间。 - 提交接口立即返回 HTTP
202 Accepted、task_id和status_url。浏览器解除按钮占用并提示“任务已接收”,不等待宿主机执行完成。 - 未完成任务只返回
completed: false,不公开内部阶段、尝试次数或“待核对”状态。 - 完成任务只返回
completed: true,且status只能是succeeded或failed。 - 失败回执同时返回
effect_may_have_applied与safe_to_resubmit。界面只报告失败和风险,不提供自动或手动“重试”按钮。 - 所有浏览器观察请求均为只读 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 的成功判定来自明确证据而非仅观察“仍在运行”。
设计依据
- RFC 9110 - 202 Accepted:接收处理不代表处理已完成,响应应说明当前状态并指向状态监视。
- RFC 9110 - Retrying Requests:客户端不应自动重试非幂等请求,除非能证明请求未被应用或能够检测并恢复部分失败。
- Google AIP-151 - Long-running operations:长任务先返回操作资源,随后以明确的完成状态携带结果或错误。
- libvirt domain API:关机、重启及作业中止调用具有不同的完成语义,API 返回不能被统一解释为来宾最终状态。