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

13 KiB

libvirt 执行期限与引擎停机

可靠性审查第 3、4 项引入 libvirt 调用期限和停机总预算;随后第 1、8 项把全进程写锁改为资源锁,并增加数据库持久执行占用。部署仍使用单个引擎 worker。原生 libvirt 错误分类、主密钥初始化和公网防伪隔离属于独立修复范围。

资源锁、持久占用、后台任务交接及升级恢复协议见 引擎协调说明。

执行边界

生产 VMService 工厂必须传入稳定的 execution_scope(注册宿主机 ID,旧入口使用 host scope)。每个连接使用一个通过 spawn 启动的独立 Python 进程,连接及 domain/pool/volume/stream 句柄只在该进程内存活。父进程保留业务步骤、数据库写入、操作编号、锁和进度回调。私有 socket 只传输有大小限制的 JSON、二进制编码和本会话句柄;不使用网络监听或任意对象反序列化。

默认期限:

边界 默认值 配置/说明
等待执行容量、资源锁 5 秒 CLOUD_ENGINE_LIBVIRT_QUEUE_TIMEOUT
worker 就绪、连接建立 20 秒 CLOUD_ENGINE_LIBVIRT_CONNECT_TIMEOUT;各阶段仍受连接总期限限制
单次普通 RPC 120 秒 CLOUD_ENGINE_LIBVIRT_RPC_TIMEOUT;取其与剩余连接预算的较小值
只读连接总预算 30 秒 LIBVIRT_READ_BUDGET
普通变更连接总预算 180 秒 LIBVIRT_MUTATION_BUDGET
镜像、重装、磁盘等连接总预算 30 分钟 LIBVIRT_STORAGE_BUDGET;同步 createXMLFrom 使用剩余预算
快照备份/恢复连接总预算 4 小时 + 120 秒 保留既有长任务轮询窗口,但每个普通 RPC 仍有自己的上限
正常连接关闭 RPC 最多 2 秒 同时受剩余连接预算限制
活跃连接数 全局 32、每宿主 4 CLOUD_ENGINE_LIBVIRT_MAX_CONNECTIONS、CLOUD_ENGINE_LIBVIRT_MAX_PER_HOST

这些是连接及 RPC 期限,不把镜像下载、外部 SSH 命令或一个包含多个连接的业务工作流误称为同一个请求墙钟期限。现有下载/SSH/后台任务预算仍适用。环境变量必须是有限正数,容量必须是正整数。测试用的显式无 scope 原生适配器不应出现在生产工厂。

业务 RPC 超时或停机后,会话永久失败,关闭 socket,并向本地 worker 私有进程组发送 TERM,再在有界等待后发送 KILL,回收其 SSH 子进程。业务代码即使捕获底层异常,离开连接上下文时也会重新抛出统一错误,不能把超时伪装成成功或 404。仅发生在连接收尾阶段、且没有未确认写入的错误单独记录为 cleanup_failure,不覆盖已经返回的命令或业务结果。

写入结果未知与恢复

终止本地客户端不证明远端 libvirtd/QEMU 已停止写入。 每次变更 RPC 发送前,引擎在 <data_dir>/libvirt-execution/<scope 的 SHA-256>/<session>.json 持久写入版本 2 意图:scope、随机 session ID、递增 sequence、pending_write 的序号/方法、last_write_ack 及时间。文件系统一致性快照还记录下文限定恢复所需的任务、运行代、目标卷身份和阶段凭据;不保存连接 URI、凭据、完整 XML 或任意 RPC 参数。

成功响应完整解码后,普通写入通过删除本次意图并 fsync 目录确认回执,再返回调用者;下次写入必须重新持久化新的 pending。准备、发送、读取响应、解码及确认均在同一会话 I/O 锁内,读取不能确认写入,并发调用不能清除彼此的 pending。删除或 fsync 失败时恢复原文件;无法恢复则停止接纳写入。

因此,已经确认的写入之后,info() 等读取失败只报告观察失败;close() 超时单独记录清理错误,两者不再因为历史写入产生整个宿主机的阻断。多步骤业务是否完成仍由 VM/存储级任务及持久占用判断,不能把“没有 pending RPC”当作整个创建、删除或重装成功。stream.finish() / abort() 也经过写入回执边界,上传分块成功不代表最终提交已确认。

真正丢失写入响应、解码失败或回执无法持久化时,保留 pending 与宿主保护;后来的成功回执不能覆盖之前的未确认写入。已有版本 1 和其他旧未决文件仍按原规则阻断,不迁移、不自动清理。只读观察仍可执行,现有已发往远端的并发操作不能被宣称已撤销。

原生 libvirtError 与成功回执不同。收到错误时记录独立 write_error_receipt,维持现有业务在同连接内读取、回退及核验的能力,例如存储池 build() 报错后的 create()。后续成功 RPC 不清除此错误记录;只有原工作流正常收尾才按既有规则解除。后续读取或关闭超时仍保留保护,不把原生错误当成成功或无副作用证明。

错误码 含义
libvirt_execution_timeout 没有未确认写入的 RPC 超时或失去执行器;可能已有成功写入回执
libvirt_execution_stopped 没有未确认写入时引擎停止接单,或使用已关闭会话
libvirt_execution_uncertain 待确认写入、错误收尾或必要恢复阶段的结果未知
libvirt_execution_blocked 同宿主存在未解决的写入意图,本次写入被阻止
libvirt_connection_failed 原生 libvirt 连接未建立;只有本次执行尚无远端写入证据时才允许释放新占用

这组错误不会转换为 libvirtError。真正未知写入及其旧阻断记录跨重启保留,不自动重放、释放 IP/归属或触发清理退款;仅被拒绝的新请求仍适用未派发失败规则。快照、重装和救援任务保留原记录、必要凭据与任务占用;重装超时不会被当成新系统已提交。

依据:virConnectClose 是连接资源释放接口,不能用其失败否定此前 API 回执;libvirt 错误接口 返回原生错误信息,不提供面板业务事务回滚保证。上述序号、意图及回执是引擎自己的协议。

遇到写入保护时的运维流程:

  1. 保留原 operation_id、任务记录和意图文件。停止新的相关业务提交;使用只读状态、libvirt job、domain XML、卷/快照链及日志核对原动作。重试原请求或重启引擎不能解除保护。
  2. 确认原远端动作已完成或已确实停止,并核对磁盘、网络、IP 归属及原任务结果。仅“VM 当前不存在/关机”不足以证明远端动作已经停止。
  3. 在停止引擎的维护窗口备份对应意图文件,按实际结果处理原持久任务及业务记录。当前没有自动判定所有破坏性动作结果或一键解除保护的接口;不能仅改成 failed、退款或删任务来绕过核对。
  4. 完成核对后,仅将已确认的 session 意图移至该 scope 目录之外的受保护归档目录,再启动引擎。同 scope 有其他意图时须逐个核对,不能整目录删除。解除 libvirt 写入保护本身不会把原 operation 标成成功,也不会释放长任务的待核对占用。

意图目录是持久安全状态,应与引擎数据一起备份,不属于可随意清理的临时缓存。它针对当前单引擎进程,不是多 worker 的分布式锁;不要据此增加 --workers。

快照冻结后的限定解冻

普通写入保护不能阻止原快照任务对已冻结来宾的必要解冻。新的文件系统一致性快照在冻结前持久绑定宿主 scope、任务 ID、VM UUID、确定性快照卷名和路径、QEMU 运行 ID 及只存在于实时 XML 的 QGA 运行代令牌。冻结响应和备份启动阶段分别落盘;阶段证据无法持久化时停止后续操作。

逐次 RPC 成功不会删除这份恢复记录:pending_write 可以清空,但已确认冻结仍需要解冻,恢复身份和阶段继续持久保留。原会话明确未冻结或已取得解冻回执,且没有其他未知结果时才可在收尾删除自身记录;真正未知阶段仍保留原凭据供受限恢复使用。

原会话失败并回收本地 worker 后,快照任务立即尝试受限恢复;服务启动核对和原任务核对也使用同一入口。只有原冻结已确认,且备份尚未发送、启动响应已确认,或启动响应未知但能读到本任务精确目标的活动备份时,才允许新连接执行一次限定的 fsThaw。恢复再次检查当前 VM 运行代和备份身份;其他活跃写入者、多个未决意图、缺少证据、目标不符或无法确认旧 worker 已退出都会拒绝自动解冻。旧 worker 消失本身不构成远端阶段证明。

该入口不能发送任意写操作;普通 fsThaw 仍受原写入保护约束。解冻发送前、确认后分别持久化凭据;已确认的恢复只读取原回执,不再次发送解冻,响应未知的恢复转人工核对。解冻确认只更新来宾冻结恢复状态,不删除原意图、不解除 uncertain 占用、不把备份标成成功,也不允许重放原任务。fsThaw 返回 0 表示当前没有文件系统需要解冻,可以确认恢复,但不能证明快照已完成。

升级前记录缺少上述身份和阶段证据时,保留 manual_required 和 snapshot_thaw_recovery_required 提示,不猜测旧任务。此时应立即按以下步骤处理冻结来宾:

  1. 保存原任务、占用和意图,停止相关新任务。在可信宿主连接上核对原 VM UUID、运行代、活动 libvirt 备份及其目标路径;确认没有仍可能发送冻结请求的旧执行器。不能只按 VM 名称、当前 PID 或“没有活动 job”判断安全。
  2. 管理员确认原任务与当前来宾对应、冻结阶段已稳定后,在该宿主机执行 virsh -c qemu:///system domfsthaw <原任务的完整-VM-UUID>。这仅执行解冻,不自动 abort 备份、删除卷或解除引擎保护。随后核对 QGA 冻结状态与来宾业务恢复;QGA 状态不能单独替代任务和运行代核验。
  3. 继续按上一节核验备份结果、卷和持久任务;确认结果后才逐条归档意图并处理协调占用。无法证实阶段或运行代时,保留保护并人工排查,不自动重试冻结/备份。

依据:libvirt backupBegin、libvirt fsThaw 和 QEMU guest agent 冻结接口。

关闭流程

引擎收到 lifespan shutdown 后停止新请求和任务接纳,立即中断 libvirt 执行器并启动回收。后台池、指标采集、Fabric/VPC 维护、共享导入 runtime、各宿主生命周期与默认 asyncio 执行器共享 20 秒 deadline(内部 shutdown_timeout_seconds 可缩短用于测试)。不会为每个宿主机或每个池重新计时。

持久任务使用受管 daemon 线程池。尚未开始的 Future 可以取消,运行中的线程不能被安全强杀;超过预算时保留任务状态并记录未排空日志,不将其视为业务成功。默认 asyncio 执行器也使用同一受管实现,避免解释器退出阶段再次无限等待;活跃 worker 未排空时不提前删除它们使用中的 SSH 凭据。

部署 unit 设置 Uvicorn 请求排空 10 秒、TimeoutStopSec=45s、KillMode=control-group。通常应用在共享预算内退出;无法取消的外部行为、事件循环阻塞或操作系统异常仍由 systemd 的整个控制组终止提供最后边界。终止进程不改变远端结果未知的语义。

已有部署必须同步更新 /etc/systemd/system/virt-cloud-engine.service 并执行 systemctl daemon-reload,在维护窗口重启才能应用新期限。仅拉取 Python 源码不会改变旧 unit。本次代码验证不执行生产重启。

验证边界

隔离测试使用真实 spawn 进程与测试 libvirt 后端,覆盖连接/读取/写入/关闭卡住、会话总期限、容量饱和、跨会话句柄、native error 字段、二进制流、QGA、TERM 忽略、子进程组回收、关机竞态、重启后保留意图及业务异常吞噬。另以真实 Python 子进程验证无限后台线程不会拖住退出。

Linux 部署验收还需在专用测试宿主验证真实 libvirt-python/SSH、QGA、镜像上传/克隆、长快照、超时后远端继续执行、systemd stop 的墙钟期限和控制组无遗留进程。当前 macOS 隔离结果不能代替该验收,也不能证明已终止远端 job。

语义依据:Python executor shutdown 明确运行中的 Future 不会因 cancel 被终止,且普通线程池会阻止解释器退出;libvirt job API 提供特定 job 的取消接口,不能替代每种远程调用的统一本地执行边界。