第 10 章 QEMU/KVM 虚拟机

10.QEMU/KVM 虚拟机 QEMU/KVM Virtual Machines

QEMU（Quick Emulator）是开源的 hypervisor ， 用于模拟一台物理计算机。在运行 QEMU 的主机看来 ， QEMU 只是一个普通用户程序 —— 它访问本地分区、文件、网卡等资源 ， 再把它们转交给被模拟的计算机 ， 使客户机将它们视为真实设备。

运行在被模拟计算机中的客户机操作系统访问这些设备 ， 就像运行在真实硬件上一样。例如把 ISO 作为参数传给 QEMU， 客户机便会看到光驱中插入了真实 CD-ROM。

QEMU 可模拟从 ARM 到 Sparc 等多种硬件 ， 但 Proxmox VE 仅关注 32/64 位 PC 克隆 —— 它们构成服务器硬件的绝大多数；且由于处理器扩展的存在（模拟架构与宿主架构相同时大幅加速）， PC 克隆的模拟也最快。

Proxmox VE 中的 QEMU 以 root 运行 ， 以便访问块设备与 PCI 设备。

10.1.模拟设备与半虚拟化设备 Emulated devices and paravirtualized devices

QEMU 模拟的 PC 硬件包括主板、网卡、 SCSI / IDE / SATA 控制器、串口等（完整清单见 kvm(1) 手册页）， 它们完全是现有硬件设备的软件等价物 —— 若客户机装有合适驱动 ， 就会把它们当真硬件使用 ， 这使 QEMU 能运行未经修改的操作系统。

但这会带来性能代价 —— 本该由硬件完成的工作改由软件模拟 ， 主机 CPU 要做大量额外工作。为此 ， QEMU 可向客户机提供 半虚拟化设备（paravirtualized devices）， 此时客户机明白自己在 QEMU 中运行并与 hypervisor 协作。

QEMU 基于 virtio 虚拟化标准 ， 可提供半虚拟化的通用磁盘控制器、网卡、串口、 SCSI 控制器等。

10.2.虚拟机设置 Virtual Machines Settings

总体上 ， Proxmox VE 为虚拟机（VM）选择了合理默认值。请在修改前充分理解各设置的含义 ， 以免拖慢性能或让数据面临风险。

10.2.1.通用设置 General Settings

VM 的通用设置包括：

• Node：VM 将运行的物理节点
• VM ID：本 Proxmox VE 安装中标识 VM 的唯一数字
• Name：用于描述 VM 的自由格式文本
• Resource Pool：VM 的逻辑分组

10.2.2.操作系统设置 OS Settings

创建 VM 时正确选择操作系统 ， Proxmox VE 便可据此优化一些底层参数。例如 Windows 期望 BIOS 时钟使用本地时间 ， Unix 系期望为 UTC。

10.2.3.系统设置 System Settings

创建 VM 时可调整一些基本系统组件 —— 例如使用的显示类型。 SCSI 控制器亦可更改。如计划安装 QEMU Guest Agent， 或所选 ISO 已自动安装它 ， 可勾选 QEMU Agent ， Proxmox VE 会据此提供更多信息、更智能地完成关机 / 快照等操作。

Proxmox VE 允许用不同固件与机器类型启动 VM —— SeaBIOS 与 OVMF。多数场景使用默认 SeaBIOS 即可；仅当您计划做 PCIe 直通等特殊用途时才切换到 OVMF。

机器类型（Machine Type）

VM 的 Machine Type 定义其虚拟主板硬件布局。可在默认 Intel 440FX 与 Q35 之间选择；后者提供虚拟 PCIe 总线 ， 适合需要 PCIe 直通的场景。此外还可选择 vIOMMU 实现。

机器版本（Machine Version）

每种机器类型在 QEMU 中都有版本号 ， 一个 QEMU 二进制支持多个版本。新版本可能带来新特性、修复或改进 ， 也会改变虚拟硬件属性。为避免客户机视角下的突变以及兼容 VM 状态、在线迁移与带 RAM 的快照 ， 复用已启动时的机器版本。

对 Windows 客户机 ， 机器版本在创建时 固化（Windows 即便冷启动对虚拟硬件变化也敏感 ， 例如不同版本下网卡枚举可能不同）。 Linux 等系统通常能适应这种变化 ， 默认为 Latest（冷启动时使用当前 QEMU 二进制支持的最新版本 ， 例如 QEMU 8.1 对各机器类型使用 8.1 版）。

机器版本还在实现新特性 / 修复时作为向后兼容保障。对运行中 VM 的操作（如在线迁移）会保存当前运行的机器版本 ， 确保恢复时 VM 不仅从 QEMU 虚拟化视角 ， 也从 Proxmox VE 构造 QEMU 实例的视角完全一致。

PVE 机器修订号（PVE Machine Revision）

有时 Proxmox VE 需在不等待新 QEMU 发布的情况下修改硬件布局或选项 —— 为此追加一个下游修订号 +pveX。每个新 QEMU 机器版本的 X 从 0 开始（0 时可省略）， 例如 pc-q35-9.2 等同于 pc-q35-9.2+pve0。若 Proxmox VE 需改动硬件布局或默认选项 ， 修订号递增 ， 用于新建客户机或在使用 Latest 版本的 VM 重启时生效。

QEMU 机器版本弃用策略

自 QEMU 10.1 起 ， 机器版本在上游 QEMU 中 6 年后移除。 Proxmox VE 约每 2 年一次大版本发布 ， 因此一个大版本通常支持约两个前代大版本的机器版本。

升级至新大版本前 ， 应先把 VM 配置中的机器版本避开下个大版本将移除的版本 ， 以保证整个生命周期客户机可用。见下文 「更新到新机器版本」。

弃用策略尚未在 Proxmox VE 8 中生效 ， 因此其机器版本基线仍为 2.4。 PVE 9 生命周期预计最后 QEMU 为 11.2， 将移除早于 6.0 的版本 —— 故 6.0 成为 PVE 9 的基线；此基线预计每个大版本递增约 2 个主版本（例如 PVE 10 为 8.0）。

更新到新机器版本

若看到弃用警告 ， 应切换至更新的机器版本。请先做好备份 ， 并对硬件变化有预期 ， 某些场景下可能需要重装驱动。还要检查使用这些版本做过的 带 RAM 快照（配置中的 runningmachine 条目）—— 快照的机器版本无法修改 ， 必须加载快照才能取出数据。

10.2.4.硬盘 Hard Disk

总线 / 控制器

QEMU 可模拟多种存储控制器：

• IDE：设计可追溯到 1984 年的 PC/AT ， 已被新设计取代 ； 但几乎所有 OS 都支持 ， 适合运行 2003 年之前发布的系统 ， 最多挂接 4 个设备。
• SATA（Serial ATA）：2003 年以来 ， 更现代的设计 ， 吞吐更高、可挂设备更多 ， 最多 6 个。
• SCSI：设计于 1985 年 ， 常见于服务器级硬件 ， 可挂 14 个设备。 Proxmox VE 默认模拟 LSI 53C895A。
• VirtIO SCSI single 控制器配合挂载磁盘的 IO Thread 选项是性能最佳方案 —— 自 Proxmox VE 7.3 起对新建 Linux VM 为默认。每块磁盘拥有独立 VirtIO SCSI 控制器 ， QEMU 在专用线程处理其 IO。 Linux 自 2012 年起支持 ， FreeBSD 自 2014 年起支持 ； Windows 需安装时提供包含驱动的额外 ISO。
• VirtIO Block（virtio-blk）：更早的半虚拟化控制器 ， 在功能上已被 VirtIO SCSI 取代。

镜像格式

每个控制器上挂载的模拟硬盘背后是所配置存储中的文件或块设备。存储类型决定硬盘镜像格式 —— 块设备类（LVM / ZFS / Ceph）要求 raw ； 基于文件的存储（Ext4 / XFS / NFS / CIFS）可任选 raw 或 QEMU image format：

• QEMU image format（qcow2）：写时复制 ， 支持快照与精简置备。
• Raw：磁盘的逐位镜像 ， 类似 Linux 上 dd 块设备。本身不支持精简置备或快照 ， 需存储层协作；但可能比 qcow2 快 10%。
• VMware：仅当您打算与其他 hypervisor 互导 / 互出镜像时使用。

缓存模式（Cache Mode）

硬盘缓存模式影响主机如何向客户机通告块写完成。默认 No cache 表示块到达物理存储的写队列时即通告完成（忽略主机 page cache）， 在安全与速度之间取得较好平衡。

若希望 Proxmox VE 备份时跳过某块磁盘 ， 可为其设置 No backup。若希望存储复制机制跳过某磁盘 ， 可设 Skip replication（Proxmox VE 5.0 起复制要求镜像在 zfspool 类型存储上 ， 若 VM 已配置复制而要把镜像放到其他存储 ， 则必须为该镜像跳过复制）。

Trim / Discard

若存储支持精简置备 ， 可为磁盘启用 Discard。配合启用 TRIM 的客户机 OS， 当 VM 文件系统在删除文件后将块标为未用时 ， 控制器会把信息上抛到存储层 ， 使镜像相应收缩。客户机发 TRIM 需启用本选项 ； 某些客户机 OS 还要求启用 SSD Emulation。 VirtIO Block 上的 Discard 仅在 Linux 内核 ≥ 5.0 的客户机上生效。

希望把磁盘以 SSD 呈现给客户机（而非机械盘）可启用 SSD Emulation， 不要求底层存储实际为 SSD。 VirtIO Block 不支持 SSD Emulation。

IO Thread

IO Thread 仅在使用 VirtIO 控制器、或使用 SCSI 控制器且模拟类型为 VirtIO SCSI single 时可用。启用后 ， QEMU 为每个存储控制器创建独立 I/O 线程 ， 而非在主事件循环或 vCPU 线程中处理所有 I/O —— 好处是更好的工作分发与底层存储利用率 ， 以及在极重 IO 场景下客户机延迟（卡顿）降低（主线程与 vCPU 线程均不会被磁盘 I/O 阻塞）。

10.2.5.CPU CPU

CPU socket 是主板上的物理插槽；一个 CPU 内可含一个或多个 core（独立处理单元）。从性能角度看 ， 「1 Socket × 4 Cores」与 「2 Sockets × 2 Cores」几乎无差别；但某些软件授权依赖 socket 数 —— 此时应把 socket 数设为授权允许值。

增加虚拟 CPU（核与插槽）通常提升性能 ， 但严重依赖 VM 的负载 ， 多线程应用自然受益最大 —— QEMU 为每个 vCPU 在主机创建新线程。不确定负载时 ， 把 Total cores 设为 2 通常是安全起步。

资源限制

cpulimit

除了虚拟核数外 ， 可用 cpulimit 设定 VM 能消耗的「主机 CPU 时间」总量 —— 浮点值 ， 表示 CPU 时间百分比 ， 1.0 代表 100%， 2.5 代表 250%。单进程跑满一个核算 100% ； 4 核 VM 全跑满理论上 400%（实际可能稍高 ， 因为 QEMU 还有外设线程）。

适用场景 ：某 VM 运行多个并行进程 ， 希望有多个 vCPU ， 但整体不允许同时跑满。例如希望获益于 8 个 vCPU 但不想全部跑满（以免耽误其他 VM / 容器）， 可把 cpulimit=4.0（400%）：若 8 个 vCPU 并行用满 ， 每个 vCPU 最多获得 50% 物理核时间；若只用满 4 个 ， 每个 vCPU 仍可获得 100%， 共计 400%。

cpuunits

如今常称 CPU shares / CPU weight —— 控制 VM 相较其他运行中 VM 所获 CPU 时间的相对权重 ， 默认 100（若主机使用 cgroup v1 旧版 ， 则默认 1024）。值越高 ， 调度器越偏向此 VM。例如 VM 100 为默认 100、 VM 200 改为 200， 后者获得前者两倍的 CPU 带宽。详见 man systemd.resource-control（CPUQuota 对应 cpulimit， CPUWeight 对应 cpuunits）。

affinity

用 affinity 可指定 VM 的 vCPU 只运行于哪些物理核（VM 的外设 I/O 线程不受影响）。 affinity 不是安全机制。

强制 CPU 亲和在少数场景有意义 ， 但伴随复杂度与维护成本 —— 例如以后增 VM 或迁到核数更少的节点；还容易造成部分核满载、部分空闲的异步瓶颈。格式通过 taskset CLI 工具设定 ， 接受主机 CPU 编号（见 lscpu）的 List Format（man cpuset）， 可用数字或区间 ， 如 0-1,8-11（展开为 0,1,8,9,10,11）。

CPU 类型

QEMU 可模拟多种 CPU 类型 ， 从 486 到最新 Xeon —— 每代新处理器带来新特性（硬件加速 3D、 RNG、内存保护等）， 同代也可通过 microcode 更新修复 bug 或安全问题。

通常选与主机 CPU 最接近的类型 ， 以便主机的 CPU flags 可在 VM 中可用。若要完全一致 ， 可设 host —— VM 获得与主机完全相同的 flags。

缺点 ：如需在不同主机间在线迁移 ， VM 可能落到不同 CPU 或不同微码版本的节点；若客户机期望的 flag 不存在 ， QEMU 进程会停止。为此 QEMU 提供虚拟 CPU 类型 ， Proxmox VE 默认使用它们。

后端默认 kvm64 —— 在几乎所有 x86_64 主机上都能跑；新建 VM 的 UI 默认 x86-64-v2-AES —— 要求 Intel 自 Westmere 起、 AMD 自第四代 Opteron 起。

简言之：

• 不关心在线迁移或集群同构（同 CPU 同微码）：设 host ， 理论最佳性能。
• 关心在线迁移与安全 ， 且全 Intel 或全 AMD：选集群中最低代的 CPU 型号。
• 关心在线迁移但不介意安全 ， 或 Intel/AMD 混合：选最低兼容的虚拟 QEMU 类型。

QEMU CPU 类型

QEMU 也提供与 Intel / AMD 主机 CPU 均兼容的虚拟类型。

历史上 Proxmox VE 的 kvm64 仅启用 Pentium 4 级别 flags， 某些负载性能不佳。 2020 年 AMD / Intel / Red Hat / SUSE 协作定义了 x86-64 baseline 之上的 3 个微架构级别 ， 启用更现代的 flags（详见 x86-64-ABI 规范）。 CentOS 9 等较新发行版以 x86-64-v2 为最低要求。

• kvm64（x86-64-v1）：Intel ≥ Pentium 4、 AMD ≥ Phenom 兼容。
• x86-64-v2：Intel ≥ Nehalem、 AMD ≥ Opteron_G3。相对 v1 增加 +cx16 +lahf-lm +popcnt +pni +sse4.1 +sse4.2 +ssse3。
• x86-64-v2-AES：Intel ≥ Westmere、 AMD ≥ Opteron_G4。相对 v2 增加 +aes。
• x86-64-v3：Intel ≥ Haswell、 AMD ≥ EPYC。相对 v2-AES 增加 +avx +avx2 +bmi1 +bmi2 +f16c +fma +movbe +xsave。
• x86-64-v4：Intel ≥ Skylake、 AMD ≥ EPYC v4 Genoa。相对 v3 增加 +avx512f +avx512bw +avx512cd +avx512dq +avx512vl。

自定义 CPU 类型

可指定带自定义特性集的 CPU 类型 ， 由管理员在 /etc/pve/virtual-guest/cpu-models.conf 维护。格式详见 man cpu-models.conf。拥有 /nodes 上 Sys.Audit 权限的用户可选用；通过 CLI / API 配置时 ， 名称需加前缀 custom-。

Meltdown / Spectre 相关 CPU flags

与 Meltdown、 Spectre 漏洞相关的 CPU flags 若未被所选 CPU 类型默认启用 ， 需手动开启。启用这些 flag 的两个前提：

• 主机 CPU 必须支持该特性并将其向客户机 vCPU 暴露；
• 客户机 OS 需已更新到能缓解并利用该 CPU 特性的版本。

否则需手动设置虚拟 CPU 的 flag —— Web UI 中编辑 CPU 选项 ， 或在 VM 配置的 cpu 属性中设 flags。 Spectre v1/v2/v4 修复同样需要 CPU / 系统厂商提供 「microcode 更新」， 见「固件更新」章节；部分受影响 CPU 可能无法更新到支持 spec-ctrl。

检查主机漏洞状态：

for f in /sys/devices/system/cpu/vulnerabilities/*; do echo "${f##*/} -" $(cat "$f"); done

Intel 处理器

pcid

减轻 Meltdown（CVE-2017-5754）缓解机制 KPTI（Kernel Page-Table Isolation）的性能损失 —— 无 PCID 时 KPTI 代价较高。检查：

# grep ' pcid ' /proc/cpuinfo

有输出即主机 CPU 支持 pcid。

spec-ctrl

修复 Spectre v1（CVE-2017-5753）与 v2（CVE-2017-5715）所需（当 retpoline 不足时）。带 -IBRS 后缀的 Intel 型号默认包含；无 -IBRS 后缀需显式启用。需更新主机微码（intel-microcode ≥ 20180425）。

ssbd

修复 Spectre v4（CVE-2018-3639）所需。所有 Intel 型号均 不默认 包含 ， 必须显式启用。需 intel-microcode ≥ 20180703。

AMD 处理器

ibpb

修复 Spectre v1/v2 所需（当 retpoline 不足时）。带 -IBPB 后缀型号默认包含；否则需显式启用 ， 并需主机 CPU 微码支持。

virt-ssbd

修复 Spectre v4 所需 ， 所有 AMD 型号均 不默认 包含 ， 必须显式启用。即便提供了 amd-ssbd 也应一并暴露此项以最大化客户机兼容性。使用 host CPU 模型时也必须显式启用 —— 这是物理 CPU 不存在的虚拟特性。

amd-ssbd

修复 Spectre v4 的更高性能实现 ， 主机支持时应尽量暴露；但仍建议同时暴露 virt-ssbd， 因为有些内核仅识别后者。

amd-no-ssb

指示主机 不 受 Spectre v4 影响 ， 未来硬件将不受影响 ， 暴露此 flag 通知客户机无需启用缓解。与 virt-ssbd 和 amd-ssbd 互斥。

NUMA

可选地为 VM 模拟 NUMA 架构 ——NUMA 将内存按「就近 socket」分块 ， 避免全局内存池成为瓶颈。若 numactl --hardware | grep available 返回多节点 ， 主机即 NUMA 架构 ， 建议启用以便正确分布 VM 资源；CPU 或内存热插拔也需要它。使用 NUMA 时 ， 建议把 socket 数设为主机 NUMA 节点数。

vCPU 热插拔

现代 OS 支持在运行系统中热插拔（以及在一定程度上热拔出）CPU。虚拟化屏蔽了真实硬件的许多问题 ， 但该特性仍相对新颖复杂 ， 应限于确有必要的场景 —— 大部分功能可用更成熟的 资源限制 替代。

Proxmox VE 中最大可插 CPU 数始终为 cores × sockets。若希望 VM 启动时不插满 ， 用 vcpus 指定启动时插入的 vCPU 数。目前仅在 Linux 上支持 —— 需内核 > 3.10， 建议 > 4.7。可用下列 udev 规则自动上线新加 CPU：

SUBSYSTEM=="cpu", ACTION=="add", TEST=="online", ATTR{online}=="0", ATTR{online}="1"

保存到 /etc/udev/rules.d/ 下 .rules 结尾的文件。 注意 ：热移除依赖机器类型与客户机配合 —— 删除命令只是请求 ， 不保证 CPU 真正被移除（x86/amd64 上通常走 ACPI）。

10.2.6.内存 Memory

可为每台 VM 设置固定内存 ， 或让 Proxmox VE 根据主机当前 RAM 使用情况动态分配。

固定内存分配

将 memory 与 minimum memory 设为相同值时 ， Proxmox VE 将按指定量直接分配给 VM。即便使用固定内存 ， 仍会添加 balloon 设备 —— 它提供客户机实际内存占用等有用信息。一般建议保留 balloon， 如需禁用（例如调试）取消勾选 Ballooning Device 或在配置中设置：

balloon: 0

自动内存分配

当 minimum memory 低于 memory 时 ， Proxmox VE 保证总能把最小量提供给 VM；若主机 RAM 使用低于目标百分比 ， 则动态把内存加到客户机直至 maximum memory。目标百分比默认 80% ， 可在节点选项中配置。

主机 RAM 紧张时 VM 会释放内存回主机 ， 需要时换出运行中进程 ， 最终启动 OOM killer。客户机内部由特殊 balloon 内核驱动负责在主机 / 客户机之间移交内存页。

多台 VM 使用自动分配时 ， 可通过 Shares 系数指定各 VM 获取空闲内存的相对比例。例如 4 台 VM ：3 台 HTTP、 1 台数据库 ， 主机 32 GB 内存 ， 目标 80% ， 当前用 16 GB —— 可分配 32 × 0.8 - 16 = 9 GB。把数据库 VM 的 Shares 设 3000， 其余保持默认 1000， 数据库 VM 获得 9 × 3000 / 6000 = 4.5 GB， 其他每台 HTTP 获 1.5 GB。

2010 年之后发布的 Linux 发行版都内建 balloon 内核驱动。 Windows 需手动加装 ， 可能引起客户机变慢 ， 不建议在关键系统上用。分配内存的经验 ： 始终给主机留 1 GB。

10.2.7.内存加密 Memory Encryption

AMD SEV

SEV（Secure Encrypted Virtualization）基于 AES-128 与 AMD Secure Processor 为 VM 启用内存加密。 SEV-ES（Encrypted State）进一步加密所有 CPU 寄存器内容 ， 防止信息泄露至 hypervisor。 SEV-SNP（Secure Nested Paging）还尝试阻止基于软件的完整性攻击。详见 AMD SEV SNP 白皮书。

主机要求：

• AMD EPYC CPU
• SEV-ES 仅支持 AMD EPYC 7002 及更新 EPYC
• SEV-SNP 仅支持 AMD EPYC 7003 及更新 EPYC
• SEV-SNP 需主机内核 ≥ 6.11
• 在 BIOS 中启用 AMD 内存加密
• 若默认未启用 ， 在内核参数追加 kvm_amd.sev=1
• 若要对主机内存本身加密（SME）， 内核参数加 mem_encrypt=on
• 可能需要增大 SWIOTLB

检查主机 SEV 启用情况：

# dmesg | grep -i sev
[...] ccp 0000:45:00.1: sev enabled
[...] ccp 0000:45:00.1: SEV API:<N.N> build:<N>
[...] SEV supported: <N> ASIDs
[...] SEV-ES supported: <N> ASIDs
# cat /sys/module/kvm_amd/parameters/sev
Y

客户机要求：edk2-OVMF、建议使用 Q35、客户机 OS 需含 SEV 支持。

限制：由于内存加密 ， 主机视角内存用量不准；涉及保存 / 恢复内存的操作（快照、在线迁移）暂不可用或有被攻击风险；不支持 PCI 直通； SEV-ES / SEV-SNP 仍非常实验性； SEV-SNP 不支持 EFI 盘； SEV-SNP 下 VM 内 reboot 仅会关机。

配置示例（SEV）：

# qm set <vmid> -amd-sev type=std,no-debug=1,no-key-sharing=1,kernel-hashes=1

type 定义加密技术（可选 std、 es、 snp）。 QEMU policy 参数由 no-debug、 no-key-sharing 计算（对应 policy-bit 0/1）； type=es 时 policy-bit 2=1 启用 SEV-ES； policy-bit 3（nosend）始终为 1 防迁移攻击。 kernel-hashes 默认关闭 ， 以兼容旧 OVMF / 不测量内核的客户机。

在 VM 中验证 SEV：

# dmesg | grep -i sev
AMD Memory Encryption Features active: SEV

# apt install msr-tools
# modprobe msr
# rdmsr -a 0xc0010131
1

配置示例（SEV-SNP）：

# qm set <vmid> -amd-sev type=snp,allow-smt=1,no-debug=1,kernel-hashes=1

allow-smt 默认置位；若设为 0， 主机必须关闭 SMT 才能启动该 VM。验证：

# dmesg | grep -i snp
Memory Encryption Features active: AMD SEV SEV-ES SEV-SNP
SEV: Using SNP CPUID table, 29 entries present.
SEV: SNP guest platform device initialized.

10.2.8.网络设备 Network Device

每个 VM 可有多个网卡 ， 共 4 种类型：

• Intel E1000：默认 ， 模拟 Intel 千兆网卡。
• VirtIO 半虚拟化网卡 ：追求极致性能首选 ， 需客户机 OS 安装驱动。
• Realtek 8139：模拟旧式 100 MB/s 网卡 ， 仅用于 2002 年前的老系统。
• vmxnet3：另一种半虚拟化设备 ， 仅在从其他 hypervisor 导入 VM 时使用。

Proxmox VE 会为每个 NIC 生成随机 MAC 地址。 NIC 有两种连接模型：

• Bridged（默认）：每个虚拟 NIC 在主机上由 tap 设备支撑 ， 加入到 bridge（PVE 默认 vmbr0）， VM 可直接访问主机所在以太局域网。
• NAT：虚拟 NIC 仅与 QEMU 用户态网络栈通信 ， 其内置 router 与 DHCP 服务器（10.0.2.0/24）提供访问。比 bridged 慢得多 ， 只宜测试。仅 CLI / API 可配 ， Web UI 不可见。

也可选 No network device 跳过。 VirtIO 网卡可手动覆盖 MTU（留空或 mtu=1 继承所在 bridge）。

Multiqueue

使用 VirtIO 驱动时可选启用 Multiqueue， 让客户机用多 vCPU 处理网络包。启用后 Proxmox VE 将 NIC 每个网络队列交给主机内核 ， 由 vhost 驱动派生的线程处理 ， 从而把多个队列送入主机内核。

推荐把 Multiqueue 设为客户机 vCPU 数（= sockets × cores）。同时在 VM 内 VirtIO NIC 上设 ethtool：

ethtool -L ens1 combined X

X 为 vCPU 数。 Windows 客户机需安装 Red Hat VirtIO 以太网驱动 ， 在设备管理器 → 网卡属性 → 高级 → Receive Side Scaling 启用 ， 并把 Maximum number of RSS Queues 设为 vCPU 数。

注意 ：Multiqueue > 1 会随流量增加提升主机与客户机 CPU 开销。建议仅在 VM 需处理大量传入连接（如路由器、反向代理、长轮询 HTTP 服务器）时启用。

10.2.9.显示 Display

QEMU 可虚拟几种 VGA 硬件：

• std（默认）：带 Bochs VBE 扩展的显卡。
• cirrus：模拟非常老的硬件 ， 问题较多 —— 除非迫不得已（如 Windows XP 及更早）不要用。
• vmware：兼容 VMware SVGA-II。
• qxl：QXL 半虚拟化显卡 ， 同时为 VM 启用 SPICE（远程查看协议）。
• virtio-gl（常称 VirGL）：虚拟 3D GPU， 可把工作负载卸载到主机 GPU， 无需昂贵专用型号与驱动 ， 也不独占主机 GPU ， 可与多客户机 / 主机共享。

可通过 memory 选项调整给虚拟 GPU 的显存 ， 有助于在 SPICE/QXL 中提高分辨率。多显示器（如 SPICE 的 qxl2）会按显示器数倍增显存；Windows 需要每个显示器一个设备。选择 serialX 作为显示类型会禁用 VGA 输出 ， 把 Web Console 重定向到所选串口 ， 此时 memory 被忽略。

VNC 剪贴板

把 clipboard 设为 vnc 以启用 VNC 剪贴板：

# qm set <vmid> -vga <displaytype>,clipboard=vnc

使用前须在客户机安装 SPICE guest tools —— Debian 系 spice-vdagent。安装后 ， 在 noVNC 控制台即可用剪贴板。使用 SPICE / virtio / virgl 时需选择使用何种剪贴板 —— 设 clipboard=vnc 后 ， 默认 SPICE 剪贴板会被 VNC 剪贴板替代。

10.2.10.USB 直通 USB Passthrough

有两种 USB 直通：

• Host USB passthrough
• SPICE USB passthrough

Host USB passthrough 把主机某 USB 设备交给 VM， 可通过 vendor/product-id（形如 0123:abcd）或 host bus/port（形如 1-2.3.4）识别。 VM 启动时设备若不在主机上 ， VM 也能正常启动；当设备 / 端口在主机上出现时会被直通。

SPICE USB 直通 为 VM 添加一个或多个 SPICE USB 端口 ， 可从 SPICE 客户端动态把本地 USB 设备直通给 VM —— 适合临时重定向输入设备或硬件狗。

还可在集群级别做设备映射 ， 以便与 HA 搭配、检测硬件变化并允许非 root 用户配置 —— 详见 §10.12 资源映射。

10.2.11.BIOS 与 UEFI BIOS and UEFI

为正确模拟计算机 ， QEMU 需要固件 —— 即 PC 上常见的 BIOS 或 (U)EFI， 在 VM 启动时作为最早步骤之一执行 ， 负责基础硬件初始化并为 OS 提供固件 / 硬件接口。 QEMU 默认使用 SeaBIOS（开源 x86 BIOS 实现）， 对多数标准场景足够。

某些 OS（如 Windows 11）需要 UEFI 兼容实现 ， 此时必须用 OVMF（开源 UEFI 实现）。在另一些场景（如 VGA 直通）SeaBIOS 也不理想。

使用 OVMF 需注意 ：为保存 boot order 等信息 ， 需一块 EFI Disk —— 会包含在备份 / 快照里 ， 且只能有一块：

# qm set <vmid> -efidisk0 <storage>:1,format=<format>,efitype=4m,pre-enrolled-keys=1

亦可在 Web UI 硬件区 Add → EFI Disk。 efitype 决定 OVMF 固件版本 —— 新 VM 应总用 4m（支持 Secure Boot ， 预留更多空间 ， Web UI 默认）。 pre-enroll-keys 决定是否预装发行版与 Microsoft Standard Secure Boot 密钥 ， 也会默认启用 Secure Boot（仍可在 VM 内 OVMF 菜单关闭）。

OVMF 配合虚拟显示（无 VGA 直通）时 ， 需在 OVMF 菜单中设置客户端分辨率（启动时按 ESC）， 或选 SPICE 显示类型。 OVMF PXE 启动要求为 VM 加 RNG 设备 —— 出于安全 ， OVMF 对无 RNG 的客户机禁用 PXE 启动。

10.2.12.可信平台模块（TPM） Trusted Platform Module (TPM)

TPM 安全地保存密钥等机密 ， 并为系统启动提供防篡改校验功能。某些 OS（如 Windows 11）要求机器（物理或虚拟）挂载 TPM。

通过指定 tpmstate 卷添加 TPM ， 类似 efidisk —— 创建后只能删除 ， 不能改动：

# qm set <vmid> -tpmstate0 <storage>:1,version=<version>

<version> 为 v1.2 或 v2.0。 Web UI 中 Add → TPM State。 v2.0 规范更新、更受支持 ， 除非有明确需求否则优先选 v2.0。

10.2.13.VM 间共享内存 Inter-VM shared memory

可添加 Inter-VM shared memory 设备（ivshmem）， 在主机与客户机之间、或多个客户机之间共享内存：

# qm set <vmid> -ivshmem size=32,name=foo

size 单位 MiB。文件位于 /dev/shm/pve-shm-$name（默认名为 vmid）。

典型用途 ：Looking Glass 项目 —— 实现主机与客户机间高性能、低延迟的显示镜像。

10.2.14.音频设备 Audio Device

qm set <vmid> -audio0 device=<device>

支持的音频设备：

• ich9-intel-hda：Intel HD Audio Controller， 模拟 ICH9。
• intel-hda：Intel HD Audio Controller， 模拟 ICH6。
• AC97：Audio Codec '97， 适合 Windows XP 等老系统。

两种后端 ：spice（配合 SPICE 使用）与 none（VM 内某软件必须有音频设备存在才能工作时有用）。要使用主机物理音频设备请走设备直通（PCI / USB）；远程协议（如 RDP）也带声音选项。

10.2.15.VirtIO RNG VirtIO RNG

RNG（随机数生成器）为系统提供熵。虚拟硬件 RNG 可把主机的熵注入客户机 ， 避免其熵饥荒（尤其启动过程中）：

qm set <vmid> -rng0 source=<source>[,max_bytes=X,period=Y]

source 取值：

• /dev/urandom（首选）：非阻塞的内核熵池。
• /dev/random（不推荐）：阻塞内核池 ， 可能导致主机熵饥荒。
• /dev/hwrng：直通主机硬件 RNG（多个时使用 /sys/devices/virtual/misc/hw_random/rng_current 所选那个）。

通过 max_bytes 与 period（毫秒）限速 —— 表示「每 period 毫秒最多 max_bytes 字节」， 但非线性关系 ：1024B/1000ms 意为 1 秒定时器刷出最多 1 KiB， 并不是 1 KiB 被均匀流式注入。缩短 period 可加快注入。默认 1024 B / 1000 ms（≈ 1 KiB/s）， 建议始终开启限速；需要时 max_bytes=0 可禁用限制。

10.2.16.Virtiofs Virtiofs

Virtiofs 是面向虚拟化环境的共享文件系统 —— 将主机上的目录树挂载到 VM 内 ， 不走网络栈 ， 力求与源文件系统相近的性能与语义。使用需后台运行 virtiofsd， Proxmox VE 在启动带 virtiofs 挂载的 VM 时自动拉起它。内核 ≥ 5.4 的 Linux VM 默认含 virtiofs 模块 ， 但部分功能需更新内核。需要在 PVE 主机安装：

apt install virtiofsd

Windows VM 使用 virtiofs 可参考官方指南。

已知限制

• virtiofsd 崩溃时 ， VM 内挂载点会卡住 ， 直到 VM 完全停止。
• virtiofsd 无响应会造成挂载卡死（类似不可达的 NFS）。
• 内存热插拔与 virtiofs 不兼容（同样会挂死）。
• 与内存相关的特性（在线迁移、快照、休眠）在有 virtiofs 的 VM 上 均不可用。
• Windows 无法理解 virtiofs 上下文的 ACL —— 不要对 Windows VM 暴露 ACL， 否则 VM 内看不到 virtiofs 设备。

为共享目录添加映射

参照 §10.12 资源映射 ， 可直接用 pvesh：

pvesh create /cluster/mapping/dir --id dir1 \
    --map node=node1,path=/path/to/share1 \
    --map node=node2,path=/path/to/share2 \

为 VM 添加 virtiofs

在 VM 配置添加 virtiofsN（N 为 0–9）， 值使用资源映射中配置的 dirid。可选 cache：always、 never、 metadata、 auto（默认）。 virtiofsd 支持 ACL 与 xattr 透传 ， 分别通过 expose-acl 与 expose-xattr 启用（要求底层与客户机文件系统均兼容 —— 多数 Linux FS 支持 ACL， Windows 不支持）。 expose-acl=1 隐式 expose-xattr=1。若希望 virtiofs 尊重 O_DIRECT， 设 direct-io=1（默认 0）—— 性能下降 ， 但应用有自己缓存时有用：

qm set <vmid> -virtiofs0 dirid=<id>,cache=always,direct-io=1
qm set <vmid> -virtiofs1 <id>,cache=never,expose-xattr=1
qm set <vmid> -virtiofs2 <id>,expose-acl=1

VM 内临时挂载（Linux）：

mount -t virtiofs <mount tag> <mount point>

持久化可写 fstab：

<mount tag> <mount point> virtiofs rw,relatime 0 0

节点上路径对应的 dirid 也是挂载标签（客户机内使用的名）。

10.2.17.设备启动顺序 Device Boot Order

QEMU 可告知客户机从哪些设备启动、以什么顺序。配置中的 boot 属性例如：

boot: order=scsi0;net0;hostpci0

客户机先试 scsi0 盘；失败则尝试从 net0 网络启动；再失败尝试直通 PCIe 设备（NVMe 视为磁盘 ， 否则尝试装入其 option ROM）。 Web UI 可拖拽排序 ， 勾选框决定某设备是否参与启动。

未在列表中或未勾选的设备 ， 在客户机 OS 启动并初始化之后仍可使用 ——bootable 标志 只 影响客户机 BIOS 与 bootloader。

10.2.18.虚拟机自动启停 Automatic Start and Shutdown of Virtual Machines

创建 VM 后若希望主机启动时自动开机 ， 在 VM Options 面板勾 Start at boot， 或：

# qm set <vmid> -onboot 1

启停顺序

• Start/Shutdown order：定义启动顺序优先级 —— 1 最先。关机顺序与启动顺序相反 ， 即 1 最后关机。同一主机上顺序相同的 VM 再按 VMID 升序。
• Startup delay：本 VM 启动后 ， 等待多少秒再启动后续 VM， 如 240 等待 4 分钟。
• Shutdown timeout：下发关机命令后等待 VM 离线的秒数 ， 默认 180 ； 超时仍在线则强制停止。

未设置 Start/Shutdown order 的机器始终晚于已设置者。该参数仅在同一主机内生效 ， 不跨集群。若需要在主机启动后延迟启动首个 VM， 参见「Proxmox VE 节点管理」。

10.2.19.QEMU Guest Agent QEMU Guest Agent

QEMU Guest Agent（QGA）是在 VM 内运行的服务 ， 提供主机 ↔ 客户机的通信通道 ， 用于交换信息并允许主机向客户机下发命令。例如 VM 摘要面板的 IP 地址即通过 QGA 获取；启动备份时 QGA 调用 fs-freeze、 fs-thaw 同步未落盘写。

正常工作需两件事 ：客户机内安装并运行 agent ； 在 Proxmox VE 中启用与 agent 的通信。

安装 Guest Agent

多数 Linux 发行版的包名为 qemu-guest-agent。 Windows 可从 Fedora VirtIO driver ISO 安装。

启用 Guest Agent 通信

在 VM Options 面板启用与 agent 的通信 ， 需 VM 冷启动方能生效。

基于 QGA 的自动 TRIM

启用 Run guest-trim 后 ， Proxmox VE 将在以下可能向存储写零的操作后向客户机下发 trim：

• 把磁盘移到其他存储
• 在线迁移到使用本地存储的节点

这能帮助精简置备存储回收空间。

文件系统 Freeze & Thaw

若 VM 中启用了 QGA 且 agent 可用 ， 在以下操作时会通过 fs-freeze 同步客户机文件系统以保证一致性：

• 快照模式备份
• 运行中 VM 的克隆
• 运行中 VM 的复制
• 对运行中 VM 做不带 RAM 的快照

Windows 客户机的某些应用（如挂 VSS 的 SQL Server）可能被 fs-freeze 干扰 —— 例如触发 SQL Writer VSS 模块以破坏 SQL Server 差异备份链。处理方式有二：

1. 让 QGA 使用不会干扰其他 VSS 用户的 VSS 变体 —— 详见 PVE Wiki。
2. 把 QGA 选项 freeze-fs-on-backup 设为 0 ， 不做 freeze/thaw —— GUI 中 「备份时冻结 / 解冻客户机文件系统以保证一致性」。

故障排除

VM 无法关机：确保 guest agent 已安装并运行。启用 agent 后 ， Proxmox VE 通过它发 shutdown 等电源命令 ； agent 未运行时 ， 命令无法执行 ， shutdown 会超时。

10.2.20.SPICE 增强 SPICE Enhancements

可提升 SPICE 远程查看体验的可选特性。 GUI 中在 VM Options 面板启用 ， 或 CLI：

qm set <vmid> -spice_enhancements foldersharing=1,videostreaming=all

文件夹共享

把本地文件夹共享给客户机。客户机内需安装 spice-webdavd 守护进程 —— 它把共享目录通过本地 WebDAV（http://localhost:9843）提供。 Windows 的安装包可从 SPICE 官网下载；多数 Linux 发行版提供 spice-webdavd 包。在 Virt-Viewer 中 File → Preferences 选择目录并勾选启用。

视频流

把快速刷新区域编码为视频流。两种模式：

• all：任何快速刷新区域都编码为视频流。
• filter：额外过滤决定是否使用视频流（当前仅跳过小窗口表面）。

是否启用、选哪个模式没有一刀切的建议 —— 视具体场景而定。

故障排除

共享目录未出现：确认客户机内的 WebDAV 服务已启用并运行 —— Windows 服务名 Spice webdav proxy ， Linux 通常为 spice-webdavd（发行版可能不同）。检查方法 ：在客户机浏览器访问 http://localhost:9843。重启 SPICE 会话也可能有用。

10.3.迁移 Migration

在集群中可把 VM 迁移到其他主机：

# qm migrate <vmid> <target>

两种机制 ：在线迁移（Live Migration） 与 离线迁移。

10.3.1.在线迁移 Online Migration

若 VM 在运行且未配置本地绑定资源（如直通设备）， 可在 qm migration 加 --online 触发在线迁移 ， Web UI 在 VM 运行时默认即在线迁移。

原理

目标主机先以 incoming 标志启动新的 QEMU 进程 ， 仅做基础初始化 ， 客户机 vCPU 保持暂停 ， 等待源 VM 的内存与设备状态流。其他资源（如磁盘）要么共享要么已先传 ， 运行态迁移只剩内存与设备状态。

连接建立后 ， 源异步把内存送到目标；若源上客户机内存变更 ， 相应段标为脏并再传一轮。循环直到源 / 目标间差异少到几毫秒内可传完 —— 此时源 VM 被完全暂停 ， 用户 / 程序几乎察觉不到；剩余数据发完后取消目标 VM CPU 暂停 ， 在 1 秒内完成切换。

要求

• VM 无不可迁移的本地资源（PCI / USB 直通当前阻止在线迁移 ， 但本地盘可通过传送给目标来迁移）。
• 主机在同一 Proxmox VE 集群。
• 主机间有可靠网络连接。
• 目标主机的 Proxmox VE 包版本必须 ≥ 源；反向有时可行 ， 但不保证。
• 主机 CPU 同厂商、能力相近。不同厂商视机型与 VM CPU 类型可能可行 ， 但不保证 —— 上线前请测试。

conntrack 状态迁移

conntrack 是 Linux 内核跟踪单个连接、实现有状态防火墙的机制。在线迁移后 ， 目标节点若没有同样的 conntrack 条目 ， 防火墙会丢包 ， 中断活动连接。 conntrack 状态迁移会把被迁 VM 的所有 conntrack 条目复制到目标 ， 并刷出源节点对应条目。

10.3.2.离线迁移 Offline Migration

即便有本地资源 ， 只要所有盘都在两端都定义了的存储上 ， 仍可离线迁移 —— 通过网络把磁盘复制到目标。注意硬件直通配置可能需要根据目标主机设备位置调整。

10.4.拷贝与克隆 Copies and Clones

VM 安装通常借助 OS 厂商的安装介质完成 —— 视 OS 可能耗时。批量部署同类 VM 的便捷做法是拷贝现有 VM， 这类拷贝称为 克隆（clone）， 分 完整克隆 与 链接克隆：

Full Clone（完整克隆）

结果是一台与原 VM 不共享任何存储资源的独立 VM。可选 Target Storage 迁到不同存储；若存储驱动支持多格式 ， 还可更改镜像格式。完整克隆需读并拷贝全部镜像数据 ， 通常显著慢于链接克隆。某些存储允许拷贝指定 Snapshot（默认为当前数据）， 最终副本不包含源 VM 的其他快照。

Linked Clone（链接克隆）

现代存储驱动支持快速链接克隆 —— 可写副本 ， 初始内容与原数据相同 ， 创建几乎瞬时 ， 初始零额外空间。之所以「链接」：未改块从原镜像读 ； 改动写入新位置（Copy-on-write）。要求原卷只读 ——Proxmox VE 可把任意 VM 转为只读的 Template ， 之后由模板高效生成链接克隆。 只要还有链接克隆存在 ， 原模板就不能删除。 链接克隆不能换目标存储（存储内部特性）。

Target node 可指定在其他节点创建新 VM， 但要求 VM 在共享存储上且目标节点也能访问该存储。为避免资源冲突 ， 所有 NIC 的 MAC 会被随机化 ， BIOS（smbios1）UUID 会生成新值。

10.5.虚拟机模板 Virtual Machine Templates

VM 可转换为只读的 模板， 用于生成链接克隆。 模板不能启动 ， 否则会修改盘镜像；要改模板 ， 先做链接克隆再改。

10.6.VM Generation ID VM Generation ID

Proxmox VE 为 VM 支持 Virtual Machine Generation ID（vmgenid）， 供客户机 OS 检测任何造成「时间回跳」的事件（如恢复备份、回滚快照）。

新建 VM 时自动生成 vmgenid 并存入配置。为已有 VM 追加：传特殊值 1 让 Proxmox VE 自动生成 ， 或手动指定 UUID：

# qm set VMID -vmgenid 1
# qm set VMID -vmgenid 00000000-0000-0000-0000-000000000000

极少数不希望此机制的场景可在创建时传 0， 或事后删除：

# qm set VMID -delete vmgenid

最典型使用场景是较新 Microsoft Windows —— 在回滚快照、备份恢复、整机克隆时避免时间敏感 / 复制类服务（如数据库、域控）出现问题。

10.7.导入虚拟机 Importing Virtual Machines

从异构 hypervisor 或其他 Proxmox VE 集群导入 VM 有多种方式 ， 常见：

• 原生导入向导（使用 import 内容类型 ， 如 ESXi 特殊存储提供）。
• 源端备份 + 目标端恢复 —— 最适合 PVE 之间迁移。
• qm 的 OVF 专用导入命令。

从其他 hypervisor 导入时 ， 建议先熟悉 Proxmox VE 的核心概念。

10.7.1.导入向导 Import Wizard

Proxmox VE 基于存储插件系统提供内置 VM 导入器 ， 原生集成到 API 与 Web UI —— 可把 VM 整体导入 ， 大部分配置映射到 PVE 配置模型 ， 停机时间缩到最低。

先在 Datacenter → Storage → Add 新建导入源存储 ， 然后在资源树选中该存储 ， 打开 Virtual Guests 内容页查看可导入的客户机。选中并点 Import（或双击）打开向导 ， 可在此修改部分选项后开始导入 ； 更高级的调整可在导入完成后再做。

OVA / OVF 导入

导入 OVA / OVF 需要启用 import 内容类型的文件型存储 —— 其下会有 import 目录 ， 把 OVA 文件或 OVF + 对应镜像平铺放入 ， 或用 Web UI 直接上传 / 下载 OVA ， 然后用 Web UI 选中并通过向导导入。

OVA 需要额外空间临时解压镜像 —— 需要启用 images 内容类型的文件型存储。默认选源存储 ； 可通过 Import Working Storage 指定解压存储 ， 再导入到真正的目标存储。

10.7.2.通过 CLI 导入 OVF / OVA Import OVF/OVA Through CLI

异构 hypervisor 的 VM 导出通常是若干磁盘镜像加一个配置文件 —— 从 VMware / VirtualBox 来可能是 vmdk， 从 KVM 来可能是 qcow2。最流行的配置格式是 OVF 标准 ， 但实践互通有限 ， 因为规范本身未定义许多设置 ， 各 hypervisor 以非标扩展导出补充信息。

此外 ， 从他处导入盘镜像时 ， 若模拟硬件差异过大可能失败 —— Windows 尤为敏感。可在导出前装 MergeIDE.zip ， 并在导入的 Windows VM 首次启动前选 IDE 硬盘类型来缓解。

半虚拟化驱动是各家私有的 —— GNU/Linux 与多数自由 Unix 默认自带 ， 导入后立即可切换 ； Windows VM 需自行安装半虚拟化驱动。通常 Linux / 自由 Unix 导入无忧 ， Windows 因上述原因不保证成功。

Windows OVF 导入分步示例

Microsoft 提供 Windows 开发用虚拟机下载 ， 可用来演示 OVF 导入。

1. 下载 VM 压缩包：同意条款后选 VMware 平台 「Windows 10 Enterprise（Evaluation Build）」下载。

2. 解压镜像：用 unzip 或其他解压工具解压 ， 通过 ssh / scp 把 ovf 与 vmdk 复制到 PVE 主机。

3. 导入 VM：按 OVF 清单的核数 / 内存 / 名称创建 VM， 并把盘导入 local-lvm。网络需手动配置：

# qm importovf 999 WinDev1709Eval.ovf local-lvm

VM 即可启动。

给现有 VM 追加外部盘镜像

可把外部（或自建）镜像加入 VM。例如用 vmdebootstrap 造 Debian/Ubuntu 镜像：

vmdebootstrap --verbose \
 --size 10GiB --serial-console \
 --grub --no-extlinux \
 --package openssh-server \
 --package avahi-daemon \
 --package qemu-guest-agent \
 --hostname vm600 --enable-dhcp \
 --customize=./copy_pub_ssh.sh \
 --sparse --image vm600.raw

然后新建目标 VM， 把镜像导入到 pvedir 并挂到 SCSI：

# qm create 600 --net0 virtio,bridge=vmbr0 --name vm600 --serial0 socket \
    --boot order=scsi0 --scsihw virtio-scsi-pci --ostype l26 \
    --scsi0 pvedir:0,import-from=/path/to/dir/vm600.raw

VM 即可启动。

10.8.Cloud-Init 支持 Cloud-Init Support

Cloud-Init 是处理 VM 实例早期初始化的事实标准多发行版包。借助它 ， 可在 hypervisor 侧配置网络与 SSH 密钥 ， VM 首次启动时由客户机内的 Cloud-Init 软件应用这些设置。

很多发行版提供开箱即用的 Cloud-Init 镜像（主要面向 OpenStack）， 在 Proxmox VE 上也能工作。但通常建议 自行制作镜像 —— 清楚装了什么 ， 方便后续定制。

制作好 Cloud-Init 镜像后 ， 建议转为 VM 模板 ， 以便快速生成链接克隆 —— 启动前只需配置网络（与 SSH 密钥）。

建议使用 SSH 密钥登录 ， 不推荐密码登录 —— 密码需以加密形式存进 Cloud-Init 数据。

Proxmox VE 生成 ISO 把 Cloud-Init 数据传入 VM ， 故 Cloud-Init VM 必须有一个光驱设备。通常还应加串口并作为显示（OpenStack 要求 ， 多数镜像依赖它）；若某些镜像与此不兼容 ， 切回默认显示即可。

10.8.1.准备 Cloud-Init 模板 Preparing Cloud-Init Templates

第一步是准备 VM —— 任意 VM 均可 ， 在 VM 里装 Cloud-Init。 Debian / Ubuntu：

apt-get install cloud-init

很多发行版直接提供 .qcow2 Cloud-Init 镜像 ， 也可直接下载并导入。以 Ubuntu 为例：

# download the image
wget https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img

# create a new VM with VirtIO SCSI controller
qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci

# import the downloaded disk to the local-lvm storage, attaching it as a SCSI drive
qm set 9000 --scsi0 local-lvm:0,import-from=/path/to/bionic-server-cloudimg-amd64.img

添加 Cloud-Init CD-ROM

qm set 9000 --ide2 local-lvm:cloudinit

设置直接从 Cloud-Init 盘启动（只从该盘引导加速启动）：

qm set 9000 --boot order=scsi0

多数 Cloud-Init 镜像要求串口作显示（不兼容时回退默认）：

qm set 9000 --serial0 socket --vga serial0

最后把 VM 转为模板：

qm template 9000

10.8.2.部署 Cloud-Init 模板 Deploying Cloud-Init Templates

qm clone 9000 123 --name ubuntu2

配置 SSH 公钥与 IP：

qm set 123 --sshkey ~/.ssh/id_rsa.pub
qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1

也可一条命令配置所有 Cloud-Init 选项 ， 这里拆开仅为减短行长。请根据环境调整 IP。

10.8.3.自定义 Cloud-Init 配置 Custom Cloud-Init Configuration

通过命令行 cicustom 用自定义配置文件替代自动生成：

qm set 9000 --cicustom "user=<volume>,network=<volume>,meta=<volume>"

自定义配置文件必须放在支持 snippets 的存储上 ， 并且 VM 将迁往的所有节点都能访问 ， 否则 VM 无法启动。例：

qm set 9000 --cicustom "user=local:snippets/userconfig.yaml"

Cloud-Init 有三类配置 ：user、 network、 meta， 可任意组合 ， 未指定的使用自动生成。可 dump 自动生成的作为基线：

qm cloudinit dump 9000 user

network 和 meta 同理。

10.8.4.Windows 上的 Cloud-Init Cloud-Init on Windows

Windows 有 Cloud-Init 的移植版 —— Cloudbase-Init。并非 Cloud-Init 所有特性都可用 ， 部分行为也与 Cloud-Init 不同。

Cloudbase-Init 需 ostype 设为任意 Windows 版本 ， 且 citype=configdrive2（Windows ostype 时默认）。

没有免费现成的 Windows 云镜像 —— 使用 Cloudbase-Init 需自行安装配置 Windows 客户机。

10.8.5.准备 Cloudbase-Init 模板 Preparing Cloudbase-Init Templates

先在 VM 里装 Windows ， 再下载安装 Cloudbase-Init（可能需要 Beta）。 安装末尾不要运行 Sysprep， 先配置 Cloudbase-Init。常设选项：

• username：设管理员用户名
• groups：把用户加入 Administrators 组
• inject_user_password=true：允许在 VM 配置中设置密码
• first_logon_behaviour=no：登录时不要求新密码
• rename_admin_user=true：把默认 Administrator 改名为 username
• metadata_services=cloudbaseinit.metadata.services.configdrive.ConfigDriveService：优先检查此服务 ， 否则启动后可能要几分钟才完成配置

部分插件（如 SetHostnamePlugin）需要重启并自动执行；要禁用自动重启 ， 设 allow_reboot=false。完整选项见 Cloudbase-Init 官方文档。

配置后可先建快照以便回滚 ， 然后关机、加 Cloud-Init 盘、转模板：

qm set 9000 --ide2 local-lvm:cloudinit
qm template 9000

克隆模板：

qm clone 9000 123 --name windows123

设置密码、网络、 SSH 密钥：

qm set 123 --cipassword <password>
qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1
qm set 123 --sshkey ~/.ssh/id_rsa.pub

设置密码前确保 ostype 已设为 Windows 版本 ， 否则密码会被加密 ， Cloudbase-Init 会把密文当明文用。首次启动登录可能暂不工作 ， VM 会因 hostname 改动自动重启 ， 之后新密码生效。

10.8.6.Cloudbase-Init 与 Sysprep Cloudbase-Init and Sysprep

Sysprep 可重置 Windows 配置产生新系统 ， 可与 Cloudbase-Init 结合做干净模板。需改两份配置文件 ：主配置与 *-unattend.conf。 Cloudbase-Init 分两步 ：先用 -unattend.conf 执行 Sysprep 阶段 ， 再用主配置执行常规阶段。 Windows Server 随附 Unattend.xml 即可 ； 普通 Windows 需额外：

1. 打开 PowerShell。
2. 启用 Administrator：net user Administrator /active:yes
3. 用 Administrator 安装 Cloudbase-Init。
4. 修改 Unattend.xml， 追加 Sysprep 后启用 Administrator 的命令：

   <RunSynchronousCommand wcm:action="add">
       <Path>net user administrator /active:yes</Path>
       <Order>1</Order>
       <Description>Enable Administrator User</Description>
   </RunSynchronousCommand>

   确保 <Order> 不与其他同步命令冲突 ， 把 Cloudbase-Init 命令的 <Order> 调大使其后运行。

5. （仅 Windows 11）移除冲突包：Get-AppxPackage -AllUsers Microsoft.OneDriveSync | Remove-AppxPackage -AllUsers
6. 进入 Cloudbase-Init 配置目录：cd 'C:\Program Files\Cloudbase Solutions\Cloudbase-Init\conf'
7. （可选）在 Sysprep 前先建快照。
8. 运行 Sysprep：C:\Windows\System32\Sysprep\sysprep.exe /generalize /oobe /unattend:Unattend.xml

完成后 VM 因 Sysprep 处于关机 —— 可将其做成模板 ， 然后克隆 / 按需配置。

10.8.7.Cloud-Init 专用选项 Cloud-Init specific Options

cicustom: [meta=<volume>][,network=<volume>][,user=<volume>][,vendor=<volume>]

指定自定义文件替代自动生成。 meta（provider 相关 ， configdrive2 与 nocloud 不同）、 network、 user、 vendor 分别传入元数据、网络、用户、厂商数据。

cipassword: <string>

分配给用户的密码。通常不建议使用 ， 请用 SSH 密钥。老版本 cloud-init 不支持散列密码。

citype: <configdrive2|nocloud|opennebula>

cloud-init 配置格式 ， 默认依 ostype：Linux 用 nocloud， Windows 用 configdrive2。

ciupgrade: <boolean>（默认 1）

首次启动后自动升级系统包。

ciuser: <string>

改 SSH 密钥 / 密码所针对的用户名（代替镜像默认用户）。

ipconfig[n]: [gw=<v4网关>][,gw6=<v6网关>][,ip=<v4/CIDR>][,ip6=<v6/CIDR>]

为相应网卡指定 IP 与网关。 IP 用 CIDR 记法 ， 网关可选但必须与 IP 同族。特殊字符串 dhcp 表示使用 DHCP（此时不指定网关）； v6 可用 auto（无状态自动配置 ， 需 cloud-init ≥ 19.4）。启用 cloud-init 且未指定 v4 / v6 时默认 v4 dhcp。

nameserver / searchdomain: <string>

DNS 服务器与搜索域 ， 两者均未设时 create 自动沿用主机设置。

sshkeys: <string>

SSH 公钥（每行一条 ， OpenSSH 格式）。

10.9.PCI(e) 直通 PCI(e) Passthrough

PCI(e) 直通让 VM 直接控制主机上的 PCI 设备 —— 相较虚拟化硬件优势：更低延迟、更高性能、更多特性（如硬件卸载）。但设备一旦直通 ， 主机与其他 VM 便无法再使用。

PCI 直通在 i440fx 与 q35 机型都可用；PCIe 直通仅 q35 可用。作为 PCI 直通的 PCIe 设备并非只能跑 PCI 速度 ——「PCIe 直通」仅是给客户机置一个 flag ， 告知「这是 PCIe 设备」而非「极快的旧 PCI 设备」， 部分应用受益于此。

10.9.1.通用要求 General Requirements

硬件

硬件需支持 IOMMU（含 CPU 与主板）中断重映射。通常 Intel 的 VT-d、 AMD 的 AMD-Vi 系统支持 ， 但不能保证开箱即用（实现质量、驱动质量因素）。服务器级硬件支持一般更好 ， 不过许多现代系统也能支持。请查询硬件厂商对 Linux 下该特性的支持情况。

确定 PCI 地址

最简方式是在 VM 硬件选项卡选 「Host PCI」添加 ， 或在命令行：

lspci

配置

IOMMU：在 BIOS / UEFI 启用 IOMMU / VT-d。 AMD CPU 默认启用；Intel CPU 在 6.8+ 内核默认启用 ， 旧内核需在内核命令行加：

intel_iommu=on

IOMMU Passthrough 模式：支持时启用可提升性能 —— VM 跳过 hypervisor 默认的 DMA 翻译 ， 直接把 DMA 请求送给硬件 IOMMU：

iommu=pt

内核模块：确保 vfio vfio_iommu_type1 vfio_pci 加载 ， 写入 /etc/modules。改完刷新 initramfs：

# update-initramfs -u -k all

检查：

# lsmod | grep vfio

重启后检查：

# dmesg | grep -e DMAR -e IOMMU -e AMD-Vi

应显示 IOMMU、 Directed I/O 或 Interrupt Remapping 已启用。另需确认要直通的设备处于独立 IOMMU 组：

# pvesh get /nodes/{nodename}/hardware/pci --pci-class-blacklist ""

设备与其功能（如 GPU 与其 HDMI 音频）或其 root port / PCI(e) bridge 同组也没关系。有时换一个 PCIe 槽可改变 IOMMU 分组。部分平台可能需允许不安全中断 —— 在 /etc/modprobe.d/ 下新建 .conf：

options vfio_iommu_type1 allow_unsafe_interrupts=1

GPU 直通说明

GPU 的 framebuffer 无法通过 Web UI 的 NoVNC / SPICE 显示。若直通整块 GPU 或 vGPU 且需要图形输出 ， 需物理接显示器 ， 或在客户机装远程桌面（VNC / RDP）。仅作硬件加速器（OpenCL / CUDA 等）则不需要。

10.9.2.主机设备直通 Host Device Passthrough

最常见的形式 —— 把整块 PCI(e) 卡（GPU、网卡等）直通给 VM。

主机配置

Proxmox VE 尝试自动让主机不使用该 PCI(e) 设备。若失败 ， 两种方式：

1. 在 /etc/modprobe.d/ 的 .conf 中用 vfio-pci 绑定设备 ID：

   options vfio-pci ids=1234:5678,4321:8765

   1234:5678 与 4321:8765 为 lspci -nn 所见 vendor:device ID。
2. 在主机完全屏蔽驱动 ， 腾出设备：

   blacklist DRIVERNAME

   通过 lspci -k | grep -A 3 "VGA" 查出驱动名（如 nouveau）：

   echo "blacklist <some-module>" >> /etc/modprobe.d/blacklist.conf

两种方式都需再次更新 initramfs 并重启。若仍不行 ， 可加软依赖 ， 让 GPU 模块先于 vfio-pci：

# echo "softdep <some-module> pre: vfio-pci" >> /etc/modprobe.d/<some-module>.conf

验证 ：lspci -nnk 输出应含 Kernel driver in use: vfio-pci（或缺失 "in use"）。

VM 配置

直通 GPU 时兼容性最好的组合 ：machine = q35、固件 = OVMF（UEFI）、总线 = PCIe。若要用 OVMF， GPU ROM 需支持 UEFI， 否则回退 SeaBIOS。使用 OVMF 可禁用 VGA 仲裁以减少启动中老旧代码：

echo "options vfio-pci ids=<vendor-id>,<device-id> disable_vga=1" > /etc/modprobe.d/vfio.conf

GUI 中在 VM 硬件区加 PCI 设备 ， 或 CLI：

# qm set VMID -hostpci0 00:02.0

或直接写配置：hostpci0: 00:02.0。若设备有多功能（00:02.0、 00:02.1）可简写 00:02 一并直通（等价 Web UI 「All Functions」）。

常用选项：

• x-vga=on|off：把 PCI(e) 设备标为 VM 主 GPU， 启用后 vga 选项被忽略。
• pcie=on|off：使用 PCIe 端口（仅 q35）。
• rombar=on|off：客户机是否可见固件 ROM， 默认 on ， 有些 PCI(e) 设备需关闭。
• romfile=<path>：可选 ROM 文件（相对 /usr/share/kvm/）。

PCIe 直通并把 GPU 设为主 GPU 示例：

# qm set VMID -hostpci0 02:00,pcie=on,x-vga=on

PCI ID 覆写

可覆写客户机所见的 vendor-id、 device-id、 sub-vendor-id、 sub-device-id —— 适合设备为驱动不识别的 variant 而又知其与受支持 variant 共用同款芯片时：

# qm set VMID -hostpci0 02:00,device-id=0x10f6,sub-vendor-id=0x0000

10.9.3.SR-IOV SR-IOV

SR-IOV（Single-Root I/O Virtualization）让单个设备对系统提供多个 VF（Virtual Functions）， 每个 VF 可用于不同 VM， 具备完整硬件特性 ， 性能与延迟优于软件虚拟化设备。最常见用例是带 SR-IOV 的网卡 —— 每个物理口提供多个 VF， 允许 VM 使用校验卸载等特性降低主机 CPU 开销。平台支持很关键 ， 可能需要先在 BIOS / UEFI 启用或选对 PCIe 槽。

主机配置

两种启用 VF 的方式：

1. 驱动模块选项（如 Intel 某些驱动）：

   max_vfs=4

   放到 /etc/modprobe.d/ 的 .conf（记得更新 initramfs）。
2. 通用方式 ：sysfs， 支持则运行时即可改 VF 数：

   # echo 4 > /sys/bus/pci/devices/0000:01:00.0/sriov_numvfs

   持久化可装 sysfsutils 并写 /etc/sysfs.conf 或 /etc/sysfs.d/FILE.conf。

VM 配置

创建 VF 后 lspci 会把它们视为独立 PCI(e) 设备 ， 按常规 PCI(e) 直通使用。

10.9.4.中介设备（vGPU、 GVT-g） Mediated Devices (vGPU, GVT-g)

中介设备用于让物理卡复用其特性与性能给虚拟硬件 ， 多见于虚拟 GPU（Intel GVT-g、 NVIDIA GRID vGPU）。物理卡可创建「虚拟卡」， 类似 SR-IOV， 但中介设备在主机上不作为 PCI(e) 设备出现 ， 仅适合 VM 使用。

主机配置

需要卡驱动支持 ， 否则无法工作 —— 请查询厂商兼容驱动与配置。 Intel GVT-g 驱动已整合进内核 ， 支持第 5 / 6 / 7 代 Intel Core 处理器以及 E3 v4 / v5 / v6 Xeon。为 Intel 显卡启用：/etc/modules 中加 kvmgt， 内核命令行加：

i915.enable_gvt=1

更新 initramfs 并重启。

VM 配置

在 hostpciX 指定 mdev 属性即可 ， 可从 sysfs 列出支持类型：

# ls /sys/bus/pci/devices/0000:00:02.0/mdev_supported_types

每项目录含 ：available_instances（剩余实例数）、 description（能力）、 create（创建端点 ， Proxmox VE 自动处理）。例如 Intel Skylake 6700K 的 GVT-g vGPU：

# qm set VMID -hostpci0 00:02.0,mdev=i915-GVTg_V5_4

启动 VM 时自动创建 ， 停止时自动清理。

10.9.5.在集群中使用 Use in Clusters

可在集群层为设备做映射 ， 以便与 HA 搭配、检测硬件变化、允许非 root 用户配置 —— 详见 §10.12 资源映射。

10.9.6.vIOMMU（模拟 IOMMU） vIOMMU (emulated IOMMU)

vIOMMU 是在 VM 内模拟的硬件 IOMMU， 为虚拟化 I/O 设备提供更好的内存访问控制与安全。通过 vIOMMU 还可把 PCI(e) 设备从 L1 VM 再直通到 L2 VM（嵌套虚拟化）。目前有两种实现 ：Intel 与 VirtIO。

Intel vIOMMU

要求 ：无论主机 Intel / AMD， VM 内核参数均需 intel_iommu=on ； 机型必须 q35：

# qm set VMID -machine q35,viommu=intel

VirtIO vIOMMU

较新的实现 ， 限制少于 Intel vIOMMU， 但生产使用相对少、文档不足。无需设内核参数；机型不必是 q35， 但若要 PCIe 建议 q35：

# qm set VMID -machine q35,viommu=virtio

10.10.钩子脚本 Hookscripts

可用 hookscript 给 VM 绑钩子：

# qm set 100 --hookscript local:snippets/hookscript.pl

该脚本会在客户机生命周期的多个阶段被调用 ， 示例与说明见 /usr/share/pve-docs/examples/guest-example-hookscript.pl。

10.11.休眠 Hibernation

可在 GUI 点 Hibernate 或：

# qm suspend ID --todisk

当前内存内容会保存到盘 ， VM 停止。下次启动时加载回内存 ， VM 从断点继续。

状态存储选择

未指定目标存储时按下列顺序自动选：

1. VM 配置中的 vmstatestorage
2. 任一 VM 盘所在的第一个共享存储
3. 任一 VM 盘所在的第一个非共享存储
4. 作为兜底的 local

10.12.资源映射 Resource Mapping

引用本地资源（如 PCI 设备地址）时直接写死路径 / ID 会有问题：

• 用 HA 时 ， 目标节点上可能存在同 ID / 路径的不同设备 —— 若 HA 组分配不当会用错设备。
• 硬件变动会改变 ID / 路径 ， 需逐一核对。

为此可定义 集群级资源映射 —— 让资源有一个集群内唯一的、用户选定的标识 ， 在不同主机上对应不同的具体设备。 HA 便不会启错设备 ， 硬件变化也可被检出。 Web GUI 在 Datacenter → Resource Mappings 对应页签创建 ， 或 CLI：

# pvesh create /cluster/mapping/<type> <options>

<type> 当前为 pci、 usb、 dir。 <options> 必须含 map 属性 ， 包含所有可识别硬件的属性 ， 以便校验硬件未变。例如添加名为 device1 的 PCI 映射 ， node1 上路径 0000:01:00.0、 ID 0002:0001 ， node2 上路径 0000:02:00.0、同 ID：

# pvesh create /cluster/mapping/pci --id device1 \
    --map node=node1,path=0000:01:00.0,id=0002:0001 \
    --map node=node2,path=0000:02:00.0,id=0002:0001

对每个节点都要重复 --map（USB 每节点每映射目前只能映射一个设备）。 GUI 更便捷 —— 会自动抓取正确属性。 PCI 设备可对同节点给出多条 map —— VM 启动时选第一个空闲的 ， 顺序也决定尝试顺序 ， 可实现任意分配策略 ， 对 SR-IOV 很有用（具体 VF 通常不重要）。

把这种映射分配给 VM：

# qm set <vmid> -hostpci0 <name>

USB 设备：

# qm set <vmid> -usb0 <name>

允许所有常规直通选项（如 mdev）。创建映射需 /mapping/<type>/<name> 的 Mapping.Modify 权限；使用映射需 Mapping.Use（外加编辑客户机配置的常规权限）。

附加选项

• mdev（PCI）：标记 PCI 设备能提供中介设备 ， 启用后配置客户机时可选类型。映射中多 PCI 时 ， 中介设备会在首个剩余实例数 > 0 的设备上创建。
• live-migration-capable（PCI）：标记 PCI 设备可在节点间在线迁移 —— 需驱动 / 硬件支持 ， 目前仅近期内核下 NVIDIA GPU 已知支持。 直通设备在线迁移为实验性特性， 可能不稳定。

10.13.使用 qm 管理 VM Managing Virtual Machines with qm

qm 是 Proxmox VE 管理 QEMU / KVM VM 的工具 ， 可创建 / 销毁 VM、控制执行（start / stop / suspend / resume）、修改关联配置文件的参数、创建或删除虚拟盘。

10.13.1.CLI 用法示例 CLI Usage Examples

以本地存储中的 iso 新建带 4 GB IDE 盘（在 local-lvm）的 VM：

# qm create 300 -ide0 local-lvm:4 -net0 e1000 -cdrom local:iso/proxmox-mailgateway_2.1.iso

启动：

# qm start 300

下发关机并等待停止：

# qm shutdown 300 && qm wait 300

同上但仅等 40 秒：

# qm shutdown 300 && qm wait 300 -timeout 40

若关机失败则强制停止并覆盖运行中的关机任务 —— 强制停止可能导致数据丢失 ， 谨慎使用：

# qm stop 300 -overrule-shutdown 1

销毁 VM 总会从 ACL 与防火墙配置中移除；如要连同复制任务、备份任务、 HA 资源一并移除 ， 需 --purge：

# qm destroy 300 --purge

把某块盘移到其他存储：

# qm move-disk 300 scsi0 other-storage

把盘划归另一台 VM（从源 VM 取下 scsi1 挂到目标 VM 的 scsi3， 后台重命名镜像使其与新属主匹配）：

# qm move-disk 300 scsi1 --target-vmid 400 --target-disk scsi3

10.14.配置 Configuration

VM 配置文件存储于 Proxmox 集群文件系统 ， 路径 /etc/pve/qemu-server/<VMID>.conf。与 /etc/pve/ 中其他文件一样 ， 自动复制到所有集群节点。

配置示例

boot: order=virtio0;net0
cores: 1
sockets: 1
memory: 512
name: webmail
ostype: l26
net0: e1000=EE:D2:28:5F:B6:3E,bridge=vmbr0
virtio0: local:vm-100-disk-1,size=32G

这些是纯文本文件 ， 可用 vi、 nano 等直接编辑 —— 偶尔用来做小改动 ， 但需重启 VM 生效。因此通常建议用 qm 或 GUI —— 工具集会尽可能即时应用改动到运行中 VM（「热插拔」）， 此时无需重启。

10.14.1.文件格式 File Format

冒号分隔的 key/value 文本：

# this is a comment
OPTION: value

空行忽略 ， 以 # 开头的行视为注释并忽略。

10.14.2.快照 Snapshots

创建快照时 ， qm 把快照时刻的配置保存到同一配置文件的独立 snapshot 段。例如创建名为 testsnapshot 的快照后：

memory: 512
swap: 512
parent: testsnaphot
...

[testsnaphot]
memory: 512
swap: 512
snaptime: 1457170803
...

快照相关属性：parent（父子关系）、 snaptime（Unix 时间戳）。可选 vmstate 保存运行中 VM 的内存 —— 目标存储选择见 §10.11 休眠中的「状态存储选择」。

10.14.3.选项 Options

VM 配置文件支持大量选项 ， 下面列出 最常用 的核心属性。完整列表（涵盖数百项）请参考官方 man qm.conf 或 pvesh get /cluster/resources 相关 API schema。

acpi: <boolean>（默认 1）

启用 / 禁用 ACPI。

affinity: <string>

执行 VM 进程使用的主机核列表 ， 如 0,5,8-11。

agent: [enabled=]<1|0>[,freeze-fs-on-backup=<1|0>][,fstrim_cloned_disks=<1|0>][,type=<virtio|isa>]

启用并配置 QEMU Guest Agent 通信 ， 包括备份时 fs-freeze/thaw、克隆 / 迁移后 fstrim、 agent 类型。

allow-ksm: <boolean>（默认 1）

允许该客户机内存通过 KSM 合并。

amd-sev: [type=]<std|es|snp>[,allow-smt=1][,kernel-hashes=0][,no-debug=0][,no-key-sharing=0]

启用 AMD SEV 内存加密。

arch: <aarch64|x86_64>

虚拟处理器架构 ， 默认与主机相同。

args: <string>

附加到 QEMU 的原始命令行参数 —— 仅建议高级用户使用。

audio0: device=<ich9-intel-hda|intel-hda|AC97>[,driver=<spice|none>]

配置音频设备。

autostart: <boolean>（默认 0）

崩溃后自动重启（未实现）。

balloon: <integer>

为 VM 动态分配内存的目标下限（MiB）， 0 禁用 ballooning。

bios: <ovmf|seabios>（默认 seabios）

选择 BIOS 实现。

boot: [[legacy=]<[acdn]{1,4}>][,order=<device[;device...]>]

指定启动顺序 ， 推荐使用 order=。

cdrom: <volume>

ide2 的别名 ， 用作 CD-ROM。

cicustom / cipassword / citype / ciupgrade / ciuser / ipconfig[n] / nameserver / searchdomain / sshkeys

Cloud-Init 相关 ， 详见 §10.8.7。

cores: <integer>（默认 1）

每 socket 核数。

cpu: [cputype=]<enum>[,flags=...]

模拟 CPU 类型 ， 详见 §10.2.5。

cpulimit: <number>（0 – 128）

CPU 使用上限（0 = 无限制）。

cpuunits: <integer>

CPU 权重 ， 详见 §10.2.5。

description: <string>

VM 描述 ， 支持 Markdown， 显示于 Web UI。

efidisk0: [file=]<volume>[,efitype=<2m|4m>][,pre-enrolled-keys=<1|0>][,format=...]

EFI Disk， 详见 §10.2.11。

freeze: <boolean>

启动时冻结 CPU（手动用 qm monitor 中 c 开始执行）。

hookscript: <volume>

生命周期钩子脚本 ， 见 §10.10。

hostpci[n]: [host=]<HOSTPCIID|mapping=mapping-id>[,...]

PCI 直通 / 映射 ， 见 §10.9 / §10.12。

hotplug: <string>（默认 network,disk,usb）

允许热插拔的设备类别。

ide[n] / sata[n] / scsi[n] / virtio[n]: [file=]<volume>[,...]

磁盘驱动器 —— 丰富选项（cache、 discard、 iothread、 ssd、 backup、 replicate、 size 等）， 见 §10.2.4。

ivshmem: size=<integer>[,name=<string>]

VM 间共享内存 ， 见 §10.2.13。

keyboard: <en-us|de|...>

VNC 服务器键盘布局。

kvm: <boolean>（默认 1）

启用 KVM 硬件虚拟化。

localtime: <boolean>

RTC 为本地时间（默认 Windows 为本地 ， 其他为 UTC）。

lock: <backup|clone|create|migrate|rollback|snapshot|suspended>

VM 锁类型 ， 见 §10.15。

machine: <enum>

机器类型 ， 见 §10.2.3。

memory: [current=]<integer>

内存（MiB）， 见 §10.2.6。

migrate_downtime: <number>（默认 0.1）

迁移可接受的最大停机时间（秒）。

migrate_speed: <integer>（默认 0）

迁移速率限制（MB/s， 0 = 不限）。

name: <string>

VM 名称 ， 只在配置 Web UI 中显示。

net[n]: [model=]<enum>[=MAC][,bridge=...][,mtu=...][,queues=...][,tag=...][,firewall=1]

网卡 ， 见 §10.2.8。

numa: <boolean>

启用 / 禁用 NUMA， 见 §10.2.5。

numa[n]: cpus=...[,hostnodes=...][,memory=...][,policy=<preferred|bind|interleave>]

NUMA 拓扑。

onboot: <boolean>（默认 0）

随主机启动。

ostype: <other|wxp|w2k|w2k3|w2k8|wvista|win7|win8|win10|win11|l24|l26|solaris>

客户机 OS 类型 ， 见 §10.2.2。

parallel[n]: /dev/parport\d+|/dev/usb/lp\d+

主机并口映射。

protection: <boolean>（默认 0）

删除保护。

reboot: <boolean>（默认 1）

允许 VM 内重启。

rng0: source=</dev/urandom|/dev/random|/dev/hwrng>[,max_bytes=...][,period=...]

VirtIO RNG， 见 §10.2.15。

scsihw: <lsi|lsi53c810|megasas|pvscsi|virtio-scsi-pci|virtio-scsi-single>

SCSI 控制器类型。

serial[n]: <socket|/dev/ttySx>

串口。

shares: <integer>（0 – 50000， 默认 1000）

自动 ballooning 的相对权重（0 禁用 auto-ballooning）。

smbios1: uuid=...[,...]

SMBIOS type 1 字段。

sockets: <integer>（默认 1）

CPU 插槽数。

spice_enhancements: ...

SPICE 增强 ， 见 §10.2.20。

startdate: <now|YYYY-MM-DD[THH:MM:SS]>（默认 now）

RTC 起始日期。

startup: [[order=]...][,up=...][,down=...]

启停顺序 ， 见 §10.2.18。

tablet: <boolean>（默认 1）

USB 平板指针（多数 OS 鼠标位置更准确）。

tags: <string>

VM 标签（分号 / 逗号分隔）。

template: <boolean>（默认 0）

是否为模板。

tpmstate0: [file=]<volume>[,version=<v1.2|v2.0>]

TPM 状态盘 ， 见 §10.2.12。

unused[n]: [file=]<volume>

未使用的孤立卷。

usb[n]: [host=]<...|spice>[,mapping=mapping-id][,usb3=1]

USB 直通 / 映射 ， 见 §10.2.10 / §10.12。

vcpus: <integer>（默认 0）

启动时在线的 vCPU 数（0 = 全部）。

vga: [type=]<std|cirrus|vmware|qxl|qxl2|qxl3|qxl4|virtio|virtio-gl|serialX>[,memory=...][,clipboard=vnc]

显示 ， 见 §10.2.9。

virtiofs[n]: dirid=<mapping-id>[,cache=...][,direct-io=0|1][,expose-acl=0|1][,expose-xattr=0|1]

Virtiofs 共享 ， 见 §10.2.16。

vmgenid: <UUID>

VM Generation ID， 见 §10.6。

vmstatestorage: <storage ID>

VM 状态 / 休眠默认存储。

watchdog: [[model=]<i6300esb|ib700>][,action=<reset|shutdown|poweroff|pause|debug|none>]

虚拟硬件看门狗设备。

10.15.锁 Locks

在线迁移、快照、备份（vzdump）会设置锁 ， 防止对 VM 的并发不兼容操作。有时需要手动移除（例如断电后残留）：

# qm unlock <vmid>