macOS 容器环境变量完全指南：基于 Docker 的 macOS 虚拟化配置详解

macOS 容器环境变量完全指南：基于 Docker 的 macOS 虚拟化配置详解

【免费下载链接】macosMacOS inside a Docker container.项目地址: https://gitcode.com/GitHub_Trending/macos/macos

macOS inside a Docker container（仓库GitHub_Trending/macos/macos）通过 QEMU 在 Linux 主机上虚拟化运行 macOS。本篇指南以仓库文档 docs/environment.md 为主体，系统讲解可用于配置该容器的全部环境变量——涵盖 macOS 身份、CPU 与内存、存储、网络、显示、Web UI、启动、内存气球（Ballooning）、关机与调试等十余个分类，并结合 src/ 目录下的 Bash 启动脚本，揭示每个变量在容器入口脚本、OpenCore 引导盘生成与 QEMU 命令行组装中的真实作用。读完本文，你将能够精确控制这台"容器版 Mac"，从选择 macOS 版本、分配 CPU/内存，到配置网络模式与动态内存回收，全部通过环境变量完成。

文档总览：一份变量清单读懂整个容器

docs/environment.md的核心是一份按功能分类的环境变量参考表。理解这份表之前，需要先记住两条通则：

• 默认值为空（空白）的变量表示"未设置"，此时容器会在适用场景下自动计算该值。例如SN、MLB、UUID、MAC未设置时会自动生成，CPU_MODEL未设置时会按 Intel / AMD 主机自动选择。
• 所有变量均通过 Docker Compose 的environment段、docker run -e或 Kubernetes 的 env 字段注入，最终由 src/entry.sh 读取并拼装成qemu-system-x86_64命令行。

从容器启动流程看，src/entry.sh 依次加载start.sh、init.sh、memory.sh、install.sh（镜像下载）、disk.sh（磁盘）、display.sh（显卡）、network.sh（网络）、boot.sh（引导）、cpu.sh（CPU 模型）、proc.sh、power.sh（关机）、balloon.sh（内存气球）、config.sh（最终参数）等脚本。因此，你设置的每一个变量，都会在某一个环节被消费——这也是本文按分类讲解变量时，会同步给出对应源码路径的原因。

🍎 macOS 身份与安装版本

VERSION：选择 macOS 版本

VERSION接受数字或名称两种写法（如14或sonoma），默认安装 macOS 14。取值与 macOS 版本的对应关系（见 readme.md）为：15=Sequoia、14=Sonoma、13=Ventura、12=Monterey、11=Big Sur，此外也支持 macOS 26（Tahoe），但官方文档提示其运行较慢、暂不推荐。

在源码层面，src/install.sh 会根据VERSION映射到 Apple 恢复目录所需的 board identifier，例如：

• tahoe | 26* | 16*→Mac-CFF7D910A743CAAF
• sequoia | 15*→Mac-937A206F2EE63C01
• sonoma | 14*→Mac-827FAC58A8FDFA22
• ventura | 13*→Mac-4B682C642B45593E
• monterey | 12*→Mac-B809C3757DA9BB8D
• bigsur | 11*→Mac-2BD1B31983FE1663
• catalina | 10*→Mac-00BE6ED71E35EB86

若VERSION未设置，src/install.sh 会默认回退到14；而镜像构建时 Dockerfile 也通过ENV VERSION="14"写入默认值。另外从 src/install.sh 可以看到，容器会使用版本号作为存储子目录（STORAGE/${VERSION,,}），因此切换VERSION会保留各版本独立的磁盘与安装介质，不会互相覆盖。

MODEL / SN / MLB / UUID：机器身份

MODEL是 OpenCore 引导层向 macOS 报告的机型标识符，默认iMacPro1,1。SN（序列号）、MLB（主板序列号）、UUID若留空，容器会自动生成并持久化：

• src/install.sh 的generateID()使用/proc/sys/kernel/random/uuid生成 UUID，并写入状态文件；
• generateSerial()（src/install.sh）调用 OpenCore 官方工具macserial按MODEL生成配套的 SN/MLB 对；
• 这些身份会通过 src/boot.sh 的configureOpenCorePlist()写入config.plist的PlatformInfo/Generic字段，作为 OpenCore 的注入身份，从而保证 macOS 激活、网络身份等在重启后保持稳定。

提示：MODEL决定macserial生成的身份与 macOS 激活状态，改动MODEL后建议重新安装或清理 NVRAM（见下文CLEAR/SMM相关说明）。

CONNECTIONS：恢复镜像下载并发数

CONNECTIONS默认4，控制从 Apple 恢复服务器（osrecovery.apple.com）下载恢复镜像时的并发连接数。src/install.sh 的download()函数将其透传给底层下载器，下载完成后还会校验Content-Length与 DMG 容器格式（checkDownloadSize/checkDmgImage，见 src/install.sh）。网络较慢或代理环境可适当调小该值。

🧠 CPU 与内存

CPU_CORES / SMP：核心数与拓扑

CPU_CORES默认1，支持数字或half（宿主机一半核心）、max（宿主机全部核心）。src/cpu.sh 的configureSmp()会把它换算为 macOS 可接受的 socket/core 拓扑：

• 1/2/4/8→sockets=1,dies=1,cores=N,threads=1
• 6/7→sockets=3,cores=2,threads=1
• 10/11→sockets=5,cores=2,threads=1
• 12/13→sockets=3,cores=4,threads=1
• 14/15→sockets=7,cores=2,threads=1
• 16/24/32/64→sockets=1,cores=N,threads=1
• 其他非 2 的幂次值会报错退出

同时normalizeCpuCores()（src/cpu.sh）会把不稳定的3/5/9等值就近规整为2/4/8。值得注意的细节：在checkClocksource()（src/cpu.sh）中，若宿主机时钟源为tsc、非 AMD 主机且CPU_CORES=1，容器会自动提升为 2 核以规避 macOS 单核拓扑问题；检测到kvm-clock（嵌套虚拟化）或hpet时钟源时会给出警告。

若你直接设置SMP，则可完全自定义拓扑而跳过上述推导。

CPU_MODEL / CPU_FLAGS / KVM：CPU 模型与加速

• CPU_MODEL留空时，Intel 主机默认使用Skylake-Client-v4（src/cpu.sh）；AMD 主机按版本选择Haswell-noTSX（macOS 13 及更早）或Skylake-Client-v4+spec-ctrl（src/cpu.sh）。
• CPU_FLAGS会追加在默认标志之后（后值生效），默认标志为vendor=GenuineIntel,vmx=off,vmware-cpuid-freq=on,-pdpe1gb（src/cpu.sh），并在 AMD 场景补充+ssse3,+sse4.2,+popcnt,+avx,+avx2,...等特性（src/cpu.sh）。这些标志把 CPU 伪装为 GenuineIntel 并隐藏嵌套 VMX，是 macOS 正常运行的关键。
• KVM=Y（默认）启用硬件加速；置为N时回退到 QEMU TCG 软件模拟（此时会禁用pcid/invpcid/xsavec等不稳定特性，见 src/cpu.sh）。checkCpuFeatures()还会检测宿主机是否支持 AVX2——macOS 13 以上版本要求 Intel Haswell / AMD Zen 及更新处理器。

RAM_SIZE / RAM_BACKEND / RAM_CHECK：内存

• RAM_SIZE默认4G，支持8G等显式值或half、max。Dockerfile 中ENV RAM_SIZE="4G"与文档一致。
• RAM_BACKEND默认空，即由容器自动选择内存后端；设为memfd可显式启用 memfd 后端内存。
• RAM_CHECK=Y（默认）会在启动前核对宿主机可用内存，不足时拒绝启动，避免 OOM。src/entry.sh 中的RAM_MINIMUM="4G"同时设置了最低内存门槛。

AMD 平台注意事项（引自 readme.md）：在 AMD 系统上，建议初始避免分配多核或超过 8GB 内存——多核可能降低性能或引发不稳定，超过 8GB 可能导致安装卡在选国家步骤。建议安装完成后再逐步调高 RAM，并在 macOS 稳定运行数小时后再增加核心数。Intel 处理器对 macOS 兼容性更好，可从一开始就分配多核与大内存。

💾 存储

主磁盘配置族：DISK_SIZE / DISK_FMT / DISK_TYPE 等

DISK_SIZE默认64G，可调大以扩容；文档提示该变量也可用于无损扩容已有磁盘——扩容后需在 macOS 终端执行diskutil repairDisk disk2与diskutil apfs resizeContainer disk3 0以分配新增空间。DISK_FMT默认raw（性能好），需要快照/稀疏文件时可选qcow2，此时DISK_FLAGS的附加选项会传给 qemu-img 的创建命令。DISK_TYPE默认blk（即 VirtIO Block，安装时在磁盘工具里看到的Apple Inc. VirtIO Block Media就是它），可切换ide或scsi以满足兼容性场景。

DISK_CACHE（默认none）、DISK_IO（默认native）、DISK_DISCARD（默认unmap，启用 TRIM）、DISK_ROTATION（默认1，将磁盘标识为 SSD 以获得 macOS 的 TRIM 行为）、DISK_OPTIONS（追加到 QEMU 磁盘设备的原始参数）共同决定了客户机看到的磁盘行为，是排查磁盘性能与兼容性问题的第一站。ALLOCATE=Y可预分配磁盘空间以避免运行时扩容抖动。

STORAGE：一切持久化数据所在

STORAGE默认/storage，是磁盘镜像、OVMF 固件变量（NVRAM）、OpenCore 引导镜像与恢复镜像的存放目录。src/boot.sh 的selectOvmfFiles()按分辨率把固件与变量模板放到$STORAGE下（如OVMF_VARS-1920x1080.fd），并支持通过CLEAR变量清理 NVRAM。install.sh还会将恢复镜像保存在$STORAGE/base.dmg。Compose 中常见的- ./macos:/storage卷挂载即是为其提供持久化。

🌐 网络

网络模式与地址

NETWORK决定整体网络形态：nat（默认，桥接 + dnsmasq，容器与宿主机共享 IP）、user（QEMU user-mode 网络，配合USER_PORTS转发端口）或N（完全禁用网络）。DHCP=Y时启用 macvtap，macOS 作为独立设备从路由器获取 IP；readme 同时指出该模式下需挂载/dev/vhost-net并放开device_cgroup_rules（c *:* rwm），且 macvlan 设计上不允许宿主机与容器通信。

IP用于覆盖自动选择的客户机 IPv4（配合MASK默认255.255.255.0），HOST设置 macOS 的计算机名与通告主机名，MAC未设置时自动生成——从 src/install.sh 看，MAC 由 UUID 的 MD5 派生并保留 Apple 厂商前缀00:16:CB，保证身份稳定。ADAPTER（默认virtio-net-pci）、DEV（上行链路接口，默认eth0）、MTU、TAP、BRIDGE则精细控制网卡与桥接细节。

内置 DNS 与端口转发

容器内置 dnsmasq（NAT 模式的 DNS/DHCP 服务）与 passt（user-mode 网络的用户态网络后端）。DNSMASQ_OPTS/DNSMASQ_DEBUG/DNSMASQ_DISABLE控制 dnsmasq 行为（调试输出或整体禁用），PASST_OPTS/PASST_DEBUG控制 passt。端口方面，HOST_PORTS可排除某些端口参与转发，USER_PORTS则在 user-mode 下额外转发端口到 macOS。

🖥️ 显示

显示后端与分辨率

DISPLAY默认web，即通过浏览器访问 Web 查看器控制虚拟机（端口WEB_PORT）；可选vnc（独立 VNC 服务）、disabled/none（无头模式）。VGA=vmware是经 macOS 验证的兼容显卡模型。

WIDTH/HEIGHT默认1920x1080，它们不仅决定 OpenCore 注入给 macOS 的分辨率，还会影响固件选择：从 src/boot.sh 看，HEIGHT=1080时使用OVMF_VARS-1920x1080.fd变量模板、768时使用OVMF_VARS-1024x768.fd，其他高度则使用通用OVMF_VARS.fd并建立独立持久化目录。configureOpenCorePlist()也会把${WIDTH}x${HEIGHT}@32写入 OpenCore 的UEFI/Output/Resolution（src/boot.sh）。

GPU=Y启用实验性 GPU 加速，配合RENDERNODE（默认/dev/dri/renderD128）指定宿主 DRM 渲染节点，需要容器内可见对应设备。

🌍 Web UI

Web 查看器是默认的人机交互入口：WEB=Y时通过WEB_PORT（默认8006）提供浏览器控制台，Compose 中通常映射8006:8006。VNC_PORT（默认5900）暴露 VNC 服务。LOSSY=Y使用有损压缩降低弱网带宽占用；AUDIO=Y把客户机音频流到浏览器（需配合 readme.md 中的提示，在 Web 查看器的 Settings → Advanced 中手动开启 Audio 才实际传输）；PROTECT=Y为 Web 界面加上密码保护。

⚙️ 系统

MACHINE=q35是 macOS 所需的现代芯片组模型（ICH9）。PCI_BUS可覆盖附加设备的 PCI 总线（默认pcie.0，OpenCore 引导盘与恢复镜像正是挂在此总线上，见 src/boot.sh 与 src/install.sh）。RNG=Y（默认）添加 Virtio RNG 随机数设备；HPET、VMPORT控制实验性定时器与 VMware 兼容端口（默认关闭以保持 macOS 兼容）。MOUSE=usb-tablet提供绝对定位指针；src/cpu.sh 还揭示了键盘/USB 控制器细节：使用nec-usb-xhci并关闭 MSI（-global nec-usb-xhci.msi=off）以保证键盘初始化可靠。

SOUND默认usb-audio，AUDIO=Y时作为客户机音频设备。最后，ARGUMENTS是万能的"后门"——它会把原始字符串原样追加到 QEMU 命令行末尾（src/entry.sh），典型用途如 USB 直通：ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x1234"（同时挂载/dev/bus/usb，见 readme.md）。由于它优先级最高，可用于绕过任何尚未暴露为变量的 QEMU 选项。

🚀 启动

OpenCore 引导链

PICKER=Y显示 OpenCore 启动选择器（并自动延长超时到 60 秒、显示辅助条目，见 src/boot.sh），适合多系统或进入恢复模式。SMM=Y启用 System Management Mode（影响 macOS 安全完整性检查，默认关闭）。LOGO=Y（默认）把自定义启动 Logo 打入 UEFI 固件（src/boot.sh 会在 Logo 缺失时自动回退到qemu.bmp并警告）。

BOOT_INDEX默认9，是 OpenCore 引导盘的启动优先级索引（见 src/boot.sh 中bootindex=$BOOT_INDEX）。MEDIA_TYPE可覆盖安装介质的设备类型。USB默认nec-usb-xhci,id=xhci，对应上文提到的 xHCI USB 控制器配置。

引导盘的生成与持久化

引导流程本身值得展开：容器会从内置的 OpenCore ISO 提取引导文件，用 assets/config.plist 模板覆写配置，注入机器身份（MODEL/SN/MLB/UUID/ROM）、分辨率与启动选择器设置，再通过签名校验确保生成正确（src/boot.sh）。生成的boot.img存放在$STORAGE下，只有当配置签名（由MODEL/SN/MLB/UUID/MAC/WIDTH/HEIGHT/PICKER等计算，见 src/boot.sh）变化时才重建——这也是"改WIDTH、MODEL后引导镜像自动更新"的底层机制。

🎈 内存气球（Memory Ballooning）

默认情况下，VM 在生命周期内独占RAM_SIZE配置的全部内存。BALLOONING=Y启用后，容器会根据宿主机内存压力动态回收客户机闲置内存，原理与 QEMU/KVM 生态的 virtio-balloon 一致。整套参数构成一个 PID 控制器：KP=0.5（比例项）、KI=0.05（积分项）决定调节强度，BALLOONING_INTERVAL=5（秒）控制采样频率，BALLOONING_HYSTERESIS=128M防止频繁微小调整；RAM_THRESHOLD（80%）与RAM_THRESHOLD_HARD（90%）分别定义常规与激进回收的宿主机内存水位，PSI_PRESSURE（10）与PSI_PRESSURE_MAX（50）则基于 PSI（Pressure Stall Information）内存压力进一步分级调节。MIN_MEM=33%保证 VM 至少保留三成内存，DEBUG=Y可输出监控器日志。

文档提示：内存气球的具体使用说明与重要注意事项，可参考 QEMU 生态的动态内存分配文档；启用前请确认你的工作负载能接受"闲置内存被回收"的行为。

🔌 关机

SHUTDOWN=Y（默认）让容器在停止时通过 ACPI 优雅关机，而非直接杀死 QEMU 进程——从 src/entry.sh 可见，禁用SHUTDOWN时容器直接以exec前台运行 QEMU。TIMEOUT定义从触发关机到强制停止的最长等待时间（文档默认115秒，src/entry.sh 中硬编码回退值为105），与 Compose 中常见的stop_grace_period配套使用。另外restart: always与--stop-timeout 120是 readme 给出的推荐配套，可避免强制终止导致磁盘状态损坏。

🐞 调试

DEBUG=Y输出各初始化阶段的详细信息（如 src/boot.sh 中仅在 DEBUG 下打印配置消息），TRACE=Y开启 Shell 追踪以排查脚本执行路径。SERIAL默认mon:stdio，MONITOR与QMP分别暴露 QEMU monitor 与 QMP 协议接口，供高级用户注入 HMP/QMP 命令进行底层调试（配合ARGUMENTS可完全掌控 QEMU 行为）。

实战：一份覆盖主要维度的完整 Compose 配置

综合以上变量，一个"家庭服务器"场景的完整配置示例如下（基础用法可参考 compose.yml 与 readme.md 的 Docker Compose 示例）：

services: macos: image: dockurr/macos container_name: macos environment: VERSION: "15" # 安装 macOS 15 Sequoia MODEL: "iMacPro1,1" # 机型标识 CPU_CORES: "4" # 4 个虚拟核心 RAM_SIZE: "8G" # 8GB 内存 RAM_CHECK: "Y" # 启动前检查宿主机内存 DISK_SIZE: "256G" # 主磁盘 256GB DISK_FMT: "qcow2" # 使用 qcow2 格式 STORAGE: "/storage" DISPLAY: "web" # Web 查看器 WIDTH: "1920" HEIGHT: "1080" AUDIO: "Y" # 开启音频（需在查看器中启用） BALLOONING: "Y" # 动态内存回收 BALLOONING_MIN_MEM: "33%" PICKER: "N" SHUTDOWN: "Y" TIMEOUT: "115" devices: - /dev/kvm - /dev/net/tun cap_add: - NET_ADMIN ports: - 8006:8006 - 5900:5900/tcp - 5900:5900/udp volumes: - ./macos:/storage # 持久化存储 restart: always stop_grace_period: 2m

使用docker run时等价于：

docker run -it --rm --name macos \ -e "VERSION=15" -e "CPU_CORES=4" -e "RAM_SIZE=8G" -e "DISK_SIZE=256G" \ -p 8006:8006 \ --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN \ -v "${PWD:-.}/macos:/storage" --stop-timeout 120 \ docker.io/dockurr/macos

Kubernetes 部署可参考仓库根目录的 kubernetes.yml，将env字段按本文变量表逐项补充即可。

结语：从变量到一条完整的 QEMU 命令行

通读 docs/environment.md 并对照源码可以发现，这套变量体系的设计思路是"把 QEMU 的复杂性封装成声明式配置"：install.sh用VERSION决定下载哪个恢复镜像、cpu.sh用CPU_*组装-cpu参数、boot.sh用MODEL/SN/MLB/UUID生成 OpenCore 引导盘、network.sh用NETWORK/DHCP/DNSMASQ_*编排网络，最终由 src/entry.sh 汇聚为一条qemu-system-x86_64命令行。掌握本文的环境变量表，你就掌握了从"起一个容器"到"精细调校一台虚拟 Mac"的全部旋钮；需要绕过封装时，ARGUMENTS始终是你直通 QEMU 的最终手段。

【免费下载链接】macosMacOS inside a Docker container.项目地址: https://gitcode.com/GitHub_Trending/macos/macos