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 的 UI 出现绿色、扭曲或出现视觉伪像

Docker Desktop 默认情况下使用硬件加速图形，这可能会导致某些 GPU 出现问题。在这种情况下，Docker Desktop 会成功启动，但某些屏幕可能会出现绿色、扭曲或出现一些视觉伪像。

要解决此问题，请通过在 Docker Desktop 的 settings.json 文件中创建一个 "disableHardwareAcceleration": true 条目来禁用硬件加速。您可以在以下位置找到此文件：

• Mac：~/Library/Group Containers/group.com.docker/settings.json
• Windows：C:\Users\[用户名]\AppData\Roaming\Docker\settings.json
• Linux：~/.docker/desktop/settings.json.

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

适用于 Linux 和 Mac 的主题

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

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

卷挂载需要为位于 /home/<用户> 目录之外的项目共享驱动器。从 **设置** 中，选择 **资源**，然后选择 **文件共享**。共享包含 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 Framework 文档中所述，大多数 2010 年及以后制造的 Mac 都支持它，

通常，具有包含扩展页表 (EPT) 和不受限制模式的 Intel VT-x 功能集的机器受支持。

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

$ sysctl kern.hv_support

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

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

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

VPNKit 不断断开连接

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

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

适用于 Windows 的主题

卷

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

从 Windows 共享文件时，Docker Desktop 会将 共享卷 上的权限设置为默认值为 0777（read、write、execute 权限适用于 user 和 group）。

共享卷上的默认权限不可配置。如果您正在使用需要与容器运行时共享卷默认值不同的权限的应用程序，您需要使用非主机挂载卷，或者找到一种方法使应用程序能够使用默认文件权限。

另请参阅常见问题解答中的 我可以在共享卷上更改权限以满足特定于容器的部署要求吗？。

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

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

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

对符号链接的支持

符号链接在容器内和跨容器之间均有效。要了解更多信息，请参阅 符号链接如何在 Windows 上工作？。

避免意外的语法错误，对容器中的文件使用 Unix 样式的行尾

任何旨在在容器内运行的文件都必须使用 Unix 样式的 \n 行尾。这包括在命令行中为构建引用的文件以及 Dockerfile 中的 RUN 命令中的文件。

Docker 容器和 docker build 在 Unix 环境中运行，因此容器中的文件必须使用 Unix 样式的行尾：\n，而不是 Windows 样式：\r\n。在使用 Windows 工具（例如，使用 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 将多个 / 视为单个条目。同一行上的每个路径出现都要进行中和。

$ 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. 适用于 Linux 的 Windows 子系统
3. BIOS 中启用了虚拟化
4. Windows 启动时启用了虚拟机监视器

Hyper-V

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

1. Hyper-V 已安装并正常运行
2. BIOS 中启用了虚拟化
3. Windows 启动时启用了虚拟机监视器

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 将无法启动。

要启用嵌套虚拟化，请参阅 在 VM 或 VDI 环境中运行 Docker Desktop for Windows.

Windows 启动时启用了虚拟机监视器

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

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 二进制文件，它允许您在没有 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 时出现 Docker Desktop 访问被拒绝 错误消息

如果 Windows 用户不是 docker-users 组的成员，Docker Desktop 会显示 Docker Desktop - 访问被拒绝 错误。

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

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