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/ENGINE_COORDINATION.md

15 KiB

引擎资源锁与持久执行占用

此变更对应可靠性审查第 1、8 项。移除 VMService._CREATE_LOCK,同时移除内部 API 覆盖整段远程工作的更新协调锁。请求不再因为另一宿主的 VM 操作而争用这两把全局锁。

资源边界

资源 互斥范围
vm:<host_id>:<canonical_uuid> 同一 VM 的电源、网络、快照、重装、救援、删除及私网元数据/QGA 写操作
allocation:<host_id> 宿主容量检查与创建准入
storage:<host_id> 宿主上的卷分配、导入、快照和存储清理
rescue-template:<rescue_scope>:<template_id> 同一宿主/救援池作用域内模板的使用与删除
catalog:network Fabric/VPC 共享目录的变更准入;Fabric 异步执行持有到终态核验
cache-gc:<host_id>:<kind> 对应宿主的缓存维护执行;队列意图仍保存在原 tombstone
maintenance 标记 在线更新与所有已接纳的写操作/后台维护互斥

同宿主的存储池名称和路径可能指向同一底层池,因此保守共用存储资源,不按输入字符串拆分。长存储操作仍串行使用该宿主的存储资源;不同宿主分离,独立 VM 的电源和防火墙修改也无需等待存储资源。镜像目录、共享缓存 GC 等原有目录锁仍可能影响其调用者,这不是所有引擎操作完全互不影响的保证。

本地资源锁按资源名排序取得,记录持有者和等待者,最后一个引用退出后删除。异步 VM 锁使用弱引用注册表,等待者仍持有强引用。生产写入先取得持久占用,再取得本地资源锁;等待有上限。锁注册表不再永久保留每个历史 VM。

宿主应用的快照、重装、救援等状态锁仅保护短状态更新;整段远程调用改用可回收的每 VM 请求锁。创建使用独立 allocation 锁,不阻塞已有 VM 的电源操作。宿主身份更换仍属于排他维护,有活动 VM 请求时立即拒绝,待原请求结束后再重试。

宿主注册与执行身份

宿主连接测试和保存使用暂存的 SSH 文件,其 libvirt URI 会随暂存目录变化。私有引擎必须从已绑定当前宿主的 StableHostManager.host_id 显式取得执行身份,与保存后的 VM 操作共用原始宿主 ID、并发预算、storage:<host_id> 锁及未决写入保护。首次添加时即使 manager.current() 为空也适用;不能按临时 URI 或指标使用的宿主哈希另建执行身份。

内部身份缺失或格式非法时,在 libvirt 操作前返回 409 并清理暂存连接;请求体不能指定或覆盖此身份。独立面板模式继续使用已验证的地址、端口、SSH 指纹三元组生成身份。本修复不改变数据库结构、指标历史或 VM 归属键,也不向用户接口恢复宿主字段。

旧版本异常留下的未决协调记录不会因本次修复或重启自动解除。若升级或后续请求被其阻塞,必须按下文人工恢复流程逐条核验;修复连接构造本身不证明历史远端操作已经结束。

连接建立失败单独返回 libvirt_connection_failed。只有明确通过 libvirt 执行远端变更、且本次执行尚未发出任何写入 RPC 的调用,才释放本次请求与资源占用,允许连接恢复后重新提交。写入证据在发送 RPC 前记录,并由同一执行的嵌套资源占用、线程池任务和后续连接共同继承;第一条连接写过后,第二条连接失败不能被当成执行前失败。VPC/Fabric 等会运行 SSH 修改脚本的工作流不使用“尚无 libvirt 写入”作为无副作用证明。该判定只用于正在执行的请求,不能据此清除历史 uncertain 记录。

RPC 另行逐次记录 pending 和成功回执:已确认写入后,读取或连接收尾超时不再留下宿主级写入阻断。回执只解除该 RPC 的待确认状态,不能重置上述工作流的累计写入证据,也不能替代多步骤任务完成或资源清理证明;快照冻结恢复仍保留独立凭据。详见 libvirt 写入回执与恢复。

宿主指纹扫描、暂存配置准备和 libvirt 校验前的只读 SSH 能力探测若失败,须先持久化本次请求的 failed_before_start 凭据,再释放占用;全局扫描入口和指定宿主入口遵循同一规则。凭据写入失败或结果不明仍保留保护;该例外不适用于暂存配置提交后的失败,也不适用于任意 SSH 修改命令。

数据库协议

coordination.py 使用现有加密 engine_records 表,record_type=coordination、record_key=admission-v1。版本 1 文档保存 revision、claims 和最多 100 条人工核验收据。通过现有 DatabaseStore.compare_and_set 的行锁事务完成短准入更新;远程调用期间不持有数据库事务。

每个占用包含随机 token、worker owner_id、独立随机 execution_id、原 operation_id、资源集合、active/uncertain 状态、任务类别、有限元数据和诊断时间。相同操作编号不等于相同执行身份,不能借它重入另一请求。后台任务在入队前持久化独立子占用并继承执行身份和 VM 资源,随后父 HTTP 请求才可返回 202。任务函数返回不代表成功,必须读到持久终态且没有未知子占用才释放。

数据库 CAS 不可用、响应丢失、文档损坏或占用容量耗尽时拒绝准入,不退回进程内锁。默认最多 1024 个未完成占用。时间戳仅用于诊断,没有 TTL 接管、PID 猜测或重启自动清空。未来 Go/多进程写入者必须使用同一加密格式、CAS 和身份/资源协议;本次没有启用多 worker,其他目录与运行时状态仍需独立验收。

取消、未知结果和维护

HTTP 请求的实际执行由受跟踪任务持有,调用者取消只停止等待;原执行继续保存结果后再释放资源。共享停机预算耗尽时保留未完成占用。普通请求的占用覆盖最终 operation 落库,不能在 libvirt 返回后、结果尚未保存时提前放行。

执行前失败与准入拒绝(2026-10-13)

不能用 HTTP 5xx 判断是否执行过写入。当前 VM 请求、嵌套资源锁、RPC 与后台线程 共享本次执行的写入和未知结果证据;仅对远端修改全部经过 RPC 的 VM 路径启用。 execution_outcome 对外提供三种有限值:

值 证据与处理
not_dispatched 当前执行已失败,未发出远端写入,没有未知提交或仍持有执行权的后台子任务;同时记录 mutation_started=false,释放本次占用
acknowledged 对应操作成功完成并保存回执;普通电源命令只确认命令被接纳
unknown 写入或本地提交结果仍可能不明,或后台执行仍待确认;不能据此重放或解锁

外层在调用子应用前仍持久保存 mutation_started=true,防止进程崩溃丢失写入边界。 只有本次存活执行的完整证明才能改为 false。状态/XML/存储检查失败和排队超时 不再仅因 502/503/504 变成永久锁。协调器确认被另一执行拒绝时传递独立准入证明; 拒绝本次 VM B 的请求只释放 B 的新占用,VM A 原有未决存储占用保持不变。 单独的错误码、旧数据库字段或先前被拒绝的证据不能覆盖后续实际写入、取消、 CAS 响应丢失或数据库异常。宿主配置提交及 VPC/Fabric 的 SSH 工作流不使用此例外。

异步重装、快照和救援由执行线程在未写入且本地任务/恢复目录处理成功后保存证明; HTTP 返回 202、队列尚未运行或父请求没有写入都不代表任务已经结束。 公网 IP 变更须先成功撤销本次新 IP 预留,才能恢复未派发状态;原 IP 保持不变。 创建退款仍要求独立的虚拟机/卷不存在与归属、凭据、IP 清理证明, not_dispatched 本身不能授权退款。

PHP 对精确绑定原操作编号的未派发失败恢复用户删除准入状态;到期删除保持到期策略, 不重新激活实例。旧任务、旧持久占用和旧 RPC 标记不做迁移或自动解除。 依据:libvirt 错误 API 与 Python 绑定说明;上面的执行证明是面板自己的协议, 不是 libvirt 错误码或 HTTP 状态码提供的事务保证。

普通电源命令与状态观察(2026-10-13)

POST vms/{uuid}/actions 的 start/shutdown/reboot/poweroff/reset 在 libvirt 调用成功返回后输出 {uuid, action, command_accepted: true}。这是命令回执, 不附带或推断实时 state,不等待来宾关机、启动完成或 QGA 就绪。 对应 operation 持久化成功后正常释放本次 VM 占用;相同 operation_id 重试只读取原回执。真正缺少写入回执的操作仍保留 uncertain,不自动重放。

PHP 仅对与原加密请求 UUID、action、POST 资源路径及操作编号相符的成功回执, 跳过私网生命周期执行与 VPC expectation 完成门禁。电源命令不推进 VPC 的 desired/applied/usable,也不改变到期/流量断网策略;独立 VPC 协调继续核验 宿主和来宾。其他任务的私网、停机、资源清理校验保持不变。

用户页面在任务确认后释放按钮,再独立刷新实时电源状态;来宾忽略正常关机时 允许提交强制断电。慢查询或查询失败不改写命令结果,新命令使旧观察失效。 救援预挂载后的开机同样只返回回执,救援状态 GET 通过实际 XML 单独确认进入救援。 本次不迁移或释放历史 uncertain 任务、协调占用及 RPC 未决标记。

依据:virDomainShutdown 与 virDomainReboot。 来宾可以忽略请求,命令成功与来宾实际状态应分开处理;删除、重装等仍须自行确认停机。

相同操作编号的重试仍校验权限和请求摘要。原占用已存在而 operation 尚未入库时返回 409;已有记录则只返回原执行状态。未知执行返回 uncertain、safe_to_refund=false,不自动重放或依据瞬时 VM 缺失退款/释放 IP。executor_active 是当前 worker 的兼容提示,false 不证明另一 worker 或远端动作已经停止。

排队快照仅在本 worker 的 Future.cancel() 证明确实未开始后才能被到期断网取消;必须完成原有持久取消凭据和目录回滚,再取得 VM 资源。不能根据另一 worker 的 queued 字段猜测取消成功。初始任务保存/提交失败的明确执行前凭据允许释放本次占用;数据库提交状态不明仍保留保护。

在线更新预检与任务发布(2026-10-13)

在线更新先执行只读 Git/版本/令牌预检,不取得全局维护占用,也不持有 VM 准入 调用 active_job() 所需的更新器本地锁。因此初次远端查询失败或缓慢,不阻断其他 宿主的 VM 写入。预检成功后通过同一 CAS 取得全局维护占用,初始 metadata 就绑定 本次随机 update_job_id;最终创建任务时重新核验本地与远端版本及现有更新任务。

最终预检或已有任务检查失败,只在 create_job() 明确返回 UpdateNotQueued (本次尚未开始保存新任务)的执行证据时释放本次占用,与 HTTP 409/502/503 无关。 进入创建任务之前的长任务检查失败也可释放;不依据“返回时 job 变量为空”猜测未派发。

保存 update.job.<id> / update.active_job 后,独立执行器可能已经领取任务, 即使引擎尚未调用 systemctl。该边界之后的数据库写入回执丢失,以及取消等待但 后台线程仍可能发布任务的情况,继续保留绑定 ID 的 uncertain 占用。版本仍由独立 执行器在 fetch 后再次核验;HTTP 成功或任务已排队不代表代码更新已完成。

正常交接后只有该更新任务确认 succeeded/failed 才释放对应 active 维护占用。 旧的无任务 ID、unknown/uncertain 或丢失结果记录不自动迁移、解锁,重启也不会清空。 更新记录和维护占用分别位于 engine_records 的 value 与 coordination 类型中; 只删 update.active_job / update.job.<id> 不能证明更新未执行,也不能解除协调占用。

Fabric 的 202 异步执行也先持久交接;根任务与全部节点都提交明确终态后才释放,interrupted 或未知节点不释放。VPC 探测线程池逐成员传播原执行上下文,避免与自己持有的 VM 资源冲突。缓存清理保留既有持久 tombstone 队列,执行过程另持有维护任务占用。未加载宿主的未决长任务也阻止在线更新。

错误码 行为
coordination_busy / 409 资源已有已接纳执行;稍后查询原操作,新的请求尚未开始
coordination_uncertain / 503 旧执行结果未确认;禁止自动接管
coordination_unavailable / 503 数据库占用/提交结果无法确认;停止后续修改并保留证据

后两项缺少上述当前执行的未派发证明时,与 libvirt 未知写入错误一样保留重装凭据、 救援 XML、快照目录和原任务,不进入通用失败补偿。拒绝新执行不会解除旧阻塞执行。

升级与人工恢复

先停止旧引擎,保存数据库和 <data_dir>/libvirt-execution,再在维护窗口启动新代码;不允许旧、新写入者混跑。启动准入迁移会扫描旧 operation:缺少 execution_id、已越过 mutation_started、仍 running/pending/uncertain 的记录被保守导入未决占用。旧任务不能仅因缺少新字段获得重放或退款许可。

核验流程同时遵循 libvirt 意图恢复:

  1. 保存原 operation、后台 job、占用 token/execution_id/owner_id 和 libvirt 意图。只读核对实际宿主任务、VM、磁盘、快照链和网络;确认原执行已完成或确实停止。同一 VM 的全部历史未决 operation 都要核对,不能只解除恰好占住资源的第一条记录。
  2. 在停止全部写入者的维护窗口,按实际结果修正原任务/业务记录;需要解除 libvirt 意图保护时逐条归档。不能用 TTL、当前不存在、关机或本地 PID 消失代替停止证据。
  3. 使用引擎维护环境中的 DurableCoordinator.snapshot() 定位精确占用,再对已经核验的身份调用 resolve(claim, evidence)。evidence 只写核验记录引用,不放凭据或完整宿主输出。该方法在同一 CAS 中核对三元身份、删除对应占用并保存有限审计收据;不得整行删除 coordination 文档。同一执行的父/子/资源占用均须逐条核验。
  4. 重新启动后查询原 operation,确认业务结果和资源归属,再恢复新任务。解除占用本身不生成成功记录或退款。

当前没有面向网页的一键强制解锁接口,也没有自动判定任意破坏性动作结果的机制。