11 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 原生适配器不应出现在生产工厂。
超时或停机后,会话永久失败,关闭 socket,并向本地 worker 私有进程组发送 TERM,再在有界等待后发送 KILL,回收其 SSH 子进程。业务代码即使捕获底层异常,离开连接上下文时也会重新抛出统一错误,不能把超时伪装成成功或 404。
写入结果未知与恢复
终止本地客户端不证明远端 libvirtd/QEMU 已停止写入。 发出第一条变更 RPC 前,引擎在 <data_dir>/libvirt-execution/<scope 的 SHA-256>/<session>.json 写入并 fsync 一个意图文件。普通意图记录 scope、随机 session ID、首个方法及时间。文件系统一致性快照还记录下文限定恢复所需的任务、运行代、目标卷身份和阶段凭据;不保存连接 URI、凭据、完整 XML 或任意 RPC 参数。
正常完成并安全关闭会话才删除意图。中断、异常退出、清理失败或关机时已有写入的会话保留意图;引擎重启仍能发现它。该宿主机后续 libvirt 写入会被拒绝,只读观察仍可执行。现有已发往远端的并发操作不能被宣称已撤销。
| 错误码 | 含义 |
|---|---|
libvirt_execution_timeout |
尚未记录写入的会话超时或失去执行器 |
libvirt_execution_stopped |
尚未记录写入时引擎停止接单 |
libvirt_execution_uncertain |
会话已记录写入,结果未知 |
libvirt_execution_blocked |
同宿主存在未解决的写入意图,本次写入被阻止 |
libvirt_connection_failed |
原生 libvirt 连接未建立;只有本次执行尚无远端写入证据时才允许释放新占用 |
这组错误不会转换为 libvirtError。后两项跨重启保持 uncertain、safe_to_refund=false,不自动重放、释放 IP/归属或触发清理退款。快照、重装和救援任务保留原记录、必要凭据与任务占用;重装超时不会被当成新系统已提交。
遇到写入保护时的运维流程:
- 保留原
operation_id、任务记录和意图文件。停止新的相关业务提交;使用只读状态、libvirt job、domain XML、卷/快照链及日志核对原动作。重试原请求或重启引擎不能解除保护。 - 确认原远端动作已完成或已确实停止,并核对磁盘、网络、IP 归属及原任务结果。仅“VM 当前不存在/关机”不足以证明远端动作已经停止。
- 在停止引擎的维护窗口备份对应意图文件,按实际结果处理原持久任务及业务记录。当前没有自动判定所有破坏性动作结果或一键解除保护的接口;不能仅改成 failed、退款或删任务来绕过核对。
- 完成核对后,仅将已确认的 session 意图移至该 scope 目录之外的受保护归档目录,再启动引擎。同 scope 有其他意图时须逐个核对,不能整目录删除。解除 libvirt 写入保护本身不会把原 operation 标成成功,也不会释放长任务的待核对占用。
意图目录是持久安全状态,应与引擎数据一起备份,不属于可随意清理的临时缓存。它针对当前单引擎进程,不是多 worker 的分布式锁;不要据此增加 --workers。
快照冻结后的限定解冻
普通写入保护不能阻止原快照任务对已冻结来宾的必要解冻。新的文件系统一致性快照在冻结前持久绑定宿主 scope、任务 ID、VM UUID、确定性快照卷名和路径、QEMU 运行 ID 及只存在于实时 XML 的 QGA 运行代令牌。冻结响应和备份启动阶段分别落盘;阶段证据无法持久化时停止后续操作。
原会话失败并回收本地 worker 后,快照任务立即尝试受限恢复;服务启动核对和原任务核对也使用同一入口。只有原冻结已确认,且备份尚未发送、启动响应已确认,或启动响应未知但能读到本任务精确目标的活动备份时,才允许新连接执行一次限定的 fsThaw。恢复再次检查当前 VM 运行代和备份身份;其他活跃写入者、多个未决意图、缺少证据、目标不符或无法确认旧 worker 已退出都会拒绝自动解冻。旧 worker 消失本身不构成远端阶段证明。
该入口不能发送任意写操作;普通 fsThaw 仍受原写入保护约束。解冻发送前、确认后分别持久化凭据;已确认的恢复只读取原回执,不再次发送解冻,响应未知的恢复转人工核对。解冻确认只更新来宾冻结恢复状态,不删除原意图、不解除 uncertain 占用、不把备份标成成功,也不允许重放原任务。fsThaw 返回 0 表示当前没有文件系统需要解冻,可以确认恢复,但不能证明快照已完成。
升级前记录缺少上述身份和阶段证据时,保留 manual_required 和 snapshot_thaw_recovery_required 提示,不猜测旧任务。此时应立即按以下步骤处理冻结来宾:
- 保存原任务、占用和意图,停止相关新任务。在可信宿主连接上核对原 VM UUID、运行代、活动 libvirt 备份及其目标路径;确认没有仍可能发送冻结请求的旧执行器。不能只按 VM 名称、当前 PID 或“没有活动 job”判断安全。
- 管理员确认原任务与当前来宾对应、冻结阶段已稳定后,在该宿主机执行
virsh -c qemu:///system domfsthaw <原任务的完整-VM-UUID>。这仅执行解冻,不自动 abort 备份、删除卷或解除引擎保护。随后核对 QGA 冻结状态与来宾业务恢复;QGA 状态不能单独替代任务和运行代核验。 - 继续按上一节核验备份结果、卷和持久任务;确认结果后才逐条归档意图并处理协调占用。无法证实阶段或运行代时,保留保护并人工排查,不自动重试冻结/备份。
依据: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 的取消接口,不能替代每种远程调用的统一本地执行边界。