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.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 啟動時啟用了虛擬機器監視器
WSL 2 enabled

Hyper-V

在 Windows 10 專業版或企業版上，您還可以使用 Hyper-V，並啟用以下功能

  1. Hyper-V 已安裝並正常執行
  2. BIOS 中啟用了虛擬化
  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 功能，然後按回車鍵。在隨後的螢幕中，驗證是否已啟用 Hyper-V。

必須啟用虛擬化

除了 Hyper-V 或 WSL 2 之外，還必須啟用虛擬化。檢查任務管理器的“效能”選項卡。或者，您也可以在終端中鍵入“systeminfo”。如果您看到“Hyper-V 要求：已檢測到虛擬機器監視器。Hyper-V 所需的功能將不會顯示”，則表示已啟用虛擬化。

Task Manager

如果您手動解除安裝 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。

右鍵單擊以將使用者新增到組。登出並重新登入以使更改生效。