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

91 lines
9.8 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 采用全新部署的单次派发模型,不迁移旧任务,不兼容旧状态,也不保留自动重试或自动核对队列。这里的“请求成功”只表示面板已经持久接收任务;宿主机操作是否成功只能由终态回执决定。
## 对外契约
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 返回不能被统一解释为来宾最终状态。