宝塔面板 KVM 虚拟机管理器使用教程

本文介绍如何在 宝塔面板（BT Panel） Linux 宿主机中安装、初始化和使用 KVM 虚拟机管理器。完成配置后，可以在单台服务器上集中管理 ISO 镜像、虚拟网络、存储池、虚拟机、模板、快照与备份，并通过 VNC 控制台安装和维护客体系统。

使用前须知

支持的宿主机系统

• Debian 12 及以上版本，包括 Debian 13。
• Ubuntu 22.04 及以上版本，包括 Ubuntu 24.04。
• 宿主机需要能够使用 apt-get 安装软件包。

KVM 与 TCG 的区别

• 当宿主机存在可用的 /dev/kvm，且 libvirt 确认支持 KVM 时，插件使用 KVM 硬件加速。
• 没有可用的 /dev/kvm 时，插件使用 TCG 软件模拟。
• TCG 可以创建和运行虚拟机，但性能明显低于 KVM，尤其是在系统安装、磁盘操作和高负载场景中。

插件不会自动修改的配置

环境安装不会自动修改宿主机物理网卡、IP 地址、默认路由或现有 Linux 网桥，也不会自动创建物理桥接网络。插件可以使用已经存在的 Linux 网桥，也可以使用 libvirt NAT 网络或 macvtap。

重要目录

插件初始化目录存储池后，会在存储根目录中使用以下子目录：

iso/         ISO 安装镜像
disks/       虚拟机 qcow2 磁盘
templates/   虚拟机模板及其元数据
backups/     虚拟机备份

默认建议将 /www/kvm 作为存储根目录。插件配置、任务、锁和临时会话保存在 /www/server/panel/data/kvm_manager。

安装插件

1. 登录宝塔面板，进入【软件商店】。
2. 搜索“KVM 虚拟机管理器”。
3. 找到插件后，点击【安装】。

插件安装脚本只执行以下操作：

1. 安装插件代码。
2. 创建插件数据、任务、锁、上传和 VNC 会话目录。
3. 安装宝塔面板的 VNC WebSocket 转发类。

此时不会自动安装 QEMU、libvirt，不会创建虚拟机，也不会修改宿主机网络。安装完成后打开插件，进入【安装与初始化】向导。

首次安装与初始化

首次向导依次包含【环境检测】、【安装确认】、【安装进度】和【存储初始化】四步。

检测虚拟化环境

打开插件后，先检查以下项目：

• 操作系统是否受支持。
• /dev/kvm 是否可用。
• 当前使用 KVM 还是 TCG。
• QEMU、libvirt 和管理命令是否已经安装。
• 默认存储是否已经初始化。

如果环境已经完整安装，向导会直接进入存储初始化；如果环境和存储均已完成，则直接进入插件主页。

安装 KVM 环境

点击【下一步】，勾选安装确认后开始安装。插件会安装以下软件包：

• qemu-system-x86
• qemu-utils
• libvirt-daemon-system
• libvirt-clients
• virtinst
• libguestfs-tools
• genisoimage
• cpu-checker
• dnsmasq-base
• bridge-utils
• ovmf
• libosinfo-bin

如果安装前检测到 APT 光盘源，插件会先创建 .kvm_manager.bak 备份，再禁用光盘源，避免 apt-get update 因 cdrom:// 源失败。

随后插件会：

1. 执行 apt-get update。
2. 安装缺失的软件包。
3. 启用 libvirtd.service，或启用模块化的 virtqemud、virtnetworkd、virtstoraged socket。
4. 检查 qemu:///system 连接。
5. 在缺少 default 网络时创建默认 libvirt NAT 网络，并设置为立即启动和自动启动。

查看安装进度

环境安装由后台任务执行，关闭插件窗口不会中断任务。安装页会显示任务 ID、状态、当前步骤和进度。

如果安装失败：

1. 在安装页查看任务日志。
2. 或进入【任务记录】，筛选【安装环境】和【执行失败】。
3. 根据日志处理 APT 源、磁盘空间、软件包冲突或 libvirt 服务问题后重新安装。

初始化存储

环境安装成功后必须初始化默认存储，可选择使用现有存储池或创建新的目录存储池。

使用现有存储池

1. 选择【使用现有目录存储池】。
2. 从列表中选择一个具有目录目标的存储池。
3. 如果存储池处于停止状态，插件会尝试启动它。
4. 点击【完成初始化】。

创建新存储池

1. 选择【创建目录存储池】。
2. 输入存储池名称，例如 kvm。
3. 输入专用绝对路径，例如 /www/kvm。
4. 点击【完成初始化】。

新建目录池会被启动并设置为随宿主机自动启动。存储根目录和相关子目录会设置为可供 libvirt 访问的权限。

页面导航与概览

插件包含【概览】、【虚拟机】、【镜像管理】、【网络管理】、【存储与备份】、【任务记录】和【系统设置】页面。

【概览】页用于查看宿主机和虚拟化环境的整体状态，包括：

• CPU 使用率、逻辑 CPU 数量和负载。
• 宿主机内存使用情况。
• 默认存储根目录的磁盘容量和占用。
• 宿主机网络累计收发量及前端采样曲线。
• KVM 或 TCG 状态。
• 虚拟机总数、运行数、关机数和资源分配量。
• 最近任务。

管理 ISO 镜像

当前【镜像管理】页只管理 ISO，不包含云镜像和 cloud-init。

通过浏览器上传

1. 点击【上传镜像】。
2. 选择 .iso 文件。

页面会显示上传字节数、分片数、进度和速度。已有同名文件时会上传失败。

从宿主机本地路径导入

【本地路径导入】适用于 ISO 已经位于宿主机上的场景。

1. 点击【从本地路径导入】。
2. 选择需要导入的 .iso 文件。

导入操作会复制文件，不会移动或删除原文件。符号链接和非普通文件会被拒绝；已有同名文件时会导入失败。

通过 URL 下载

1. 点击【URL 下载】。
2. 输入 HTTP 或 HTTPS 地址。
3. 设置目标文件名、同名处理策略和可选的 SHA256。
4. 提交后，在镜像下载任务或【任务记录】中查看进度。

默认情况下，插件禁止下载回环、链路本地、私网和保留地址，也禁止 URL 凭据和非 HTTP/HTTPS 协议。下载时会固定解析后的 IP，并重新校验重定向目标，以降低 DNS 重绑定和 SSRF 风险。

校验和删除 ISO

• SHA256 校验：执行校验后，结果会保存为同目录的校验信息，列表状态变为【已校验】。如果填写预期 SHA256，只有完全一致才算成功。
• 删除 ISO：删除会同时移除 ISO、SHA256 信息和来源元数据。删除前应确认没有虚拟机正在挂载该 ISO；删除操作不会自动替虚拟机卸载光驱。

管理虚拟网络

libvirt NAT 网络

默认的 default NAT 网络适合大多数场景。虚拟机可通过宿主机 NAT 访问外网，地址通常由 libvirt DHCP 分配。

在【网络管理】页可以启动、停止网络，以及启用或关闭自动启动。停止仍被虚拟机使用的网络，会导致对应虚拟机网络不可用。

创建自定义 NAT 网络

点击【创建 NAT 网络】，填写以下参数：

• 网络名称。
• IPv4 CIDR，例如 192.168.100.0/24。
• 网关，例如 192.168.100.1。
• DHCP 起始和结束地址。
• 是否启用 DHCP。
• 是否立即启动。
• 是否自动启动。

插件会拒绝与宿主机地址、现有 libvirt 网络重叠的网段，也会拒绝包含网关的 DHCP 范围。只有通过插件创建并登记的 NAT 网络可以在页面中删除。

删除网络前，应确认没有虚拟机继续引用该网络。删除网络不会移除虚拟机网卡配置，但虚拟机之后可能无法启动网络或获取地址。

macvtap 同网直连

选择 macvtap 后，虚拟机网卡使用物理接口的 direct/bridge 模式。虚拟机能否从同一局域网的 DHCP 获取地址，取决于上游交换机、路由器或运营商是否允许多个 MAC 地址。

macvtap 的常见限制是虚拟机可以访问局域网中的其他设备，但通常不能通过该网卡直接访问宿主机本身。

使用已有 Linux 网桥

插件只显示并使用宿主机已经存在的 Linux 网桥，不会自动创建网桥、迁移宿主机 IP 或改写物理网卡配置。选择网桥前，应先在宿主机侧确认网桥、成员接口、IP 和默认路由配置正确。

管理存储池与存储卷

添加目录型存储池

在【存储与备份】页面的【存储池】页签中点击【添加存储池】，输入名称和专用目录。创建后，存储池会自动启动并启用自动启动。

目录池是插件完整支持的写入目标。其他类型的 libvirt 存储池可以显示，但不作为插件创建磁盘、模板和备份的完整支持路径。

启动和停止存储池

• 【启动】使停止的存储池重新可用。
• 【停止】执行 libvirt 的池停止操作，不会删除目录或数据。

停止默认存储池后，创建虚拟机、添加磁盘、制作模板和备份等操作会失败。

查看存储卷

点击【存储卷】，可以查看卷的虚拟容量、实际占用和引用对象。

取消定义存储池

取消定义时，插件会先尝试停止存储池，再执行 virsh pool-undefine。该操作只删除 libvirt 中的存储池定义，不删除池目录和目录中的文件。

以下情况不可取消定义：

• 当前存储池是插件默认存储池。
• 存储池被虚拟机磁盘引用。
• 存储池被模板、备份或链接克隆引用。
• 存储池被尚未结束的相关任务引用。

如果只是暂时不使用存储池，应优先选择【停止】，不要取消定义。

创建虚拟机

点击【虚拟机】页面中的【创建虚拟机】，创建流程分为【选择系统】、【配置资源】和【确认创建】三步。

使用 ISO 创建

选择系统

填写虚拟机名称，选择 ISO 安装镜像和操作系统类型。操作系统类型支持 Debian 12/13、Ubuntu 22.04/24.04 或其他 Linux。

虚拟机名称必须以英文字母开头，只允许字母、数字、下划线、点和短横线。插件会检查同名虚拟机及目标磁盘文件冲突。

配置资源

可以选择快捷规格，也可以手动配置：

• vCPU：1 至 512。
• 内存：256 MB 至 1048576 MB。
• 系统盘：1 GB 至 65536 GB。
• 数据盘：最多 15 块，每块可选择目录存储池和 VirtIO/SATA 总线。
• 网络：libvirt 网络、macvtap 或已有 Linux 网桥。
• 固件：BIOS 或 UEFI。
• CPU 模式：host-passthrough 或 host-model。
• 系统盘总线：VirtIO 或 SATA。
• 网卡型号：VirtIO 或 e1000。
• 启动顺序：硬盘和光驱。
• 是否随宿主机自动启动。
• 是否在创建后自动启动。

默认启动顺序为“硬盘、光驱”。空系统盘首次启动时会继续尝试 ISO；系统安装完成后则优先从硬盘启动。如果手动设置为“光驱、硬盘”，安装完成后应卸载 ISO 或将硬盘调整为第一启动项，否则再次开机可能重新进入安装界面。

如果不勾选【创建后自动启动】，插件会在创建后停止虚拟机，并将所选 ISO 和启动顺序重新写入持久化配置。之后手动启动时仍可从 ISO 安装。

容量预检并确认创建

提交前，插件会检查：

• 名称和磁盘文件是否冲突。
• ISO 是否存在。
• 存储池是否运行且可写。
• 每个存储池的可用空间。
• 网络来源是否存在。
• CPU、内存、磁盘和硬件参数是否合法。

CPU 和内存超配只显示警告；磁盘空间不足、名称冲突或网络无效会阻止创建。确认后会生成后台任务，可在【任务记录】中查看完整进度和失败日志。

从模板创建

模板创建模式需要选择：

• 新虚拟机名称。
• 模板。
• 目标目录存储池。
• 完整克隆或链接克隆。
• 网络。
• 是否创建后启动、是否随宿主机启动。

CPU、内存、全部磁盘、磁盘总线、BIOS/UEFI 和启动配置从模板继承，不能在创建请求中覆盖。

完整克隆占用更多空间，但创建后的虚拟机不再依赖模板磁盘。链接克隆创建更快、占用更少，但必须保留父模板；存在链接克隆时不能删除模板。

管理虚拟机生命周期

【虚拟机】页支持搜索、筛选、分页、自动刷新，以及单台或批量生命周期操作。

搜索和筛选

• 按名称、UUID 或已经获取的 IP 搜索。
• 按运行状态筛选。
• 按网络筛选，默认显示全部网络。
• 使用分页和自动刷新。

插件会依次尝试从 guest agent、libvirt DHCP/lease 和 ARP 等来源获取 IP。虚拟机没有 guest agent、没有 DHCP 租约或网络不可见时，IP 可能显示为未获取到。

单台操作

• 启动：启动已关机虚拟机。
• 正常关机：向虚拟机发送 ACPI 关机请求。客体系统响应较慢时，状态不会立即变为关机；系统安装完成前关机可能失效，失效时可使用强制停止。
• 强制停止：相当于立即断电，可能造成客体文件系统损坏。
• 重启：请求客体正常重启。
• 克隆：要求源虚拟机完全关机，并执行完整磁盘克隆。
• 删除：要求虚拟机完全关机，并输入虚拟机名称确认。

删除时可以选择是否同时删除磁盘。选择删除磁盘时，只会删除插件能够确认的受管 qcow2 文件；不选择时仅删除虚拟机定义，磁盘文件会保留。

批量操作

列表支持批量启动、批量关机和批量删除。批量删除只处理已关机虚拟机，并逐台执行删除。失败项会单独显示，不会因一台失败而将其他操作错误标记为全部成功。

任务锁

同一虚拟机同时只能执行一个写任务。创建模板、备份、克隆或其他写任务运行期间，冲突操作会被拒绝。例如，虚拟机正在制作模板时不能启动。

查看和调整虚拟机详情

虚拟机详情抽屉包含【概况】、【监控】、【磁盘】、【快照】和【设置】等功能。

概况

可以查看 UUID、状态、运行时间、IP、vCPU、内存、固件、CPU 模式、系统盘容量与实际占用、网卡类型、网络来源、网卡型号、MAC，以及经过凭据脱敏的 libvirt XML。

资源监控

运行中的虚拟机每 5 秒采样一次，前端保留最近 30 个点：

• CPU：根据 domstats cpu.time 累计值差计算。
• 内存：只使用新鲜有效的 libvirt balloon available/usable 数据。
• 磁盘：根据块设备累计读写字节计算速率。
• 网络：根据网卡累计收发字节计算速率。

如果客体不支持 balloon 统计、数据陈旧或数值无效，内存会显示“暂不可用”。插件不会使用 QEMU RSS、配置内存或估算值代替真实内存占用。

磁盘管理

添加、扩容和分离磁盘都要求虚拟机完全关机。

• 添加数据盘：选择容量、目录存储池和 VirtIO/SATA 总线。每台虚拟机最多有 15 块数据盘。
• 扩容：只能扩容，不能缩小。扩容 qcow2 后，仍需进入客体系统扩展分区和文件系统；宿主机扩容不会自动扩大客体文件系统。
• 分离：系统盘不能分离。分离数据盘时，可以选择仅从虚拟机配置中分离，或同时删除插件能够确认的受管磁盘文件，并输入设备名确认。

快照

快照支持运行中、暂停和关机状态，也支持多个受管 qcow2 磁盘。所有相关磁盘必须位于目录存储池的 disks/ 目录中。创建时使用原子快照参数，任意磁盘不满足要求时会拒绝整个操作。

可以创建、恢复和删除快照，快照描述不能超过 200 个字符。

设置

• 自动启动可以单独修改。
• 修改 vCPU 和内存要求关机。
• 修改网络类型、网络来源、网卡型号和 MAC 要求关机。
• 修改启动顺序以及挂载或卸载 ISO 要求关机。

网络修改通过受控字段生成 XML，不支持提交任意 XML。保存失败时，插件会尝试恢复原始定义。

VNC 控制台

虚拟机必须处于运行状态并具有 VNC 图形设备。

1. 打开虚拟机详情。
2. 点击 VNC 控制台入口。
3. 插件创建一次性临时令牌，并通过宝塔登录态建立 WebSocket 通道。
4. 页面连接宿主机本地 127.0.0.1 上的虚拟机 VNC 端口。

临时令牌约 90 秒有效，并且只能消费一次；连接建立后可持续使用到主动断开。插件不会将 VNC 端口直接暴露到公网，也不设置或管理 VNC 密码。

如果网页控制台不可用，先在【系统设置】→【查看完整诊断】中检查 VNC 面板桥接文件。必要时重启宝塔面板，使 WebSocket 类重新加载。

管理虚拟机模板

制作模板

在【存储与备份】→【模板】中点击【从虚拟机制作模板】，选择源虚拟机、模板名称和目标目录存储池。

源虚拟机需要满足以下要求：

• 必须完全关机。
• 至少有一块磁盘，最多为一块系统盘加 15 块数据盘。
• 所有磁盘必须是文件型 qcow2。
• 所有磁盘必须位于某个目录存储池的 disks/ 目录中。
• 磁盘总线必须是 VirtIO、SATA、SCSI 或 IDE。

插件会复制全部磁盘，对副本执行 virt-sysprep，再压缩生成模板。源虚拟机和源磁盘不会被 virt-sysprep 修改。

删除模板

删除模板会删除模板元数据和全部模板磁盘。存在链接克隆依赖时会拒绝删除，包括通过插件元数据或实际 qcow2 backing chain 检测到的依赖。

备份与恢复

创建备份

在【存储与备份】→【备份】中选择来源虚拟机，可填写备份名称并选择目标目录存储池。

备份会保存虚拟机 XML、全部磁盘和元数据。运行中备份不会自动冻结客体文件系统和应用，重要数据库业务应自行安排应用一致性措施。

恢复备份

页面恢复操作要求输入新的虚拟机名称。恢复始终创建新虚拟机，不覆盖原虚拟机。恢复时插件会：

• 将备份磁盘转换为新的 qcow2 文件。
• 删除原 UUID，让 libvirt 生成新 UUID。
• 删除原 MAC，让 libvirt 生成新 MAC。
• 将 VNC 重置为本地监听和自动端口。
• 将新虚拟机定义为关机状态。

页面操作默认恢复到当前默认存储池，并保留备份 XML 中的网络来源。恢复前，应确认对应的 libvirt 网络或 Linux 网桥仍然存在。

删除备份

删除备份会删除完整备份目录，包括 XML、元数据和全部备份磁盘，不影响原虚拟机和已经从该备份恢复出的新虚拟机。

查看任务记录

安装环境、创建或克隆虚拟机、下载或导入或校验 ISO、制作模板、创建或恢复备份，以及清空虚拟化数据与环境等操作均通过后台任务执行。

任务页支持按类型、状态筛选和分页，并显示操作对象、任务状态、进度、当前步骤、开始时间、耗时、任务日志和失败原因。

点击失败任务的【查看原因】，可以检查完整错误和执行日志。

运行中或等待中的任务可以取消。只有失败或已取消的创建虚拟机、克隆、下载、导入、校验、备份、恢复和模板任务可以重新执行；环境安装和清理任务不能通过通用重试按钮重试。

默认最多同时执行两个重任务，下载和校验并发数可以在【系统设置】中调整为 1 至 3。同一虚拟机的写任务仍受独立锁限制。

系统设置与环境诊断

基础设置

【系统设置】页可以设置默认目录存储池、默认网络模式和网络来源、默认 CPU 模式、默认磁盘总线、创建后是否自动启动，以及是否随宿主机自动启动。

磁盘格式固定为 qcow2，页面只读显示，不支持创建 raw 磁盘。

VNC 与下载安全

• VNC 临时连接有效期固定为 90 秒。
• VNC 最大并发连接数可设置为 1 至 5。
• 最大并发下载数可设置为 1 至 3。
• 可以设置任务日志保留天数。
• 可以选择是否允许 URL 下载访问私网地址。

“VNC 使用宝塔登录态建立临时通道”是固定安全能力，不会直接开放公网端口。

环境诊断

点击【查看完整诊断】，可以检查操作系统和软件包、QEMU、libvirt、系统命令、libvirt 服务和连接、/dev/kvm 与加速模式、默认 NAT 网络、默认存储池与目录权限，以及 VNC 面板桥接条件。

诊断内容可用于复制和排查环境问题，其中的敏感信息会进行脱敏。

卸载插件与清空数据

仅卸载插件

在宝塔面板卸载插件时，卸载脚本会终止插件任务 Worker，并删除插件代码和面板 VNC WebSocket 类。

卸载插件不会执行以下操作：

• 卸载 QEMU/libvirt 套件。
• 删除虚拟机。
• 删除磁盘、ISO、模板或备份。
• 删除 libvirt 网络和存储池定义。
• 删除 /www/server/panel/data/kvm_manager 中的持久化数据。

因此，只卸载插件通常可以在重新安装后继续管理原有资源。

清空虚拟化数据与环境

真正的清空操作应在【系统设置】→【清空虚拟化数据与环境】中执行。

停止其他任务

先进入【任务记录】，确认没有等待或执行中的创建、下载、模板、备份等任务。

查看清理预检

点击【清理数据与环境】，插件会列出：

• 将删除的全部 qemu:///system 虚拟机。
• 可以安全确认的 qcow2 磁盘和 ISO。
• 模板和备份目录。
• 将取消定义的全部目录型存储池。
• 将卸载的 KVM/libvirt 软件包。
• 因风险过高而跳过的路径和资源。

务必核对列表并完成外部备份。

完成二次确认

1. 勾选【我已备份重要数据】。
2. 输入页面动态显示的确认短语。
3. 点击【执行】。

后台清理顺序

清理任务会按以下顺序执行：

1. 强制停止并取消定义全部 libvirt 虚拟机，同时清理 managed save、快照元数据和 NVRAM 定义。
2. 在安全目录范围内删除已经确认的 qcow2 磁盘和 ISO。
3. 删除受控的 templates/ 和 backups/ 目录。
4. 清理虚拟机元数据、上传临时文件和 VNC 临时会话。
5. 停止并取消定义全部目录型存储池。
6. 重置插件默认存储配置。
7. 停止 libvirt 服务，并通过 APT 卸载已经安装的 KVM/libvirt 相关套件。

清理时会主动跳过块设备磁盘、网络磁盘、非 qcow2 虚拟磁盘、符号链接、不在已确认目录存储池中的文件、过于宽泛的目录根路径、目录池中的未知文件和 libvirt 虚拟网络。

如果有任何虚拟机定义删除失败，清理会保留磁盘文件、存储池和 KVM/libvirt 环境，避免在虚拟机仍被引用时继续破坏性删除。失败和跳过原因可以在清理任务日志中查看。

清理完成后，插件代码仍然存在。再次打开插件会重新进入环境安装与存储初始化流程。如果不再需要插件，可在确认清理结果后再从宝塔面板卸载插件代码。

常见问题

系统安装完成后为什么又进入安装界面？

检查启动顺序是否为“光驱、硬盘”。建议改为“硬盘、光驱”，或者在系统安装完成后卸载 ISO。

为什么虚拟机无法显示真实内存占用？

真实内存依赖客体 balloon 统计。确认虚拟机使用 balloon 设备，并在客体系统中安装和启用相应驱动或 guest agent。没有有效数据时，插件会显示“暂不可用”。

为什么虚拟机获取不到 IP？

确认网络已经启动、DHCP 可用，并检查虚拟机内网卡配置。macvtap 还取决于上游网络是否允许多个 MAC 地址。没有 guest agent 或 DHCP 租约时，插件不保证能够识别 IP。

VNC 控制台为什么无法连接？

确认虚拟机正在运行、域 XML 中存在 VNC 图形设备，并检查环境诊断中的 VNC 面板桥接。更新插件文件后如果桥接仍未加载，可以重启宝塔面板。

为什么存储池无法取消定义？

先检查该存储池是否为默认池，或是否仍被虚拟机、模板、备份、链接克隆及任务引用。取消定义不会删除数据；如果需要保留定义但暂时停用，应选择【停止】。

运行中备份与关机备份有什么区别？

运行中备份属于崩溃一致性，类似突然断电后磁盘可恢复的状态；关机备份属于离线一致性，更适合数据库和重要业务。重要业务应优先安排关机备份，或在运行中备份前自行冻结应用写入。

相关文档

• 宝塔面板快速安装教程
• 在宝塔面板软件商店安装应用
• 在宝塔面板软件商店卸载应用