在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

sickcodes/Docker-OSX

菜单

故障排除

相关源文件

本页面提供了使用 Docker-OSX 时遇到常见问题的诊断和解决的全面指南。我们将涵盖安装问题、运行时错误、性能问题和特定于平台的疑难解答。有关不同镜像变体及其特定配置选项的信息，请参阅镜像变体。

诊断信息收集

在对 Docker-OSX 问题进行故障排除或寻求社区帮助时，使用以下命令收集系统信息会很有帮助

来源: .github/ISSUE_TEMPLATE/issue-running-docker-osx.md11-26

常见问题与解决方案

Docker Engine未运行

症状: Docker 命令失败，出现类似 无法连接到 Docker daemon 或 docker: command not found 的错误。

解决方案

  1. 如果 Docker 未安装，请安装 Docker Desktop（适用于 Windows/macOS）或使用您 Linux 发行版的包管理器
  2. 如果 Docker 已安装但未运行
  3. 如果您遇到权限问题

来源: FAQ.md75-85

虚拟化问题

KVM 错误

症状: 启动 Docker-OSX 时出现错误消息 error gathering device information while adding custom device "/dev/kvm": no such file or directory。

原因

  • BIOS/UEFI 中未启用虚拟化
  • KVM 模块未加载到内核中
  • 云虚拟机不支持嵌套虚拟化
  • /dev/kvm 权限问题

解决方案

  1. 在 BIOS/UEFI 中启用虚拟化（Intel 为 VT-x，AMD 为 AMD-V）
  2. 加载 KVM 模块
  3. 将您的用户添加到 KVM 组
  4. 对于云环境，请检查您的提供商是否支持嵌套虚拟化

来源: FAQ.md89-91

显示和图形问题

GTK 初始化失败

症状: 启动 Docker-OSX 时出现与 X11 显示相关的错误消息：GTK initialization failed。

原因: X11 连接问题或显示服务器的权限问题。

解决方案

  1. 允许连接到您的 X 服务器
  2. 使用 VNC 而不是 X11（请参阅 README 的此部分 进行说明）

来源: FAQ.md83-87

音频问题

ALSA 错误

症状: 启动 Docker-OSX 时出现此类错误

ALSA lib confmisc.c:767:(parse_card) cannot find card '0'
ALSA lib conf.c:4745:(_snd_config_evaluate) function snd_func_card_driver returned error: No such file or directory
...
audio: Failed to create voice 'adc'

解决方案

  1. 如果您的主机使用 PulseAudio 而不是 ALSA
  2. 如果您不需要音频
  3. 对于 WSL 上的 PulseAudio

来源: FAQ.md93-145

安装和启动问题

没有可供安装的磁盘

症状: 在 macOS 安装程序中没有显示磁盘来安装操作系统。

解决方案: 您需要先格式化虚拟磁盘

  1. 在 macOS 安装程序中，打开磁盘工具
  2. 选择“视图” > “显示所有设备”
  3. 选择 QEMU 磁盘
  4. 点击“抹掉”并格式化为 APFS
  5. 格式化后，退出磁盘工具并继续安装

来源: FAQ.md147-149

安装缓慢

症状: macOS 安装进度似乎非常慢或似乎已冻结。

解决方案: 请耐心等待。macOS 安装过程会给出不准确的时间估计，并且可能长时间看起来冻结。虚拟机中的安装可能需要数小时。

来源: FAQ.md151-153

安装完成后的安装程序

症状: 安装完成后，系统会重新启动到安装程序，而不是启动到 macOS。

解决方案: 您正在从安装磁盘启动，而不是从已安装的系统磁盘启动。重启并选择正确的磁盘启动。

来源: FAQ.md155-157

性能问题

UI 性能缓慢

症状: macOS UI 非常迟缓或无响应。

原因: macOS UI 依赖 GPU 加速，而虚拟机中无法获得 GPU 加速。

解决方案

  1. 为虚拟机分配更多资源
  2. 使用 osx-optimizer 来优化 macOS 以便在虚拟机中使用
  3. 通过系统偏好设置减少 macOS 中的视觉效果

来源: FAQ.md163-165

磁盘空间问题

症状: 主机磁盘空间不足。

解决方案

  1. 查找 VM 磁盘镜像
  2. 将 Docker 存储移动到更大的驱动器（请参阅 README)

来源: FAQ.md171-173

iServices 和序列号问题

症状: iMessage、FaceTime、App Store 或其他 Apple 服务无法通过身份验证。

解决方案

  1. 生成唯一的序列号
  2. 使序列号在重启之间持久化

来源: FAQ.md32-34

平台特定问题

Windows with WSL2

要求

  • Windows 11（不支持 Windows 10）
  • 已安装并正确配置 WSL2
  • 适用于 Windows 的 X 服务器或 WSLg

常见问题

  • 显示配置问题
  • 音频直通挑战
  • 性能限制

解决方案: 请参阅 README 中的Windows 安装部分 中的详细说明。

来源: FAQ.md57-59

macOS 主机

常见问题

  • 嵌套虚拟化限制
  • 性能问题

推荐

  • 对于 Apple Silicon Mac，请使用 UTM
  • 对于 Intel Mac，请考虑直接使用带有 HVF 加速的 QEMU

来源: FAQ.md61-65

云服务

限制: 大多数云提供商在其标准虚拟机中不支持嵌套虚拟化，这使得 Docker-OSX 难以或不可能运行。

可能的解决方案: 寻找提供直接硬件访问的“裸金属”实例类型。

来源: FAQ.md67-71

故障排除工作流程

当遇到 Docker-OSX 的问题时，遵循结构化的故障排除方法有助于有效识别和解决问题

系统架构和问题点

该图说明了 Docker-OSX 的架构和常见的故障点

获取帮助

如果在尝试上述故障排除步骤后仍遇到问题

  1. 使用本页面开头的命令收集诊断信息
  2. 检查您的问题是否已记录在 FAQ
  3. 在 GitHub 仓库 打开一个问题
  4. 请务必包含
    • 主机操作系统和版本
    • Docker 版本
    • 您正在使用的 Docker-OSX 镜像变体
    • 完整的错误消息
    • 重现问题的步骤

来源: FAQ.md160-178 .github/ISSUE_TEMPLATE/open-an-issue.md1-10

资源分配以获得更好的性能

要提高性能，您可以在创建 Docker-OSX 容器时自定义资源分配

参数描述使用示例
内存内存分配（MB）-e RAM=8192
SMPCPU 线程数-e SMP=4
CORESCPU 核心数-e CORES=2
DISPLAYX11 显示目标-e DISPLAY=:0
AUDIO_DRIVER要使用的音频子系统-e AUDIO_DRIVER="pa"
GENERATE_UNIQUE生成唯一的序列号-e GENERATE_UNIQUE=true
NOPICKER跳过启动选择器-e NOPICKER=1

来源： FAQ.md175-177