為什麼 Docker pull 會逾時?先分清楚流量路徑
在 Linux 伺服器、OpenWrt 主機或家用 NAS 上執行 docker pull 時,常見症狀包括長時間停在 Pulling from library、解析 registry-1.docker.io 失敗、下載 layer 到一半中斷,或最後出現 context deadline exceeded、i/o timeout 與 TLS handshake timeout。這些錯誤都可能被簡化成「Docker Hub 被擋住」,但實際上往往是 DNS、Docker daemon 代理設定,以及 Clash TUN 是否真正接管流量三者之一沒有對齊。
一次完整的 Docker Hub 拉取,通常不只連到一個網域。Docker CLI 先與 registry-1.docker.io 建立 Registry API 連線,再向 auth.docker.io 取得驗證 token,實際 layer 下載時還可能轉往雲端物件儲存或 CDN 主機。也就是說,瀏覽器能開 Docker Hub 首頁,不代表 Docker daemon 的所有請求都能成功;同樣地,宿主機上的 curl 能通,也不代表背景服務使用了相同的代理路徑。
本文以 Mihomo(Clash Meta)TUN 透明代理為主軸,示範如何把 Docker Hub 相關流量納入代理、保留一般區域網路直連,並使用日誌逐步確認問題究竟發生在名稱解析、路由選擇、TLS 握手還是 layer 傳輸。設定前請確認你使用的是合法且符合所在地規範的網路服務與容器映像來源。
HTTP_PROXY 或桌面版 Clash 系統代理。若只在瀏覽器或終端設定代理,Docker pull 仍可能繼續直連。Docker Hub、DNS 與 TUN 接管的關係
TUN 模式會建立虛擬網卡,將符合條件的 IP 流量導入 Mihomo 核心,再由核心按照模式與規則選擇代理或直連。相較於只處理瀏覽器的系統代理,TUN 能涵蓋許多不支援 HTTP 代理的程式,因此特別適合 Docker、Git、套件管理器與命令列工具。不過,TUN 並不是「開啟後所有問題自動消失」:核心必須有足夠權限,路由表不能被其他 VPN 覆蓋,DNS 也要使用能與規則判斷配合的模式。
在 Mihomo 中,auto-route 主要負責把流量導入 TUN,auto-detect-interface 協助核心選擇實體出口,strict-route 則可減少部分流量繞過虛擬介面的情況。DNS 方面,enhanced-mode: fake-ip 常能讓域名規則更穩定,但某些內網服務、主機名或需要真實 IP 的應用可能需要加入 fake-ip-filter。若你只看到 IP 連線而看不到預期的域名,先不要急著增加規則,應先確認 DNS 請求到底由誰處理。
Docker Hub 的網域會隨登入流程、映像供應商與 CDN 路徑改變,因此建議先從 Clash 連線記錄觀察實際 hostname,再補充規則。常見起點包括:
registry-1.docker.io:Docker Registry API,負責查詢 manifest 與 layer 資訊。auth.docker.io:登入或拉取公開映像時使用的 token 服務。index.docker.io:部分舊版工具或相容流程仍可能出現。- 第三方映像的儲存與 CDN 網域:實際名稱以 Mihomo 連線日誌為準,不建議直接把整個雲端供應商網域送入代理。
Mihomo Clash TUN 透明代理完整配置示例
以下範例適合放在 Mihomo 設定檔中作為結構參考。PROXY、DIRECT 與節點名稱必須替換成你自己的策略組;如果訂閱已經提供同名策略組,請避免重複定義。範例將 Docker Hub 的核心服務集中到獨立策略組,方便你在故障時單獨切換線路,而不是把所有網站都改成全域代理。
mixed-port: 7890
mode: rule
allow-lan: true
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
strict-route: true
endpoint-independent-nat: true
dns:
enable: true
listen: 0.0.0.0:1053
ipv6: false
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
nameserver:
- https://1.1.1.1/dns-query
- https://8.8.8.8/dns-query
fake-ip-filter:
- "*.lan"
- "*.local"
- localhost.ptlogin2.qq.com
proxy-groups:
- name: DOCKER-HUB
type: select
proxies:
- PROXY
- DIRECT
rules:
- DOMAIN,registry-1.docker.io,DOCKER-HUB
- DOMAIN,auth.docker.io,DOCKER-HUB
- DOMAIN,index.docker.io,DOCKER-HUB
- DOMAIN-SUFFIX,docker.io,DOCKER-HUB
- MATCH,DIRECT
這份配置的重點不是網域數量,而是規則順序與可觀測性。Docker 相關規則必須放在最後的 MATCH 之前,否則先命中 GEOIP、FINAL 或其他廣泛規則時,Docker Hub 流量可能仍被送往直連。若你的節點對 Docker Hub 的長連線不穩定,可以先使用 select 做對照測試;確認代理可用後,再考慮改成 url-test,但不要在排障初期讓策略組自動切換,否則很難判斷是哪個變因造成逾時。
DOMAIN-SUFFIX,amazonaws.com 或整個 CDN 供應商網域。這可能把大量與 Docker 無關的工作流量送入代理,造成頻寬浪費、延遲升高,甚至影響內部雲端服務。Docker daemon 代理設定:TUN 與 HTTP 代理如何選
如果 Docker daemon 與 Mihomo TUN 位於同一台主機,最簡單的路徑通常是讓 TUN 接管 daemon 的 TCP 流量。這時 Docker 不需要知道 127.0.0.1:7890,因為它只是照正常方式建立連線,再由系統路由送入 TUN。這種方式對 HTTPS、Registry API 與 layer 下載較透明,也不必處理 Docker 對 HTTP CONNECT 代理的細節。
但在某些 Linux 發行版、Docker Desktop、容器化部署或 TUN 權限受限的環境,直接接管可能不完整。此時可為 Docker daemon 設定代理環境變數。以 systemd 為例,建立 docker.service.d 目錄與覆寫檔:
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/proxy.conf <<'EOF'
[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,::1,.local,192.168.0.0/16,10.0.0.0/8"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
systemctl show --property=Environment docker
代理位址必須是 Docker daemon 能連到的位址。若 daemon 在容器或另一台主機內,127.0.0.1 指向的是它自己,不是 Clash 所在主機;此時應改用可達的區域網路 IP,並在 Clash 開啟 allow-lan、設定安全的 bind-address 與存取控制。不要把管理端口直接暴露到公網,也不要在配置中硬編碼需要保密的代理帳密。
設定完成後,可先查看 Docker 服務是否取得新環境,再測試解析與拉取:
docker info
curl -I https://registry-1.docker.io/v2/
docker pull hello-world
curl 回傳 401 Unauthorized 不一定是失敗,對公開 Registry 而言,這通常代表 HTTPS 已經成功到達服務,只是請求尚未攜帶驗證 token。相反地,若是 DNS 失敗、連接逾時或 TLS handshake 逾時,才需要繼續檢查代理與規則。
日誌診斷與常見網路錯誤修復
排查時建議一次只改一個變因,並在 Mihomo 的連線紀錄中保留時間、hostname、命中的規則與策略組。先重現一次 docker pull,再對照 Docker daemon 日誌;不要只根據終端最後一行錯誤猜測原因。不同錯誤通常可用下表快速分類:
| 錯誤或症狀 | 常見原因 | 優先檢查項目 |
|---|---|---|
lookup registry-1.docker.io 失敗 |
DNS 未被 TUN 或 Mihomo 接管 | 確認 DNS 監聽位址、系統 resolv.conf 與 fake-ip 設定 |
i/o timeout |
流量直連、路由錯誤或節點丟包 | 查看命中規則,將 DOCKER-HUB 暫時固定到穩定節點 |
TLS handshake timeout |
代理出口抖動、MTU 不合或中間設備干擾 | 比較 TUN 與 HTTP 代理模式,降低 MTU 並測試其他節點 |
| manifest 成功但 layer 下載失敗 | 實際下載網域未加入規則 | 從連線表找出 CDN hostname,再新增精確規則 |
| 只在 daemon 失敗,Shell 正常 | systemd 未取得代理環境 | 使用 systemctl show 檢查並重新載入服務 |
如果你使用 Docker Desktop,還要注意它可能在虛擬機或獨立網路命名空間中執行。宿主機的 Clash TUN 並不保證能直接接管 Docker Desktop 的內部流量。此時應優先使用 Docker Desktop 支援的 daemon proxy 設定,或在其虛擬網路可達的位置提供代理服務;不要把宿主機成功的路由結果直接套用到虛擬機。
另一個容易忽略的因素是 MTU。當 TUN、WireGuard、PPPoE 或行動網路多層封裝同時存在時,TCP 握手可能成功,傳輸較大的 layer 卻反覆重傳。可先查看介面 MTU,逐步測試較保守的數值,並觀察是否只有大型映像失敗。若調整 MTU 後仍無改善,請恢復原值,繼續從節點品質、DNS 與下載 CDN 規則排查。
FAQ:Docker Hub 透明代理的維護建議
只代理 registry-1.docker.io,為什麼還是 pull 失敗?
因為 Docker 拉取流程還可能使用 auth.docker.io、index.docker.io 或映像實際儲存所在的 CDN。請在失敗當下觀察完整連線紀錄,確認每個新出現的 hostname 是否命中預期策略。不要直接把所有 HTTPS 流量改為代理,否則雖然可能暫時成功,卻會失去分流與診斷能力。
已開 TUN,還需要設定 Docker daemon 代理嗎?
同一台主機且 TUN 能完整接管 Docker 流量時,通常不需要;但 Docker Desktop、容器化 daemon 或權限受限環境可能需要額外設定。判斷方式不是看開關,而是查看 Mihomo 連線表是否出現 Docker 的實際請求,以及 Docker daemon 是否能連到 Clash 代理端口。
Docker daemon 應該使用公共 DNS 還是 Clash DNS?
重點是 DNS 結果與實際代理路徑一致。若 DNS 由外部服務解析、TCP 卻由 TUN 代理,可能遇到污染、錯誤 CDN 或規則判斷不一致。建議讓 Mihomo 統一處理需要分流的 DNS,同時把 *.lan、內部域名與本地服務加入過濾清單,避免影響區域網路。
如何避免更新訂閱後 Docker 規則消失?
不要直接修改每次都會被覆蓋的遠端訂閱內容。可使用 Mihomo 的覆寫、merge 或本地延伸設定功能,將 Docker 策略組與規則放在獨立檔案,並在每次更新後檢查最終配置。完成變更後重新載入核心,再用 docker pull hello-world 做最小化驗證。
相較於部分同類 VPN 工具只提供全域開關,或要求使用者為每個應用手動輸入代理,Docker daemon、TUN 與 CDN 分流往往難以同時兼顧;一些主流客戶端也缺少清楚的規則命中紀錄,遇到 context deadline exceeded 時只能反覆更換伺服器。Clash 搭配 Mihomo 核心則能以 TUN 接管非瀏覽器流量,透過獨立的 DOCKER-HUB 策略組拆分 registry、token 與下載路徑,並利用 DNS 與連線日誌定位真正的逾時環節。若你還沒有安裝適合自己平台的 Clash 客戶端,可以前往 客戶端下載頁 取得版本資訊,依照裝置與核心需求完成配置。