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

97 lines
13 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.

# libvirt 执行期限与引擎停机
可靠性审查第 3、4 项引入 libvirt 调用期限和停机总预算;随后第 1、8 项把全进程写锁改为资源锁,并增加数据库持久执行占用。部署仍使用单个引擎 worker。原生 libvirt 错误分类、主密钥初始化和公网防伪隔离属于独立修复范围。
资源锁、持久占用、后台任务交接及升级恢复协议见 [引擎协调说明](ENGINE_COORDINATION.md)。
## 执行边界
生产 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/归属或触发清理退款;仅被拒绝的新请求仍适用[未派发失败规则](ENGINE_COORDINATION.md#执行前失败与准入拒绝2026-10-13)。快照、重装和救援任务保留原记录、必要凭据与任务占用;重装超时不会被当成新系统已提交。
依据:[virConnectClose](https://libvirt.org/html/libvirt-libvirt-host.html#virConnectClose) 是连接资源释放接口,不能用其失败否定此前 API 回执;[libvirt 错误接口](https://libvirt.org/html/libvirt-virterror.html) 返回原生错误信息,不提供面板业务事务回滚保证。上述序号、意图及回执是引擎自己的协议。
遇到写入保护时的运维流程:
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](https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainBackupBegin)、[libvirt fsThaw](https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainFSThaw) 和 [QEMU guest agent 冻结接口](https://www.qemu.org/docs/master/interop/qemu-ga-ref.html#command-guest-fsfreeze-status)。
## 关闭流程
引擎收到 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](https://docs.python.org/3.12/library/concurrent.futures.html#concurrent.futures.Executor.shutdown) 明确运行中的 Future 不会因 cancel 被终止,且普通线程池会阻止解释器退出;[libvirt job API](https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainAbortJob) 提供特定 job 的取消接口,不能替代每种远程调用的统一本地执行边界。