Docker Desktop 排查主题

Table of contents

Tip

如果在排查过程中未找到解决方案，请浏览 GitHub 仓库或创建新问题。

所有平台的主题

证书未正确设置

错误消息

尝试从注册表拉取镜像时，可能会遇到以下错误：

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 守护进程配置并启用 TLS 身份验证。

Docker Desktop 的 UI 显示为绿色、失真或出现视觉伪影

原因

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

解决方案

禁用硬件加速：

编辑 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.
添加以下条目：
$ "disableHardwareAcceleration": true
保存文件并重启 Docker Desktop。

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

原因

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

解决方案

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

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

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

从设置中选择 共享文件夹。
共享包含 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 平台上无法启动

错误消息

由于 Unix 域套接字路径长度限制，Docker 无法启动：

[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 仪表板执行应用内升级。

解决方案

Important

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

要升级 Docker Desktop：

请管理员将新版本安装到现有版本之上。
如果适合您的设置，请使用 --user 安装标志。

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

原因

您收到此通知是因为配置完整性检查功能检测到第三方应用程序已更改您的 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 框架参考以及 Docker Desktop Mac 系统要求。

VPNKit 不断中断

原因

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

解决方案

要继续使用 VPNKit：

打开位于 ~/Library/Group Containers/group.com.docker/settings-store.json 的 settings-store.json 文件
添加：
$ "networkType":"vpnkit"
保存文件并重启 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 上的路径转换错误

解决方案

更新源路径。例如，如果您使用的是传统的 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 家庭版

虚拟机平台
Windows Subsystem for Linux
BIOS 中启用虚拟化注意，许多 Windows 设备已经启用了虚拟化，因此这可能不适用。
在 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：

Hyper-V 已安装并正常工作
BIOS 中启用虚拟化注意，许多 Windows 设备已经启用了虚拟化，因此这可能不适用。
在 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 功能并按回车。在随后的屏幕中，验证 Hyper-V 是否已启用。

必须启用虚拟化

除了启用 Hyper-V 或 WSL 2 之外，还必须开启虚拟化功能。请检查任务管理器中的“性能”选项卡。或者，您也可以在终端中输入 systeminfo 命令。如果您看到提示信息“Hyper-V 要求: 已检测到虚拟机监控程序。将不会显示 Hyper-V 所需的功能”，则表示虚拟化已启用。

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

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

在 Windows 启动时启用虚拟机监控程序

如果您已完成上述步骤，但仍遇到 Docker Desktop 启动问题，这可能是因为虚拟机监控程序已安装，但在 Windows 启动时未启动。某些工具（例如旧版本的 Virtual Box）和视频游戏安装程序会在启动时关闭虚拟机监控程序。要重新启用它，请执行以下操作：

以管理员身份打开控制台提示符。
运行 bcdedit /set hypervisorlaunchtype auto。
重启 Windows。

您还可以参考 Microsoft TechNet 文章中关于代码流防护（CFG）设置的说明。

开启嵌套虚拟化

如果您在使用 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 出现“The media is write protected”错误

错误消息

FSCTL_EXTEND_VOLUME \\?\Volume{GUID}: The media is write protected

原因

如果您在使用 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 保护的固定驱动器

Note

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

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

错误消息

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

Docker Desktop - Access Denied

原因

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

解决方案

如果您的管理员账户与用户账户不同，请将其添加到 docker-users 组：

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

Ask me about Docker

Docker Desktop 排查主题