Docker Desktop 故障排除主題

提示

如果您在故障排除中未找到解決方案，請瀏覽 GitHub 儲存庫或建立新問題

• docker/for-mac
• docker/for-win
• docker/for-linux

所有平臺主題

證書設定不正確

錯誤資訊

嘗試使用 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 忽略了不安全登錄檔下列出的證書。
• 客戶端證書未傳送到不安全登錄檔，導致握手失敗。

解決方案

• 確保您的登錄檔已正確配置有效 SSL 證書。
• 如果您的登錄檔是自簽名的，請透過將其新增到 Docker 的證書目錄（Linux 上為 /etc/docker/certs.d/）來配置 Docker 信任該證書。
• 如果問題仍然存在，請檢查您的 Docker 守護程式配置並啟用 TLS 身份驗證。

Docker Desktop UI 顯示綠色、失真或有視覺偽影

原因

Docker Desktop 預設使用硬體加速圖形，這可能會導致某些 GPU 出現問題。

解決方案

停用硬體加速

1. 編輯 Docker Desktop 的 settings-store.json 檔案（對於 Docker Desktop 4.34 及更早版本，則為 settings.json）。您可以在以下位置找到此檔案：

   • 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.

2. 新增以下條目

   $ "disableHardwareAcceleration": true

3. 儲存檔案並重新啟動 Docker Desktop。

使用掛載卷時遇到執行時錯誤，指示找不到應用程式檔案，拒絕訪問卷掛載，或服務無法啟動

原因

如果您的專案目錄位於您的主目錄（/home/<user>）之外，Docker Desktop 需要檔案共享許可權才能訪問它。

解決方案

在 Mac 和 Linux 上啟用 Docker Desktop 的檔案共享

1. 導航到設定，選擇資源，然後選擇檔案共享。
2. 新增包含 Dockerfile 和卷掛載路徑的驅動器或資料夾。

在 Windows 上啟用 Docker Desktop 的檔案共享

1. 從設定中，選擇共享資料夾。
2. 共享包含 Dockerfile 和卷掛載路徑的資料夾。

埠已被分配錯誤

錯誤資訊

啟動容器時，您可能會看到類似以下的錯誤：

Bind for 0.0.0.0:8080 failed: port is already allocated

或者

listen tcp:0.0.0.0:8080: bind: address is already in use

原因

• 系統上的另一個應用程式已在使用指定的埠。
• 之前執行的容器未正確停止，仍繫結到該埠。

解決方案

要發現此軟體的身份，請執行以下操作之一：

• 使用 resmon.exe GUI，選擇網路，然後選擇偵聽埠
• 在 PowerShell 中，使用 netstat -aon | find /i "listening " 查詢當前使用該埠的程序的 PID（PID 是最右側列中的數字）。

然後，決定是關閉其他程序，還是在 Docker 應用程式中使用不同的埠。

Linux 和 Mac 主題

Docker Desktop 在 Mac 或 Linux 平臺上啟動失敗

錯誤資訊

Docker 因 Unix 域套接字路徑長度限制而無法啟動

[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 和 Linux 上，Docker Desktop 建立用於程序間通訊的 Unix 域套接字。這些套接字在使用者的主目錄下建立。

Unix 域套接字具有最大路徑長度

• Mac 上為 104 個字元
• Linux 上為 108 個字元

如果您的主目錄路徑太長，Docker Desktop 將無法建立必要的套接字。

解決方案

確保您的使用者名稱足夠短，以使路徑在允許的限制內

• Mac：使用者名稱應 ≤ 33 個字元
• Linux：使用者名稱應 ≤ 55 個字元

Mac 主題

升級需要管理員許可權

原因

在 macOS 上，沒有管理員許可權的使用者無法從 Docker Desktop 儀表板執行應用程式內升級。

解決方案

重要

升級前請勿解除安裝當前版本。這樣做會刪除所有本地 Docker 容器、映象和卷。

升級 Docker Desktop

• 請管理員將新版本安裝到現有版本之上。
• 如果適合您的設定，請使用 []--user 安裝標誌](/manuals/desktop/setup/install/mac-install.md#security-and-access)。

持續通知提示應用程式已更改我的桌面配置

原因

您收到此通知是因為“配置完整性檢查”功能檢測到第三方應用程式已更改您的 Docker Desktop 配置。這通常是由於不正確或丟失的符號連結造成的。此通知可確保您瞭解這些更改，以便您可以檢視和修復任何潛在問題以維護系統可靠性。

開啟通知會彈出一個視窗，提供有關檢測到的完整性問題的詳細資訊。

解決方案

如果您選擇忽略通知，它只會在下次 Docker Desktop 啟動時再次顯示。如果您選擇修復配置，則不會再次收到提示。

如果您想關閉“配置完整性檢查”通知，請導航到 Docker Desktop 的設定，然後在“常規”選項卡中，清除“自動檢查配置”設定。

退出應用程式後，com.docker.vmnetd仍在執行

特權幫助程式程序 com.docker.vmnetd 由 launchd 啟動並在後臺執行。除非 Docker.app 連線到它，否則該程序不消耗任何資源，因此可以安全地忽略。

檢測到不相容的 CPU

原因

Docker Desktop 需要支援虛擬化，更具體地說，支援 Apple Hypervisor 框架的處理器 (CPU)。

解決方案

檢查

• 您已為您的架構安裝了正確的 Docker Desktop 版本

• 您的 Mac 支援 Apple 的 Hypervisor 框架。要檢查您的 Mac 是否支援 Hypervisor 框架，請在終端視窗中執行以下命令。

  $ sysctl kern.hv_support
  

  如果您的 Mac 支援 Hypervisor 框架，該命令將列印 kern.hv_support: 1。

  如果不支援，該命令將列印 kern.hv_support: 0。

另請參閱 Apple 文件中的 Hypervisor Framework 參考，以及 Docker Desktop Mac 系統要求。

VPNKit 不斷出現故障

原因

在 Docker Desktop 4.19 版中，gVisor 取代了 VPNKit，以在使用 macOS 13 及更高版本上的虛擬化框架時提高 VM 網路的效能。

解決方案

要繼續使用 VPNKit

1. 開啟位於 ~/Library/Group Containers/group.com.docker/settings-store.json 的 settings-store.json 檔案

2. 新增

   $ "networkType":"vpnkit"

3. 儲存檔案並重新啟動 Docker Desktop。

Windows 主題

安裝防病毒軟體後 Docker Desktop 啟動失敗

原因

某些防病毒軟體可能與 Hyper-V 和 Microsoft Windows 10 版本不相容。衝突通常發生在 Windows 更新之後，表現為 Docker 守護程式的錯誤響應和 Docker Desktop 啟動失敗。

解決方案

作為臨時解決方法，解除安裝防病毒軟體，或將 Docker 新增到防病毒軟體的排除/例外列表中。

共享卷資料目錄上的許可權錯誤

原因

從 Windows 共享檔案時，Docker Desktop 會將 共享卷的許可權設定為預設值 0777（使用者和組的讀、寫、執行許可權）。

共享卷的預設許可權不可配置。

解決方案

如果您正在使用需要不同許可權的應用程式，請執行以下操作之一：

• 使用非主機掛載卷
• 找到一種方法使應用程式與預設檔案許可權一起工作

意外的語法錯誤，容器中的檔案使用 Unix 風格的行尾

原因

Docker 容器期望 Unix 風格的行結束符 \n，而不是 Windows 風格的 \r\n。這包括在命令列中用於構建的檔案以及 Dockerfile 中 RUN 命令中引用的檔案。

在使用 Windows 工具編寫 shell 指令碼等檔案時，請記住這一點，因為預設情況下可能會是 Windows 風格的行結束符。這些命令最終會傳遞給基於 Unix 的容器內的 Unix 命令（例如，傳遞給 /bin/sh 的 shell 指令碼）。如果使用 Windows 風格的行結束符，docker run 將因語法錯誤而失敗。

解決方案

• 使用以下方式將檔案轉換為 Unix 風格的行結束符

  $ dos2unix script.sh
  

• 在 VS Code 中，將行結束符設定為 LF (Unix) 而不是 CRLF (Windows)。

Windows 上的路徑轉換錯誤

原因

與 Linux 不同，Windows 需要顯式路徑轉換才能進行卷掛載。

在 Linux 上，系統會處理將一個路徑掛載到另一個路徑。例如，當您在 Linux 上執行以下命令時

$ docker run --rm -ti -v /home/user/work:/work alpine

它會向目標容器新增一個 /work 目錄以映象指定的路徑。

解決方案

更新源路徑。例如，如果您使用舊版 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 中 Docker 命令失敗

錯誤資訊

$ docker run --rm -ti -v C:\Users\user\work:/work alpine
docker: Error response from daemon: mkdir C:UsersUserwork: Access is denied.

$ 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.

原因

Git Bash（或 MSYS）在 Windows 上提供了一個類似 Unix 的環境。這些工具會在命令列上應用自己的預處理。

這會影響 $(pwd)、冒號分隔的路徑和波浪號 (~)

此外，\ 字元在 Git Bash 中具有特殊含義。

解決方案

• 暫時停用 Git Bash 路徑轉換。例如，執行帶有 MSYS 路徑轉換停用功能的命令

  $ MSYS_NO_PATHCONV=1 docker run --rm -ti -v $(pwd):/work alpine
  

• 使用正確的路徑格式
  • 使用雙斜槓和反斜槓（\\ //）而不是單個（\ /）。
  • 如果引用 $(pwd)，請新增一個額外的 /

指令碼的可移植性不受影響，因為 Linux 將多個 / 視為單個條目。

Docker Desktop 因虛擬化未工作而失敗

錯誤資訊

一個典型的錯誤訊息是“Docker Desktop - 意外的 WSL 錯誤”，其中提及錯誤程式碼 Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED。手動執行 wsl 命令也會因相同的錯誤程式碼而失敗。

原因

• BIOS 中停用了虛擬化設定。
• 缺少 Windows Hyper-V 或 WSL 2 元件。

請注意，某些第三方軟體（如 Android 模擬器）會在安裝時停用 Hyper-V。

解決方案

您的機器必須具有以下功能才能使 Docker Desktop 正常執行

WSL 2 和 Windows 家庭版

1. 虛擬機器平臺
2. 適用於 Linux 的 Windows 子系統
3. BIOS 中啟用了虛擬化 請注意，許多 Windows 裝置已經啟用了虛擬化，因此這可能不適用。
4. Windows 啟動時啟用 Hypervisor

必須能夠無錯誤地執行 WSL 2 命令，例如

PS C:\users\> wsl -l -v
  NAME              STATE           VERSION
* Ubuntu            Running         2
  docker-desktop    Stopped         2
PS C:\users\> wsl -d docker-desktop echo WSL 2 is working
WSL 2 is working

如果功能已啟用但命令不工作，請首先檢查虛擬化已開啟，然後根據需要在 Windows 啟動時啟用 Hypervisor。如果在虛擬機器中執行 Docker Desktop，請確保hypervisor 已啟用巢狀虛擬化。

Hyper-V

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

1. Hyper-V 已安裝並正常工作
2. BIOS 中啟用了虛擬化 請注意，許多 Windows 裝置已經啟用了虛擬化，因此這可能不適用。
3. Windows 啟動時啟用 Hypervisor

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 要求：已檢測到 Hypervisor。Hyper-V 所需功能將不會顯示，則表示虛擬化已啟用。

如果手動解除安裝 Hyper-V、WSL 2 或關閉虛擬化，Docker Desktop 將無法啟動。

要開啟巢狀虛擬化，請參閱在 VM 或 VDI 環境中執行 Windows 版 Docker Desktop。

Windows 啟動時啟用 Hypervisor

如果您已完成上述步驟但 Docker Desktop 仍存在啟動問題，這可能是因為 Hypervisor 已安裝，但在 Windows 啟動時未啟動。某些工具（例如舊版 Virtual Box）和影片遊戲安裝程式會在啟動時關閉 Hypervisor。要重新開啟它：

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 容器的 Docker Desktop 失敗，並顯示“介質防寫”錯誤

錯誤資訊

FSCTL_EXTEND_VOLUME \\?\Volume{GUID}: 介質防寫

原因

如果您在使用 Windows 容器執行 Docker Desktop 時遇到故障，這可能是由於特定的 Windows 配置策略：FDVDenyWriteAccess。

此策略啟用後，會導致 Windows 將所有未受 BitLocker 加密的固定驅動器掛載為只讀。這也會影響虛擬機器卷，因此 Docker Desktop 可能無法正確啟動或執行容器，因為它需要對這些卷的讀寫訪問許可權。

FDVDenyWriteAccess 是一項 Windows 組策略設定，啟用後會阻止對未受 BitLocker 保護的固定資料驅動器進行寫入訪問。這通常用於注重安全的環境，但可能會干擾 Docker 等開發工具。在 Windows 登錄檔中，可以在 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Policies\Microsoft\FVE\FDVDenyWriteAccess 找到它。

解決方案

Docker Desktop 不支援在啟用 FDVDenyWriteAccess 的系統上執行 Windows 容器。此設定會干擾 Docker 正確掛載卷的能力，這對於容器功能至關重要。

要將 Docker Desktop 與 Windows 容器一起使用，請確保 FDVDenyWriteAccess 已停用。您可以在登錄檔或透過組策略編輯器 (gpedit.msc) 檢查和更改此設定，路徑為

計算機配置 > 管理模板 > Windows 元件 > BitLocker 驅動器加密 > 固定資料驅動器 > 拒絕向未受 BitLocker 保護的固定驅動器寫入訪問許可權

注意

修改組策略設定可能需要管理員許可權，並應遵守您組織的 IT 策略。如果設定在一段時間後重置，這通常意味著它被您的 IT 部門的集中配置覆蓋。在進行任何更改之前，請與他們溝通。

啟動 Docker Desktop 時出現“Docker Desktop Access Denied”錯誤訊息

錯誤資訊

啟動 Docker Desktop 時，出現以下錯誤：

Docker Desktop - Access Denied

原因

使用者不屬於 docker-users 組，而該組是許可權所必需的。

解決方案

如果您的管理員帳戶與您的使用者帳戶不同，請新增它

1. 以管理員身份執行計算機管理。
2. 導航到本地使用者和組 > 組 > docker-users。
3. 右鍵單擊以將使用者新增到組中。
4. 登出並重新登入以使更改生效