Docker Desktop 故障排除主题

提示

如果您在故障排除中未找到解决方案，请浏览 GitHub 存储库或创建新问题

• docker/for-mac
• docker/for-win
• docker/for-linux

所有平台主题

证书设置不正确

错误信息

尝试使用 docker run 从注册表拉取时，您可能会遇到以下错误

Error response from daemon: Get http://192.168.203.139:5858/v2/: malformed HTTP response "\x15\x03\x01\x00\x02\x02"

此外，注册表日志可能会显示

2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52882: tls: client didn't provide a certificate
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52883: tls: first record does not look like a TLS handshake

可能原因

• Docker Desktop 忽略了不安全注册表下列出的证书。
• 客户端证书未发送到不安全注册表，导致握手失败。

解决方案

• 确保您的注册表已正确配置有效 SSL 证书。
• 如果您的注册表是自签名的，请通过将其添加到 Docker 的证书目录（Linux 上为 /etc/docker/certs.d/）来配置 Docker 信任该证书。
• 如果问题仍然存在，请检查您的 Docker 守护程序配置并启用 TLS 身份验证。

Docker Desktop UI 显示绿色、失真或有视觉伪影

原因

Docker Desktop 默认使用硬件加速图形，这可能会导致某些 GPU 出现问题。

解决方案

禁用硬件加速

1. 编辑 Docker Desktop 的 settings-store.json 文件（对于 Docker Desktop 4.34 及更早版本，则为 settings.json）。您可以在以下位置找到此文件：

   • Mac: ~/Library/Group Containers/group.com.docker/settings-store.json
   • Windows: C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json
   • Linux: ~/.docker/desktop/settings-store.json.

2. 添加以下条目

   $ "disableHardwareAcceleration": true

3. 保存文件并重新启动 Docker Desktop。

使用挂载卷时遇到运行时错误，指示找不到应用程序文件，拒绝访问卷挂载，或服务无法启动

原因

如果您的项目目录位于您的主目录（/home/<user>）之外，Docker Desktop 需要文件共享权限才能访问它。

解决方案

在 Mac 和 Linux 上启用 Docker Desktop 的文件共享

1. 导航到设置，选择资源，然后选择文件共享。
2. 添加包含 Dockerfile 和卷挂载路径的驱动器或文件夹。

在 Windows 上启用 Docker Desktop 的文件共享

1. 从设置中，选择共享文件夹。
2. 共享包含 Dockerfile 和卷挂载路径的文件夹。

端口已被分配错误

错误信息

启动容器时，您可能会看到类似以下的错误：

Bind for 0.0.0.0:8080 failed: port is already allocated

或者

listen tcp:0.0.0.0:8080: bind: address is already in use

原因

• 系统上的另一个应用程序已在使用指定的端口。
• 之前运行的容器未正确停止，仍绑定到该端口。

解决方案

要发现此软件的身份，请执行以下操作之一：

• 使用 resmon.exe GUI，选择网络，然后选择侦听端口
• 在 PowerShell 中，使用 netstat -aon | find /i "listening " 查找当前使用该端口的进程的 PID（PID 是最右侧列中的数字）。

然后，决定是关闭其他进程，还是在 Docker 应用程序中使用不同的端口。

Linux 和 Mac 主题

Docker Desktop 在 Mac 或 Linux 平台上启动失败

错误信息

Docker 因 Unix 域套接字路径长度限制而无法启动

[vpnkit-bridge][F] listen unix <HOME>/Library/Containers/com.docker.docker/Data/http-proxy-control.sock: bind: invalid argument

[com.docker.backend][E] listen(vsock:4099) failed: listen unix <HOME>/Library/Containers/com.docker.docker/Data/vms/0/00000002.00001003: bind: invalid argument

原因

在 Mac 和 Linux 上，Docker Desktop 创建用于进程间通信的 Unix 域套接字。这些套接字在用户的主目录下创建。

Unix 域套接字具有最大路径长度

• Mac 上为 104 个字符
• Linux 上为 108 个字符

如果您的主目录路径太长，Docker Desktop 将无法创建必要的套接字。

解决方案

确保您的用户名足够短，以使路径在允许的限制内

• Mac：用户名应 ≤ 33 个字符
• Linux：用户名应 ≤ 55 个字符

Mac 主题

升级需要管理员权限

原因

在 macOS 上，没有管理员权限的用户无法从 Docker Desktop 仪表板执行应用程序内升级。

解决方案

重要

升级前请勿卸载当前版本。这样做会删除所有本地 Docker 容器、镜像和卷。

升级 Docker Desktop

• 请管理员将新版本安装到现有版本之上。
• 如果适合您的设置，请使用 []--user 安装标志](/manuals/desktop/setup/install/mac-install.md#security-and-access)。

持续通知提示应用程序已更改我的桌面配置

原因

您收到此通知是因为“配置完整性检查”功能检测到第三方应用程序已更改您的 Docker Desktop 配置。这通常是由于不正确或丢失的符号链接造成的。此通知可确保您了解这些更改，以便您可以查看和修复任何潜在问题以维护系统可靠性。

打开通知会弹出一个窗口，提供有关检测到的完整性问题的详细信息。

解决方案

如果您选择忽略通知，它只会在下次 Docker Desktop 启动时再次显示。如果您选择修复配置，则不会再次收到提示。

如果您想关闭“配置完整性检查”通知，请导航到 Docker Desktop 的设置，然后在“常规”选项卡中，清除“自动检查配置”设置。

退出应用程序后，com.docker.vmnetd仍在运行

特权帮助程序进程 com.docker.vmnetd 由 launchd 启动并在后台运行。除非 Docker.app 连接到它，否则该进程不消耗任何资源，因此可以安全地忽略。

检测到不兼容的 CPU

原因

Docker Desktop 需要支持虚拟化，更具体地说，支持 Apple Hypervisor 框架的处理器 (CPU)。

解决方案

检查

• 您已为您的架构安装了正确的 Docker Desktop 版本

• 您的 Mac 支持 Apple 的 Hypervisor 框架。要检查您的 Mac 是否支持 Hypervisor 框架，请在终端窗口中运行以下命令。

  $ sysctl kern.hv_support
  

  如果您的 Mac 支持 Hypervisor 框架，该命令将打印 kern.hv_support: 1。

  如果不支持，该命令将打印 kern.hv_support: 0。

另请参阅 Apple 文档中的 Hypervisor Framework 参考，以及 Docker Desktop Mac 系统要求。

VPNKit 不断出现故障

原因

在 Docker Desktop 4.19 版中，gVisor 取代了 VPNKit，以在使用 macOS 13 及更高版本上的虚拟化框架时提高 VM 网络的性能。

解决方案

要继续使用 VPNKit

1. 打开位于 ~/Library/Group Containers/group.com.docker/settings-store.json 的 settings-store.json 文件

2. 添加

   $ "networkType":"vpnkit"

3. 保存文件并重新启动 Docker Desktop。

Windows 主题

安装防病毒软件后 Docker Desktop 启动失败

原因

某些防病毒软件可能与 Hyper-V 和 Microsoft Windows 10 版本不兼容。冲突通常发生在 Windows 更新之后，表现为 Docker 守护程序的错误响应和 Docker Desktop 启动失败。

解决方案

作为临时解决方法，卸载防病毒软件，或将 Docker 添加到防病毒软件的排除/例外列表中。

共享卷数据目录上的权限错误

原因

从 Windows 共享文件时，Docker Desktop 会将 共享卷的权限设置为默认值 0777（用户和组的读、写、执行权限）。

共享卷的默认权限不可配置。

解决方案

如果您正在使用需要不同权限的应用程序，请执行以下操作之一：

• 使用非主机挂载卷
• 找到一种方法使应用程序与默认文件权限一起工作

意外的语法错误，容器中的文件使用 Unix 风格的行尾

原因

Docker 容器期望 Unix 风格的行结束符 \n，而不是 Windows 风格的 \r\n。这包括在命令行中用于构建的文件以及 Dockerfile 中 RUN 命令中引用的文件。

在使用 Windows 工具编写 shell 脚本等文件时，请记住这一点，因为默认情况下可能会是 Windows 风格的行结束符。这些命令最终会传递给基于 Unix 的容器内的 Unix 命令（例如，传递给 /bin/sh 的 shell 脚本）。如果使用 Windows 风格的行结束符，docker run 将因语法错误而失败。

解决方案

• 使用以下方式将文件转换为 Unix 风格的行结束符

  $ dos2unix script.sh
  

• 在 VS Code 中，将行结束符设置为 LF (Unix) 而不是 CRLF (Windows)。

Windows 上的路径转换错误

原因

与 Linux 不同，Windows 需要显式路径转换才能进行卷挂载。

在 Linux 上，系统会处理将一个路径挂载到另一个路径。例如，当您在 Linux 上运行以下命令时

$ docker run --rm -ti -v /home/user/work:/work alpine

它会向目标容器添加一个 /work 目录以镜像指定的路径。

解决方案

更新源路径。例如，如果您使用旧版 Windows shell (cmd.exe)，则可以使用以下命令

$ docker run --rm -ti -v C:\Users\user\work:/work alpine

这将启动容器并确保卷可用。这之所以可行，是因为 Docker Desktop 会检测 Windows 风格的路径并提供适当的转换以挂载目录。

Docker Desktop 还允许您使用 Unix 风格的路径转换为适当的格式。例如：

$ docker run --rm -ti -v /c/Users/user/work:/work alpine ls /work

Git Bash 中 Docker 命令失败

错误信息

$ docker run --rm -ti -v C:\Users\user\work:/work alpine
docker: Error response from daemon: mkdir C:UsersUserwork: Access is denied.

$ docker run --rm -ti -v $(pwd):/work alpine
docker: Error response from daemon: OCI runtime create failed: invalid mount {Destination:\Program Files\Git\work Type:bind Source:/run/desktop/mnt/host/c/Users/user/work;C Options:[rbind rprivate]}: mount destination \Program Files\Git\work not absolute: unknown.

原因

Git Bash（或 MSYS）在 Windows 上提供了一个类似 Unix 的环境。这些工具会在命令行上应用自己的预处理。

这会影响 $(pwd)、冒号分隔的路径和波浪号 (~)

此外，\ 字符在 Git Bash 中具有特殊含义。

解决方案

• 暂时禁用 Git Bash 路径转换。例如，运行带有 MSYS 路径转换禁用功能的命令

  $ MSYS_NO_PATHCONV=1 docker run --rm -ti -v $(pwd):/work alpine
  

• 使用正确的路径格式
  • 使用双斜杠和反斜杠（\\ //）而不是单个（\ /）。
  • 如果引用 $(pwd)，请添加一个额外的 /

脚本的可移植性不受影响，因为 Linux 将多个 / 视为单个条目。

Docker Desktop 因虚拟化未工作而失败

错误信息

一个典型的错误消息是“Docker Desktop - 意外的 WSL 错误”，其中提及错误代码 Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED。手动执行 wsl 命令也会因相同的错误代码而失败。

原因

• BIOS 中禁用了虚拟化设置。
• 缺少 Windows Hyper-V 或 WSL 2 组件。

请注意，某些第三方软件（如 Android 模拟器）会在安装时禁用 Hyper-V。

解决方案

您的机器必须具有以下功能才能使 Docker Desktop 正常运行

WSL 2 和 Windows 家庭版

1. 虚拟机平台
2. 适用于 Linux 的 Windows 子系统
3. BIOS 中启用了虚拟化 请注意，许多 Windows 设备已经启用了虚拟化，因此这可能不适用。
4. Windows 启动时启用 Hypervisor

必须能够无错误地运行 WSL 2 命令，例如

PS C:\users\> wsl -l -v
  NAME              STATE           VERSION
* Ubuntu            Running         2
  docker-desktop    Stopped         2
PS C:\users\> wsl -d docker-desktop echo WSL 2 is working
WSL 2 is working

如果功能已启用但命令不工作，请首先检查虚拟化已打开，然后根据需要在 Windows 启动时启用 Hypervisor。如果在虚拟机中运行 Docker Desktop，请确保hypervisor 已启用嵌套虚拟化。

Hyper-V

在 Windows 10 专业版或企业版上，您还可以使用启用以下功能的 Hyper-V：

1. Hyper-V 已安装并正常工作
2. BIOS 中启用了虚拟化 请注意，许多 Windows 设备已经启用了虚拟化，因此这可能不适用。
3. Windows 启动时启用 Hypervisor

Docker Desktop 需要安装并启用 Hyper-V 以及适用于 Windows PowerShell 的 Hyper-V 模块。Docker Desktop 安装程序会自动为您启用它们。

Docker Desktop 还需要两个 CPU 硬件功能才能使用 Hyper-V：虚拟化和二级地址转换 (SLAT)，也称为快速虚拟化索引 (RVI)。在某些系统上，必须在 BIOS 中启用虚拟化。所需的步骤因供应商而异，但通常 BIOS 选项被称为 Virtualization Technology (VTx) 或类似名称。运行命令 systeminfo 以检查所有必需的 Hyper-V 功能。有关更多详细信息，请参阅 Windows 10 上 Hyper-V 的先决条件。

要手动安装 Hyper-V，请参阅 在 Windows 10 上安装 Hyper-V。安装后需要重启。如果未重启就安装 Hyper-V，Docker Desktop 将无法正常工作。

从开始菜单，键入打开或关闭 Windows 功能并按 Enter。在随后的屏幕中，验证 Hyper-V 是否已启用。

必须开启虚拟化

除了 Hyper-V 或 WSL 2，虚拟化必须开启。检查任务管理器上的“性能”选项卡。或者，您可以在终端中键入 systeminfo。如果您看到 Hyper-V 要求：已检测到 Hypervisor。Hyper-V 所需功能将不会显示，则表示虚拟化已启用。

如果手动卸载 Hyper-V、WSL 2 或关闭虚拟化，Docker Desktop 将无法启动。

要开启嵌套虚拟化，请参阅在 VM 或 VDI 环境中运行 Windows 版 Docker Desktop。

Windows 启动时启用 Hypervisor

如果您已完成上述步骤但 Docker Desktop 仍存在启动问题，这可能是因为 Hypervisor 已安装，但在 Windows 启动时未启动。某些工具（例如旧版 Virtual Box）和视频游戏安装程序会在启动时关闭 Hypervisor。要重新打开它：

1. 打开管理控制台提示符。
2. 运行 bcdedit /set hypervisorlaunchtype auto。
3. 重启 Windows。

您还可以参考有关代码流防护 (CFG) 设置的 Microsoft TechNet 文章。

开启嵌套虚拟化

如果您在使用 Hyper-V 并在 VDI 环境中运行 Docker Desktop 时收到以下错误消息

The Virtual Machine Management Service failed to start the virtual machine 'DockerDesktopVM' because one of the Hyper-V components is not running

尝试启用嵌套虚拟化。

带有 Windows 容器的 Docker Desktop 失败，并显示“介质写保护”错误

错误信息

FSCTL_EXTEND_VOLUME \\?\Volume{GUID}: 介质写保护

原因

如果您在使用 Windows 容器运行 Docker Desktop 时遇到故障，这可能是由于特定的 Windows 配置策略：FDVDenyWriteAccess。

此策略启用后，会导致 Windows 将所有未受 BitLocker 加密的固定驱动器挂载为只读。这也会影响虚拟机卷，因此 Docker Desktop 可能无法正确启动或运行容器，因为它需要对这些卷的读写访问权限。

FDVDenyWriteAccess 是一项 Windows 组策略设置，启用后会阻止对未受 BitLocker 保护的固定数据驱动器进行写入访问。这通常用于注重安全的环境，但可能会干扰 Docker 等开发工具。在 Windows 注册表中，可以在 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Policies\Microsoft\FVE\FDVDenyWriteAccess 找到它。

解决方案

Docker Desktop 不支持在启用 FDVDenyWriteAccess 的系统上运行 Windows 容器。此设置会干扰 Docker 正确挂载卷的能力，这对于容器功能至关重要。

要将 Docker Desktop 与 Windows 容器一起使用，请确保 FDVDenyWriteAccess 已禁用。您可以在注册表或通过组策略编辑器 (gpedit.msc) 检查和更改此设置，路径为

计算机配置 > 管理模板 > Windows 组件 > BitLocker 驱动器加密 > 固定数据驱动器 > 拒绝向未受 BitLocker 保护的固定驱动器写入访问权限

注意

修改组策略设置可能需要管理员权限，并应遵守您组织的 IT 策略。如果设置在一段时间后重置，这通常意味着它被您的 IT 部门的集中配置覆盖。在进行任何更改之前，请与他们沟通。

启动 Docker Desktop 时出现“Docker Desktop Access Denied”错误消息

错误信息

启动 Docker Desktop 时，出现以下错误：

Docker Desktop - Access Denied

原因

用户不属于 docker-users 组，而该组是权限所必需的。

解决方案

如果您的管理员帐户与您的用户帐户不同，请添加它

1. 以管理员身份运行计算机管理。
2. 导航到本地用户和组 > 组 > docker-users。
3. 右键单击以将用户添加到组中。
4. 注销并重新登录以使更改生效