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 和卷挂载路径的文件夹。

port already allocated 错误

错误消息

启动容器时，可能会看到以下错误

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 domain socket 路径长度限制而启动失败

[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 domain socket。这些 socket 在用户主目录下创建。

Unix domain socket 的最大路径长度为

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

如果你的主目录路径太长，Docker Desktop 将无法创建必要的 socket。

解决方案

确保你的用户名足够短，以便路径保持在允许的限制范围内

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

Mac 的主题

持续通知提示某个应用程序更改了我的 Desktop 配置

原因

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

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

解决方案

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

如果你想关闭配置完整性检查通知，请导航到 Docker Desktop 的设置，并在常规标签页中，取消勾选自动检查配置设置。

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

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

检测到不兼容的 CPU

原因

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

解决方案

检查是否

• 你已安装了适用于你的架构的正确 Docker Desktop 版本

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

  $ sysctl kern.hv_support
  

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

  否则，该命令将打印 kern.hv_support: 0。

另请参阅 Apple 文档中的Hypervisor Framework Reference，以及 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（user 和 group 的 read、write、execute 权限）。

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

解决方案

如果你使用的应用程序需要不同的权限，可以

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

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

原因

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

使用 Windows 工具编写 shell 脚本等文件时请记住这一点，Windows 工具的默认行结束符很可能是 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

Docker 命令在 Git Bash 中失败

错误消息

$ 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 因虚拟化设置而失败

原因

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

解决方案

你的机器必须具备以下功能，Docker Desktop 才能正常运行

WSL 2 和 Windows Home

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

Hyper-V

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

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

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

Docker Desktop 还需要两项 CPU 硬件功能才能使用 Hyper-V：虚拟化（Virtualization）和二级地址转换（Second Level Address Translation，SLAT），SLAT 也称为快速虚拟化索引（Rapid Virtualization Indexing，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 Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed，则表示已启用虚拟化。

如果您手动卸载 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

尝试启用嵌套虚拟化。

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

错误消息

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

Docker Desktop - Access Denied

原因

用户不是 docker-users 组的一部分，而该组是权限所必需的。

解决方案

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

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