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

> 本文介绍如何在宝塔面板（BT Panel）Linux 宿主机中安装并使用 KVM 虚拟机管理器，覆盖环境初始化、ISO 镜像、网络与存储、虚拟机生命周期、模板、备份、VNC 控制台及故障诊断，适用于需要在单机上部署和维护虚拟化资源的运维人员。

原文：[宝塔面板 KVM 虚拟机管理器使用教程](https://docs.bt.cn/practical-tutorials/kvm-virtual-machine-manager)

文档范围：宝塔面板及相关产品（当前文档）。生成时间：2026-09-22。

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

| 项目         | 说明                        |
| ---------- | ------------------------- |
| 适用插件       | KVM 虚拟机管理器（`kvm_manager`） |
| 文档对应版本     | `1.0.0`                   |
| 适用范围       | 宝塔面板所在的单台 Linux 宿主机       |
| libvirt 连接 | 本机 `qemu:///system`       |

> **说明：版本说明**
>
> 插件功能可能随版本更新而变化。如果本文与当前插件页面不一致，请以插件页面显示为准。

## 使用前须知

### 支持的宿主机系统

- 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。

### 重要目录

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

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

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

## 安装插件

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

![在宝塔面板软件商店搜索并安装 KVM 虚拟机管理器](https://docs.bt.cn/img/practical-tutorials/kvm-manager/install-plugin.png)

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

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

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

## 首次安装与初始化

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

### 检测虚拟化环境

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

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

![KVM 虚拟机管理器首次安装时的环境检测结果](https://docs.bt.cn/img/practical-tutorials/kvm-manager/environment-check.png)

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

### 安装 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 访问的权限。

> **警告：存储目录要求**
>
> 不要将 `/`、`/www`、`/var`、`/home`、`/usr`、`/etc`、`/root` 或 `/tmp` 等范围过大的目录直接作为插件存储根目录。应使用 `/www/kvm` 这类专用目录。

## 页面导航与概览

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

![KVM 虚拟机管理器概览页显示宿主机和虚拟化资源状态](https://docs.bt.cn/img/practical-tutorials/kvm-manager/overview.png)

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

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

## 管理 ISO 镜像

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

### 通过浏览器上传

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

![通过浏览器向 KVM 虚拟机管理器上传 ISO 镜像](https://docs.bt.cn/img/practical-tutorials/kvm-manager/iso-upload.png)

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

### 从宿主机本地路径导入

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

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

![从宿主机本地路径选择并导入 ISO 镜像](https://docs.bt.cn/img/practical-tutorials/kvm-manager/iso-local-import.png)

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

### 通过 URL 下载

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

![填写 ISO 镜像下载地址和可选 SHA256 校验值](https://docs.bt.cn/img/practical-tutorials/kvm-manager/iso-url-download.png)

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

> **警告：私网下载安全风险**
>
> 在【系统设置】中启用【允许 URL 下载访问私网地址】后，插件会允许访问私有镜像源，同时允许使用不受信任或自签名的 HTTPS 证书。此选项存在 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。
- 是否立即启动。
- 是否自动启动。

![在 KVM 虚拟机管理器中创建自定义 NAT 网络](https://docs.bt.cn/img/practical-tutorials/kvm-manager/create-nat-network.png)

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

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

### macvtap 同网直连

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

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

### 使用已有 Linux 网桥

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

## 管理存储池与存储卷

### 添加目录型存储池

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

![在存储与备份页面添加目录型存储池](https://docs.bt.cn/img/practical-tutorials/kvm-manager/add-storage-pool.png)

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

### 启动和停止存储池

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

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

### 查看存储卷

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

![查看目录型存储池中的虚拟磁盘卷和引用对象](https://docs.bt.cn/img/practical-tutorials/kvm-manager/storage-volumes.png)

### 取消定义存储池

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

以下情况不可取消定义：

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

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

## 创建虚拟机

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

### 使用 ISO 创建

#### 选择系统

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

![选择 ISO 镜像并填写虚拟机名称和操作系统类型](https://docs.bt.cn/img/practical-tutorials/kvm-manager/create-vm-system.png)

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

#### 配置资源

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

- 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。
- 启动顺序：硬盘和光驱。
- 是否随宿主机自动启动。
- 是否在创建后自动启动。

![为新虚拟机选择快捷规格并配置 CPU 内存磁盘和网络](https://docs.bt.cn/img/practical-tutorials/kvm-manager/create-vm-resources.png)

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

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

#### 容量预检并确认创建

提交前，插件会检查：

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

![创建虚拟机前的资源容量预检和配置确认](https://docs.bt.cn/img/practical-tutorials/kvm-manager/create-vm-precheck.png)

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

### 从模板创建

模板创建模式需要选择：

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

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

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

## 管理虚拟机生命周期

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

![KVM 虚拟机列表和启动关机等生命周期操作入口](https://docs.bt.cn/img/practical-tutorials/kvm-manager/vm-list.png)

### 搜索和筛选

- 按名称、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 个字符。

> **警告：运行中快照的一致性**
>
> 创建、恢复和删除快照不强制要求关机。运行中快照不会自动执行 guest agent 文件系统冻结，因此应按崩溃一致性理解。数据库等业务建议先在客体系统内停止写入，或自行执行一致性处理。

### 设置

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

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

### VNC 控制台

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

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

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

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

## 管理虚拟机模板

### 制作模板

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

![从已关机虚拟机制作 KVM 虚拟机模板](https://docs.bt.cn/img/practical-tutorials/kvm-manager/create-template.png)

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

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

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

### 删除模板

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

## 备份与恢复

### 创建备份

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

![选择来源虚拟机和目标存储池创建虚拟机备份](https://docs.bt.cn/img/practical-tutorials/kvm-manager/create-backup.png)

| 虚拟机状态 | 备份方式                                       | 一致性   |
| ----- | ------------------------------------------ | ----- |
| 关机    | 使用 `qemu-img convert` 复制全部磁盘               | 离线一致性 |
| 运行或暂停 | 使用 libvirt `backup-begin` 复制全部文件型 qcow2 磁盘 | 崩溃一致性 |

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

### 恢复备份

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

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

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

### 删除备份

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

## 查看任务记录

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

![KVM 虚拟机管理器后台任务列表和执行状态](https://docs.bt.cn/img/practical-tutorials/kvm-manager/task-list.png)

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

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

![查看虚拟机模板制作失败的任务日志](https://docs.bt.cn/img/practical-tutorials/kvm-manager/task-failure-log.png)

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

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

## 系统设置与环境诊断

### 基础设置

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

![KVM 虚拟机管理器基础设置和 VNC 下载安全配置](https://docs.bt.cn/img/practical-tutorials/kvm-manager/system-settings.png)

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

### VNC 与下载安全

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

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

### 环境诊断

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

![KVM 虚拟机管理器完整环境诊断结果](https://docs.bt.cn/img/practical-tutorials/kvm-manager/environment-diagnostics.png)

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

## 卸载插件与清空数据

### 仅卸载插件

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

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

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

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

### 清空虚拟化数据与环境

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

> **危险：不可恢复的高风险操作**
>
> 清空操作会主动删除虚拟机和安全范围内的数据，并卸载 KVM/libvirt 环境。执行前必须停止其他任务、核对预检列表并完成外部备份。

![清空虚拟化数据与环境前的资源预检和二次确认](https://docs.bt.cn/img/practical-tutorials/kvm-manager/clear-virtualization-data.png)

#### 停止其他任务

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

#### 查看清理预检

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

- 将删除的全部 `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 面板桥接。更新插件文件后如果桥接仍未加载，可以重启宝塔面板。

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

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

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

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

## 相关文档

- [宝塔面板快速安装教程](https://docs.bt.cn/getting-started/quick-installation-of-bt-panel.md)
- [在宝塔面板软件商店安装应用](https://docs.bt.cn/user-guide/soft/install.md)
- [在宝塔面板软件商店卸载应用](https://docs.bt.cn/user-guide/soft/uninstall.md)