这是本节的多页打印视图。 .
文档
-
1: 快速开始
-
2: 虚拟机定义(vms.csv)
-
3: 虚拟机生命周期
-
4: 基础镜像
-
5: 网络
-
6: 数据盘
-
7: 快照
-
8: 用户账户
-
9: 虚拟机控制台
-
10: 远程桌面
-
11: 防火墙
-
12: macOS 虚拟机
-
13: macOS 基础镜像
用 Ansible 与 libvirt 定义和管理 KVM 虚拟机的完整指南。
- 快速开始 — 安装依赖并创建第一台虚拟机
- 虚拟机定义 — 在
vms.csv中配置虚拟机 - 虚拟机生命周期 — 列出、启动、停止、重启和销毁虚拟机
- 基础镜像 — 下载 Linux 与 Windows 基础镜像
- 网络 — 网桥网络、DHCP 与静态 IP
- 数据盘 — 挂载、扩容与热插拔数据盘
- 快照 — 创建、恢复与删除快照
- 用户账户 — 创建带免密 sudo 的 SSH 用户
- 虚拟机控制台 — VNC/SPICE 与串口控制台访问
- 远程桌面 — Windows 虚拟机的 RDP 访问
- 防火墙 — 托管的 nftables 防火墙
- macOS 虚拟机 — 免键盘启动的黑苹果客户机
- macOS 基础镜像 — macOS 基础镜像的制作过程
1 - 快速开始
环境要求
- 宿主机系统:Debian 12(Bookworm)
- 软件包:
qemu-kvm、libvirt-daemon-system、libvirt-clients、ovmf、swtpm
安装
快速上手
项目结构
下一步
2 - 虚拟机定义(vms.csv)
虚拟机在 vms.csv 文件中定义,每一行代表一台虚拟机,字段如下:
| 字段 | 说明 | 示例 |
|---|---|---|
name |
虚拟机名称 | win11-dev |
host |
KVM 宿主机(inventory 名称) | local |
type |
系统类型:windows / linux / macos |
windows |
memory_mb |
内存大小(MB) | 8192 |
vcpus |
CPU 核数 | 4 |
os |
系统变体 | win11 |
disk_gb |
系统盘大小 | 80 |
data_disk_gb |
数据盘大小(0 表示无) | 10 |
base_image |
基础 qcow2 镜像路径 | /path/to/base.qcow2 |
bridge |
网络网桥 | br0 |
mac |
MAC 地址 | 52:54:00:xx:xx:xx |
firmware |
efi 或留空(BIOS) |
efi |
autostart |
开机自启(默认:false) |
true |
storage_dir |
虚拟机存储路径(可选,默认:/var/lib/libvirt/images) |
/data/vms |
ip |
静态 IP(可选,留空 = DHCP)。Linux:创建时经 cloud-init 生效;macOS:之后由 configure-macos-network.yaml 配置,见 macOS 虚拟机 |
192.168.1.100 |
netmask |
子网 CIDR(可选,默认:22) |
24 |
gateway |
默认网关(设置 ip 时必填) |
192.168.1.1 |
dns |
DNS 服务器,逗号分隔(设置 ip 时必填) |
8.8.8.8,8.8.4.4 |
vms.csv 示例
要点
- MAC 地址:每台虚拟机需要唯一的 MAC 地址,以获得稳定的 DHCP 租约
- Autostart:只有 debian12-01 配置了
autostart=true(随宿主机启动) - 存储:虚拟机可使用自定义存储路径,默认
/var/lib/libvirt/images - 静态 IP:Linux 虚拟机通过 cloud-init;macOS 虚拟机通过 SSH 执行
configure-macos-network.yaml(macOS 没有 cloud-init)——见 macOS 虚拟机 - 幂等:
create-vmplaybook 创建前会检查虚拟机是否已存在,可安全重复执行
3 - 虚拟机生命周期
所有 playbook 都是幂等的(可安全重复执行)。
列出虚拟机
输出示例:
启动虚拟机
停止虚拟机
使用 virsh shutdown,发送 ACPI 关机信号。对于配置了 QEMU guest agent 的 Windows 虚拟机,这会触发干净关机。
重启虚拟机
销毁虚拟机
删除内容:domain 定义、磁盘镜像(qcow2)、OVMF VARS、cloud-init ISO、TPM 状态。
警告:该操作具有破坏性且不可恢复,必须传入 confirm=true。
4 - 基础镜像
Linux 基础镜像
Linux 虚拟机使用官方 cloud 镜像,这些镜像已预置 cloud-init 支持。
Debian
下载最新的 Debian 12(Bookworm)镜像:
其他版本:在 https://cloud.debian.org/images/cloud/ 浏览 bookworm、bullseye、trixie 等版本。
Ubuntu
下载最新的 Ubuntu 24.04 LTS(Noble)镜像:
下载最新的 Ubuntu 26.04 LTS(Resolute)镜像:
重要:Ubuntu cloud 镜像需要 virtio 网络驱动。本项目的虚拟机模板已使用 virtio,无需额外配置。
注意:请务必对照官方 SHA256SUMS 文件校验下载的镜像,避免镜像损坏导致启动失败。
其他版本:在 https://cloud-images.ubuntu.com/ 浏览其他 Ubuntu 发行版。
Fedora
下载最新的 Fedora 44 Cloud Base 镜像:
注意:Fedora 使用 wheel 组授予 sudo 权限(而非 sudo 组)。setup-user playbook 会自动检测并使用正确的组。
其他版本:在 https://fedoraproject.org/cloud/download/ 浏览其他 Fedora 发行版。
Rocky Linux
下载最新的 Rocky Linux 10 Cloud Base 镜像:
注意:Rocky Linux 使用 wheel 组授予 sudo 权限(与 RHEL/CentOS 相同)。setup-user playbook 会自动检测并使用正确的组。
其他版本:在 https://rockylinux.org/download 浏览其他 Rocky Linux 发行版。
配置
在 vms.csv 的 base_image 字段中设置镜像路径:
镜像会在首次启动时通过 cloud-init 自动配置(SSH 密钥、用户、软件包等,来自 group_vars/kvm_hosts/vms_all.yaml)。
Windows 基础镜像
Windows qcow2 基础镜像由 packer-windows-kubevirt 构建。它使用 Packer + QEMU 生成 sysprep 泛化的 Windows 镜像,包含:
- 预装 virtio 驱动(vioscsi、viostor、netkvm、vioserial、viorng、balloon、viofs)
- QEMU Guest Agent + Cloudbase-Init
- 启用 WinRM HTTPS(端口 5986)和 RDP(端口 3389)
- EFI 启动,带 secure boot 密钥
构建你自己的镜像:
然后在 vms.csv 的 base_image 字段中设置输出路径。
Windows 虚拟机特性
当 type=windows 时,domain XML 模板包含:
- Hyper-V 优化项(relaxed、vapic、spinlocks、synic、stimer 等),支持嵌套 WSL2
- VMX 透传,支持虚拟机内嵌套虚拟化(WSL2/Hyper-V)
- EFI + vTPM 2.0(OVMF secure boot + 模拟 TPM)
- virtio-scsi 磁盘总线 + virtio 网卡
- Localtime 时钟,带 hypervclock
macOS 基础镜像
macOS 虚拟机使用在 KVM 宿主机上通过 OSX-KVM 手工制作的自包含 qcow2 基础镜像。与 Linux、Windows 镜像不同,它既不是下载的,也不是用 Packer 构建的:
- macOS Sonoma 14.8.9(x86_64),4 vCPU / 8 GB,账户
admin/admin,Remote Login 已开启 - OpenCore 引导盘 + 已 bless 的 OVMF NVRAM 模板,冷启动无需键盘操作
- 虚拟容量 64 GiB,实际占用约 29 GiB,无 backing file——可直接作为 backing 镜像使用
每台 macOS 虚拟机都会以其为基础派生独立的系统盘 overlay、OpenCore overlay,以及一份 per-VM 的 blessed OVMF VARS 文件。在 vms.csv 的 base_image 字段中设置镜像路径。
完整制作流程(安装介质下载、bless、NVRAM 校验、镜像转换)见 macOS 基础镜像。
5 - 网络
虚拟机通过网桥(默认 br0)接入本地网络,支持两种 IP 分配方式:
DHCP 模式(默认)
当 ip 字段留空时,虚拟机从局域网的 DHCP 服务器获取 IP 地址——与宿主机处于同一子网。
每台虚拟机在 vms.csv 中都分配了固定的 MAC 地址,因此 DHCP 租约是稳定的。查询虚拟机 IP:
也可以使用 list-vms playbook,它会自动完成这一步。
静态 IP 模式(Linux 虚拟机)
对于 Linux 虚拟机,可在 vms.csv 中填写 ip、netmask、gateway、dns 字段来配置静态 IP。
vms.csv 配置示例
说明
- 静态 IP 配置仅适用于 Linux 虚拟机(cloud-init network-config)
- Windows 虚拟机不支持通过该方式配置静态 IP
- 当
ip留空或省略时,虚拟机使用 DHCP(默认行为) - IP 地址是持久的,重启后保持不变
- 确保静态 IP 位于 DHCP 池之外,避免地址冲突
生成的网络配置
cloud-init 会在 /etc/netplan/50-cloud-init.yaml 生成 netplan 配置:
验证
虚拟机创建完成后,验证静态 IP 是否生效:
网桥配置
KVM 宿主机需要网络网桥(br0),虚拟机才能直接访问局域网。根据宿主机的网络管理方式选择方法:NetworkManager 处于活动状态(大多数桌面环境)用 nmcli,传统服务器配置用 ifupdown。用 systemctl is-active NetworkManager 检查。
方法 1:nmcli(NetworkManager)
先找到当前的连接配置、其 IP 配置,以及要桥接的网卡:
创建承载相同静态 IP 的网桥(或在 br0 上用 ipv4.method auto 走 DHCP),然后挂接网卡作为网桥端口,再禁用旧配置以免它抢回网卡:
两个连接都会持久化,重启后依然有效。回滚方法:nmcli connection up "<existing profile name>" 并恢复 connection.autoconnect yes。
方法 2:ifupdown(/etc/network/interfaces)
/etc/network/interfaces 示例:
将 eth0 替换为实际的网卡名(用 ip link 查看)。修改后:
验证网桥已启用:
6 - 数据盘
macOS 虚拟机:本文档中的 playbook 不适用于 macOS 客户机。 macOS 磁盘位于 q35 内置的 SATA 控制器上(不支持热插拔,也没有 virtio-blk 驱动),且 macOS 客户机内没有可供 Ansible 使用的 Python。 数据盘改为在创建虚拟机时根据
data_disk_gb列自动创建 (见 macOS 虚拟机);各 playbook 会检测type=macos并以diskutil提示中止。
挂载数据盘
从 vms.csv 读取 data_disk_gb,虚拟机必须在 CSV 中定义了 data_disk_gb > 0。通过 virsh attach-disk --config --live 将磁盘热插到运行中的虚拟机(持久化 + 立即生效)。
在虚拟机内部格式化并挂载新磁盘:
扩容数据盘
从 vms.csv 读取目标 data_disk_gb。playbook 会:
- 检查目标大小是否大于当前大小(不支持缩小)
- 若虚拟机正在运行 → 优雅关机并等待停止
- 使用
qemu-img resize扩容 qcow2 文件 - 若虚拟机之前在运行 → 自动重新启动
扩容完成后,在虚拟机内扩展文件系统:
注意:如果虚拟机已处于关机状态,playbook 直接扩容磁盘,不会自动开机。
挂载磁盘
在 Linux 虚拟机内部格式化并挂载数据盘。要求虚拟机已在 hosts.ini 中定义。
参数
disk_device:磁盘设备路径(默认:/dev/vdb)mount_point:挂载点(必填,如/data)disk_format:文件系统类型(默认:ext4)need_partition:创建 GPT 分区(默认:false,裸盘挂载)format_force:强制重新格式化(默认:false)auto_mount:写入 fstab(默认:true)
示例
playbook 会:
- 按需安装
parted - 创建 GPT 分区表(当
need_partition=true) - 使用指定文件系统格式化磁盘
- 以 UUID 写入 fstab
- 挂载并验证
Tags: -t partition、-t format、-t mount(只执行特定步骤)
额外磁盘(添加 / 列出 / 删除)
可在运行时按需添加任意数量的额外 virtio-blk 磁盘,独立于
data_disk_gb 列(该列专供 create-vm.yaml 创建的单块数据盘)。
磁盘命名为 <vm>-extra<N>.qcow2,存放在虚拟机的存储目录中;下一个可用
索引和下一个可用宿主机目标(vdX)都会从运行态和持久化配置中自动
检测,重复执行不会冲突。
仅限 Linux 客户机:virtio-blk 热插拔对运行中的虚拟机有效
(--config --live,立即生效,无需重启);已关机的虚拟机只会通过
--config 添加磁盘,下次启动时可见。
添加
列出
显示每块磁盘的索引、虚拟大小,以及在运行态 domain 和/或持久化配置中的目标设备:
删除
先卸载磁盘(运行中虚拟机的运行态 + 配置——virtio-blk 热拔除),再删除 qcow2 文件。该操作会销毁数据,必须传入 confirm=true:
在客户机内识别磁盘
客户机内核会分配自己的 vdX 名称,通常与宿主机的目标设备不同。每块额外磁盘带有序列号 <vm>-extra<N>——按序列号匹配:
之后用 mount-disk.yaml 格式化/挂载(传入客户机内的设备名,如 -e disk_device=/dev/vdc)。
7 - 快照
使用 libvirt 内置的快照支持创建、列出、恢复和删除虚拟机快照。
用法
参数
vm_name:虚拟机名称(必填)snap_action:create/list/restore/delete(必填)snapshot_name:快照名称(create 时自动生成;restore/delete 时必填)snapshot_desc:描述(可选,仅 create)halt:快照前先关机以保证磁盘一致性,完成后恢复之前的状态(可选,仅 create,默认:true)confirm:安全标志(restore 和 delete 必填)
行为
- halt=true(默认):若虚拟机在运行 → 关机 → 快照 → 启动(恢复运行状态)。若虚拟机已关机 → 快照 → 保持关机(保留关机状态)。
- halt=false:虚拟机运行中创建快照(live snapshot)。速度更快,但磁盘写入可能不完整。
- Restore 将虚拟机恢复到快照时刻的精确状态(运行或关机,取决于快照时的状态)。
8 - 用户账户
在 Linux 虚拟机上创建带 SSH 密钥和免密 sudo 的用户账户,自动跳过非 Linux 主机。
用法
参数
HOSTS:目标主机或主机组(默认:vms)username:要创建的用户名(默认:admin)ssh_pubkey:SSH 公钥文件路径(默认:~/.ssh/id_rsa.pub)user_shell:登录 shell(默认:/bin/bash)user_groups:用户组,逗号分隔(自动检测:Fedora/RHEL 用wheel,Debian/Ubuntu 用sudo)passwordless_sudo:启用免密 sudo(默认:true)
行为
- 通过
gather_facts: true自动检测操作系统 - Linux 主机:创建用户、配置 SSH 密钥、启用免密 sudo
- 非 Linux 主机(Windows 等):跳过,并显示检测到的操作系统
- 幂等:可在同一主机上安全重复执行
9 - 虚拟机控制台
虚拟机根据系统类型使用不同的图形后端:
- Windows 虚拟机:SPICE 图形(端口 5900+)
- Linux 虚拟机:VNC 图形(端口 5900+)
连接虚拟机控制台
通过 SSH 隧道远程访问
示例
查看 Windows 虚拟机的启动过程:
10 - 远程桌面
Windows 虚拟机支持 3389 端口的 RDP(Remote Desktop Protocol)。
查找虚拟机 IP 地址
通过 RDP 连接
Linux 桌面(推荐):Remmina
安装:sudo apt install remmina remmina-plugin-rdp
GUI:支持 RDP、VNC、SPICE、SSH 特性:剪贴板共享、文件夹重定向、多显示器
其他选择
- xfreerdp:
xfreerdp /v:<vm-ip> /u:Administrator - Windows:内置"远程桌面连接"(mstsc.exe)
- macOS:App Store 中的 “Microsoft Remote Desktop”
示例
11 - 防火墙
nftables role 管理 KVM 宿主机的防火墙,支持 Debian 系(Debian、Ubuntu)与 RedHat 系(Fedora、Rocky Linux)主机。
在 Ubuntu 上,部分镜像自带并启用了 ufw;默认会将其禁用(nftables_disable_ufw),避免两个管理器争抢规则集。在 Fedora 和 Rocky 上,firewalld 默认被停止并 mask(nftables_disable_firewalld),原因相同。
用法
除非
nftables_ssh_allow_all为 true,nftables_ssh_sources必须至少包含一条记录,且应包含 Ansible 控制节点,否则 role 拒绝应用空列表。已建立的 SSH 会话在重载后不会中断(established/related 被放行),但来源不在列表中的新连接会被丢弃。
role 做了什么
- 在改动主机前校验输入(OS family、
nftables_ssh_sources的 IPv4/CIDR 格式、SSH 端口非空、set 名称)。 - 安装 nftables(Debian 系用 apt,RedHat 系用 dnf);Debian 系默认移除 netfilter-persistent / iptables-persistent。
- 禁用冲突的管理器:Ubuntu 上执行
ufw --force disable(当处于活动状态);Fedora/Rocky 上停止并 mask firewalld。 - 将规则集渲染到
/etc/nftables.conf(Debian 系)或/etc/sysconfig/nftables.conf(RedHat 系),写入前先用nft -c -f校验;内容变化时通过nft -f重载。 - 设置 nftables 服务开机自启。
渲染出的配置定义了两张独立的表 inet _filter 和 inet _nat,重载时只删除并重建这两张表——无关的表(例如 Docker 的)不受影响。
变量
| 变量 | 说明 | 默认值 |
|---|---|---|
nftables_ssh_sources |
允许建立 SSH 连接的来源 IPv4 地址/CIDR | —(除非 allow-all,否则必填) |
nftables_ssh_allow_all |
接受任意来源的 SSH | false |
nftables_ssh_ports |
宿主机 SSH 端口列表;列出 sshd 监听的每个端口 | [22] |
nftables_sets |
命名地址集合(name + subnet 列表) |
[] |
nftables_rules |
原样插入 filter_default、filter_forward、nat_prerouting、nat_postrouting 的规则 |
[] |
filter_forward_default_policy |
FORWARD 链默认策略 | drop |
net_postrouting_default_policy |
POSTROUTING 链默认策略 | accept |
nftables_remove_iptables_persistent |
移除 netfilter-persistent / iptables-persistent | true |
nftables_disable_ufw |
已安装且启用时禁用 ufw | true |
nftables_disable_firewalld |
RedHat 系已安装 firewalld 时停止并 mask | true |
示例
内置链
deny— dropnolimit— acceptswitch— 总开关,把规则指向它即可切换:
说明
- 当
nftables_sets和nftables_rules都为空时,只放行 loopback、established/related 流量、DHCP 应答、ICMP,以及来自nftables_ssh_sources的 SSH。 - role 用自己的模板替换发行版自带的
/etc/nftables.conf。对于之前已在运行发行版配置的主机,残留的空inet filter表只有在可证明不会过滤流量时(无规则、无 drop/reject 策略)才会被删除。 - 在 Fedora 和 Rocky 上,
nftables.service的ExecReload以flush ruleset开头,会清空无关的表。因此 role 直接执行nft -f <config>重载,而不使用systemctl reload nftables。 - mask firewalld 同时会阻止 D-Bus 激活,
firewall-cmd无法将其拉起。用systemctl unmask firewalld恢复。
12 - macOS 虚拟机
macOS 客户机与 Linux/Windows 虚拟机并行运行。基础镜像如何用 kholia/OSX-KVM 从零构建,见 macOS 基础镜像(中文)。
macOS 与 Linux/Windows 的区别
| 方面 | Linux/Windows | macOS |
|---|---|---|
| 显示 | qxl/virtio/spice | 通过 qemu:commandline 使用 vmware-svga |
| SMC | — | 通过 qemu:commandline 使用 isa-applesmc,osk=... |
| 启动 | 直接引导系统盘 | OpenCore overlay(顺序 1)→ macOS 磁盘(顺序 2) |
| 固件 | 发行版 OVMF 或 SeaBIOS | 持久化 OVMF + 预先 bless 的 NVRAM 模板 |
| 网络 | libvirt <interface> |
网桥,virtio 网卡固定在 root-bus slot=0x05 |
| IP 配置 | cloud-init | 无 cloud-init — 默认 DHCP |
| 关机 | virsh shutdown(ACPI) |
macOS 忽略 ACPI — 从桌面或通过 SSH 关机 |
资产
共享的只读模板位于 macos_asset_dir(默认
/home/fish/bucket/kvm/macos/):
| 文件 | 用途 |
|---|---|
macos-sonoma-base.img |
Sonoma 14.8.9 基础镜像,admin/admin,已开启 Remote Login |
OpenCore.qcow2 |
OpenCore 引导盘(SIP 已关闭、自动引导) |
OVMF_VARS-blessed.fd |
预 bless 的 NVRAM 模板——冷启动免键盘的关键 |
把资产复制到另一台宿主机
三个文件是自包含的——复制到新宿主机的 macos_asset_dir 即可在该主机上
创建 macOS 虚拟机。bless 后的 Preboot 卷 UUID、APFS 布局和 boot.efi 路径
都随文件一起迁移。
新宿主机还需要:
apt install ovmf—— 模板还引用了宿主机的/usr/share/OVMF/OVMF_CODE_4M.fd(发行版持久化构建)。不要 使用 OSX-KVM 自带的非持久化副本,否则 bless 不可见,冷启动会停在 Apple 的磁盘选择界面(见下方约束 1)- 匹配的拓扑 —— q35 +
1f:2处内置 SATA + 系统盘在 2 号端口是domain-macos.xml.j2中硬编码的,使用同一个 ansible-vms role 即自动满足 - QEMU >= 8.2.2 及相近版本的 libvirt(用于
qemu:commandline)
无需复制:BaseSystem.img、fetch-macOS-v2.py、
boot-macos-install.sh——仅在重建基础镜像时使用。
配置(vms.csv)
添加一行,type=macos。disk_gb 必须等于基础镜像的虚拟大小(64)。
macOS 使用 DHCP,因此 ip/netmask/gateway/dns 留空(只有需要静态 IP
时才填写——见 静态 IP)。VNC 端口由 libvirt 自动分配
(list-vms 显示实际端口)。
数据盘:把 data_disk_gb 列(第 8 列)设为大于 0 的大小,即可在同一个
内置 AHCI 控制器上挂载一块额外的 SATA 磁盘(sdc)——macOS 原生识别,
无需 kext。与 Linux/Windows 客户机一样,SATA 总线不能热插拔,所以要在
创建时设置(或冷 attach 后重启);对已创建的虚拟机该列会被忽略。
创建
构建两个 overlay(系统盘 + OpenCore),从 bless 模板播种每台虚拟机的 NVRAM,并定义/启动 domain。冷启动无需任何键盘输入;登录窗口约 40 秒内 出现。
网络:默认 DHCP(br0 上游路由器)。查询 IP:
IP 列会列出每台虚拟机的地址(如 macOS 的 192.168.100.45),VNC 列显示
127.0.0.1:<port>。
对 macOS 客户机执行 Ansible 必须用
-m raw——客户机内没有 Python 解释器。
静态 IP(可选)
要把 macOS 虚拟机从 DHCP 切换为自定义静态 IP,分两步:
-
先在
vms.csv中定义网络——填写ip、netmask(CIDR 前缀,如22)、gateway和dns列(四项都必填;configure-macos-network.yaml会在操作客户机前断言这一点): -
针对当前(DHCP)地址运行 playbook:
boot_ip是虚拟机此刻响应的 DHCP 地址(用list-vms查询)。playbook 通过 SSH 登录,按虚拟机的 MAC 定位 BSD 接口,执行networksetup -setmanual/-setdnsservers,并验证新的静态 IP 在 22 端口可响应。之后把该虚拟机的条目在hosts.ini中更新(或新增)为 静态 IP。
启动
停止
macOS 忽略 ACPI 关机,因此 playbook 只打印提示:
- 从桌面:Apple 菜单 → 关机
- 或通过 SSH:
ssh admin@<ip> 'sudo shutdown -h now'
virsh shutdown对 macOS 客户机无效——不要使用。
销毁
先停止虚拟机(见上)。共享的基础镜像和资产不会被触碰。
快照
macOS domain 通过 pflash OVMF 和 RAW NVRAM 文件启动,libvirt 因此拒绝 完整(含内存)快照。快照 playbook 会对 macOS 自动回退为仅磁盘快照:
需要了解的局限:
- NVRAM 不包含在快照中——启动状态永远不会回滚
halt=true时 playbook 会中止并提示:macOS 忽略 ACPI,如需一致的快照 请先自行关机(桌面或 SSH)- AHCI 上的 APFS 没有 TRIM,删除快照回收的空间有限
模板约束(domain-macos.xml.j2)
有四处细节必须与验证过的手工配置一致;违反任何一处都会表现为看似无关的 另一种故障:
- 持久化 OVMF:使用宿主机的
/usr/share/OVMF/OVMF_CODE_4M.fd,而非 OSX-KVM 自带的非持久化构建 - bless 拓扑匹配:磁盘位于 q35 内置 AHCI(PCI
1f:2); 绝不能添加第二块ich9-ahci设备 - 网卡固定在 root-bus
slot=0x05:macOS 的 virtio-net 驱动只会在 固定的 root-bus 位置绑定——如果 libvirt 把网卡自动放到pcie-root-port子设备上,客户机将永远看不到它 <seclabel type='none'/>:外部(仅磁盘)快照会把共享的OpenCore.qcow2/ 基础镜像在 backing 链中多嵌套一层 (… →.inited→ overlay → base)。libvirt 的virt-aa-helper只允许 XML 中列出的文件(源 + 一层 backingStore),更深层的共享资产会被 AppArmor 拒绝,虚拟机无法启动。在此禁用按域的 AppArmor 是安全的——qemu:commandline自定义设备已使该 domain 超出标准 confined-qemu 模型。
完整原理与 bless 流程: macOS 基础镜像。
13 - macOS 基础镜像
在 Debian 12 KVM 宿主机上,用 kholia/OSX-KVM 方案手工安装 macOS Sonoma,再把成品盘固化成一张自包含的 qcow2 模板镜像,供后续派生 macOS VM 使用。
- 产出物:
/home/fish/bucket/kvm/macos/macos-sonoma-base.img - Guest:macOS Sonoma 14.8.9(x86_64),4 vCPU / 8 GB,账户
admin/admin,Remote Login 已开 - OSX-KVM 仓库(下文简称 repo):
/home/fish/bucket/OSX-KVM - 记录时间:2026-09-10(更新于 2026-09-20)
前置条件
- 宿主机 QEMU >= 8.2.2(本机 10.0.2)、libvirt >= 9(本机 11.3.0,来自 bookworm-backports)
/dev/kvm可用- 已 clone OSX-KVM 仓库到 repo
- VNC 客户端:宿主机
DISPLAY=:0上的 VNC viewer,或ssh -L转发后本地连接 - 磁盘空间:base image 实际约 29G,安装过程需额外空间
OVMF 选择(重要)
安装阶段可以使用 OSX-KVM 自带的 OVMF(非持久化,不影响安装):
OVMF_CODE_4M.fd(3.5M)OVMF_VARS-1920x1080.fd(128K)——必须用不带-exp后缀的版本
Bless + 集成到 libvirt 时必须换成宿主机发行版的持久化 OVMF:
- code:
/usr/share/OVMF/OVMF_CODE_4M.fd - vars: 540672 字节的持久化 VARS 文件(从真实 bless 后落盘的 VARS 复制而来)
OSX-KVM 自带的 OVMF 是 RAM-backed / EmuVariable 版本,完全不读写磁盘上的 VARS 文件。 bless 写入的
efi-boot-device变量无法持久化,冷启动必然停在 Apple Startup Manager。
1. 下载并转换安装介质
2. 创建安装目录和磁盘
qcow2 支持后期扩容:
qemu-img resize xxx.qcow2 128G+ guest 内diskutil apfs resizeContainer diskN 0,初始选小不影响后续。
3. 启动安装 VM
使用 boot-macos-install.sh 脚本(位于 /home/fish/bucket/OSX-KVM/):
启动:
要点:
- 三块盘全部挂 q35 内置 AHCI(
ide.0/ide.1/ide.2),不额外加ich9-ahci设备——保证磁盘控制器在 PCI1f:2,这是后续 bless 正确落盘的前提(详见"技术背景:PCI 拓扑与 bless") snapshot=on保护 OpenCore 盘不被安装过程修改usb-tablet让 VNC 客户端指针绝对定位(点击才准)- VNC display
:83(端口 5983) - 使用宿主机持久化 OVMF CODE(
/usr/share/OVMF/OVMF_CODE_4M.fd),确保 bless 后变量能落盘
4. VNC 完成安装
连接 VNC:
安装流程(全程人工点击,键盘不稳时以鼠标为主):
- OpenCore 选择界面:方向键选
macOS Base System,回车进 Recovery - Recovery 主窗口 -> 双击
Reinstall macOS Sonoma行 -> 右下 Continue - 许可页 Agree
- 目标磁盘选择页:如果只显示
macOS Base System(2.87G,Recovery 自身),说明目标盘还没分区。点 Back 退回 Recovery - 打开 Disk Utility -> 菜单
View -> Show All Devices-> 选中QEMU HARDDISK Media(整块虚拟盘) - Erase:Name
Macintosh HD/ FormatAPFS/ SchemeGUID Partition Map,抹完关掉 Disk Utility - 重新进 Reinstall macOS Sonoma,此时列表出现
Macintosh HD-> Continue - 等待安装完成(几十分钟到一小时+),弹出
Restart-> 点击 - 重启回 OpenCore 选择界面 -> 选
Macintosh HD-> 进首次启动引导 - Setup Assistant:
- 语言只选 English(减少语言包占用)
- Region 随意(选美国/澳洲比较中性,别选 American Samoa 之类奇葩时区)
- 键盘默认
- 迁移选 Not Now
- 不安装 Xcode CLI tools(省 ~1.5G)
- Account:Full Name / Account Name 用
admin,密码admin
坑:
- 首次启动时
vmware-svga驱动加载有一小段灰屏(几分钟),别当成卡死 - Recovery 主窗口的键盘导航不稳(Tab 移焦点可以、Space/Return 无法激活列表项),列表行必须鼠标双击
- 从 VNC 脚本化点击(手写 RFB PointerEvent)在 QEMU 上不稳(BrokenPipe),直接用真 VNC 客户端最省事
5. 体积优化(安装完成后、bless 之前)
SSH 或在 Terminal 里执行:
6. 开 Remote Login(SSH)
System Settings -> General -> Sharing -> Remote Login 打开,右侧 i -> 允许 All users。
macOS 默认关闭 Remote Login;关掉 Network Firewall 或允许 ssh,避免
kex_exchange_identification: Connection closed。
7. Bless + 干净关机
这是让冷启动免键盘的关键步骤(详见"技术背景:PCI 拓扑与 bless")。
在 macOS guest 内执行:
别硬 kill QEMU——qcow2 会脏,还可能被 journal 卡住恢复。
看到 SSH 断、QEMU 进程自己退出(pgrep -f qemu-system 无输出)即可。
8. 校验并晋升 NVRAM 模板
9. 生成 base image
校验:
产物就是只读模板。派生新 VM 时以它为 backing:
注意:macOS APFS 在 AHCI SATA 上不支持 TRIM(QEMU 只有 virtio-blk/scsi/nvme 支持), 所以
fstrim和qemu-img convert的稀疏回收效果有限。实测 Sonoma 精简安装的 地板约 29G,无法通过在线方式显著缩小。
技术背景:PCI 拓扑与 bless
这是 macOS-on-KVM 最容易踩坑的地方,理解它可以避免大量排查弯路。
问题
Apple boot.efi 自己画的 Startup Manager(磁盘选择界面):只要 OVMF 里持久化的
efi-boot-device / efi-boot-device-data 变量缺失、或其中编码的设备路径跟当前
PCI 拓扑对不上,就会停在这里等键盘输入。
而 libvirt 对 macOS guest 的键盘注入(send-key / QMP input-send-event)实测
三种 USB 控制器(默认 xhci、pin 到 bus0 的 xhci、ich9-ehci1 + ich9-uhci1)
全部无响应(截图像素级 AE=0),完全相同的设备配置在裸 qemu 里却是好的。
所以正确做法是让冷启动本身不需要任何键盘输入。
PCI 拓扑匹配
q35 机器类型自带一块 ICH9 AHCI 控制器固定在 PCI 1f:2,libvirt 的
<controller type='sata'> 用的就是这个内置控制器。
OSX-KVM 教程脚本里的 -device ich9-ahci,id=sata 是额外加的第二块控制器,
落在 02:0。在 02:0 拓扑下 bless 出来的 efi-boot-device device-path 放进
1f:2 拓扑的 libvirt 域里不匹配,照样弹 picker。
这个拓扑不匹配一度被误判为"libvirt 键盘坏了导致的集成障碍",实际根因从头到尾只是 设备路径对不上。
正确做法
安装脚本(boot-macos-install.sh)不加额外 ich9-ahci,磁盘直接挂 q35 内置
AHCI 总线(ide.0 / ide.1 / ide.2),天然 1f:2。在这个拓扑下 bless,设备
路径就是 PCI(dev=1f:2)/SATA(port=N)/...,与任何同样使用 1f:2 的 libvirt 域
完全匹配。
OpenCore config.plist 注意事项
NVRAM > Delete 列表里不能有 efi-boot-device / efi-boot-device-data
(只留 boot-args 和 ForceDisplayRotationInEFI),否则每次启动都会被自己抹掉,
破坏 bless 持久化。
libvirt EFI 域生命周期坑
virsh undefine 对带 nvram 的域必须加 --nvram,而加了之后会删除 VARS 文件。
因为这份 VARS 是预先烘焙好内容的模板(不是 libvirt 自动生成的空模板),手工重新
define 前必须先重新 cp 一次 OVMF_VARS-blessed.fd 到目标路径:
create-vm role 每次创建时都会重新播种 VARS,所以走 role 正常不受影响;只有手工
改 XML 重定义才需要记这个顺序。
技术背景:关键决策
- 选 Sonoma 而非最新 macOS:OSX-KVM 对 Intel 模拟(Skylake-Client + OpenCore)+ Sonoma 组合最成熟;Tahoe 起 Intel 支持收窄
- 保留 OpenCore.qcow2 的
snapshot=on:EFI 盘改动不落地,避免多次启动互相污染 - 不共用 OVMF_VARS .fd:每台 VM 必须独立拷贝一份,否则 NVRAM 冲突
附录 A:OpenCore 引导盘
OpenCore/OpenCore.qcow2 是预构建的 OpenCore 引导盘,关键配置:
- SIP 已关闭:
csr-active-config设为 NVRAM Protections disabled - 自动引导:
Misc > Boot已配置跳过 picker(bless 后自动选 macOS 盘) NVRAM > Delete列表:只删boot-args和ForceDisplayRotationInEFI,不能删efi-boot-device/efi-boot-device-data
安装时挂法:
snapshot=on 确保安装过程对 OpenCore 盘的改动不落盘,保持引导盘干净。
附录 B:OSX-KVM 仓库资产清单
仓库地址:kholia/OSX-KVM
本机路径:/home/fish/bucket/OSX-KVM
| 文件 | 大小 | 用途 |
|---|---|---|
fetch-macOS-v2.py |
– | 从 Apple CDN 下载 macOS 恢复镜像(交互式选版本) |
BaseSystem.dmg |
753M | Apple 官方恢复镜像原始下载 |
BaseSystem.img |
3.0G | dmg2img 转换后的 raw 安装器,直接挂给 VM |
OpenCore/OpenCore.qcow2 |
– | 已打补丁的 OpenCore 引导盘(SIP 已关、自动引导) |
OVMF_CODE_4M.fd |
3.5M | OSX-KVM 自带的 OVMF CODE(非持久化) |
OVMF_VARS-1920x1080.fd |
128K | OSX-KVM 自带的 OVMF VARS 模板(非持久化) |
仓库内脚本说明
| 脚本 | 说明 |
|---|---|
boot-macos-install.sh |
base image 安装启动脚本(本文第 3 步) |
boot-macos-ctrl4.sh |
bless 实验脚本,用 q35 内置 AHCI(1f:2),不加额外 ich9-ahci |
boot-macos-experiment.sh |
早期实验安装脚本(128G + 额外 ich9-ahci 02:0),仅供参考 |
boot-macos-ctrl.sh / ctrl2 / ctrl3 |
迭代版本,已不需要 |
boot-macOS-headless.sh |
OSX-KVM 原版 GUI 启动脚本 |
附录 C:磁盘布局
附录 D:资产流转
实测执行记录(2026-09-20,本次制作)
按上述步骤实际执行一遍,记录关键命令与验证结果,供下次复现对照。
安装阶段网络坑与修复
安装 VM 用 QEMU user-net(slirp NAT),guest 里 ipconfig getifaddr en0 拿到
10.0.2.15——这是 NAT 内部地址,宿主机无法直接 ping/SSH 到。修复:给
boot-macos-install.sh 的 -netdev user,id=net0 加上
hostfwd=tcp::2222-:22,宿主机通过 ssh -p 2222 admin@127.0.0.1 直接访问 guest,
不需要改网络拓扑、不需要 VNC 里手动敲命令。
体积优化(步骤 5)
bless 验证(步骤 7)
关键输出(确认写入的是 UUID 指向 preboot 卷、拓扑正确):
关机(shutdown -h now,rc=255 是 SSH 断开的正常表现,不是错误)后,
宿主机上必须等 QEMU 进程自己退出(用 pgrep/ps 确认,不能用 pgrep 匹配
到自己刚执行的 shell 命令),否则 VARS 文件可能还没落盘完整。
校验 NVRAM(步骤 8)
期望看到 Boot0080,devpath 必须读作 PciRoot()/PCI(dev=1f:2)/SATA(port=2)/...
——本次实测正是这个路径(port=2 对应安装盘挂在 ide.2,与 libvirt 域将来
用的拓扑一致,见"技术背景:PCI 拓扑与 bless"):
生成 base image(步骤 9)
最终产物校验:
再次验证:虚拟盘从 128G 缩到 64G,实际占用仍是 29.1G(对比之前 128G 虚拟盘实测 28.9G, 基本一致)。印证了本文档开头结论:base image 无法通过调整虚拟盘大小来缩小实际占用, 29G 是 macOS APFS-on-AHCI 无 TRIM 支持下的固有地板(详见"体积优化"与"技术背景"两节)。