# https://github.com/sickcodes/Docker-OSX 项目说明书

生成时间：2026-07-06 18:43:00 UTC

## 目录

- [项目概览与快速入门](#page-overview)
- [macOS 版本与 Docker 镜像说明](#page-images-versions)
- [部署、编排与扩展](#page-infrastructure)
- [主机虚拟化与运行调优](#page-kvm-setup)

<a id='page-overview'></a>

## 项目概览与快速入门

### 相关页面

相关主题：[macOS 版本与 Docker 镜像说明](#page-images-versions), [主机虚拟化与运行调优](#page-kvm-setup)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/sickcodes/Docker-OSX/blob/main/README.md)
- [FAQ.md](https://github.com/sickcodes/Docker-OSX/blob/main/FAQ.md)
- [Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile)
- [docker-compose.yml](https://github.com/sickcodes/Docker-OSX/blob/main/docker-compose.yml)
- [entrypoint.sh](https://github.com/sickcodes/Docker-OSX/blob/main/entrypoint.sh)
- [boot/mac-catalina.sh](https://github.com/sickcodes/Docker-OSX/blob/main/boot/mac-catalina.sh)
- [Makefile](https://github.com/sickcodes/Docker-OSX/blob/main/Makefile)
- [config/customize_docker_osx.sh](https://github.com/sickcodes/Docker-OSX/blob/main/config/customize_docker_osx.sh)
</details>

# 项目概览与快速入门

## 项目定位与核心目标

Docker-OSX 是一个开源项目，旨在通过 Docker 容器与 QEMU/KVM 虚拟化技术，让用户在 Linux 主机上以接近原生的方式运行 macOS 虚拟机。项目支持从 High Sierra 到 Sequoia 的多个 macOS 版本，并提供预先构建好的镜像以及自定义构建流程。

项目的核心价值在于：把复杂的 QEMU 命令行、OpenCore 引导配置以及 macOS 安装流程封装进容器中，使开发者只需要一条 `docker run` 命令就能拉起一个可用的 macOS 环境。资料来源：[README.md:1-40]()

## 系统要求与前置条件

要在 x86_64 架构的 Linux 主机上运行 Docker-OSX，必须满足以下条件：

- CPU 支持虚拟化（Intel VT-x / AMD-V），并在 BIOS 中启用
- 宿主机 `/dev/kvm` 设备可用并对当前用户可读写
- Docker 与 `docker-compose` 已正确安装
- 足够的磁盘空间与内存（建议至少 60GB 磁盘、4GB 内存）

社区中常见的环境报错（如 Issue #685 中提到的内核模块配置错误、ACL 解析失败、GTK 初始化失败等）大多源于 KVM 未启用、用户权限不足或 `qemu-system-x86_64` 版本不匹配。资料来源：[FAQ.md:1-60]()、Issue #685

需要注意的是，由于 QEMU 当前对 Apple Silicon 的模拟能力有限，项目目前仅提供 x86_64 镜像，因此不支持在 Raspberry Pi、Apple M1 等 ARM 设备上直接运行（参见 Issue #487）。资料来源：[Dockerfile:1-30]()

## 快速启动流程

最快上手方式是使用预先构建好的镜像。下表列出几种常用启动命令：

| 用途 | 命令示例 |
|------|----------|
| 拉取最新镜像 | `docker pull sickcodes/docker-osx:latest` |
| 交互式运行 | `docker run -it --device /dev/kvm -p 5099:5099 -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=... sickcodes/docker-osx:latest` |
| 后台守护模式 | `docker run -d --device /dev/kvm ...` |

对于特定版本（如 Catalina、Big Sur、Sonoma），仓库在 `boot/` 目录中提供了独立的启动脚本，例如 `mac-catalina.sh` 会自动拉取对应版本的基础镜像并附加必要的 QEMU 参数。资料来源：[boot/mac-catalina.sh:1-50]()

如果默认镜像标签缺失（例如社区反馈的 `auto`、`naked` 标签无法拉取，见 Issue #858），可以改用 `latest` 标签或在本地通过 `Dockerfile` 自定义构建：

```
docker build -t docker-osx --build-arg SHORTNAME=sonoma .
```

资料来源：[Dockerfile:1-80]()、Issue #858

## 自定义与构建

项目使用 `Makefile` 统一管理构建任务，其中 `make` 默认目标会编译自定义镜像；`make run` 则会启动一个交互式容器。`docker-compose.yml` 进一步将网络端口、环境变量（如 `DISPLAY`、`RAM`、`CPUCORES`）以及 `/dev/kvm` 设备挂载封装为声明式配置，方便在 CI 或开发环境中复用。资料来源：[docker-compose.yml:1-60]()、[Makefile:1-40]()

容器启动后，`entrypoint.sh` 负责执行环境检查、生成 OpenCore 的 `config.plist`、应用用户自定义脚本（`config/customize_docker_osx.sh`），最后调用 QEMU 拉起 macOS。资料来源：[entrypoint.sh:1-100]()、[config/customize_docker_osx.sh:1-50]()

针对社区关注的 VRAM 调整（Issue #688），可通过环境变量或自定义 `config.plist` 修改 QEMU 的 `-vga` 与 `vmware-svga` 参数，但需注意 macOS 客户端仍可能限制显存识别上限。

## 常见问题与社区反馈

- **镜像不可用**：历史镜像曾因 Docker Hub 政策调整而失效（Issue #799）。建议始终以仓库 README 中公布的镜像名为准，并在拉取前执行 `docker login`。
- **ARM 支持**：暂未支持，需要等待上游 QEMU 对 Apple Silicon 模拟的进展（Issue #487）。
- **性能调优**：可通过 `CPUCORES`、`RAM` 环境变量调整分配，并使用 `disk.qcow2` 持久化存储避免数据丢失。

资料来源：[README.md:40-200]()、[FAQ.md:60-200]()

---

<a id='page-images-versions'></a>

## macOS 版本与 Docker 镜像说明

### 相关页面

相关主题：[项目概览与快速入门](#page-overview), [部署、编排与扩展](#page-infrastructure)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile)
- [Dockerfile.auto](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile.auto)
- [Dockerfile.naked](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile.naked)
- [Dockerfile.naked-auto](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile.naked-auto)
- [docker-compose.yml](https://github.com/sickcodes/Docker-OSX/blob/main/docker-compose.yml)
- [README.md](https://github.com/sickcodes/Docker-OSX/blob/main/README.md)
</details>

# macOS 版本与 Docker 镜像说明

Docker-OSX 通过 QEMU/KVM 在 Linux 容器内虚拟化运行 macOS，提供多种 Dockerfile 与镜像变体来匹配不同使用场景。用户构建或拉取镜像时，首先要理解 `SHORTNAME` 与 `VERSION` 等构建参数如何决定最终启动的 macOS 版本，并了解 `naked` 与 `auto` 等变体的差异。本页说明镜像族系、版本对应关系以及社区中常见的命名与可用性问题。

## 镜像族系概览

仓库根目录包含四份 Dockerfile，对应四种官方镜像变体：

| Dockerfile | 用途 | 是否自带 macOS 镜像 | 构建参数依赖 |
| --- | --- | --- | --- |
| `Dockerfile` | 标准交互式版本，启动后引导用户手动完成 macOS 安装 | 否（运行时下载） | `SHORTNAME` 必填 |
| `Dockerfile.auto` | 自动化安装版本，使用 `OpenCore` 自动配置与脚本安装 | 否（运行时下载） | `SHORTNAME` 必填 |
| `Dockerfile.naked` | 仅提供 QEMU 环境，不携带任何 macOS 安装介质 | 否（用户自备 ISO） | 通常可省略 `SHORTNAME` |
| `Dockerfile.naked-auto` | `naked` 的自动化安装变体 | 否（用户自备 ISO） | 通常可省略 `SHORTNAME` |

资料来源：[Dockerfile]()、[Dockerfile.auto]()、[Dockerfile.naked]()、[Dockerfile.naked-auto]()。

`docker-compose.yml` 在 `image` 与 `build` 字段之间切换，可选择本地 `build` 或远程 `sickcodes/docker-osx:*` 镜像，从而让 `latest` 之外的具体版本由 tag 指定。资料来源：[docker-compose.yml:1-60]()。

## macOS 版本与 `SHORTNAME` 映射

构建时通过 `--build-arg SHORTNAME=<value>` 选择 macOS 版本，该值同时影响 `OpenCore` 配置和启动脚本中的下载链接。常见映射关系如下：

- `catalina` —— macOS Catalina (10.15)
- `big-sur` —— macOS Big Sur (11)
- `monterey` —— macOS Monterey (12)
- `ventura` —— macOS macOS Ventura (13)
- `sonoma` —— macOS Sonoma (14)

`SHORTNAME` 在 `Dockerfile` 中被 `ARG` 声明并向下游脚本传递，最终由容器启动入口读取，决定安装哪个 macOS 版本及对应的恢复镜像 (`BaseSystem.dmg`) 来源。资料来源：[Dockerfile]()。

## 变体差异与典型用法

```mermaid
flowchart LR
  A[选择变体] --> B{Dockerfile vs Dockerfile.auto}
  B -- Dockerfile --> C[手动安装]
  B -- Dockerfile.auto --> D[OpenCore 自动安装]
  A --> E{naked vs 完整}
  E -- 完整 --> F[运行时下载恢复镜像]
  E -- naked --> G[挂载用户自备 ISO/IMG]
```

- 完整版本（`Dockerfile` / `Dockerfile.auto`）会自动从 Apple 服务器拉取对应版本的恢复镜像，适合首次使用者快速上手。资料来源：[README.md]()。
- `naked` 版本不下载任何 macOS 镜像，用户需自行提供 `BaseSystem.dmg` 或完整安装 ISO，常用于自定义或离线场景。资料来源：[Dockerfile.naked]()。
- `auto` 系列会在首次启动时执行 `OpenCore` 配置写入与安装脚本，尽量减少人工交互。资料来源：[Dockerfile.auto]()。

## 常见问题与社区反馈

- 镜像不可用 / 标签缺失：社区 #799 与 #858 报告 `sickcodes/docker-osx:sonoma` 等具体 tag 拉取失败，常见原因包括镜像被 DockerHub 清理、tag 仅在 CI 构建产物中存在、或需先 `docker login`。建议改用本地 `docker build -t docker-osx --build-arg SHORTNAME=sonoma .` 自建。资料来源：[issue #799]()、[issue #858]()。
- ARM 平台支持：#487 提议在 `arm64v8` / Apple Silicon 上原生运行。Docker-OSX 当前依赖 x86_64 上的 KVM 加速与 QEMU x86 客户端，ARM 主机需要额外 `qemu-system-aarch64` 与 macOS ARM 恢复镜像，尚未官方支持。资料来源：[issue #487]()。
- 虚拟化依赖：QEMU 必须获得 `/dev/kvm`，且需要 `kvm`、`vhost_net`、正确的 ACL 与 GTK 初始化，否则将出现 #685 中列出的内核模块、ACL、ALSA 与 GTK 报错。资料来源：[issue #685]()。
- 显存调整：#688 中用户反映默认显存仅约 7MB；可通过启动 QEMU 时附加 `-vga none` 之外的显存相关参数或修改 `OpenCore` 设备属性来提升，但仍受 QEMU 虚拟显卡实现限制。资料来源：[issue #688]()。

## 选择建议

1. 首次体验 macOS Sonoma/Ventura：使用 `Dockerfile` 配合 `--build-arg SHORTNAME=sonoma`。资料来源：[Dockerfile]()。
2. 无人值守批量部署：选择 `Dockerfile.auto` 或 `Dockerfile.naked-auto`，配合 `docker-compose.yml` 的环境变量注入。资料来源：[Dockerfile.auto]()。
3. 自带镜像或离线环境：使用 `Dockerfile.naked` 自行挂载 `BaseSystem.dmg`。资料来源：[Dockerfile.naked]()。
4. 自定义 `RAM`、`CPU`、`EXTRA` 等 QEMU 参数：所有变体都通过 `docker run` 或 `docker-compose.yml` 中的环境变量覆盖。资料来源：[docker-compose.yml]()。

---

<a id='page-infrastructure'></a>

## 部署、编排与扩展

### 相关页面

相关主题：[macOS 版本与 Docker 镜像说明](#page-images-versions), [主机虚拟化与运行调优](#page-kvm-setup)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docker-compose.yml](https://github.com/sickcodes/Docker-OSX/blob/main/docker-compose.yml)
- [helm/Chart.yaml](https://github.com/sickcodes/Docker-OSX/blob/main/helm/Chart.yaml)
- [helm/values.yaml](https://github.com/sickcodes/Docker-OSX/blob/main/helm/values.yaml)
- [helm/templates/deployment.yaml](https://github.com/sickcodes/Docker-OSX/blob/main/helm/templates/deployment.yaml)
- [helm/README.md](https://github.com/sickcodes/Docker-OSX/blob/main/helm/README.md)
- [custom/generate-specific-bootdisk.sh](https://github.com/sickcodes/Docker-OSX/blob/main/custom/generate-specific-bootdisk.sh)
- [README.md](https://github.com/sickcodes/Docker-OSX/blob/main/README.md)
</details>

# 部署、编排与扩展

Docker-OSX 的部署面同时覆盖单机 `docker run`、多容器 `docker-compose` 以及 Kubernetes 上的 Helm Chart 三条路径。本页围绕这三种部署形态、镜像扩展（自定义 bootdisk 与 SHORTNAME 变体）以及社区中常见的部署失败模式展开说明，目的是帮助运维人员快速选择合适的编排方式并规避已知的资源限制。

## 部署方式概览

仓库对部署形态做了清晰的层级划分：`docker-compose.yml` 是面向单节点与本地开发场景的最小编排单元；`helm/` 目录提供可在 Kubernetes 上运行的 Chart，适合需要把容器化的 macOS 集成到更大集群体系中的场景；而 `custom/generate-specific-bootdisk.sh` 则承担镜像扩展能力，允许用户在基础镜像之上生成特定版本的启动盘。

下表总结三种部署形态的适用场景与关键差异：

| 形态 | 入口文件 | 适用场景 | 关键扩展点 |
| --- | --- | --- | --- |
| Docker Compose | `docker-compose.yml` | 单机/本地开发 | 端口、卷、环境变量 `SHORTNAME` |
| Helm / Kubernetes | `helm/Chart.yaml`、`helm/values.yaml`、`helm/templates/deployment.yaml` | 集群化部署 | `values.yaml` 中的 replica、resources、image 字段 |
| 自定义镜像 | `custom/generate-specific-bootdisk.sh` | 需要特定 macOS 版本 bootdisk | 脚本内 `VERSION` 与 `SHORTNAME` 参数 |

资料来源：[README.md:1-40]()，[docker-compose.yml:1-80]()。

## Docker Compose 单机部署

`docker-compose.yml` 是项目推荐的入门编排方式，其结构遵循标准 Compose 规范。核心字段包括 `image`、`container_name`、`privileged`（容器需要特权模式以访问 `/dev/kvm`）、`devices`、`ports` 与 `volumes`，缺一不可。容器必须挂载宿主的 KVM 设备节点才能进行硬件加速虚拟化。

Compose 文件中通过环境变量 `SHORTNAME` 控制最终使用的镜像变体（例如 `big-sur`、`monterey`、`ventura`、`sonoma`）。当 `SHORTNAME` 未在本地缓存时，`docker compose up` 会尝试从 Docker Hub 拉取对应 tag；社区中反馈的 #799 “Docker Image disappeared” 与 #858 “`naked`、`auto` 等 tag 不存在” 都是这一环节的典型失败点：仓库在 Docker Hub 上长期仅保留 `latest` 等少数 tag，自定义 `SHORTNAME` 必须通过本地 `docker build` 自行构建，或从官方/社区维护的镜像源获取。

资料来源：[docker-compose.yml:1-120]()，[README.md:40-90]()。

## Helm / Kubernetes 编排

Helm Chart 位于 `helm/` 目录，结构遵循官方 Chart 模板约定。`Chart.yaml` 定义 Chart 的元数据（`apiVersion`、`name`、`version`、`appVersion`），`values.yaml` 暴露用户级参数（镜像仓库、tag、replica 数、CPU/内存 requests/limits、持久卷声明），而 `helm/templates/deployment.yaml` 则把这些参数渲染成 Kubernetes Deployment 对象。

部署命令通常为 `helm install docker-osx ./helm -f my-values.yaml`。在 `values.yaml` 中可以调整 `image.repository`、`image.tag` 来指向内部镜像仓库，这正是解决 #799 / #858 类“镜像缺失”问题的标准做法——把镜像同步到私有仓库后由 Chart 引用即可。`helm/README.md` 详细列出了可配置项和升级注意事项，包括 `persistence.size`、`resources.limits`、以及与 KVM 透传相关的 `hostPath` 挂载。

资料来源：[helm/Chart.yaml:1-20]()，[helm/values.yaml:1-60]()，[helm/templates/deployment.yaml:1-90]()，[helm/README.md:1-80]()。

## 自定义启动盘与镜像扩展

当标准镜像无法满足版本需求时，可使用 `custom/generate-specific-bootdisk.sh` 扩展。该脚本接受 macOS 版本号与 `SHORTNAME` 作为输入，调用底层 QEMU/OpenCore 工具链生成一个特定版本的启动磁盘镜像，再叠加到基础 Docker 镜像之上。其输出可作为新的 Docker 镜像 tag 发布，或在 Helm `values.yaml` 中以 `image.tag` 形式引用，从而把“特定版本 macOS”纳入标准的编排流程。

社区请求 #487 提出的 arm64v8 支持目前并未在仓库主分支提供，扩展方案仍以 x86_64 KVM 为主；这与 #685 反馈的内核模块配置问题、ACL 解析失败、ALSA/GTK 初始化失败等诊断项一致——它们都是宿主机 KVM 环境检查脚本（`uname -a`、`grep NAME /etc/os-release`、`ls -lha /dev/kvm` 等）的输出目标，可在部署前预先排查。

资源扩展方面，社区 #688 反映默认 VRAM 仅有 7 MB，需要更高显存时应在 `docker-compose.yml` 或 Helm 模板中调整 QEMU 的 `-vga` / `-device VGA` 相关参数，并通过环境变量传入容器。

资料来源：[custom/generate-specific-bootdisk.sh:1-120]()，[README.md:90-160]()，[docker-compose.yml:80-120]()。

---

<a id='page-kvm-setup'></a>

## 主机虚拟化与运行调优

### 相关页面

相关主题：[项目概览与快速入门](#page-overview), [部署、编排与扩展](#page-infrastructure)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/sickcodes/Docker-OSX/blob/main/README.md)
- [Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/main/Dockerfile)
- [helm/INSTALL-QEMU-AND-GPU-IOMMU.md](https://github.com/sickcodes/Docker-OSX/blob/main/helm/INSTALL-QEMU-AND-GPU-IOMMU.md)
- [CHANGELOG.md](https://github.com/sickcodes/Docker-OSX/blob/main/CHANGELOG.md)
- [docker-compose.yml](https://github.com/sickcodes/Docker-OSX/blob/main/docker-compose.yml)
- [custom-name.yml](https://github.com/sickcodes/Docker-OSX/blob/main/custom-name.yml)
- [naked.yml](https://github.com/sickcodes/Docker-OSX/blob/main/naked.yml)
- [auto.yml](https://github.com/sickcodes/Docker-OSX/blob/main/auto.yml)
</details>

# 主机虚拟化与运行调优

Docker-OSX 通过 QEMU/KVM 在 Linux 主机上以容器形式运行近原生的 macOS 虚拟机。"主机虚拟化与运行调优"涵盖宿主机侧必须具备的硬件虚拟化能力、内核模块配置、CPU 与内存资源分配、GPU/IOMMU 直通以及图形显存调优等关键内容，这些参数直接决定了容器能否启动、macOS 客户机性能是否达标，以及 OpenGL/Metal 等图形加速是否可用。

## 宿主机虚拟化前提条件

项目要求宿主机 CPU 必须支持硬件虚拟化扩展，并加载对应的内核模块。在 Linux 上，这意味着 Intel CPU 需暴露 `vmx` 标志，AMD CPU 需暴露 `svm` 标志，可通过 `egrep -c '(svm|vmx)' /proc/cpuinfo` 校验 资料来源：[README.md]()。

宿主机内核必须加载 `kvm`、`kvm_intel` 或 `kvm_amd` 模块，并通过 `ls -lha /dev/kvm` 确认 KVM 设备节点对运行用户可读写 资料来源：[README.md]()。若设备权限不正确，Docker 在启动容器时需使用 `--device /dev/kvm --privileged` 或将用户加入 `kvm` 用户组 资料来源：[Dockerfile:50-70]()。

社区常见的 `ignore_msrs` 报错（如 Issue #685）通常通过执行 `echo 1 | sudo tee /sys/module/kvm/parameters/ignore_msrs` 临时绕过，该参数控制 KVM 在客户机写入未实现 MSR 寄存器时是否报错 资料来源：[README.md]()。

## CPU、内存与磁盘资源调优

`Dockerfile` 与 `docker-compose.yml` 默认通过环境变量与 QEMU 命令行为客户机分配资源：

- `RAM`：控制客户机内存大小（默认 3 GB，可上调至 8 GB 以上以改善 Xcode 编译性能） 资料来源：[Dockerfile:90-110]()。
- `CPUS`：分配给客户机的 vCPU 数量，建议与宿主机物理核心数匹配或保持 1:1 比例 资料来源：[docker-compose.yml]()。
- `DISK`：通过 QEMU 的 qcow2 或 raw 镜像作为后端存储，初始大小由镜像模板决定，后续可使用 `qemu-img resize` 扩容 资料来源：[custom-name.yml]()。

针对社区反馈的 `naked` 与 `auto` 镜像拉取失败问题（Issue #858），README 指出官方目前仅发布 `latest` 标签；用户可通过本地 `docker build -t docker-osx --build-arg SHORTNAME=sonoma .` 自行构建所需变体 资料来源：[CHANGELOG.md]()。

## GPU 直通与 IOMMU 配置

当需要为 macOS 提供硬件加速图形时，必须启用 IOMMU 并将 GPU 直通到容器。项目提供了专门的安装文档 `INSTALL-QEMU-AND-GPU-IOMMU.md`，其中关键步骤包括：

- BIOS 中启用 VT-d / AMD-Vi；
- 内核启动参数追加 `intel_iommu=on iommu=pt` 或 `amd_iommu=on`；
- 通过 `vfio-pci.ids=xxxx:xxxx` 将目标 GPU 的 vendor/device ID 绑定到 vfio-pci 驱动 资料来源：[helm/INSTALL-QEMU-AND-GPU-IOMMU.md]()。

容器启动时需使用 `--device /dev/vfio/XX:/dev/vfio/XX` 暴露 IOMMU 组设备，并配合 QEMU 的 `-device vfio-pci,host=...` 将其挂入客户机 资料来源：[Dockerfile:120-140]()。

## 显存与图形性能调优

社区对"7 MB 显存"的抱怨（Issue #688）来源于 QEMU 默认的 `virtio-vga` 设备仅暴露最小帧缓冲。可通过以下方式扩大：

- 在 QEMU 命令行追加 `-device vmware-svga` 或 `-vga none -device virtio-vga-gl`；
- 使用 `-global vmware-svga.max_outputs=1` 与 `-global vmware-svga.vram_size=X` 自定义 VRAM；
- 配合 `-display gtk,gl=on` 或 VNC/SPICE 启用硬件 OpenGL 加速 资料来源：[README.md]()。

若宿主机运行 headless 环境（如 Kubernetes/Helm 部署），可借助 EGL/GLES 后端，并通过 `LIBGL_ALWAYS_SOFTWARE=1` 兜底软渲染 资料来源：[helm/INSTALL-QEMU-AND-GPU-IOMMU.md]()。

## 架构总览

```mermaid
flowchart LR
    A[宿主机 Linux 内核] -->|加载 kvm/kvm_intel| B[/dev/kvm 设备节点]
    A -->|intel_iommu=on| C[vfio-pci 驱动]
    B --> D[Docker 容器 --privileged]
    C -->|--device /dev/vfio/*| D
    D --> E[QEMU-system-x86_64]
    E -->|CPU/RAM/DISK| F[macOS 客户机]
    E -->|vmware-svga / virtio-gpu| F
```

## 常见调优问题速查

| 现象 | 排查点 | 处理方式 |
|------|--------|----------|
| `KVM not available` | `/dev/kvm` 权限、内核模块 | 加载 `kvm_intel/amd`，加入 `kvm` 组 |
| macOS 启动卡顿 | `ignore_msrs`、CPU 拓扑 | 写入 `1` 到 `ignore_msrs`、调整 `smp` 参数 |
| 显存仅 7 MB | QEMU `-vga` 设置 | 改用 `vmware-svga` 或 `virtio-vga-gl` |
| ARM 平台无法运行 | x86_64 客户机限制 | 见 Issue #487 暂不支持，需通过远程转译 |
| Docker 镜像拉取失败 | 标签不存在 | 仅保留 `latest`，其他需本地构建 |

合理的宿主机虚拟化配置与运行调优是 Docker-OSX 性能与稳定性的根基：先保证 KVM 与 IOMMU 正确暴露，再按需分配 CPU/内存，最后通过 vfio-pci 与合适的 `-vga` 选项提升图形体验，方能完整释放近原生 macOS 的能力。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：sickcodes/Docker-OSX

摘要：发现 21 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Anyone having success with iMessage?。

## 1. 安装坑 · 来源证据：Anyone having success with iMessage?

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Anyone having success with iMessage?
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/526 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：Blank wallpaper and cannot login into apple ID.

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Blank wallpaper and cannot login into apple ID.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/904 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：Boot loop on various macOS versions - can't get past the recovery screen

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Boot loop on various macOS versions - can't get past the recovery screen
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/914 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：Can't contact recovery server from Docker-OSX during installation in a proxied environment

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Can't contact recovery server from Docker-OSX during installation in a proxied environment
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/413 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：Macos sonoma with amd RX580

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Macos sonoma with amd RX580
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/923 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：Mouse does not work

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Mouse does not work
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/844 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：QEMU Docker OSX, Mouse always not working after running 2 minutes

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：QEMU Docker OSX, Mouse always not working after running 2 minutes
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/666 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 8. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -it --device /dev/kvm -p 50922:10022 -v /tmp/.X11-unix:/tmp/.X11-unix -e "DISPLAY=${DISPLAY:-:0.0}" -e SHORTNAME=catalina sickcodes/docker-osx:latest # docker build -t docker-osx
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -it --device /dev/kvm -p 50922:10022 -v /tmp/.X11-unix:/tmp/.X11-unix -e "DISPLAY=${DISPLAY:-:0.0}" -e SHORTNAME=catalina sickcodes/docker-osx:latest # docker build -t docker-osx`
- 证据：identity.distribution | https://github.com/sickcodes/Docker-OSX | docker run -it --device /dev/kvm -p 50922:10022 -v /tmp/.X11-unix:/tmp/.X11-unix -e "DISPLAY=${DISPLAY:-:0.0}" -e SHORTNAME=catalina sickcodes/docker-osx:latest # docker build -t docker-osx

## 9. 安装坑 · 来源证据：Docker Image disappeared

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docker Image disappeared
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/799 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 10. 安装坑 · 来源证据：How to get docker-osx running on mac silicon (arm64)?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：How to get docker-osx running on mac silicon (arm64)?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/547 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 11. 安装坑 · 来源证据：MacOS Installation error pkdownloaderror 8

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MacOS Installation error pkdownloaderror 8
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/531 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 12. 安装坑 · 来源证据：The BASESYSTEM_IMAGE parameter has no effect in Launch.sh

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：The BASESYSTEM_IMAGE parameter has no effect in Launch.sh
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/918 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 安装坑 · 来源证据：The recovery server could not be contacted but has internet access

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：The recovery server could not be contacted but has internet access
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/543 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 14. 安装坑 · 来源证据：unable to start tahoe

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：unable to start tahoe
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/924 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 15. 安装坑 · 来源证据：wont boot, best way to recover?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：wont boot, best way to recover?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/sickcodes/Docker-OSX/issues/402 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 16. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/sickcodes/Docker-OSX | README/documentation is current enough for a first validation pass.

## 17. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/sickcodes/Docker-OSX | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/sickcodes/Docker-OSX | no_demo; severity=medium

## 19. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/sickcodes/Docker-OSX | no_demo; severity=medium

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/sickcodes/Docker-OSX | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/sickcodes/Docker-OSX | release_recency=unknown

<!-- canonical_name: sickcodes/Docker-OSX; human_manual_source: deepwiki_human_wiki -->