Docker拉取鏡像部分成功部分失敗的解決方案

更新時間：2025年05月28日 10:33:20 作者：mr.Darker

最近在部署 Zitadel 身份認證平臺的過程中,遇到一個看似“隨機”的問題：Docker 有些鏡像可以拉取,有些卻一直超時失敗,最終通過配置 Docker 守護進程級別的代理才解決,文章記錄整個問題分析和解決過程,便于自己和大家后期參考,需要的朋友可以參考下

問題背景

部署 Zitadel 時，使用官方提供的 getting-started-with-zitadel.sh 腳本，腳本會拉取多個 Docker 鏡像，比如：

ghcr.io/zitadel/zitadel
docker.io/library/caddy
netbirdio/** 等

問題表現

在執(zhí)行過程中，有些鏡像可以拉取成功，有些會報如下錯誤：

Error response from daemon: Get "https://registry-1.docker.io/v2/": 
net/http: request canceled while waiting for connection 
(Client.Timeout exceeded while awaiting headers)

觀察結果是：

鏡像	是否拉取成功
`ghcr.io/zitadel/zitadel`	? 成功
`docker.io/library/caddy`	? 成功
`netbirdio/management` / `netbirdio/signal`	? 超時失敗

同時，我們很早就配置了一些 Docker Hub 鏡像加速器（如阿里云，騰訊云，DaoCloud 等），這也是為什么有些鏡像能順利拉取，有些卻不能的原因之一。

因為鏡像加速器僅能加速“Docker Hub 官方鏡像”，如 library/nginx 或 docker.io/library/caddy，而像 netbirdio/* 這種非官方項目的鏡像并不在加速器白名單內，因此仍然會拉取失敗。

初步排查

網絡本身沒有問題

ping registry-1.docker.io 正常
curl https://registry-1.docker.io/v2/ 正常
docker login 也沒有任何異常

但 Docker 拉取仍舊失敗

通過多次測試發(fā)現，Docker 有些鏡像拉得飛快，有些鏡像卡死或超時，尤其是 docker.io/netbirdio 相關的鏡像。

這時開始懷疑：

可能和代理有關

解決思路：配置 Docker 的守護進程代理

平時我們習慣配置終端代理，例如：

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

但實際上：

Docker 守護進程（dockerd）是獨立運行的，它不會繼承當前 shell 的代理環(huán)境變量！

解決方案：配置 Docker 的 systemd 代理

創(chuàng)建代理配置目錄（如不存在）：

sudo mkdir -p /etc/systemd/system/docker.service.d

創(chuàng)建代理配置文件：

sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

寫入以下內容（根據你實際代理修改）：

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,.corp"

應用配置并重啟 Docker：

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl restart docker

驗證代理是否生效：

sudo systemctl show --property=Environment docker

輸出應該包含你剛才設置的代理環(huán)境變量。

最終結果

重啟 Docker 后再次運行部署腳本：

所有鏡像（包括 netbirdio）都能成功拉取
部署流程順利走完

總結

問題	結論
Docker 部分鏡像拉取失敗	是由于 Docker 守護進程未配置代理，而不是網絡本身問題
解決方案	配置 `systemd` 層面的 `http-proxy.conf`，讓 `dockerd` 使用代理
驗證方式	`systemctl show --property=Environment docker` 查看生效狀態(tài)