Docker Desktop 故障排除主题

提示

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

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

适用于所有平台的主题

确保证书已正确配置

Docker Desktop 会忽略不安全注册表中列出的证书，并且不会向这些注册表发送客户端证书。尝试从注册表拉取镜像的命令（如 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 的用户界面显示为绿色、失真或出现视觉伪影

Docker Desktop 默认使用硬件加速图形渲染，这可能导致某些 GPU 出现问题。在这些情况下， Docker Desktop 可以正常启动，但部分界面可能出现绿色、失真或存在视觉伪影等问题。

为解决此问题，请通过在 Docker Desktop 的 "disableHardwareAcceleration": true 文件中创建一个 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.

更新 settings-store.json 文件后，请关闭并重新启动 Docker Desktop 以应用更改。

Linux 和 Mac 主题

卷挂载要求对 $HOME 之外的任何项目目录进行文件共享

如果您使用的是挂载卷，并且在运行时遇到错误，提示未找到应用程序文件、拒绝访问卷挂载点，或服务无法启动（例如使用 Docker Compose时）， 您可能需要启用 文件共享。

卷挂载要求共享驱动器，用于位于 /home/<user> 目录之外的项目。请从 设置 中选择 资源，然后选择 文件共享。共享包含 Dockerfile 和卷的驱动器。

Docker Desktop 在 macOS 或 Linux 平台上无法启动

在 macOS 和 Linux 上，Docker Desktop 会创建用于进程间通信的 Unix 域套接字。

如果以下任一套接字的绝对路径长度超过操作系统限制（macOS 上为 104 个字符，Linux 上为 108 个字符），Docker 将无法启动。这些套接字创建于用户主目录下。若用户 ID 长度过长，导致套接字的绝对路径超出操作系统路径长度限制，则 Docker Desktop 将无法创建该套接字，从而启动失败。解决此问题的方法是缩短用户 ID，我们建议其最大长度在 macOS 上不超过 33 个字符，在 Linux 上不超过 55 个字符。

以下是MacOS系统中表示启动失败是由于超出上述操作系统限制的错误示例：

[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 相关主题

检测到不兼容的 CPU

Docker Desktop 需要处理器（CPU）支持虚拟化技术，更具体地说，需要支持 Apple Hypervisor 框架。 Docker Desktop 仅兼容配备支持 Hypervisor 框架的 CPU 的 Mac 系统。根据 Apple Hypervisor 框架文档中关于支持硬件的说明，2010 年及之后生产的大多数 Mac 均支持该框架。

通常，支持具有扩展页表（EPT）和无限制模式（Unrestricted Mode）特性的Intel VT-x功能集的计算机。

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

$ sysctl kern.hv_support

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

如果不是，则命令打印 kern.hv_support: 0。

另请参阅， Hypervisor 框架 参考文档 （Apple 文档），以及 Docker Desktop Mac 系统要求。

VPNKit 持续中断

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

要继续使用 VPNKit，请将 "networkType":"vpnkit" 添加到位于 ~/Library/Group Containers/group.com.docker/settings-store.json 的 settings-store.json 文件中。

Windows 相关主题

卷

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

当从 Windows 共享文件时，Docker Desktop 会将 共享卷 的权限设置为默认值 0777 （https://docs.docker.com/desktop/settings-and-maintenance/settings/#file-sharing、link、https://chmodcommand.com/chmod-0777/ 的权限分别对应 pl-1 icon-svg icon-sm 和 0 -960 960 960）。

共享卷的默认权限是不可配置的。如果您正在使用需要在容器运行时具有不同于共享卷默认权限的应用程序，则您需要要么使用非主机挂载卷，要么找到一种方法使应用程序能够适应默认文件权限。

另请参阅， 我能否为容器特定的部署需求更改共享卷的权限？ 常见问题解答。

挂载卷需要为 Linux 容器设置共享文件夹

如果您使用的是挂载卷，并遇到运行时错误，提示未找到应用程序文件、无法访问卷挂载点，或服务无法启动（例如使用 Docker Compose时）， 您可能需要启用 共享文件夹功能。

使用 Hyper-V 后端时，挂载 Windows 中的文件需要为 Linux 容器设置共享文件夹。请从 设置 中选择 共享文件夹，并共享包含 Dockerfile 和数据卷的文件夹。

支持符号链接

符号链接可在容器内部及跨容器使用。如需了解更多详情，请参阅 Windows 上的符号链接是如何工作的？。

避免意外的语法错误，容器中的文件请使用 Unix 风格的换行符

任何计划在容器内运行的文件都必须使用 Unix 风格的 \n 行尾符。这包括构建时在命令行中引用的文件，以及 Dockerfile 中 RUN 命令所引用的文件。

Docker 容器和 docker build 运行在 Unix 环境中，因此容器内的文件必须使用 Unix 风格的换行符：\n，而非 Windows 风格：\r\n。 在使用 Windows 工具编写文件（例如 shell 脚本）时，请注意这一点，因为这些工具的默认换行符通常是 Windows 风格。这些命令最终会被传递到基于 Unix 的容器内的 Unix 命令中（例如，传递给 /bin/sh 的 shell 脚本）。如果使用 Windows 风格的换行符，docker run 会因语法错误而失败。

有关此问题及其解决方案的示例，请参见 GitHub 上的以下问题：Docker RUN 命令无法执行 shell 脚本。

Windows 上的路径转换

在 Linux 系统中，系统会自动将一个路径挂载到另一个路径。例如，在 Linux 上运行以下命令时：

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

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

然而，在 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

Git Bash（或 MSYS）在 Windows 上提供类 Unix 环境。这些工具会对命令行进行自身的预处理。例如，如果您在 Git Bash 中运行以下命令，将出现错误：

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

这是因为 \ 字符在 Git Bash 中具有特殊含义。如果您正在使用 Git Bash，则必须使用 \\ 对其进行转义：

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

此外，在脚本中，pwd 命令用于避免硬编码文件系统路径，其输出为 Unix 风格的路径。

$ pwd
/c/Users/user/work

结合 $() 语法，以下命令在 Linux 上可以正常运行，但在 Git Bash 上会失败。

$ 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.

您可以通过使用额外的 / 来绕过此问题

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

脚本的可移植性不受影响，因为 Linux 将多个 / 视为单个条目。 同一行中的每个路径都必须被中和（neutralized）。

$ docker run --rm -ti -v /$(pwd):/work alpine ls /work
ls: C:/Program Files/Git/work: No such file or directory

在此示例中，由于前面存在 /，因此 $(pwd) 不会被转换。然而，第二个 /work 会在传递给 Docker Desktop 之前由 POSIX 层进行转换。您还可以通过使用额外的 / 来规避此问题。

$ docker run --rm -ti -v /$(pwd):/work alpine ls //work

要验证错误是来自您的脚本还是其他来源，可以使用环境变量。例如：

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

此处仅要求设置环境变量，其值无关紧要。

在某些情况下，MSYS 也会将冒号转换为分号。当使用 ~ 时同样可能触发此类转换，因为 POSIX 层会将其翻译为 DOS 路径。此时 MSYS_NO_PATHCONV 也同样适用。

虚拟化

您的计算机必须具备以下功能，Docker Desktop 才能正常运行：

WSL 2 和 Windows 家庭版

1. 虚拟机平台
2. Windows Subsystem for Linux
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 模块。 Docker Desktop 安装程序将为您自动启用这些组件。

Docker Desktop 还需要两个 CPU 硬件功能才能使用 Hyper-V：虚拟化（Virtualization）和二级地址转换（SLAT），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 启动时已启用虚拟机监控程序（Hypervisor）

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

1. 打开管理控制台命令提示符。
2. 运行 bcdedit /set hypervisorlaunchtype auto。
3. 重启 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 容器和 Windows Server

Docker Desktop 不支持 Windows Server。如果您有关于如何在 Windows 10 上运行 Windows 容器的问题，请参阅 在 Windows 和 Linux 容器之间切换。

完整的教程可在 docker/labs 和 Windows容器入门中找到。

您可以安装原生 Windows Binaries，以便在不使用 Docker Desktop 的情况下开发和运行 Windows 容器。然而，若以这种方式安装 Docker，则无法开发或运行 Linux 容器。如果您尝试在原生 Docker 守护进程中运行 Linux 容器，将出现错误：

C:\Program Files\Docker\docker.exe:
 image operating system "linux" cannot be used on this platform.
 See 'C:\Program Files\Docker\docker.exe run --help'.

Docker Desktop Access Denied 启动 Docker Desktop 时的错误消息

如果 Windows 用户不属于 docker-users 组，Docker Desktop 将显示 Docker Desktop - 访问被拒绝 错误。

如果您的管理员账户与您的用户账户不同，请将用户添加到docker-users组。以管理员身份运行计算机管理，然后导航至本地用户和组 > 组 > docker-users。

右键单击，将用户添加到组中。注销后重新登录以使更改生效。