使用 Docker 時，最常遇到的問題不一定是 Docker 本身故障，而可能來自套件安裝、Docker daemon、權限、磁碟空間、Container 程式錯誤、Port 衝突、Network、DNS 或 Storage Driver。
本篇整理 Docker 常見錯誤的判斷方法與實際排錯流程，適合 Ubuntu Server 與一般 Linux Docker 環境。每個案例都會說明錯誤現象、原因、檢查指令與建議處理方式，讓你遇到 Docker 問題時可以依序排查，而不是直接重裝 Docker。
Docker 錯誤排除基本流程
遇到 Docker 問題時，不建議一開始就重裝 Docker。先確認問題發生在哪一層，可以大幅縮短排錯時間。
| 檢查順序 | 指令 | 用途 |
|---|---|---|
| 1 | docker version | 確認 Docker CLI 與 Engine 是否正常通訊 |
| 2 | systemctl status docker | 確認 Docker daemon 狀態 |
| 3 | journalctl -u docker | 查看 Docker daemon 日誌 |
| 4 | docker ps -a | 查看所有 Container 狀態 |
| 5 | docker logs <container> | 查看 Container 應用程式錯誤 |
| 6 | df -h | 檢查主機磁碟空間 |
| 7 | docker network ls | 檢查 Docker Network |
| 8 | docker info | 查看 Engine、Storage 與系統資訊 |
如果 Docker CLI 已經無法連線 daemon，就先處理 daemon；如果 daemon 正常但單一 Container 無法啟動，則應把排查重點放在 Container logs、環境變數、Volume、Port 與 Network。
Docker 安裝階段常見錯誤
錯誤一：apt 安裝 Docker 套件失敗
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin如果出現 Unable to locate package、unmet dependencies 或套件找不到，常見原因是 Docker 官方 APT Repository 尚未正確設定、套件索引過期，或系統存在舊 Docker 套件造成衝突。
先確認 Ubuntu 的套件來源及更新狀態：
sudo apt update
apt-cache policy docker-ceDocker 官方目前建議在 Ubuntu 上使用 Docker 官方 APT Repository 安裝 Docker Engine，並安裝 Docker Engine、CLI、containerd、Buildx 與 Compose Plugin 等套件。
錯誤二：GPG Key 或 Repository 設定錯誤
NO_PUBKEY
The repository is not signed
Unable to locate package docker-ce如果出現 GPG 或 Repository 錯誤，應檢查 Docker 官方金鑰與 APT Repository，而不是直接下載不明來源的 Docker 套件。
目前 Docker 官方 Ubuntu 安裝文件使用 /etc/apt/keyrings/docker.asc 與 /etc/apt/sources.list.d/docker.sources 的方式設定 Repository。
錯誤三：舊版 Docker 套件造成衝突
如果主機以前安裝過 Ubuntu 的 docker.io、舊版 Compose 或其他 Container runtime，可能會與 Docker 官方套件產生衝突。
可以先確認：
dpkg -l | grep -E 'docker|containerd|runc'確認現有套件後，再按照目前系統與 Docker 官方文件決定哪些套件需要移除。不要在不確認環境的情況下直接刪除整個 Docker 資料目錄。
Docker daemon 常見錯誤
錯誤一：Cannot connect to the Docker daemon
Cannot connect to the Docker daemon at unix:///var/run/docker.sock這通常代表 Docker daemon 尚未啟動、服務異常，或目前使用者沒有權限存取 Docker socket。
先檢查：
sudo systemctl status docker
sudo journalctl -u docker --no-pager -n 100如果 Docker 沒有啟動，可以嘗試：
sudo systemctl start docker
sudo systemctl status docker
在使用 systemd 的 Ubuntu 環境中，Docker daemon 通常由系統服務管理。Docker 官方也提供使用 systemctl start docker 啟動 daemon 的方式。
錯誤二：permission denied while trying to connect
permission denied while trying to connect to the Docker daemon socket
如果使用 sudo docker ps 正常，但直接執行 docker ps 出現 Permission denied，通常是目前使用者沒有 Docker socket 所需權限。
可以加入 docker 群組：
sudo usermod -aG docker $USER
newgrp docker
docker ps也可以登出 Linux 後重新登入，使新的群組權限生效。
錯誤三：no space left on device
no space left on device這不一定只是 Docker image 太多，也可能是主機磁碟、Docker 資料目錄或 inode 用盡。
先檢查：
df -h
df -i
docker system df如果確認有不再使用的 Image、Container、Network 等資源，再依需求進行清理。
docker system prune不要一看到磁碟滿就直接執行：
docker system prune -a --volumes
因為加入 --volumes 後涉及 Volume 清理，若 Volume 中仍有應用程式資料，可能造成資料遺失。執行任何清理命令前都應先確認哪些資料可以刪除。
錯誤四：daemon 初始化失敗
failed to start daemon
failed to initialize
invalid JSON in daemon.json
如果 Docker 啟動失敗，常見原因包括 /etc/docker/daemon.json 格式錯誤、設定項目不相容、Storage Driver 問題或其他系統層級設定。
先檢查：
sudo cat /etc/docker/daemon.json
sudo journalctl -u docker --no-pager -n 200
docker info如果最近才修改 daemon.json，優先檢查 JSON 格式與新增的設定項目。
Container 執行錯誤
錯誤一：Container 啟動後立即停止
docker ps -a
docker logs my_container
Container 的狀態如果是 Exited，不代表 Docker daemon 壞掉。更常見的是 Container 裡面的主要程序已經結束或應用程式啟動失敗。
先查看：
docker ps -a
docker logs my_container
docker inspect my_container如果日誌顯示資料庫連線失敗、環境變數錯誤、設定檔不存在或權限問題，應優先處理應用程式本身，而不是一直重啟 Container。
錯誤二：Container 不斷 Restart
docker ps -a如果 Container 一直重新啟動，可以查看：
docker logs --tail 100 my_container
docker inspect my_container確認是否設定了 restart policy，以及程式本身是否因設定錯誤而重複退出。
錯誤三：Image 拉取失敗
docker pull nginx如果出現 Image 拉取錯誤，常見原因包括 Image 名稱或 Tag 錯誤、Registry 連線失敗、DNS 問題、代理伺服器設定或 Registry 認證問題。
可以先測試：
docker pull nginx:latest如果仍然失敗，再檢查 DNS 與主機網路連線。
Port 與服務衝突
錯誤：Bind for 0.0.0.0 failed
Bind for 0.0.0.0:8080 failed: port is already allocated表示 Docker 想使用的 Host Port 已經被其他 Container 或主機上的服務占用。
先確認是哪個程式或 Container 使用該 Port：
sudo ss -lntp | grep :8080
docker ps --format "table {{.Names}}\t{{.Ports}}"如果確認 Host Port 8080 已經被其他服務使用，可以改用其他 Port：
docker run -d -p 8081:80 --name web nginx這代表：
| 位置 | Port |
|---|---|
| Docker Host | 8081 |
| Container | 80 |
Docker 官方文件說明，-p 8080:80 是把 Host 的 8080 Port 映射到 Container 的 80 Port；如果沒有指定 Host IP，發布的 Port 預設可能綁定在主機所有網路介面，因此需要注意暴露範圍。
Docker Network 與 DNS 問題
Network 無法互通
Container 之間無法連線時，先確認它們是否連接到相同的 Docker Network。
docker network ls
docker network inspect my_network
docker inspect container_a
docker inspect container_b自訂 Bridge Network 可以讓同一個 Network 中的 Container 互相通訊。Docker 官方也將 Container networking、User-defined networks 與 published ports 分開處理，因此排查時不要把 Port 問題與 Container-to-Container 網路問題混在一起。
DNS 解析失敗
docker exec -it my_container cat /etc/resolv.conf如果 Container 無法解析網域名稱，可以先確認 Container 本身是否可以連線，以及 DNS 設定是否正常。
也可以建立測試 Container：
docker run --rm busybox nslookup example.com不要在沒有確認問題原因之前就把 Google DNS 或其他公共 DNS 硬編碼進所有 Container。企業環境可能有內部 DNS、Proxy、Split DNS 或防火牆限制。
Storage Driver 與磁碟空間問題
查看 Storage Driver
docker info | grep "Storage Driver"Linux 上的 Docker Engine 常見 Storage Driver 是 overlay2。Docker 官方文件指出，overlay2 支援多種 backing filesystem，例如 ext4；使用 XFS 時則需要符合相應的 d_type/ftype 條件。
overlay2 不支援
如果出現 overlay2 相關錯誤，不應直接把 Storage Driver 強制改成另一個 driver。 首先確認 Kernel、Backing Filesystem 與 Docker 設定。
uname -r
df -T /var/lib/docker
docker info
如果 /var/lib/docker 位於 XFS，也可以確認：
sudo xfs_info /var/lib/dockerDocker 官方指出，overlay2 在 XFS 上需要正確的 d_type/ftype 支援；此外，更換 Storage Driver 後，原有本機上的 Images 與 Containers 可能無法直接使用，因此不能把更換 Storage Driver 當成一般性的快速修復方法。
完整 Docker 排錯實戰流程
以下是一套適合 Ubuntu Server 的實戰排錯順序。遇到 Docker 問題時，可以照著執行。
第一步：確認 Docker Engine
docker version
docker info如果這裡就出現 Cannot connect to Docker daemon，先處理 Docker service。
第二步：檢查 Docker service
sudo systemctl status docker
sudo journalctl -u docker --no-pager -n 100第三步：查看 Container 狀態
docker ps
docker ps -a第四步：查看發生錯誤的 Container Logs
docker logs --tail 200 my_container第五步：檢查 Port
sudo ss -lntp
docker ps --format "table {{.Names}}\t{{.Ports}}"第六步：檢查 Network
docker network ls
docker network inspect my_network第七步：檢查主機磁碟與 Docker 空間
df -h
df -i
docker system df第八步：最後才考慮清理或重建
確認問題原因後，再決定是否刪除 Image、Container、Network 或 Volume。尤其資料庫、Redis、MySQL 等服務使用的 Volume，不應在沒有確認資料備份的情況下直接刪除。
Docker daemon → Container 狀態 → Container logs → Port → Network → DNS → Storage → 磁碟空間
FAQ 常見問題
Docker daemon 無法啟動怎麼辦？
先執行 sudo systemctl status docker 與 sudo journalctl -u docker --no-pager -n 100。確認是設定檔、Storage、權限、磁碟空間或其他服務問題後，再針對原因處理。
docker ps 出現 permission denied 怎麼辦？
如果 sudo docker ps 正常而 docker ps 失敗，可以確認目前使用者是否加入 docker 群組，例如 sudo usermod -aG docker $USER，之後重新登入或使用 newgrp docker。
Container 啟動後馬上停止怎麼辦？
先執行 docker ps -a 與 docker logs <container>。通常應先找出應用程式為什麼退出，而不是一直執行 docker restart。
Docker Port 被占用怎麼辦？
使用 sudo ss -lntp 或 docker ps 找出占用來源。確認後，可以停止衝突服務，或改用其他 Host Port，例如 -p 8081:80。
可以直接開放 Docker 2375 Port 嗎？
不建議。Docker Remote API 涉及高權限操作，除非已正確設計 TLS、驗證與網路隔離，否則不要把 Docker daemon 暴露在不可信任的網路上。
Docker 磁碟滿了可以直接 prune 嗎？
可以清理不再使用的 Docker 資源，但應先使用 docker system df 查看佔用，再決定清理範圍。涉及 Volume 時尤其要小心，因為 Volume 可能包含正式環境資料。
overlay2 not supported 怎麼辦？
先檢查 Kernel、Backing Filesystem 與 Docker 的 Storage Driver 設定。Ubuntu 常見使用 overlay2，但 XFS 等檔案系統需要符合 Docker 對 overlay2 的支援條件，不能只靠修改 daemon.json 解決。
Container DNS 解析失敗怎麼辦？
先檢查 Container 的 /etc/resolv.conf、Docker Network、主機 DNS 與外部網路連線。可以使用臨時測試 Container 驗證 DNS，而不是一開始就修改所有 Docker DNS 設定。
🔍 Docker 延伸教學
如果你正在 Ubuntu Server 上部署 Docker，也可以繼續閱讀其他 Docker 與 Linux Server 教學。
總結： Docker 錯誤排除最重要的不是記住大量指令，而是先判斷問題位於哪一層。 遇到問題時，可以依照 daemon → Container → logs → Port → Network → DNS → Storage → 磁碟 的順序逐步檢查。 這樣通常比直接重裝 Docker 更容易找到真正原因，也能降低誤刪 Container 或 Volume 的風險。