快捷導(dǎo)航

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

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

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

問題背景

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

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

問題表現(xiàn)

在執(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)

觀察結(jié)果是：

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

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

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

初步排查

網(wǎng)絡(luò)本身沒有問題

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

但 Docker 拉取仍舊失敗

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

這時開始懷疑：

可能和代理有關(guān)

解決思路：配置 Docker 的守護(hù)進(jìn)程代理

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

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

但實(shí)際上：

Docker 守護(hù)進(jìn)程（dockerd）是獨(dú)立運(yùn)行的，它不會繼承當(dāng)前 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

寫入以下內(nèi)容（根據(jù)你實(shí)際代理修改）：

[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"

應(yīng)用配置并重啟 Docker：

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

驗(yàn)證代理是否生效：

sudo systemctl show --property=Environment docker

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

最終結(jié)果

重啟 Docker 后再次運(yùn)行部署腳本：

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

總結(jié)

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

經(jīng)驗(yàn)教訓(xùn)

Docker CLI 和 Docker 守護(hù)進(jìn)程環(huán)境是 兩套東西，網(wǎng)絡(luò)設(shè)置互不影響
如果你使用代理加速訪問 Docker Hub，務(wù)必同步設(shè)置到 系統(tǒng)服務(wù)級別
部署復(fù)雜服務(wù)時，像 Zitadel 這類一鍵腳本可能集成很多鏡像，盡早配置好代理 可避免不必要的卡頓
配置鏡像加速器雖然有用，但僅限于部分鏡像。像 netbirdio、ghcr.io 上的鏡像，加速器是無法覆蓋的，因此守護(hù)進(jìn)程代理是更通用的做法
Docker 官方解決文檔

以上就是Docker拉取鏡像部分成功部分失敗的解決方案的詳細(xì)內(nèi)容，更多關(guān)于Docker拉取鏡像部分成功部分失敗的資料請關(guān)注腳本之家其它相關(guān)文章！

您可能感興趣的文章: