GuestKit

---

更新内容

版本	更新内容
Agent (1.2.6)	在访客 Agent 中提供按容器配置的 eBPF 网络策略和 BPF-LSM 控制（guestkit.netpolicy / guestkit.lsm），默认关闭，先审计，仅在限时租约期间强制执行
1.2.5	run_migrate_repair 支持离线注入：主机名、网络、用户、服务、首次启动脚本、cloud-init、重新加入 AD、Windows KMS 和 RDP，并将其追加到修复计划中
1.2.5	在线快照通过特权辅助程序冻结文件系统，因此由 PVC 支持的 VM 可在使用非特权 Agent 时正常创建 KubeVirt 快照
1.2.5	Linux Agent 可在标准发行版上连接 virtio 通道（udev 规则已包含在 DEB、RPM 和 tarball 中）；并发 NBD 挂载不再发生竞争
1.2.2	Web Image Vault 功能达到 TUI 水平：包含清单标签页、Assurance（计划、passport、修复预览和受控应用）、Profiles 和 Files
1.2.0	推出 guestkit-qemu 保障型 QEMU/VirtIO 运行时、guestkit vm、virtctl-guestkit guestfs、切换套件，以及用于处理超大磁盘的 guestkit shrink

完整历史记录：CHANGELOG.md。

为什么选择 GuestKit

每次虚拟机监控程序退出时，问题都一样：你会在凌晨 2 点、切换窗口期间、开机之后，才发现磁盘已损坏。GuestKit 可在来宾关机时读取磁盘——qcow2、VMDK、VHDX、VHD、VDI 或 raw——通过自有的纯 Rust 引擎（NBD 或 loop mount）进行读取。无需设备守护进程，也不用“开机看看”。

当遇到这种情况时……	GuestKit 为你提供……
“能启动吗？”要等到开机时才能知道	离线 doctor 评分（0–100），并为每个阻断问题提供根因链
每次迁移都依赖脚本和口口相传的经验	JSON/YAML 格式的结构化计划，并基于相同评分设置 CI 门禁
切换周末状况百出	感知虚拟机监控程序的 migrate-plan 和 day-0 包，支持 8 个目标平台
没有经过检查的审计记录	为每块磁盘提供一份签名的 Cutover Passport
通过挂载镜像后手动编辑来修复	可供查看的修复计划，应用时会创建备份并支持回滚
靠人工猜测迁移顺序	fleet wave-plan：感知依赖关系的分波计划

修复绝不会隐式进行。所有修复都通过可供查看的计划执行，并会创建备份且支持回滚；相同的评分还用于 CI 门禁、签名的 Cutover Passport 和可信的 QEMU 启动。

启动就绪度评分 首次启动概率评分为 0–100，说明阻断问题，并提供可供审查的修复计划。 切换问题	离线修复 所有修复都通过可供查看的计划执行，并会创建备份且支持回滚。 你可以做什么	迁移保障 相同的评分用于 CI 门禁、签名的 Cutover Passport 和可信的 QEMU 启动。 快速入门
引擎和格式 通过 NBD 或 loop mount，使用纯 Rust 引擎处理 qcow2、VMDK、VHDX、VHD、VDI 和 raw。 平台布局	套件间交接 使用 Transiva 导出，使用 h2kvm 转换和部署，使用 GuestKit 验证保障，并在 Zorvia 或 Zeus OS 上运行。 各工具的职责	CLI、TUI、Web、CI CLI、TUI、QEMU、Python、Web 控制台、来宾内 Agent 和 GitHub Action。 运行 Web 技术栈

完整对比包含更多对比项，包括集群漂移、带来宾内 Agent 的 Carbon TUI，以及可直接替代 virsh qemu-agent-command 的 guestkit qga。

---

GuestKit 与 libguestfs + virt-v2v 对比

	GuestKit	libguestfs + virt-v2v
磁盘访问	Rust 引擎；通过主机上的 qemu-nbd 或 loop 挂载访问客户机文件	启动一个小型设备虚拟机来读取和编辑磁盘
启动就绪情况	doctor：针对每个目标给出 0–100 的首次启动评分，并说明阻碍项	检查和转换；不提供就绪评分
迁移计划	针对每个目标（kvm、proxmox、qemu、kubevirt、aws、azure、gcp、hyperv）生成 migrate-plan	virt-v2v 将客户机转换为可在 KVM 上运行的虚拟机
修复	修复计划包含备份和回滚；rescue 可用于 SSH、GRUB 和密码	使用 virt-customize、virt-rescue 和 guestfish 执行脚本化编辑
切换凭证	签名的 Cutover Passport，以及评分低于阈值时会失败的 GitHub Action	工具包不包含此功能
接口	CLI、TUI、Python、Web 控制台、客户机内 Agent、GitHub Action	CLI 工具和语言绑定
适合选择 libguestfs 的情况		你需要它广泛支持的文件系统和操作系统，或需要 virt-v2v 的端到端转换，且不需要评分或切换记录

GuestKit 与转换工具配合使用，而不是取代所有转换工具：h2kvm 负责转换和部署，并调用 GuestKit 执行离线修复。

---

在线预览

---

各组件如何协同工作

  disk.qcow2 / .vmdk / .vhdx / .vhd / .vdi / .raw
                    │
                    ▼
         ┌──────────────────────┐
         │  Pure-Rust engine    │──►  doctor 0–100 + blockers
         │  NBD / loop mount    │──►  migrate-plan YAML
         └──────────────────────┘──►  Passport · repair · CI gate
                    │                 guestkit-qemu (assured launch)
      CLI · TUI · QEMU · Python · Web · Agent · GitHub Action

使用 Transiva（Apache-2.0）导出 → 使用 h2kvm（Zyvor Production License）转换并部署 → 使用 GuestKit（Apache-2.0）提供保障 → 在 Zorvia 或 Zeus OS 上运行。 使用 FluxVM 运行和管理虚拟机。各组件的职责 · h2kvm 集成概览

深入了解架构：docs/architecture/overview.md。

---

快速入门

# v1.2.6 GitHub Release — crates.io `guestkit` is still 0.3.2
curl -fsSL -O https://github.com/zyvorai/zyvor-guestkit/releases/download/v1.2.6/guestkit-1.2.6-linux-amd64.tar.gz

guestkit doctor vm.qcow2 --target proxmox --explain
guestkit migrate-plan vm.vmdk --target kvm --export plan.yaml
guestkit passport emit vm.qcow2 --target kvm -o passport.json
guestctl tui vm.qcow2           # Assurance · preview · export
guestkit-qemu plan vm.qcow2 --json   # assurance → QEMU definition

CI 门禁 — 得分相同，无需安装 CLI：

- uses: zyvorai/guestkit@v1
  with:
    disk: vm.qcow2
    target: kvm
    fail-below: '80'

目标平台：kvm · proxmox · qemu · kubevirt · aws · azure · gcp · hyperv。主机要求：Linux，且需安装 qemu-img、losetup 和 qemu-nbd（挂载/修复可能需要 root 权限）。

Python（v1.1.0+），可在 PyPI 获取：运行 pip install zyvor-guestkit，然后调用 guestkit.run_doctor("vm.qcow2", target="kvm", explain=True)。完整的快速入门、缩小镜像和 Python 示例请见：docs/quick-start.md。

MCP 服务 — guestkit mcp-serve <image> [--target kvm] 是一个 stdio MCP 服务，针对单个磁盘映像提供六个只读证据工具。使用 cargo build --release --features mcp 构建。注册表名称为 io.github.zyvorai/guestkit；OCI 镜像为 ghcr.io/zyvorai/guestkit-mcp。打开磁盘需要 loop/NBD，因此容器必须以 root 身份并使用 --privileged 运行（或使用 SYS_ADMIN 和相应设备），尽管其默认用户为 nonroot。请参阅 docs/guides/MCP.md 和 DOCKER.md。

---

文档

目标	文档
文档站点	zyvorai.github.io/zyvor-guestkit
文档主页	docs/README.md · INDEX
DevOps 运行手册	docs/devops
功能指南	guestkit-user-feature-guide.md
h2kvm 集成	h2kvm 集成
QEMU / VirtIO 运行时	qemu-runtime.md
导出 virsh → GuestKit	virsh-to-guestkit.md
架构	概览

完整索引以及更新日志和路线图请见 docs/documentation-map.md。

深入了解

• **图库：**控制台截图和演示视频 — docs/gallery.md。
• **分工说明：**套件划分以及 libvirt/virsh 索引 — docs/who-does-what.md。
• h2kvm 集成：docs/h2kvm-at-a-glance.md。
• **可执行的操作：**验证、规划、认证、修复、启动 — docs/capabilities.md。
• 免费 Web 套件（GHCR）：docs/web-stack-ghcr.md。
• 开源版与 Enterprise 版：docs/oss-vs-enterprise.md。
• 平台布局：docs/platform-layout.md。
• 代码库：docs/repository-layout.md。
• 前置条件和构建：docs/prerequisites-and-build.md；docs/ 和此 README 为权威信息源。

开源版与企业版

开源版 — 基于 Apache-2.0 协议免费使用。 本仓库适用于个人、实验室和商业生产环境。提供完整的离线 doctor、迁移计划、修复、集群、策略 · CLI · TUI · Python · 可自托管的 Web 界面/工作进程。

企业版 — 面向项目付费。 使用相同的引擎 — 不是锁定版 doctor。Command Center · Portfolio · Assurance · Migration Factory · Passport Authority · OIDC / RBAC / 审计 · SLA · 空气隔离 · 虚拟机监控程序迁出研讨会。

开源版与企业版对比 · 完整功能矩阵 · 30 天企业版试用 · 定价

试用已过期或想要有人指导评估？ 预约演示 或 开始 30 天 PoC — 无需提供电子邮件。[email protected] 仍可作为备用联系方式。

---

成熟度

GuestKit 当前为 v1.2.6（GitHub Release；PyPI zyvor-guestkit；crates.io 上的 guestkit 仍为 0.3.2）。架构概述明确说明了引擎的适用范围：

领域	状态
纯 Rust 解析：分区表、文件系统签名、证据架构、启动引擎、保证 API	已发布
Web UI（deploy/ui：清单、Assurance、Profiles、Files）、GHCR zyvor-ui	已发布
进程内读取 QCOW2	部分支持：格式检测和选择性读取；完整集群遍历交由 qemu-nbd 完成
访问来宾系统中的文件	通过 loop 设备 / qemu-nbd 和主机挂载实现，而非使用进程内 ext4/NTFS 解析器
guestkit shrink	有意限制适用范围：仅支持单个/最后一个 ext2/3/4 分区、MBR 或 GPT，不支持 LVM/LUKS；其他布局会报告但不会修改
GHCR Web 技术栈（deploy/docker-compose.ghcr.yml）	仅用于评估：未启用身份验证，请勿暴露到 localhost 之外
来宾 Agent 的 eBPF 策略和 LSM	选择启用：受 capabilities.ebpf 控制，默认关闭

---

Zyvor 技术栈的一部分

产品	在 GuestKit 周边扮演的角色
GuestKit	离线 VM 保证：启动评分、修复、Cutover Passport
Transiva	将 VM 从源虚拟机监控程序导出，位于 GuestKit 上游
h2kvm	转换并部署到 KVM；使用 GuestKit Python 包进行离线修复
Zorvia	用于运行迁移后 VM 的 KubeVirt VM 平台
FluxVM	运行和管理 VM；生产运行、网络和 TTL 在该平台中管理，而非在 guestkit vm 中

→ zyvor.dev

---

支持

基于 Apache-2.0 协议免费使用。如果它对你有帮助，你可以捐赠任意金额：https://rzp.io/rzp/utwdYh3。捐赠完全自愿，用于支持开发和维护。捐赠不是购买：不包含任何支持服务、SLA、功能、优先权或许可证，也不可抵税（Zyvor AI Labs Private Limited 是一家企业，而非慈善机构）。Zyvor 企业版（受支持的版本、SLA、专属联系人和企业功能）另行提供：[email protected]。

许可证

GuestKit 基于 Apache License, Version 2.0，免费且开源。您可以免费将其用于个人、实验室和商业生产环境，也可以修改和运行，但须遵守 Apache-2.0 条款（在要求的情况下保留声明和 NOTICE）。如适用，请参阅 NOTICE 和 docs/legal/。这一点不会改变。

Zyvor Enterprise 提供生产团队所需的服务：受支持的版本、部署和升级指导、优先事件分类处理、专属技术联系人，以及全天候的严重问题受理。生产支持、SLA 和 Zyvor Enterprise 产品需单独授权。方案和条款：docs/SUBSCRIPTION-MODEL.md · 定价 · [email protected]。

请按照 SECURITY.md 的说明私下报告漏洞。更多信息：zyvor.dev/guestkit · 文档 · 博客。

---