好不容易找到一个还活着的镜像源，`docker pull nginx` 秒拉成功，信心满满打开 Immich 的 compose 文件 `docker compose up -d`，然后卡住了：`pulling ghcr.io/immich-app/immich-server`，超时、重试、再超时。
第一反应多半是："源又挂了？"于是换源、重启、再试，折腾一晚上。
但这事儿换源解决不了。因为问题根本不在源上——这些镜像从一开始就不在 Docker Hub 上。你配的加速，只加了一半。
为什么"源明明能用"，有些镜像就是拉不下来
先把机制说透，这个坑的原理其实一句话：
`registry-mirrors` 不是全局代理，它只接管"没写仓库域名的镜像"。知乎`docker pull nginx`、`docker pull redis`，这种不带域名的短名字，Docker 默认去 Docker Hub 找，`registry-mirrors` 在这条链路上生效。但 `docker pull ghcr.io/immich-app/immich-server` 这种明确写了仓库域名的镜像，会原封不动直奔对应仓库，你配的加速源全程不参与。
Docker 官方文档对 pull-through mirror 的定位就是面向 Docker Hub 的。知乎8 月中旬知乎上那篇《Docker 配了 registry-mirrors，GHCR 和 registry.k8s.io 仍需分别处理》就是专门掰扯这件事的，评论区没人反驳，因为机制就是这样。所以你会看到一个很分裂的现象：nginx、redis、mysql、portainer 拉得飞快，一到 Immich、Home Assistant、Homepage 就转圈。不是玄学，是它们走的根本是另一条路。
你家那套服务，镜像到底都住在哪
这两年新起来的自托管项目，越来越多把官方镜像放到 ghcr.io（GitHub 自家的容器仓库），而不是 Docker Hub。知乎知乎我翻了一圈各项目的部署文档和近期教程，把家庭自托管最常见的几个整理出来：
服务 | 官方镜像所在地 | 备注 |
|---|---|---|
Immich（照片备份） | 群晖、威联通、极空间教程清一色 ghcr | |
Home Assistant（容器版） | Docker Hub 上也有镜像，但官方文档主推 ghcr | |
Homepage（导航页） | ||
Paperless-ngx（文档管理） | ||
LinuxServer 全家桶（qbittorrent、jellyfin 等常用 ls 镜像） | 又是另一个独立仓库 | |
nginx / redis / mysql / portainer / uptime-kuma / vaultwarden / n8n | Docker Hub | 这部分才是镜像源真正覆盖的 |
（以上按各项目当前部署文档的主流写法整理，个别项目两边仓库都有副本，以你手上那份 compose 文件为准。）
看出问题了吗？配一套家庭服务，你需要的不是"一个加速源"，而是"好几条通路"。 这也是为什么很多人觉得"源时灵时不灵"——其实是拉 Docker Hub 的镜像时灵，拉 ghcr 的镜像时不灵，被混在一起当成了同一个问题。
今年 3 月就有篇《配置了 Docker 镜像源，为啥还在疯狂访问官方仓库？》专门讲这个踩坑，直到 8 月还在被人翻出来问，说明踩的人是真的多。知乎
三条路，按你的情况选
路线一：改镜像名，零成本最快上手
不少国内加速服务除了 Docker Hub，还提供 ghcr 的专属转发入口，用法是把 compose 里的 `ghcr.io/xxx` 改写成"加速入口/ghcr.io/xxx"，显式指定拉取。知乎
优点：不动环境，改一行 compose 就能跑通，适合先在 NAS 上部署一两个应用试试水的。
缺点：每个 compose 都要手动改；第三方站点的可用性波动大，今天能查明天可能就 404；私有仓库镜像别走这条路。
路线二：自建多仓库拉通代理，一劳永逸
用 `registry:2` 或专门的多仓库缓存工具自建一个本地代理，把 Docker Hub、ghcr、quay 一起接进来，全家设备都指向它。知乎上有《5 分钟零成本搭自己的 GitHub/Docker 加速站》这种现成教程。
但要提醒一句：那篇教程的作者自己都点名了，不少自建工具"原生支持 Docker Hub，但 GHCR/Quay/GCR 这些小众容器仓库很多不支持、或者经常炸"。知乎搭之前先确认它覆盖哪些上游，别搭完了发现还是拉不动 Immich。
优点：配一次全家受益，镜像名不用逐个改写，缓存还能省重复下载的流量。
缺点：占带宽和磁盘，得自己维护，代理本身挂了全家断粮。
路线三：containerd 用户，用 hosts.toml 按仓库配镜像
如果你跑的是 K3s，或者 NAS 底层运行时是 containerd，注意：别去改 Docker 的 daemon.json，containerd 根本不读它。containerd 反而原生支持"按仓库分别配镜像源"，在 `/etc/containerd/certs.d/ghcr.io/` 下按域名建目录、写 hosts.toml 就行，每个仓库一条通路，互不干扰。知乎讽刺的是，这个"按仓库配加速"的能力，恰恰是 Docker Engine 那边一直缺的。
另外单独提醒 Docker Desktop 用户：别在 daemon.json 里折腾代理配置，Desktop 不采纳那里的设置，去 Desktop 自己的设置页面改。知乎
怎么选，一句话版：
NAS 上偶尔部署一两个应用 → 路线一
容器几十个、多台设备都要用的 homelab → 路线二
跑 K3s 或 containerd → 路线三
改完之后，先验证再收工
别改完就散，花一分钟确认：
用一个明确 tag 拉一次，比如 `docker pull ghcr.io/immich-app/immich-server:release`，能拉下来且输出有 digest，才算真的通了；
`docker info` 看一眼 Registry Mirrors 是不是你预期的配置；
如果走了第三方入口，别用 `latest` 这种漂移 tag，固定版本号，哪天站挂了也好排查。
还有个安全底线：不要把自己的私有仓库凭证走任何第三方代理，镜像拉取请求里带着的认证信息，对代理方是透明的。
最后说两句
这类问题接下来只会多不会少：新项目越来越爱用 ghcr，而国内能稳定用的加速入口只会越来越少。下次再遇到"pull 失败"，先别急着换源，看一眼完整镜像名——带着 `ghcr.io`、`quay.io`、`lscr.io` 前缀的，换多少个 Docker Hub 源都没用。
之前我们实测过一轮国内还在维护的 Docker 镜像源，Docker Hub 那半边的选择可以直接翻那篇；这半边 ghcr 的盲区，今天算是补上了。
你拉镜像还被哪些仓库卡过？评论区聊聊，互相避个坑。
