Guides Platform

Appearance

Docker 配置国内镜像加速：Windows、macOS、Linux 与 NAS ​

日常使用 Docker 时，可能会遇到 docker pull nginx 或 Docker Compose 拉取镜像长时间卡住，最后超时失败。镜像仓库访问慢或无法访问是这类问题的常见原因之一。

没有显式仓库域名的镜像默认从 Docker Hub 拉取。网络链路、DNS、代理、仓库限流或镜像名称错误，都可能导致拉取缓慢或失败。

国内用户可以根据主机所在网络，选择有公开说明的公共镜像源、云厂商限定地址、账号专属服务，或部署企业私有 Registry 与镜像缓存。

这篇文章就先区分镜像来自哪个 Registry，再按推荐顺序选择公共镜像源、账号专属地址或企业私有缓存，分别配置 Docker Desktop、Linux Docker Engine、NAS、Compose 和独立 BuildKit builder。

确认访问镜像 ​

没有显式仓库域名的镜像通常来自 Docker Hub；也可以显式指定其他 Registry，例如 ghcr.io/owner/app:1.0.0 来自 GitHub Container Registry。

镜像写法实际 RegistryDocker Hub mirror 是否生效
nginx:1.27-alpinedocker.io/library/nginx是
portainer/portainer-ce:2.27.9docker.io/portainer/portainer-ce是
ghcr.io/owner/app:1.0.0GitHub Container Registry否
quay.io/owner/app:1.0.0Quay否
mcr.microsoft.com/example/app:1.0.0Microsoft Container Registry否

Docker 的 registry-mirrors 只代理逻辑上的 docker.io。如果镜像显式指定了第三方 Registry，例如错误信息指向 ghcr.io、quay.io、mcr.microsoft.com，增加 Docker Hub mirror 不会解决问题，需要使用对应 Registry 的合规网络出口、完整代理前缀、企业同步或离线导入。

查看和保存镜像拉取失败信息：

bash
docker pull alpine:3.21
docker info

重点记录错误中的主机名和状态：

  • lookup ... no such host 通常先检查 DNS；
  • x509 通常先检查系统时间、证书链和 HTTPS 代理；
  • 429 Too Many Requests 表示上游或代理限流；
  • 401 Unauthorized 出现在 Registry /v2/ 探测时可能只是正常的 Bearer 鉴权挑战；
  • manifest unknown 通常先检查镜像名、命名空间和 tag。

选择哪一种镜像源 ​

使用场景推荐方式原因
临时处理公开 Docker Hub 镜像有公开说明的公共代理配置成本最低，但不承诺长期稳定
个人开发机或云主机账号专属加速地址可追溯到账号，访问范围和限制更明确
多台服务器、团队或生产环境企业 Harbor 或 Distribution 缓存地址、认证、缓存、审计和生命周期由自己控制
固定且数量有限的生产镜像同步到自己的私有 Registry发布时完成同步，运行时不依赖公共代理
隔离或离线环境受控 Registry 或离线导入不把运行稳定性建立在临时公网服务上

不要一次写入大量公共地址。失效地址会延长等待时间，还会让故障归因变得困难。先选一个来源完成端点、daemon、拉取和运行验证，再决定是否配置一个经过同样验证的备用地址。

公共镜像源推荐 ​

下面的顺序不是速度排行榜，而是根据维护主体、公开文档、使用边界和可观察状态给出的使用建议。网络质量与服务状态会随地区、运营商、缓存命中和时段变化。

顺序服务镜像源地址快速使用方法当前边界
1DaoCloudhttps://docker.m.daocloud.io配置为 Docker Hub mirror，或在镜像名前增加完整代理前缀项目公开后端、状态页、限流和缓存说明；繁忙时段可能拥堵
2毫秒镜像https://docker.1ms.run免费线路用于个人公开镜像；需要来源控制时使用账号专属域名免费线路与付费线路能力不同；专属域名会消耗资源包或余额
31Panelhttps://docker.1panel.live配置到 Docker Engine、Docker Desktop 或 1Panel 的镜像加速设置临时地址且仅限境内机器；网络不可控时仍可能超时，过多请求可能被限制

1Panel 明确要求不要让 Watchtower 或自动化脚本持续高频请求该地址，请求过于频繁或次数过多可能被限制。这个临时地址适合人工拉取或低频使用，不应作为无人值守、高频更新流程的唯一镜像来源。

默认可以先尝试 DaoCloud。需要备用地址时，只增加一个经过同样验证的来源；地址越多，失效后的累计等待时间和排障成本越高。

检查 Registry 入口响应 ​

可以检查镜像源 /v2/ 入口是否返回 Registry V2 可识别响应。HTTP 200 表示入口直接响应；HTTP 401 如果同时带有 Docker-Distribution-Api-Version 和合理的 WWW-Authenticate，通常是 Registry 的正常鉴权挑战。

bash
curl -sSI https://docker.m.daocloud.io/v2/

没有清晰维护说明、使用条款或配置文档的公共地址不进入默认推荐。入口偶尔返回 200 也不足以证明适合作为长期基础设施。

DaoCloud 的两种使用方式 ​

Docker Hub 可以直接配置 daemon mirror：

json
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

DaoCloud 对多个上游 Registry 更推荐“增加完整前缀”，例如：

bash
docker pull m.daocloud.io/docker.io/library/alpine:3.21
docker pull m.daocloud.io/ghcr.io/owner/app:1.0.0

第二条只是镜像名称的结构示例，owner/app:1.0.0 需要替换为真实存在的公开镜像。不要把 ghcr.io、quay.io 等上游对应的 DaoCloud 地址放进 Docker 的 registry-mirrors；Docker daemon 的这个字段只处理 Docker Hub。

Windows 与 macOS：Docker Desktop 配置镜像源 ​

Windows 与 macOS 使用相同的配置入口：

  1. 打开 Docker Desktop；
  2. 进入 Settings -> Docker Engine；
  3. 把 registry-mirrors 合并到现有 JSON；
  4. 保留已有代理、DNS、日志、地址池和 insecure-registries 配置；
  5. 点击 Apply & Restart，等待 Docker Desktop 恢复。

以首选公共地址为例：

json
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

已有配置时只增加字段：

json
{
  "features": {
    "buildkit": true
  },
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

macOS 验证配置成功 ​

bash
docker info | sed -n '/Registry Mirrors/,+5p'
docker pull alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-release

Windows PowerShell 验证配置成功 ​

powershell
docker info | Select-String "Registry Mirrors" -Context 0,5
docker pull alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-release

Docker Desktop 使用 WSL 2 Linux containers 时，普通 WSL 发行版中的 /etc/docker/daemon.json 通常不控制 Docker Desktop 内部 daemon，应在 Docker Desktop 的 Docker Engine 页面修改。Windows containers 常用基础镜像来自 mcr.microsoft.com，Docker Hub mirror 对这类镜像无效。

Linux Docker Engine 配置镜像源 ​

修改 daemon 配置会重启主机上的 Docker 服务，如果是生产环境应先安排维护窗口并记录运行中的容器：

bash
docker version
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
sudo install -d -m 0755 /etc/docker
sudo test ! -f /etc/docker/daemon.json || \
  sudo cp -a /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo cat /etc/docker/daemon.json 2>/dev/null || true

使用 sudoedit 编辑 /etc/docker/daemon.json 配置文件：

bash
sudoedit /etc/docker/daemon.json

文件不存在或为空时使用：

json
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

文件已有其他字段时，只合并 registry-mirrors，不要覆盖原配置，也不要创建第二个同名键。

安装了 jq 时先检查 JSON，再让 Docker 校验 daemon 配置：

bash
# 校验 json
sudo jq empty /etc/docker/daemon.json
# 校验 docker 配置
sudo dockerd --validate --config-file=/etc/docker/daemon.json

校验通过后重启并检查：

bash
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl status docker --no-pager
docker info | sed -n '/Registry Mirrors/,+5p'

服务启动失败时先读取日志，不要连续重启：

bash
sudo journalctl -u docker -n 100 --no-pager

常见原因包括 JSON 逗号或引号错误、字段重复，以及同一个 daemon 选项同时出现在启动参数和 daemon.json 中。

NAS 配置镜像源：先识别管理方式 ​

不同 NAS 品牌、型号、固件和 Docker 应用可能使用不同配置文件与服务管理方式。设备界面如果明确提供“镜像加速”或 Registry Mirror，应优先使用界面入口，并保留已有设置。

没有明确入口时，可以在维护窗口临时启用 SSH。

先记录容器、端口、Compose 项目和数据卷，再识别运行方式：

bash
docker version
docker compose version
docker ps -a
cat /etc/docker/daemon.json 2>/dev/null
systemctl status docker --no-pager
ps -ef | grep '[d]ockerd'

只有 /etc/docker/daemon.json 和 systemctl status docker 能确认标准 Docker Engine 时，才沿用 Linux 章节的备份、合并、校验和重启流程。

如果固件没有把 Docker 暴露为标准 systemd 服务：

  • 不要猜测服务名；
  • 不要强制结束 dockerd、containerd 或未知守护进程；
  • 使用 NAS 界面重启 Docker 应用；
  • 没有独立入口时，在维护窗口重启 NAS；
  • 固件或 Docker 应用升级后重新检查配置；
  • 操作完成后关闭不再需要的 SSH 服务。

受限或账号专属镜像加速 ​

公共地址无法满足访问范围、额度或自动化需求时，可以切换到云厂商限定地址或账号专属服务。不同服务的接入方式并不相同：有些可以写入 registry-mirrors，有些必须登录独立 Registry 并改写镜像前缀。

账号专属地址比匿名公共地址更容易管理访问范围，但专属域名本身可能相当于访问凭据，不要把真实地址写进公开仓库、镜像、工单截图或共享日志。

阿里云 ACR 镜像加速器（阿里云专属） ​

阿里云 ACR 为阿里云账号或 RAM 用户生成独立的 Docker Hub 加速地址。当前官方规则明确限制为个人开发场景，并且加速地址只允许阿里云 ECS 访问；非阿里云机器可能返回 HTTP 403。生产环境或非阿里云主机应使用 ACR 制品订阅、自己的 Registry 或其他受控方案。

获取流程：

  1. 登录 阿里云容器镜像服务控制台；
  2. 进入 镜像工具 -> 镜像加速器；
  3. 复制当前账号显示的加速器地址；
  4. 不要把地址中的账号专属部分提交到公开代码库。

将控制台地址填入 Docker Desktop 或 Linux 的 registry-mirrors：

json
{
  "registry-mirrors": [
    "https://<你的加速器标识>.mirror.aliyuncs.com"
  ]
}

在阿里云 ECS 上重启 Docker 后验证：

bash
docker info | sed -n '/Registry Mirrors/,+5p'
docker pull alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-release

出现 HTTP 403 时先确认运行主机是否为阿里云 ECS，不要通过公开转发再次封装账号专属地址。

腾讯云镜像加速（腾讯云 CVM） ​

腾讯云提供固定地址 https://mirror.ccs.tencentyun.com，不需要为每个账号生成专属标识，但该地址仅用于腾讯云机器或腾讯云网络环境。非腾讯云主机不要默认配置这个地址。

适用范围与配置流程：

  1. 确认 Docker Engine 运行在腾讯云 CVM；
  2. 备份现有 /etc/docker/daemon.json，保留其中已有字段；
  3. 将腾讯云固定地址合并到 registry-mirrors；
  4. 校验 JSON 和 Docker daemon 配置，再重启 Docker；
  5. 依次执行 docker info、镜像拉取和容器运行验证。
json
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com"
  ]
}
bash
sudo jq empty /etc/docker/daemon.json
sudo dockerd --validate --config-file=/etc/docker/daemon.json
sudo systemctl restart docker
docker info | sed -n '/Registry Mirrors/,+5p'
docker pull alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-release

如果腾讯云 CVM 仍然无法拉取，先检查实例网络、DNS、Docker 日志和镜像名称。不要把这个受网络范围限制的地址转发给其他环境使用。

轩辕镜像 ​

轩辕镜像 提供登录仓库和专属域名两种方式。官网 xuanyuan.cloud 是服务网站，不是 Registry 地址，不能把 https://xuanyuan.cloud 写入 registry-mirrors。

登录仓库方式 ​

注册并购买所需流量包后，进入 个人中心 -> 用户信息 -> 镜像仓库信息，查看系统生成的“镜像账户”和“镜像密码”。登录仓库固定为 docker.xuanyuan.run，推荐使用交互式登录，避免凭据进入命令历史：

bash
docker login docker.xuanyuan.run
docker pull docker.xuanyuan.run/library/busybox:1.37.0
docker run --rm docker.xuanyuan.run/library/busybox:1.37.0 echo mirror-ok

登录时按提示输入镜像账户和镜像密码。使用这种方式时，需要把原 Docker Hub 镜像改写为：

text
docker.xuanyuan.run/<原镜像路径>:<tag>

例如 Docker Hub 官方镜像要保留 library/。轩辕镜像用于代理拉取，不支持 docker push，不能作为用户自己的私有制品仓库。

专属域名方式 ​

开通支持专属域名的套餐后，从控制台复制系统分配的完整域名，形式类似 ***.xuanyuan.run。该方式免 docker login，但域名会消耗所属账号的流量或额度，应像访问凭据一样保护，并按服务能力限制来源。

直接拉取时替换镜像前缀：

bash
docker pull ***.xuanyuan.run/library/busybox:1.37.0

如果该专属域名绑定的是 Docker Hub 上游，也可以将控制台显示的 HTTPS 地址配置为 Docker Hub mirror：

json
{
  "registry-mirrors": [
    "https://***.xuanyuan.run"
  ]
}

Compose 同样可以使用专属域名作为完整前缀：

yaml
services:
  app:
    image: ***.xuanyuan.run/library/nginx:1.27-alpine

***.xuanyuan.run 只是格式示例，必须替换为控制台实际分配的完整域名。不同上游使用各自对应的专属域名；不要把 GHCR 等上游的专属域名配置成 Docker Hub 的 daemon mirror。

毫秒镜像专属域名 ​

毫秒镜像的专属域名与账号绑定，支持免登录拉取，适合服务器和 CI/CD。拉取会消耗域名所属账号的资源包或余额，因此专属域名应按凭据管理，并通过 IP 白名单限制来源。

创建和使用：

  1. 登录毫秒镜像控制台并打开“专属域名”；
  2. 点击“新增域名”；
  3. 为普通 Docker Hub 镜像选择 docker.io 上游；
  4. 选择域名后缀和有效期，并按实际出口配置 IP 白名单；
  5. 创建后复制带 https:// 的地址；
  6. 把地址合并到 Docker Desktop 或 Linux 的 registry-mirrors；
  7. 重启 Docker，再完成 info、pull 和 run 验证。
json
{
  "registry-mirrors": [
    "https://<你的专属域名>.d.1ms.run"
  ]
}

一个专属域名只对应一个上游。ghcr.io/owner/app 需要选择 ghcr.io 对应的专属域名，并按完整 Registry 地址使用，不能把 GHCR 专属域名当成 Docker Hub daemon mirror。

企业私有缓存 ​

如果是企业内部使用，多台服务器、团队共享或生产环境更适合部署企业私有 Registry 或镜像缓存。私有缓存减少重复下载，但不会自动解决镜像可信度、许可证、漏洞、tag 漂移和上游限流问题。

Docker Distribution pull-through cache ​

Docker Distribution 可以作为 Docker Hub 的 pull-through cache。以下配置只绑定本机回环地址，适合在一台 Linux 主机上验证缓存链路；多主机共享前必须配置受信任 HTTPS、访问控制、防火墙和容量监控。

创建目录：

bash
mkdir -p docker-hub-cache/{config,data}
cd docker-hub-cache

创建 config/config.yml：

yaml
version: 0.1

log:
  fields:
    service: docker-hub-cache

storage:
  delete:
    enabled: true
  filesystem:
    rootdirectory: /var/lib/registry

http:
  addr: 0.0.0.0:5000

proxy:
  remoteurl: https://registry-1.docker.io

创建 compose.yaml：

yaml
services:
  registry-cache:
    image: registry:3.1.1
    container_name: docker-hub-cache
    restart: unless-stopped
    ports:
      - "127.0.0.1:5000:5000"
    volumes:
      - ./config/config.yml:/etc/distribution/config.yml:ro
      - ./data:/var/lib/registry

解析并启动：

bash
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 registry-cache
curl -fsS http://127.0.0.1:5000/v2/

同一主机的 /etc/docker/daemon.json 可以指向回环地址：

json
{
  "registry-mirrors": [
    "http://127.0.0.1:5000"
  ]
}

重启 Docker 后，拉取一个尚未缓存的固定版本镜像：

bash
docker pull alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-release
docker compose logs --tail=200 registry-cache
du -sh data

成功信号包括：Docker daemon 已加载回环 mirror；首次拉取时缓存日志出现上游请求；data/ 增长；第二次拉取相同 digest 时能够复用缓存。

跨主机使用时，不要直接暴露示例中的 HTTP 端口。应给缓存入口配置受信任 HTTPS，并限制允许访问的客户端。Distribution 支持在 proxy 配置中加入 Docker Hub 用户名和密码以访问该账号可见的私有镜像，但这样会让镜像缓存的使用者间接获得该账号可访问的内容。只有在下游缓存同样启用认证、账号权限最小化并通过秘密管理系统注入凭据时才能启用。

缓存数据可以重新从上游取得，通常不必作为业务数据备份；需要备份的是 config.yml、TLS、认证配置和部署清单。清理缓存前先停止写入，并确认下一次拉取可以访问上游。

Harbor Proxy Cache ​

已经运行 Harbor 的团队可以创建 Proxy Cache 项目。Harbor 支持 Docker Hub、GHCR、Quay、AWS ECR、Azure ACR、Google Container Registry、JFrog Artifactory 和其他 Harbor/Registry 上游。

配置步骤：

  1. 以 Harbor 系统管理员登录；
  2. 在 Registries 中创建目标上游 Endpoint，选择正确的 provider 和上游地址；
  3. 需要私有镜像时填写最小权限上游账号，并先执行连接测试；
  4. 新建 Project，打开 Proxy Cache，选择刚创建的 Endpoint；
  5. 设置项目访问范围、成员、配额和 tag retention；
  6. 为自动化客户端创建只读 Robot Account；
  7. 使用 Harbor 地址和 Proxy Cache 项目名改写镜像前缀。
bash
docker login harbor.example.com
docker pull harbor.example.com/dockerhub/library/alpine:3.21

dockerhub 是示例项目名。Harbor Proxy Cache 不是 daemon 的透明 registry-mirrors 写法，客户端需要使用：

text
<Harbor 地址>/<Proxy Cache 项目>/<原镜像路径>:<tag>

上游账号能读取的全部镜像都可能通过 Proxy Cache 项目暴露给有权访问该项目的 Harbor 用户。配置私有上游前，应单独创建最小权限账号，并检查 Harbor 项目成员、Robot Account、审计日志和保留策略。

不修改全局配置：直接使用代理镜像名 ​

临时排障时可以直接使用完整代理前缀，不需要重启 Docker。以 DaoCloud 推荐的增加前缀方式为例：

bash
docker pull m.daocloud.io/docker.io/library/alpine:3.21
docker run --rm \
  m.daocloud.io/docker.io/library/alpine:3.21 \
  cat /etc/alpine-release

Docker Hub 官方镜像需要保留 library/，用户或组织镜像保留原路径：

bash
docker pull m.daocloud.io/docker.io/portainer/portainer-ce:2.27.9

本地镜像名会包含代理 hostname。既有脚本必须使用普通名称时，可以显式增加标签：

bash
docker tag \
  m.daocloud.io/docker.io/library/alpine:3.21 \
  alpine:3.21

重新打标签不会让后续的 docker pull alpine:3.21 永久使用代理。长期使用仍应配置 daemon mirror，或者使用组织管理的 Registry。

Docker Compose 如何使用镜像加速 ​

daemon mirror 生效后，Compose 文件不需要修改镜像名：

yaml
services:
  web:
    image: nginx:1.27-alpine

按顺序检查配置、拉取、启动与状态：

bash
docker compose config
docker compose pull
docker compose up -d
docker compose ps

不方便修改 daemon 时，可以临时改写 image:：

yaml
services:
  web:
    image: m.daocloud.io/docker.io/library/nginx:1.27-alpine

临时改写会改变本地镜像名称，也会把外部代理地址固化进 Compose。共享或生产使用的 Compose 应优先保留原始镜像名，通过 daemon、企业 Registry 或发布流水线控制镜像来源。

构建镜像仍然失败：检查 BuildKit ​

只执行 docker pull 和 docker compose up 的用户可以跳过这一节。BuildKit 是 Docker 当前主要的镜像构建引擎，docker buildx 使用 docker-container driver 时会启动独立的 BuildKit daemon，不能假设独立 builder 自动继承宿主机的 registry-mirrors。

先检查当前 builder：

bash
docker buildx ls
docker buildx inspect --bootstrap

如果 DRIVER 是 docker-container，在当前构建目录创建 buildkitd.toml：

toml
[registry."docker.io"]
  mirrors = ["docker.m.daocloud.io"]

使用新名称创建 builder，避免覆盖已有配置和缓存：

bash
docker buildx create \
  --name cn-mirror \
  --driver docker-container \
  --buildkitd-config ./buildkitd.toml \
  --use \
  --bootstrap
docker buildx inspect cn-mirror --bootstrap

如果 docker pull 成功，但构建仍停在 load metadata 并访问 registry-1.docker.io，应先检查 builder driver 和 buildkitd.toml。docker build --network=host 通常不能修复基础镜像元数据解析，因为解析发生在构建容器网络生效之前。

Docker 镜像源分层验证 ​

Registry 端点 ​

bash
curl -sSI https://docker.m.daocloud.io/v2/

HTTP 200，或者带 Registry V2 标头与合理鉴权挑战的 HTTP 401，都可以说明入口能够响应。端点成功不等于完整镜像可用。

daemon 配置 ​

bash
docker info | sed -n '/Registry Mirrors/,+5p'

Registry Mirrors 中出现目标地址，表示 daemon 已读取配置。这个结果不能单独证明实际流量经过目标 mirror。

镜像拉取与容器运行 ​

bash
docker pull alpine:3.21
docker image inspect alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-release

成功条件是 manifest 和所有 layer 拉取完成，镜像可以 inspect，容器输出 Alpine 版本后正常退出。需要证明流量路径时，还要结合 Docker daemon、私有缓存或代理侧日志。

Compose 与 BuildKit ​

bash
docker compose pull
docker compose up -d
docker compose ps

Compose 的成功条件是镜像拉取完成，服务进入预期状态。验证前文创建的独立 BuildKit builder 时，在空目录准备一个最小构建：

dockerfile
FROM alpine:3.21
RUN cat /etc/alpine-release

将文件保存为 Dockerfile.mirror-check，再明确指定 builder 执行：

bash
docker buildx build \
  --builder cn-mirror \
  --pull \
  --progress=plain \
  --load \
  -f Dockerfile.mirror-check \
  -t mirror-check:local \
  .
docker run --rm mirror-check:local cat /etc/alpine-release

构建日志应显示基础镜像元数据和 layer 解析成功，生成的本地镜像也应能够运行。要证明请求确实经过指定 mirror，还需结合 BuildKit daemon 或代理侧日志；只运行 docker buildx imagetools inspect 只能检查远程 manifest，不能证明 builder 已加载 buildkitd.toml。Compose 拉取成功而这个构建失败时，先检查 BuildKit driver，不要同时替换所有镜像源。

常见问题 ​

现象主要判断处理方式
/v2/ 返回 401Registry 正常发起 Bearer 鉴权的常见行为检查 Registry V2 标头和 token realm
docker info 没有目标 mirrorDesktop 未应用、daemon 未重启或 JSON 未加载检查配置，执行 Apply & Restart 或查看服务日志
完整代理名称能拉取，普通名称失败代理入口可用，但 daemon mirror 未生效确认编辑的是当前 daemon 配置
Docker Hub 正常，GHCR 仍超时Docker Hub mirror 不处理 GHCR使用 GHCR 对应代理前缀或企业同步
docker pull 成功，buildx 失败独立 BuildKit 没有 mirror 配置检查 driver，并配置 buildkitd.toml
HTTP 403地址受账号、云主机或来源范围限制检查服务条款、主机归属、IP 白名单和专属地址
HTTP 429上游或代理限流降低频率，使用账号专属地址或企业缓存
Linux Docker 重启失败JSON 无效或配置项冲突运行 jq、dockerd --validate，查看日志并恢复备份
NAS 修改后没有变化配置文件不是当前 Docker 应用读取的位置识别真实 daemon，并使用设备界面重启

镜像配置回滚 ​

Docker Desktop 中，从 Settings -> Docker Engine 删除本次增加的 mirror，保留其他配置，然后点击 Apply & Restart。

Linux 与确认使用标准 Docker Engine 的 NAS，可以恢复备份：

bash
sudo cp -a /etc/docker/daemon.json.bak /etc/docker/daemon.json
sudo dockerd --validate --config-file=/etc/docker/daemon.json
sudo systemctl restart docker

如果原文件不存在，只删除本次新增的 registry-mirrors 字段，不要顺带删除其他 daemon 配置。

BuildKit 可以切回原 builder：

bash
docker buildx use default

企业缓存需要停止时，先把客户端 daemon 或部署清单切回已验证的来源，再停止缓存服务。没有确认依赖范围和缓存用途前，不要直接清理 Harbor 项目或 Distribution 数据目录。

安全与维护 ​

  • 不要通过匿名公共代理访问 Docker Hub 私有仓库，也不要向不受控代理发送私有 Registry 凭据；
  • 公共代理可以观察来源 IP、镜像名称、tag、访问频率和时间；
  • 账号专属域名可能直接消耗账号额度，应按凭据保护并限制来源；
  • 生产部署应固定明确 tag，关键镜像进一步固定 digest，并保留来源、升级和回滚记录；
  • 公共代理和上游 Registry 都可能限流，定期执行端点、小镜像拉取和实际构建检查；
  • mirror 不会消除 Docker Hub 公平使用策略、镜像许可证义务或供应链风险；
  • 私有缓存应监控磁盘、缓存命中、上游错误、证书期限、认证和保留策略；
  • 固定生产镜像更适合提前同步到受控 Registry，而不是在发布时临时依赖公共代理。

总结 ​

个人临时使用可以先从有公开维护说明的单一公共镜像源开始；账号专属地址适合需要来源限制和独立额度的开发环境；团队与生产环境应优先建设 Harbor、Docker Distribution 或镜像同步流程。无论使用哪种方式，都要先确认原始 Registry，再完成端点、daemon、拉取、运行和构建验证。

参考资料 ​

全部公开文章由同一个站点构建和发布。

Guides Platform