Docker Desktop 的故障排除主题

故障排除
目录

提示

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

所有平台的主题

确保证书已正确设置

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-store.json 文件（或 Docker Desktop 4.34 及更早版本中的 settings.json 文件）中创建一个 "disableHardwareAcceleration": true 条目来禁用硬件加速。您可以在此处找到此文件：

  • 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将无法启动。这些套接字在用户的home目录下创建。如果用户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需要支持虚拟化，更具体地说，需要支持Apple Hypervisor框架的处理器（CPU）。Docker Desktop仅与具有支持Hypervisor框架的CPU的Mac系统兼容。根据Apple Hypervisor框架文档中对支持硬件的描述，大多数2010年及以后制造的Mac都支持它。

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

要检查您的Mac是否支持Hypervisor框架，请在终端窗口中运行以下命令：sysctl -a | grep kern.hv_support

$ 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及更高版本上使用虚拟化框架时的虚拟机网络性能。

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

Windows 的主题

卷

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

从Windows共享文件时，Docker Desktop会将共享卷上的权限设置为默认值0777（对用户和组具有read、write、execute权限）。

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

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

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

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

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

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

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

任何要在容器内运行的文件都必须使用Unix风格的\n行尾。这包括命令行中引用的用于构建的文件以及Docker文件中的RUN命令中的文件。

Docker容器和docker build在Unix环境中运行，因此容器中的文件必须使用Unix风格的行尾：\n，而不是Windows风格的：\r\n。在使用Windows工具（其默认值可能是Windows风格的行尾）创作文件（如shell脚本）时，请记住这一点。这些命令最终会被传递到基于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)不会被转换。但是，在传递给Docker Desktop之前，POSIX层会转换第二个'/work'。您也可以通过使用额外的/来解决此问题。

$ 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子系统Linux
  3. BIOS 中已启用虚拟化 请注意，许多 Windows 设备已启用虚拟化，因此此项可能不适用。
  4. Windows 启动时启用虚拟机管理程序
WSL 2 enabled

Hyper-V

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

  1. Hyper-V 已安装并运行
  2. BIOS 中已启用虚拟化 请注意，许多 Windows 设备已启用虚拟化，因此此项可能不适用。
  3. Windows 启动时启用虚拟机管理程序
Hyper-V on Windows features

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 要求：已检测到虚拟机管理程序。Hyper-V所需的功能将不会显示”，则表示已启用虚拟化。

Task Manager

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

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

Windows 启动时启用虚拟机管理程序

如果您已完成上述步骤但仍遇到 Docker Desktop 启动问题，这可能是因为已安装虚拟机管理程序，但在 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。

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