macOS 容器环境变量完全指南基于 Docker 的 macOS 虚拟化配置详解【免费下载链接】macosMacOS inside a Docker container.项目地址: https://gitcode.com/GitHub_Trending/macos/macosmacOS 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.shCPU 模型、proc.sh、power.sh关机、balloon.sh内存气球、config.sh最终参数等脚本。因此你设置的每一个变量都会在某一个环节被消费——这也是本文按分类讲解变量时会同步给出对应源码路径的原因。 macOS 身份与安装版本变量默认值说明VERSION14要安装的 macOS 版本如14或sonomaMODELiMacPro1,1供 OpenCore 使用的 Mac 机型标识符SN空Mac 序列号未设置时自动生成MLB空Mac 主板序列号未设置时自动生成UUID空Mac 系统 UUID未设置时自动生成CONNECTIONS4下载恢复镜像时使用的连接数VERSION选择 macOS 版本VERSION接受数字或名称两种写法如14或sonoma默认安装 macOS 14。取值与 macOS 版本的对应关系见 readme.md为15Sequoia、14Sonoma、13Ventura、12Monterey、11Big Sur此外也支持 macOS 26Tahoe但官方文档提示其运行较慢、暂不推荐。在源码层面src/install.sh 会根据VERSION映射到 Apple 恢复目录所需的 board identifier例如tahoe | 26* | 16*→Mac-CFF7D910A743CAAFsequoia | 15*→Mac-937A206F2EE63C01sonoma | 14*→Mac-827FAC58A8FDFA22ventura | 13*→Mac-4B682C642B45593Emonterey | 12*→Mac-B809C3757DA9BB8Dbigsur | 11*→Mac-2BD1B31983FE1663catalina | 10*→Mac-00BE6ED71E35EB86若VERSION未设置src/install.sh 会默认回退到14而镜像构建时 Dockerfile 也通过ENV VERSION14写入默认值。另外从 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_CORES1虚拟 CPU 核心数如4、half、maxCPU_MODEL空QEMU CPU 模型未设置时按 Intel/AMD 主机自动选择CPU_FLAGS空附加的 QEMU CPU 特性标志SMP空自定义 CPU 拓扑未设置时由CPU_CORES推导KVMY启用 KVM 硬件加速RAM_SIZE4G分配给 macOS 的内存如8G、half、maxRAM_BACKEND空客户机内存后端机制设为memfd使用 memfd 后端内存RAM_CHECKY启动 macOS 前检查宿主机可用内存是否充足CPU_CORES / SMP核心数与拓扑CPU_CORES默认1支持数字或half宿主机一半核心、max宿主机全部核心。src/cpu.sh 的configureSmp()会把它换算为 macOS 可接受的 socket/core 拓扑1/2/4/8→sockets1,dies1,coresN,threads16/7→sockets3,cores2,threads110/11→sockets5,cores2,threads112/13→sockets3,cores4,threads114/15→sockets7,cores2,threads116/24/32/64→sockets1,coresN,threads1其他非 2 的幂次值会报错退出同时normalizeCpuCores()src/cpu.sh会把不稳定的3/5/9等值就近规整为2/4/8。值得注意的细节在checkClocksource()src/cpu.sh中若宿主机时钟源为tsc、非 AMD 主机且CPU_CORES1容器会自动提升为 2 核以规避 macOS 单核拓扑问题检测到kvm-clock嵌套虚拟化或hpet时钟源时会给出警告。若你直接设置SMP则可完全自定义拓扑而跳过上述推导。CPU_MODEL / CPU_FLAGS / KVMCPU 模型与加速CPU_MODEL留空时Intel 主机默认使用Skylake-Client-v4src/cpu.shAMD 主机按版本选择Haswell-noTSXmacOS 13 及更早或Skylake-Client-v4spec-ctrlsrc/cpu.sh。CPU_FLAGS会追加在默认标志之后后值生效默认标志为vendorGenuineIntel,vmxoff,vmware-cpuid-freqon,-pdpe1gbsrc/cpu.sh并在 AMD 场景补充ssse3,sse4.2,popcnt,avx,avx2,...等特性src/cpu.sh。这些标志把 CPU 伪装为 GenuineIntel 并隐藏嵌套 VMX是 macOS 正常运行的关键。KVMY默认启用硬件加速置为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_SIZE4G与文档一致。RAM_BACKEND默认空即由容器自动选择内存后端设为memfd可显式启用 memfd 后端内存。RAM_CHECKY默认会在启动前核对宿主机可用内存不足时拒绝启动避免 OOM。src/entry.sh 中的RAM_MINIMUM4G同时设置了最低内存门槛。AMD 平台注意事项引自 readme.md在 AMD 系统上建议初始避免分配多核或超过 8GB 内存——多核可能降低性能或引发不稳定超过 8GB 可能导致安装卡在选国家步骤。建议安装完成后再逐步调高 RAM并在 macOS 稳定运行数小时后再增加核心数。Intel 处理器对 macOS 兼容性更好可从一开始就分配多核与大内存。 存储变量默认值说明DISK_SIZE64G主磁盘大小DISK_FMTraw磁盘镜像格式raw或qcow2DISK_TYPEblk磁盘设备类型如ide、scsi、blkDISK_CACHEnone磁盘缓存模式如none、writebackDISK_IOnative磁盘 I/O 模式如native、threads、io_uringDISK_DISCARDunmap主磁盘的 Discard/TRIM 模式DISK_ROTATION1向客户机报告的转速设为1将磁盘识别为 SSDDISK_FLAGS空创建qcow2磁盘时的附加选项DISK_OPTIONS空附加到 QEMU 磁盘设备的其他选项ALLOCATEN预分配主磁盘空间STORAGE/storage存储目录存放磁盘、固件变量与下载文件主磁盘配置族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 磁盘设备的原始参数共同决定了客户机看到的磁盘行为是排查磁盘性能与兼容性问题的第一站。ALLOCATEY可预分配磁盘空间以避免运行时扩容抖动。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、user、或N禁用网络DHCPN启用 macvtap 网络让 macOS 从路由器获取 DHCP 地址HOST空可选的 macOS 计算机名与通告的主机名IP空覆盖自动选择的客户机 IPv4 地址MAC空客户机网卡 MAC 地址未设置时自动生成ADAPTERvirtio-net-pciQEMU 网卡模型DEVeth0用作上行链路的容器网络接口MTU空分配给客户机网卡的 MTUMASK255.255.255.0客户机网络的 IPv4 掩码TAPqemuTAP 或 macvtap 接口名BRIDGEdockerNAT 网络使用的网桥名HOST_PORTS空不参与客户机端口转发的端口USER_PORTS空使用 user 模式网络时额外转发到 macOS 的端口DNSMASQ_OPTS空传给 dnsmasq 的附加选项DNSMASQ_DEBUGN启用 dnsmasq 调试输出DNSMASQ_DISABLEN禁用内置 dnsmasq 解析器PASST_OPTS空传给 passt 的附加选项PASST_DEBUGN启用 passt 调试输出网络模式与地址NETWORK决定整体网络形态nat默认桥接 dnsmasq容器与宿主机共享 IP、userQEMU user-mode 网络配合USER_PORTS转发端口或N完全禁用网络。DHCPY时启用 macvtapmacOS 作为独立设备从路由器获取 IPreadme 同时指出该模式下需挂载/dev/vhost-net并放开device_cgroup_rulesc *:* rwm且 macvlan 设计上不允许宿主机与容器通信。IP用于覆盖自动选择的客户机 IPv4配合MASK默认255.255.255.0HOST设置 macOS 的计算机名与通告主机名MAC未设置时自动生成——从 src/install.sh 看MAC 由 UUID 的 MD5 派生并保留 Apple 厂商前缀00:16:CB保证身份稳定。ADAPTER默认virtio-net-pci、DEV上行链路接口默认eth0、MTU、TAP、BRIDGE则精细控制网卡与桥接细节。内置 DNS 与端口转发容器内置 dnsmasqNAT 模式的 DNS/DHCP 服务与 passtuser-mode 网络的用户态网络后端。DNSMASQ_OPTS/DNSMASQ_DEBUG/DNSMASQ_DISABLE控制 dnsmasq 行为调试输出或整体禁用PASST_OPTS/PASST_DEBUG控制 passt。端口方面HOST_PORTS可排除某些端口参与转发USER_PORTS则在 user-mode 下额外转发端口到 macOS。️ 显示变量默认值说明DISPLAYweb显示后端如web、vnc、disabled、noneVGAvmwareQEMU 显卡模型WIDTH1920为 macOS 与 OpenCore 配置的显示宽度HEIGHT1080为 macOS 与 OpenCore 配置的显示高度GPUN启用实验性 GPU 加速RENDERNODE/dev/dri/renderD128GPU 加速使用的渲染节点显示后端与分辨率DISPLAY默认web即通过浏览器访问 Web 查看器控制虚拟机端口WEB_PORT可选vnc独立 VNC 服务、disabled/none无头模式。VGAvmware是经 macOS 验证的兼容显卡模型。WIDTH/HEIGHT默认1920x1080它们不仅决定 OpenCore 注入给 macOS 的分辨率还会影响固件选择从 src/boot.sh 看HEIGHT1080时使用OVMF_VARS-1920x1080.fd变量模板、768时使用OVMF_VARS-1024x768.fd其他高度则使用通用OVMF_VARS.fd并建立独立持久化目录。configureOpenCorePlist()也会把${WIDTH}x${HEIGHT}32写入 OpenCore 的UEFI/Output/Resolutionsrc/boot.sh。GPUY启用实验性 GPU 加速配合RENDERNODE默认/dev/dri/renderD128指定宿主 DRM 渲染节点需要容器内可见对应设备。 Web UI变量默认值说明WEBY启用 Web 界面WEB_PORT8006Web 界面端口VNC_PORT5900VNC 服务器端口LOSSYN启用有损 VNC 压缩以降低带宽AUDION将客户机音频流式传输到 Web 查看器PROTECTN为 Web 界面启用密码保护Web 查看器是默认的人机交互入口WEBY时通过WEB_PORT默认8006提供浏览器控制台Compose 中通常映射8006:8006。VNC_PORT默认5900暴露 VNC 服务。LOSSYY使用有损压缩降低弱网带宽占用AUDIOY把客户机音频流到浏览器需配合 readme.md 中的提示在 Web 查看器的 Settings → Advanced 中手动开启 Audio 才实际传输PROTECTY为 Web 界面加上密码保护。⚙️ 系统变量默认值说明MACHINEq35QEMU 机器类型PCI_BUSpcie.0覆盖附加设备使用的 PCI 总线RNGY为机器添加 Virtio RNG 设备HPETNHPET 定时器设置VMPORTNVMware 端口设置MOUSEusb-tablet机器使用的指针设备SOUNDusb-audioAUDIOY时使用的音频设备ARGUMENTS空追加到 QEMU 命令行的原始参数MACHINEq35是 macOS 所需的现代芯片组模型ICH9。PCI_BUS可覆盖附加设备的 PCI 总线默认pcie.0OpenCore 引导盘与恢复镜像正是挂在此总线上见 src/boot.sh 与 src/install.sh。RNGY默认添加 Virtio RNG 随机数设备HPET、VMPORT控制实验性定时器与 VMware 兼容端口默认关闭以保持 macOS 兼容。MOUSEusb-tablet提供绝对定位指针src/cpu.sh 还揭示了键盘/USB 控制器细节使用nec-usb-xhci并关闭 MSI-global nec-usb-xhci.msioff以保证键盘初始化可靠。SOUND默认usb-audioAUDIOY时作为客户机音频设备。最后ARGUMENTS是万能的后门——它会把原始字符串原样追加到 QEMU 命令行末尾src/entry.sh典型用途如 USB 直通ARGUMENTS: -device usb-host,vendorid0x1234,productid0x1234同时挂载/dev/bus/usb见 readme.md。由于它优先级最高可用于绕过任何尚未暴露为变量的 QEMU 选项。 启动变量默认值说明PICKERN显示 OpenCore 启动选择器SMMN启用 System Management ModeLOGOY启用自定义启动 LogoBOOT_INDEX9OpenCore 引导介质的启动优先级索引MEDIA_TYPE空安装介质使用的设备类型USBnec-usb-xhci,idxhciQEMU USB 控制器配置OpenCore 引导链PICKERY显示 OpenCore 启动选择器并自动延长超时到 60 秒、显示辅助条目见 src/boot.sh适合多系统或进入恢复模式。SMMY启用 System Management Mode影响 macOS 安全完整性检查默认关闭。LOGOY默认把自定义启动 Logo 打入 UEFI 固件src/boot.sh 会在 Logo 缺失时自动回退到qemu.bmp并警告。BOOT_INDEX默认9是 OpenCore 引导盘的启动优先级索引见 src/boot.sh 中bootindex$BOOT_INDEX。MEDIA_TYPE可覆盖安装介质的设备类型。USB默认nec-usb-xhci,idxhci对应上文提到的 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变量默认值说明BALLOONINGN启用动态内存气球BALLOONING_MIN_MEM33%VM 保留的最低内存量BALLOONING_RAM_THRESHOLD80.0宿主机内存占用百分比达到后开始调整内存BALLOONING_RAM_THRESHOLD_HARD90.0宿主机内存占用百分比达到后更激进地回收BALLOONING_PSI_PRESSURE10.0PSI 内存压力水平达到后更激进地回收BALLOONING_PSI_PRESSURE_MAX50.0PSI 内存压力水平达到后响应最强烈BALLOONING_HYSTERESIS128M气球目标更新前的最小内存变化量BALLOONING_KP0.5气球控制器的比例增益BALLOONING_KI0.05气球控制器的积分增益BALLOONING_INTERVAL5轮询间隔秒BALLOONING_DEBUGN启用气球监控器的调试输出默认情况下VM 在生命周期内独占RAM_SIZE配置的全部内存。BALLOONINGY启用后容器会根据宿主机内存压力动态回收客户机闲置内存原理与 QEMU/KVM 生态的 virtio-balloon 一致。整套参数构成一个 PID 控制器KP0.5比例项、KI0.05积分项决定调节强度BALLOONING_INTERVAL5秒控制采样频率BALLOONING_HYSTERESIS128M防止频繁微小调整RAM_THRESHOLD80%与RAM_THRESHOLD_HARD90%分别定义常规与激进回收的宿主机内存水位PSI_PRESSURE10与PSI_PRESSURE_MAX50则基于 PSIPressure Stall Information内存压力进一步分级调节。MIN_MEM33%保证 VM 至少保留三成内存DEBUGY可输出监控器日志。文档提示内存气球的具体使用说明与重要注意事项可参考 QEMU 生态的动态内存分配文档启用前请确认你的工作负载能接受闲置内存被回收的行为。 关机变量默认值说明SHUTDOWNY启用优雅的 ACPI 关机TIMEOUT115强制停止 macOS 前的最长等待秒数SHUTDOWNY默认让容器在停止时通过 ACPI 优雅关机而非直接杀死 QEMU 进程——从 src/entry.sh 可见禁用SHUTDOWN时容器直接以exec前台运行 QEMU。TIMEOUT定义从触发关机到强制停止的最长等待时间文档默认115秒src/entry.sh 中硬编码回退值为105与 Compose 中常见的stop_grace_period配套使用。另外restart: always与--stop-timeout 120是 readme 给出的推荐配套可避免强制终止导致磁盘状态损坏。 调试变量默认值说明DEBUGN启用详细调试输出TRACEN启用 Shell 命令追踪set -x风格SERIALmon:stdioQEMU 串口设备配置MONITOR空QEMU monitor 配置QMP空QEMU Machine Protocol 配置DEBUGY输出各初始化阶段的详细信息如 src/boot.sh 中仅在 DEBUG 下打印配置消息TRACEY开启 Shell 追踪以排查脚本执行路径。SERIAL默认mon:stdioMONITOR与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 VERSION15 -e CPU_CORES4 -e RAM_SIZE8G -e DISK_SIZE256G \ -p 8006:8006 \ --device/dev/kvm --device/dev/net/tun --cap-add NET_ADMIN \ -v ${PWD:-.}/macos:/storage --stop-timeout 120 \ docker.io/dockurr/macosKubernetes 部署可参考仓库根目录的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 macOS 容器环境变量完全指南：基于 Docker 的 macOS 虚拟化配置详解
macOS 容器环境变量完全指南基于 Docker 的 macOS 虚拟化配置详解【免费下载链接】macosMacOS inside a Docker container.项目地址: https://gitcode.com/GitHub_Trending/macos/macosmacOS 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.shCPU 模型、proc.sh、power.sh关机、balloon.sh内存气球、config.sh最终参数等脚本。因此你设置的每一个变量都会在某一个环节被消费——这也是本文按分类讲解变量时会同步给出对应源码路径的原因。 macOS 身份与安装版本变量默认值说明VERSION14要安装的 macOS 版本如14或sonomaMODELiMacPro1,1供 OpenCore 使用的 Mac 机型标识符SN空Mac 序列号未设置时自动生成MLB空Mac 主板序列号未设置时自动生成UUID空Mac 系统 UUID未设置时自动生成CONNECTIONS4下载恢复镜像时使用的连接数VERSION选择 macOS 版本VERSION接受数字或名称两种写法如14或sonoma默认安装 macOS 14。取值与 macOS 版本的对应关系见 readme.md为15Sequoia、14Sonoma、13Ventura、12Monterey、11Big Sur此外也支持 macOS 26Tahoe但官方文档提示其运行较慢、暂不推荐。在源码层面src/install.sh 会根据VERSION映射到 Apple 恢复目录所需的 board identifier例如tahoe | 26* | 16*→Mac-CFF7D910A743CAAFsequoia | 15*→Mac-937A206F2EE63C01sonoma | 14*→Mac-827FAC58A8FDFA22ventura | 13*→Mac-4B682C642B45593Emonterey | 12*→Mac-B809C3757DA9BB8Dbigsur | 11*→Mac-2BD1B31983FE1663catalina | 10*→Mac-00BE6ED71E35EB86若VERSION未设置src/install.sh 会默认回退到14而镜像构建时 Dockerfile 也通过ENV VERSION14写入默认值。另外从 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_CORES1虚拟 CPU 核心数如4、half、maxCPU_MODEL空QEMU CPU 模型未设置时按 Intel/AMD 主机自动选择CPU_FLAGS空附加的 QEMU CPU 特性标志SMP空自定义 CPU 拓扑未设置时由CPU_CORES推导KVMY启用 KVM 硬件加速RAM_SIZE4G分配给 macOS 的内存如8G、half、maxRAM_BACKEND空客户机内存后端机制设为memfd使用 memfd 后端内存RAM_CHECKY启动 macOS 前检查宿主机可用内存是否充足CPU_CORES / SMP核心数与拓扑CPU_CORES默认1支持数字或half宿主机一半核心、max宿主机全部核心。src/cpu.sh 的configureSmp()会把它换算为 macOS 可接受的 socket/core 拓扑1/2/4/8→sockets1,dies1,coresN,threads16/7→sockets3,cores2,threads110/11→sockets5,cores2,threads112/13→sockets3,cores4,threads114/15→sockets7,cores2,threads116/24/32/64→sockets1,coresN,threads1其他非 2 的幂次值会报错退出同时normalizeCpuCores()src/cpu.sh会把不稳定的3/5/9等值就近规整为2/4/8。值得注意的细节在checkClocksource()src/cpu.sh中若宿主机时钟源为tsc、非 AMD 主机且CPU_CORES1容器会自动提升为 2 核以规避 macOS 单核拓扑问题检测到kvm-clock嵌套虚拟化或hpet时钟源时会给出警告。若你直接设置SMP则可完全自定义拓扑而跳过上述推导。CPU_MODEL / CPU_FLAGS / KVMCPU 模型与加速CPU_MODEL留空时Intel 主机默认使用Skylake-Client-v4src/cpu.shAMD 主机按版本选择Haswell-noTSXmacOS 13 及更早或Skylake-Client-v4spec-ctrlsrc/cpu.sh。CPU_FLAGS会追加在默认标志之后后值生效默认标志为vendorGenuineIntel,vmxoff,vmware-cpuid-freqon,-pdpe1gbsrc/cpu.sh并在 AMD 场景补充ssse3,sse4.2,popcnt,avx,avx2,...等特性src/cpu.sh。这些标志把 CPU 伪装为 GenuineIntel 并隐藏嵌套 VMX是 macOS 正常运行的关键。KVMY默认启用硬件加速置为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_SIZE4G与文档一致。RAM_BACKEND默认空即由容器自动选择内存后端设为memfd可显式启用 memfd 后端内存。RAM_CHECKY默认会在启动前核对宿主机可用内存不足时拒绝启动避免 OOM。src/entry.sh 中的RAM_MINIMUM4G同时设置了最低内存门槛。AMD 平台注意事项引自 readme.md在 AMD 系统上建议初始避免分配多核或超过 8GB 内存——多核可能降低性能或引发不稳定超过 8GB 可能导致安装卡在选国家步骤。建议安装完成后再逐步调高 RAM并在 macOS 稳定运行数小时后再增加核心数。Intel 处理器对 macOS 兼容性更好可从一开始就分配多核与大内存。 存储变量默认值说明DISK_SIZE64G主磁盘大小DISK_FMTraw磁盘镜像格式raw或qcow2DISK_TYPEblk磁盘设备类型如ide、scsi、blkDISK_CACHEnone磁盘缓存模式如none、writebackDISK_IOnative磁盘 I/O 模式如native、threads、io_uringDISK_DISCARDunmap主磁盘的 Discard/TRIM 模式DISK_ROTATION1向客户机报告的转速设为1将磁盘识别为 SSDDISK_FLAGS空创建qcow2磁盘时的附加选项DISK_OPTIONS空附加到 QEMU 磁盘设备的其他选项ALLOCATEN预分配主磁盘空间STORAGE/storage存储目录存放磁盘、固件变量与下载文件主磁盘配置族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 磁盘设备的原始参数共同决定了客户机看到的磁盘行为是排查磁盘性能与兼容性问题的第一站。ALLOCATEY可预分配磁盘空间以避免运行时扩容抖动。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、user、或N禁用网络DHCPN启用 macvtap 网络让 macOS 从路由器获取 DHCP 地址HOST空可选的 macOS 计算机名与通告的主机名IP空覆盖自动选择的客户机 IPv4 地址MAC空客户机网卡 MAC 地址未设置时自动生成ADAPTERvirtio-net-pciQEMU 网卡模型DEVeth0用作上行链路的容器网络接口MTU空分配给客户机网卡的 MTUMASK255.255.255.0客户机网络的 IPv4 掩码TAPqemuTAP 或 macvtap 接口名BRIDGEdockerNAT 网络使用的网桥名HOST_PORTS空不参与客户机端口转发的端口USER_PORTS空使用 user 模式网络时额外转发到 macOS 的端口DNSMASQ_OPTS空传给 dnsmasq 的附加选项DNSMASQ_DEBUGN启用 dnsmasq 调试输出DNSMASQ_DISABLEN禁用内置 dnsmasq 解析器PASST_OPTS空传给 passt 的附加选项PASST_DEBUGN启用 passt 调试输出网络模式与地址NETWORK决定整体网络形态nat默认桥接 dnsmasq容器与宿主机共享 IP、userQEMU user-mode 网络配合USER_PORTS转发端口或N完全禁用网络。DHCPY时启用 macvtapmacOS 作为独立设备从路由器获取 IPreadme 同时指出该模式下需挂载/dev/vhost-net并放开device_cgroup_rulesc *:* rwm且 macvlan 设计上不允许宿主机与容器通信。IP用于覆盖自动选择的客户机 IPv4配合MASK默认255.255.255.0HOST设置 macOS 的计算机名与通告主机名MAC未设置时自动生成——从 src/install.sh 看MAC 由 UUID 的 MD5 派生并保留 Apple 厂商前缀00:16:CB保证身份稳定。ADAPTER默认virtio-net-pci、DEV上行链路接口默认eth0、MTU、TAP、BRIDGE则精细控制网卡与桥接细节。内置 DNS 与端口转发容器内置 dnsmasqNAT 模式的 DNS/DHCP 服务与 passtuser-mode 网络的用户态网络后端。DNSMASQ_OPTS/DNSMASQ_DEBUG/DNSMASQ_DISABLE控制 dnsmasq 行为调试输出或整体禁用PASST_OPTS/PASST_DEBUG控制 passt。端口方面HOST_PORTS可排除某些端口参与转发USER_PORTS则在 user-mode 下额外转发端口到 macOS。️ 显示变量默认值说明DISPLAYweb显示后端如web、vnc、disabled、noneVGAvmwareQEMU 显卡模型WIDTH1920为 macOS 与 OpenCore 配置的显示宽度HEIGHT1080为 macOS 与 OpenCore 配置的显示高度GPUN启用实验性 GPU 加速RENDERNODE/dev/dri/renderD128GPU 加速使用的渲染节点显示后端与分辨率DISPLAY默认web即通过浏览器访问 Web 查看器控制虚拟机端口WEB_PORT可选vnc独立 VNC 服务、disabled/none无头模式。VGAvmware是经 macOS 验证的兼容显卡模型。WIDTH/HEIGHT默认1920x1080它们不仅决定 OpenCore 注入给 macOS 的分辨率还会影响固件选择从 src/boot.sh 看HEIGHT1080时使用OVMF_VARS-1920x1080.fd变量模板、768时使用OVMF_VARS-1024x768.fd其他高度则使用通用OVMF_VARS.fd并建立独立持久化目录。configureOpenCorePlist()也会把${WIDTH}x${HEIGHT}32写入 OpenCore 的UEFI/Output/Resolutionsrc/boot.sh。GPUY启用实验性 GPU 加速配合RENDERNODE默认/dev/dri/renderD128指定宿主 DRM 渲染节点需要容器内可见对应设备。 Web UI变量默认值说明WEBY启用 Web 界面WEB_PORT8006Web 界面端口VNC_PORT5900VNC 服务器端口LOSSYN启用有损 VNC 压缩以降低带宽AUDION将客户机音频流式传输到 Web 查看器PROTECTN为 Web 界面启用密码保护Web 查看器是默认的人机交互入口WEBY时通过WEB_PORT默认8006提供浏览器控制台Compose 中通常映射8006:8006。VNC_PORT默认5900暴露 VNC 服务。LOSSYY使用有损压缩降低弱网带宽占用AUDIOY把客户机音频流到浏览器需配合 readme.md 中的提示在 Web 查看器的 Settings → Advanced 中手动开启 Audio 才实际传输PROTECTY为 Web 界面加上密码保护。⚙️ 系统变量默认值说明MACHINEq35QEMU 机器类型PCI_BUSpcie.0覆盖附加设备使用的 PCI 总线RNGY为机器添加 Virtio RNG 设备HPETNHPET 定时器设置VMPORTNVMware 端口设置MOUSEusb-tablet机器使用的指针设备SOUNDusb-audioAUDIOY时使用的音频设备ARGUMENTS空追加到 QEMU 命令行的原始参数MACHINEq35是 macOS 所需的现代芯片组模型ICH9。PCI_BUS可覆盖附加设备的 PCI 总线默认pcie.0OpenCore 引导盘与恢复镜像正是挂在此总线上见 src/boot.sh 与 src/install.sh。RNGY默认添加 Virtio RNG 随机数设备HPET、VMPORT控制实验性定时器与 VMware 兼容端口默认关闭以保持 macOS 兼容。MOUSEusb-tablet提供绝对定位指针src/cpu.sh 还揭示了键盘/USB 控制器细节使用nec-usb-xhci并关闭 MSI-global nec-usb-xhci.msioff以保证键盘初始化可靠。SOUND默认usb-audioAUDIOY时作为客户机音频设备。最后ARGUMENTS是万能的后门——它会把原始字符串原样追加到 QEMU 命令行末尾src/entry.sh典型用途如 USB 直通ARGUMENTS: -device usb-host,vendorid0x1234,productid0x1234同时挂载/dev/bus/usb见 readme.md。由于它优先级最高可用于绕过任何尚未暴露为变量的 QEMU 选项。 启动变量默认值说明PICKERN显示 OpenCore 启动选择器SMMN启用 System Management ModeLOGOY启用自定义启动 LogoBOOT_INDEX9OpenCore 引导介质的启动优先级索引MEDIA_TYPE空安装介质使用的设备类型USBnec-usb-xhci,idxhciQEMU USB 控制器配置OpenCore 引导链PICKERY显示 OpenCore 启动选择器并自动延长超时到 60 秒、显示辅助条目见 src/boot.sh适合多系统或进入恢复模式。SMMY启用 System Management Mode影响 macOS 安全完整性检查默认关闭。LOGOY默认把自定义启动 Logo 打入 UEFI 固件src/boot.sh 会在 Logo 缺失时自动回退到qemu.bmp并警告。BOOT_INDEX默认9是 OpenCore 引导盘的启动优先级索引见 src/boot.sh 中bootindex$BOOT_INDEX。MEDIA_TYPE可覆盖安装介质的设备类型。USB默认nec-usb-xhci,idxhci对应上文提到的 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变量默认值说明BALLOONINGN启用动态内存气球BALLOONING_MIN_MEM33%VM 保留的最低内存量BALLOONING_RAM_THRESHOLD80.0宿主机内存占用百分比达到后开始调整内存BALLOONING_RAM_THRESHOLD_HARD90.0宿主机内存占用百分比达到后更激进地回收BALLOONING_PSI_PRESSURE10.0PSI 内存压力水平达到后更激进地回收BALLOONING_PSI_PRESSURE_MAX50.0PSI 内存压力水平达到后响应最强烈BALLOONING_HYSTERESIS128M气球目标更新前的最小内存变化量BALLOONING_KP0.5气球控制器的比例增益BALLOONING_KI0.05气球控制器的积分增益BALLOONING_INTERVAL5轮询间隔秒BALLOONING_DEBUGN启用气球监控器的调试输出默认情况下VM 在生命周期内独占RAM_SIZE配置的全部内存。BALLOONINGY启用后容器会根据宿主机内存压力动态回收客户机闲置内存原理与 QEMU/KVM 生态的 virtio-balloon 一致。整套参数构成一个 PID 控制器KP0.5比例项、KI0.05积分项决定调节强度BALLOONING_INTERVAL5秒控制采样频率BALLOONING_HYSTERESIS128M防止频繁微小调整RAM_THRESHOLD80%与RAM_THRESHOLD_HARD90%分别定义常规与激进回收的宿主机内存水位PSI_PRESSURE10与PSI_PRESSURE_MAX50则基于 PSIPressure Stall Information内存压力进一步分级调节。MIN_MEM33%保证 VM 至少保留三成内存DEBUGY可输出监控器日志。文档提示内存气球的具体使用说明与重要注意事项可参考 QEMU 生态的动态内存分配文档启用前请确认你的工作负载能接受闲置内存被回收的行为。 关机变量默认值说明SHUTDOWNY启用优雅的 ACPI 关机TIMEOUT115强制停止 macOS 前的最长等待秒数SHUTDOWNY默认让容器在停止时通过 ACPI 优雅关机而非直接杀死 QEMU 进程——从 src/entry.sh 可见禁用SHUTDOWN时容器直接以exec前台运行 QEMU。TIMEOUT定义从触发关机到强制停止的最长等待时间文档默认115秒src/entry.sh 中硬编码回退值为105与 Compose 中常见的stop_grace_period配套使用。另外restart: always与--stop-timeout 120是 readme 给出的推荐配套可避免强制终止导致磁盘状态损坏。 调试变量默认值说明DEBUGN启用详细调试输出TRACEN启用 Shell 命令追踪set -x风格SERIALmon:stdioQEMU 串口设备配置MONITOR空QEMU monitor 配置QMP空QEMU Machine Protocol 配置DEBUGY输出各初始化阶段的详细信息如 src/boot.sh 中仅在 DEBUG 下打印配置消息TRACEY开启 Shell 追踪以排查脚本执行路径。SERIAL默认mon:stdioMONITOR与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 VERSION15 -e CPU_CORES4 -e RAM_SIZE8G -e DISK_SIZE256G \ -p 8006:8006 \ --device/dev/kvm --device/dev/net/tun --cap-add NET_ADMIN \ -v ${PWD:-.}/macos:/storage --stop-timeout 120 \ docker.io/dockurr/macosKubernetes 部署可参考仓库根目录的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考