这是本节的多页打印视图。 .
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 支持下的固有地板(详见"体积优化"与"技术背景"两节)。