Docker Desktop 主题疑难解答

提示

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

• docker/for-mac
• Docker/共赢
• 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 将成功启动，但某些屏幕可能会显示绿色、扭曲或出现一些视觉伪影。

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

• 苹果：~/Library/Group Containers/group.com.docker/settings.json
• Windows：C:\Users\[USERNAME]\AppData\Roaming\Docker\settings.json
• Linux：~/.docker/desktop/settings.json.

更新文件后settings.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 系统兼容。大多数 2010 年及以后生产的 Mac 都支持它，如 Apple Hypervisor Framework 文档中有关受支持硬件的描述：

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

要检查您的 Mac 是否支持虚拟机管理程序框架，请在终端窗口中运行以下命令。

$ sysctl kern.hv_support

如果您的 Mac 支持虚拟机管理程序框架，该命令将打印 kern.hv_support: 1.

如果没有，该命令将打印kern.hv_support: 0。

另请参阅 Apple 文档中的 虚拟机管理程序框架参考和 Docker Desktop Mac 系统要求。

VPNKit 不断出现故障

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

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

Windows 主题

卷

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

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

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

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

卷安装需要 Linux 容器的共享文件夹

如果您正在使用已安装的卷并收到运行时错误，指示未找到应用程序文件、对卷安装的访问被拒绝或服务无法启动（例如使用 Docker Compose时），您可能需要打开 共享文件夹。

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

支持符号链接

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

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

任何要在容器内运行的文件都必须使用 Unix 样式的\n行结尾。这包括在构建命令行和 Docker 文件中的 RUN 命令中引用的文件。

Docker 容器并docker build在 Unix 环境中运行，因此容器中的文件必须使用 Unix 风格的行结尾：\n，而不是Windows 风格的：\r\n。使用 Windows 工具创作 shell 脚本等文件时请记住这一点，其中默认值可能是 Windows 样式的行结尾。这些命令最终会传递给基于 Unix 的容器内的 Unix 命令（例如，传递给 的 shell 脚本/bin/sh）。如果使用 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)由于前面有“/”，因此不会转换 The。但是，第二个“/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 Home

1. 虚拟机平台
2. Linux 的 Windows 子系统
3. BIOS 中启用虚拟化
4. Windows 启动时启用管理程序

超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 功能，然后按 Enter。在随后的屏幕中，验证 Hyper-V 是否已启用。

虚拟化必须开启

除了 Hyper-V或WSL 2之外，还必须打开虚拟化。检查任务管理器上的性能选项卡。或者，您可以在终端中输入“systeminfo”。如果您看到“Hyper-V 要求：已检测到虚拟机管理程序”。 Hyper-V 所需的功能将不会显示'，然后启用虚拟化。

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

要打开嵌套虚拟化，请参阅 在 VM 或 VDI 环境中运行适用于 Windows 的 Docker Desktop。

Windows 启动时启用管理程序

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

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

尝试 启用嵌套虚拟化。

Windows 容器和 Windows Server

Windows Server 不支持 Docker Desktop。如果您对如何在 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 Access Denied 错误消息

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

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

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