OSX-KVM:在Linux上通过KVM创建和运行macOS虚拟机的开源方案

注意事项

本文档（README.md）介绍了创建 Virtual Hackintosh 系统的流程。

注意：本仓库中包含的所有二进制 blob 和资源均可通过提供的完整指导步骤重新获取！

💚 正在寻求相关的商业支持？我仅通过电子邮件提供商业支持方案的咨询服务。注：项目赞助者可访问 Private OSX-KVM 仓库并获得直接支持。

在 内容缓存（Content Caching） 方面遇到困难？我们可以提供帮助。

在 Proxmox 上运行 macOS：

• 强烈推荐查阅 Nick 的博客
• 这里有一个更新的 Proxmox 版本解决方案：OpenCore-ISO

是的，我们现在支持离线安装 macOS - 详见文档 run_offline.md 🎉

贡献指南

本项目始终欢迎您的帮助、时间与关注。我正在寻求以下工作项的协助（欢迎提交拉取请求！）：

• 在主流云服务提供商（Hetzner、GCP、AWS）上运行 macOS 的相关文档。请参考“这是否合法？”部分及相关参考资料。

• 记录并分享您如何使用本项目构建和测试开源项目/完成工作任务。

• 编写关于如何使用本项目进行 XNU 内核调试与开发的文档。

• 编写启动多个无头 macOS 虚拟机（构建农场）的流程文档。

• 编写如何使用 munki 向此类“构建农场”部署软件的文档。

• 实现开箱即用或更便捷的 VNC + SSH 支持。

• 持续欢迎提升项目健壮性的改进！

• 一个（不那么）疯狂的想法 - 通过 OpenCV 实现 macOS 安装流程的自动化。

系统要求

• 现代 Linux 发行版。例如：Ubuntu 24.04 LTS 64 位或更高版本。

• QEMU >= 8.2.2

• 要求 CPU 支持 Intel VT-x / AMD SVM 技术（可通过命令 grep -e vmx -e svm /proc/cpuinfo 检查）

• 运行 macOS Sierra 及更高版本要求 CPU 支持 SSE4.1 指令集

• 运行 macOS Ventura 及更高版本要求 CPU 支持 AVX2 指令集

注：旧款 AMD CPU 已知存在兼容性问题，但现代 AMD Ryzen 处理器（即使对于 macOS Sonoma）也能正常工作。

安装准备

• 安装 QEMU 及其他软件包。

  sudo apt-get install qemu-system uml-utilities virt-manager git \
      wget libguestfs-tools p7zip-full make dmg2img tesseract-ocr \
      tesseract-ocr-eng genisoimage vim net-tools screen -y
  

  此步骤可能需要根据您的 Linux 发行版进行调整。

• 在您的 QEMU 系统上克隆此仓库。后续步骤将使用此仓库中的文件。

  cd ~
  
  git clone --depth 1 --recursive https://github.com/kholia/OSX-KVM.git
  
  cd OSX-KVM
  

  可通过以下命令拉取仓库更新：

  git pull --rebase
  

  此仓库大量使用基于变基（rebase）的工作流。

• 主机上的 KVM 可能需要以下调整才能正常工作。

  sudo modprobe kvm; echo 1 | sudo tee /sys/module/kvm/parameters/ignore_msrs
  

  若要使此更改永久生效，可使用以下命令。如果不确定，请使用 lscpu 命令查看 CPU 信息。

  sudo cp kvm.conf /etc/modprobe.d/kvm.conf  # 仅适用于 Intel 设备
  
  sudo cp kvm_amd.conf /etc/modprobe.d/kvm.conf  # 仅适用于 AMD 设备
  

• 将用户添加到 kvm 和 libvirt 组（可能需要）。

  sudo usermod -aG kvm $(whoami)
  sudo usermod -aG libvirt $(whoami)
  sudo usermod -aG input $(whoami)
  

  注意：执行此命令后需重新登录。

• 获取 macOS 安装程序。

  ./fetch-macOS-v2.py
  

  您可以在此选择所需的 macOS 版本。执行此步骤后，当前文件夹中应会生成 BaseSystem.dmg 文件。

  注意：如果运行缓慢，请让 >= Big Sur 的安装程序在“国家/地区选择”屏幕及其他类似界面等待一段时间。macOS 初始设置向导最终会成功完成。

  运行示例：

  $ ./fetch-macOS-v2.py
  1. High Sierra (10.13)
  2. Mojave (10.14)
  3. Catalina (10.15)
  4. Big Sur (11.7)
  5. Monterey (12.6)
  6. Ventura (13)
  7. Sonoma (14) - RECOMMENDED
  8. Sequoia (15)
  9. Tahoe (26)
  
  Choose a product to download (1-9): 7
  

  注意：现代 NVIDIA 显卡在 HighSierra 上受支持，但在更高版本的 macOS 上不受支持。

• 将下载的 BaseSystem.dmg 文件转换为 BaseSystem.img 文件。

  dmg2img -i BaseSystem.dmg BaseSystem.img
  

• 创建一个用于安装 macOS 的虚拟硬盘镜像。如果将磁盘镜像的名称从 mac_hdd_ng.img 更改为其他名称，则需要更新启动脚本以指向新的镜像名称。

  qemu-img create -f qcow2 mac_hdd_ng.img 256G
  

  注意：为获得最佳效果，请在快速的 SSD/NVMe 磁盘上创建此 HDD 镜像文件。

• 现在您已准备好安装 macOS 🚀

安装

• CLI 方法（主要方法）。只需运行 OpenCore-Boot.sh 脚本即可启动安装过程。

  ./OpenCore-Boot.sh
  

  注意：此脚本适用于所有较新的 macOS 版本。

• 使用 macOS 安装程序中的 磁盘工具 对连接到 macOS 虚拟机的虚拟磁盘进行分区和格式化。对于现代 macOS 版本，请使用 APFS（默认选项）。

• 接下来，开始安装 macOS 吧 🙌

• （可选）将此 macOS 虚拟机磁盘与 libvirt（virt-manager / virsh 相关工具）配合使用。

  • 编辑 macOS-libvirt-Catalina.xml 文件，并修改其中的各种文件路径（在该文件中搜索 CHANGEME 字符串）。通常，以下命令可以完成此操作。

    sed "s/CHANGEME/$USER/g" macOS-libvirt-Catalina.xml > macOS.xml
    
    virt-xml-validate macOS.xml
    

  • 通过运行以下命令创建虚拟机。

    virsh --connect qemu:///system define macOS.xml
    

  • 如有需要，为 libvirt-qemu 用户授予必要的权限：

    sudo setfacl -m u:libvirt-qemu:rx /home/$USER
    sudo setfacl -R -m u:libvirt-qemu:rx /home/$USER/OSX-KVM
    

  • 启动 virt-manager 并启动 macOS 虚拟机。

无图形界面 macOS

• 使用提供的 boot-macOS-headless.sh 脚本。

  ./boot-macOS-headless.sh
  

合理预期

恭喜您成功搭建了 Virtual Hackintosh 系统！这样的系统可用于多种用途（例如软件构建、测试、逆向工程等），并且通过本仓库中记录的一些调整，它可能完全能满足您的需求。

然而，此类系统缺乏图形加速、可靠的声音子系统、USB 3 功能以及其他类似功能。要启用这些功能，请查看我们的 说明。我们希望能继续在此领域进行测试和文档编写工作。如果您有能力为此领域的工作提供资金支持，请 与我们联系。

实现“超越原生苹果硬件”的性能是有可能的，但这需要投入工作、耐心，或许还需要一点运气。

安装后配置

• 有关如何在虚拟机中设置网络（包括出站连接以及通过 SSH、VNC 等远程访问虚拟机的入站连接），请参阅网络说明。

• 如需直通 GPU 和其他设备，请参阅这些说明。

• 需要不同的分辨率？请查看此仓库中包含的说明。

• iMessage 遇到问题？请查看此仓库中包含的说明。

• 强烈推荐的 macOS 优化调整 - https://github.com/sickcodes/osx-optimizer

这是否合法？

“秘密的”Apple OSK 字符串在互联网上广泛存在。它也包含在一份公开的法庭文件中，可在此处获取。我不是律师，但 Apple 试图将 OSK 字符串作为商业秘密处理的尝试似乎并未成功。由于这些原因，本仓库中免费包含了 OSK 字符串。

请查看 Dortania 的 OpenCore 安装指南中关于“黑苹果的合法性”的文档内容：https://dortania.github.io/OpenCore-Install-Guide/why-oc.html#legality-of-hackintoshing。

Gabriel Somlo 也对在 QEMU/KVM 下运行 macOS 所涉及的法律方面有一些看法。

你可能还会觉得这篇“宣布推出适用于 macOS 的 Amazon EC2 Mac 实例”的文章很有趣：https://aws.amazon.com/about-aws/whats-new/2020/11/announcing-amazon-ec2-mac-instances-for-macos/。

注意：你有责任理解并接受（或不接受）Apple 的最终用户许可协议（EULA）。

注意：这不是法律建议，因此请自行做出适当评估，如有任何疑虑，请与你的律师讨论（文本来源：Dortania）

动机

我的目标是以一种简单、可重现的方式，支持基于 macOS 的教育任务、构建与测试、内核调试、逆向工程以及 macOS 安全研究，而无需（过度）投入 Apple 的封闭生态系统。

这些“虚拟黑苹果”系统并非旨在取代真正的物理 macOS 系统。

就个人而言，这个仓库是我“退出”Apple 生态系统的一种方式。它帮助我测试和比较了 Canon CanoScan LiDE 120 扫描仪和 Brother HL-2250DN 激光打印机的互操作性。这些设备现在在现代版本的 Ubuntu 上运行得相当不错（感谢自由软件）。此外，很久以前，我不得不彻底格式化我那台（当时）全新的 MacBook Pro（Retina，15 英寸，2013 年末） 并在上面安装 Xubuntu，因为 OS X 内核不断崩溃！

背景故事：我以前在加拿大是一名（贫穷的）学生，Apple 让我破解 Apple Keychains 的工作变得比原本需要的困难得多。这就是我对黑苹果系统产生兴趣的原因。