基础镜像

相关源文件

• Dockerfile
• README.md

基础镜像构成了 Docker-OSX 系统的基石，提供了在 Docker 容器内运行 macOS 所需的核心架构和功能。本页面详细介绍了基础镜像的组成、配置选项和技术架构，它是所有其他 Docker-OSX 变体的起点。

有关在此基础镜像之上构建的专用变体的信息，请参阅相应的文档：裸机镜像、自动镜像、裸机-自动镜像 和 VNC 镜像。

基础镜像概述

Docker-OSX 基础镜像构建于 Arch Linux 之上，并使用 QEMU 和 KVM 虚拟化来运行 macOS。它提供 X11 转发用于显示、SSH 访问以及一个可配置的环境来运行不同版本的 macOS。

来源：Dockerfile1-20 README.md426-443

架构详情

基础镜像由一系列层构成，每一层都提供了在 Docker 的虚拟化环境中运行 macOS 所需的核心组件。

基础组件

1. 基础操作系统：Arch Linux 及开发工具
2. 虚拟化层：QEMU 加 KVM 加速
3. 引导系统：OpenCore 引导加载程序
4. 磁盘管理：用于 macOS 的 QCOW2 磁盘镜像
5. 网络：可配置的网络适配器（默认 vmxnet3）
6. 用户界面：X11 转发和可选的 VNC

来源：Dockerfile133-140 Dockerfile185-217

关键文件和目录

组件	路径	目的
启动脚本	/home/arch/OSX-KVM/Launch.sh	启动 QEMU 的主要执行脚本，使用正确的参数
OpenCore 启动磁盘	/home/arch/OSX-KVM/OpenCore/OpenCore.qcow2	包含具有默认配置的 OpenCore 引导加载程序的启动磁盘
OpenCore 无选择器	/home/arch/OSX-KVM/OpenCore/OpenCore-nopicker.qcow2	跳过引导选择器菜单的备用启动磁盘
基础系统镜像	/home/arch/OSX-KVM/BaseSystem.img	macOS 恢复/安装镜像
系统磁盘	/home/arch/OSX-KVM/mac_hdd_ng.img	macOS 安装的主磁盘镜像

来源：Dockerfile185-217 Dockerfile245-280

构建流程

基础镜像的构建过程分为多个步骤，为运行 macOS 做好环境准备

来源：Dockerfile55-140 Dockerfile245-276

构建过程包括：

1. 设置 Arch Linux 环境
2. 安装必需的软件包（QEMU、libvirt 等）
3. 配置 SSH 访问
4. 设置 OSX-KVM 环境
5. 准备 OpenCore 启动磁盘
6. 生成默认序列号
7. 创建启动脚本

配置选项

基础镜像可通过在创建容器时传递的环境变量进行高度配置

核心系统配置

环境变量	默认值	描述
内存	4	RAM 分配（GB），也可使用“max”或“half”
CPU	Penryn	要模拟的 CPU 类型
SMP	4	CPU 核心数
CORES	4	每个插槽的核心数
EXTRA	-	额外的 QEMU 命令行参数
KVM	accel=kvm:tcg	KVM 加速选项

磁盘和存储选项

环境变量	默认值	描述
IMAGE_PATH	/home/arch/OSX-KVM/mac_hdd_ng.img	macOS 磁盘镜像路径
IMAGE_FORMAT	qcow2	macOS 磁盘镜像的格式
BOOTDISK	-	自定义 OpenCore 启动磁盘路径

网络和连接

环境变量	默认值	描述
INTERNAL_SSH_PORT	10022	容器内的 SSH 端口
NETWORKING	vmxnet3	网络适配器类型
MAC_ADDRESS	52:54:00:09:49:17	网络适配器的 MAC 地址
ADDITIONAL_PORTS	-	额外的端口转发规则

显示和用户界面

环境变量	默认值	描述
WIDTH	1920	屏幕宽度（需要序列号生成）
HEIGHT	1080	屏幕高度（需要序列号生成）
DISPLAY	:0.0	X11 显示变量
NOPICKER	false	跳过启动选择器菜单

序列号生成

环境变量	默认值	描述
GENERATE_UNIQUE	false	启动时生成唯一的序列号
GENERATE_SPECIFIC	false	使用特定的序列号
DEVICE_MODEL	iMacPro1,1	设备型号用于序列号生成
SERIAL	-	设备的序列号
BOARD_SERIAL	-	主板序列号
UUID	-	系统 UUID

来源：Dockerfile283-361 README.md739-781

启动流程

当容器启动时，会发生以下一系列操作

来源：Dockerfile364-400

使用示例

如何使用各种配置运行基础镜像

基本用法

增强资源配置

使用序列号生成

来源：README.md61-71 README.md85-101 README.md1282-1294

选择 macOS 版本

基础镜像支持多种 macOS 版本，可通过 SHORTNAME 环境变量选择

来源：README.md432-438 README.md417-425 Dockerfile360

Monterey 示例

来源：README.md90-101

与其他 Docker-OSX 变体的关系

基础镜像为所有其他 Docker-OSX 变体奠定了基础，这些变体增加了特定的功能

来源：README.md431-438 README.md568-581

基础镜像实现

基础镜像构建于 Arch Linux 之上，采用多阶段 Docker 构建过程。关键实现细节包括：

1. 启动脚本：主 Launch.sh 脚本在构建过程中生成，作为使用正确参数启动 QEMU 虚拟机的主要入口点。

2. 序列号生成：基础镜像包含生成默认、随机或特定序列号的功能，这对于 iMessage 等某些服务很重要。

3. OpenCore 配置：构建过程中会创建两种 OpenCore 启动磁盘配置：

   • 标准版本，带启动选择器菜单
   • 无选择器版本，跳过启动菜单

4. 下载逻辑：如果 macOS 基础系统镜像不存在，容器将根据指定的版本（通过 SHORTNAME）自动下载。

来源： Dockerfile185-217 Dockerfile254-276 Dockerfile364-400

技术限制与注意事项

1. 硬件要求：需要一个支持 KVM 虚拟化的宿主机系统
2. 磁盘空间：基础镜像需要大量的磁盘空间（默认 200GB）
3. 性能：性能取决于宿主机硬件能力
4. 兼容性：并非所有 macOS 功能都能在虚拟化环境中正常工作
5. 法律注意事项：用户应注意 Apple 关于虚拟化的最终用户许可协议 (EULA)

来源： README.md496-502 README.md559-563

自定义构建选项

基础镜像可以从源代码构建并进行自定义

构建参数包括

构建参数	默认	描述
SIZE	200G	macOS 磁盘镜像的大小
PARALLEL_DOWNLOADS	30	并行软件包下载数量
SHORTNAME	sequoia	macOS 版本简称
RANKMIRRORS	-	启用镜像排名以加快下载速度
MIRROR_COUNTRY	US	镜像选择的国家
MIRROR_COUNT	10	要使用的镜像数量

来源： Dockerfile61-62 Dockerfile69-70 Dockerfile360 README.md1180-1189

总结

Docker-OSX 基础镜像提供了使用 QEMU/KVM 虚拟化在 Docker 容器中运行 macOS 的基础。它通过环境变量提供了广泛的自定义选项，并且是所有其他专门的 Docker-OSX 变体的起点。该镜像基于 Arch Linux 构建，并集成了 OSX-KVM 项目的组件，为在 Docker 中进行 macOS 虚拟化提供了一个灵活而强大的平台。