# 单次派发任务架构 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` 才是结果来源。 ## 单次派发状态机 ```text 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](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 返回不能被统一解释为来宾最终状态。