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

• 苹果电脑：~/Library/Group Containers/group.com.docker/settings-store.json
• 窗户：C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json
• Linux的：~/.docker/desktop/settings-store.json.

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

适用于 Linux 和 Mac 的主题

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

如果您正在使用挂载的卷并收到指示 找不到应用程序文件，拒绝访问卷挂载，或者服务 无法启动，例如在使用 Docker Compose 时， 您可能需要打开文件共享。

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

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 文档中有关支持的硬件所述：

通常，具有包括 Extended Page 的 Intel VT-x 功能集的计算机 支持表 （EPT） 和不受限制模式。

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

$ sysctl kern.hv_support

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

否则，命令将打印 .kern.hv_support: 0

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

VPNKit 不断中断

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

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

Windows 主题

卷

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

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

共享卷的默认权限不可配置。如果你是 使用需要不同于共享权限的应用程序 卷默认值，您需要使用非主机挂载的 卷或找到一种方法使应用程序使用默认文件 权限。

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

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

如果您正在使用挂载的卷并收到指示 找不到应用程序文件，则拒绝访问卷装载或服务 无法启动，例如在使用 Docker Compose 时， 您可能需要打开共享文件夹。

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

支持符号链接

符号链接在容器内部和容器之间工作。要了解更多信息，请参阅符号链接在 Windows 上的工作原理？。

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

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

Docker 容器并在 Unix 环境中运行，因此 容器必须使用 Unix 样式的行尾： ，而不是 Windows 样式： 。 使用 Windows 创作 shell 脚本等文件时，请记住这一点 工具，其中默认值可能是 Windows 样式的行尾。这些 命令最终会传递到基于 Unix 的容器内的 Unix 命令 （例如，传递给 的 shell 脚本）。如果 Windows 样式的行尾 失败并出现语法错误。docker build\n\r\n/bin/shdocker 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 的环境。这些工具应用自己的 命令行上的 preprocessing 进行预处理。例如，如果您在 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

此外，在脚本中，该命令用于避免对文件系统位置进行硬编码。它的输出是 Unix 样式的路径。pwd

$ 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 将多个脚本视为单个条目。 必须中和单行上出现的每个 paths 。/

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

在此示例中，由于前面的 '/' 而未转换 The 。但是，第二个 '/work' 由 POSIX 层。您还可以通过使用额外的 .$(pwd)/

$ 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 中启用虚拟化请注意，许多 Windows 设备已经启用了虚拟化，因此这可能不适用。
4. 在 Windows 启动时启用 Hypervisor

Hyper-V 技术

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

1. Hyper-V 已安装并正常工作
2. 在 BIOS 中启用虚拟化请注意，许多 Windows 设备已经启用了虚拟化，因此这可能不适用。
3. 在 Windows 启动时启用 Hypervisor

Docker Desktop 需要 Hyper-V 以及适用于 Windows 的 Hyper-V 模块 要安装并启用 PowerShell 的 PowerShell 进行安装。Docker Desktop 安装程序启用 它为你。

Docker Desktop 还需要两个 CPU 硬件功能才能使用 Hyper-V：虚拟化和二级地址转换 （SLAT），也称为快速虚拟化索引 （RVI）。在某些系统上，必须在 BIOS 中启用虚拟化。所需的步骤特定于供应商，但通常调用 BIOS 选项或类似选项。运行命令以检查所有必需的 Hyper-V 功能。有关更多详细信息，请参阅 Windows 10 上 Hyper-V 的先决条件。Virtualization Technology (VTx)systeminfo

要手动安装 Hyper-V，请参阅在 Windows 10 上安装 Hyper-V。安装后需要重新启动。如果在不重新启动的情况下安装 Hyper-V，Docker Desktop 将无法正常工作。

在开始菜单中，键入 Turn Windows features on or off，然后按 Enter。 在后续屏幕中，验证 Hyper-V 是否已启用。

必须打开虚拟化

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

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

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

在 Windows 启动时启用 Hypervisor

如果您已完成上述步骤，但仍遇到 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 - Access Denied 错误。

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

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