DockerHub 镜像加速配置指南（Windows、Mac、Linux）

二、最稳妥的使用方式：在 Docker 守护进程里配置 registry mirrors

Windows / macOS（Docker Desktop）

1. 打开 Docker Desktop → Settings → Docker Engine。
2. 点击 Apply & Restart 重启生效。

将配置替换/合并为（按需增减镜像源）：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker-0.unsee.tech",
    "https://docker.m.daocloud.io"
  ],
  "features": {
    "buildkit": true
  }
}

验证：终端执行 docker info | findstr /i "Registry Mirrors"（Win）或 docker info | grep -A 3 "Registry Mirrors"（macOS/Linux），拉取测试：docker pull hello-world 或 docker pull busybox:latest。

Linux（dockerd / systemd）

Rootless Docker（如用 dockerd-rootless-setuptool.sh 安装）：将同样的 JSON 放到 ~/.config/docker/daemon.json，然后：

systemctl --user daemon-reload
systemctl --user restart docker

重载并重启：

sudo systemctl daemon-reload
sudo systemctl restart docker

创建/编辑 /etc/docker/daemon.json：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker-0.unsee.tech",
    "https://docker.m.daocloud.io"
  ],
  "live-restore": true,
  "features": {
    "buildkit": true
  }
}

containerd（含 k3s/nerdctl 等）

许多发行版/平台（如 k3s）默认用 containerd，需在其层面配置镜像加速。

1. 验证（任选其一）：
   • crictl pull docker.io/library/busybox:latest
   • nerdctl --namespace k8s.io pull docker.io/library/busybox:latest

重启：

sudo systemctl restart containerd

在 /etc/containerd/config.toml 中找到（或新增）以下段落，并替换为：

[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = ["https://docker.1ms.run", "https://docker-0.unsee.tech", "https://registry-1.docker.io"]

若没有配置文件，先生成默认模板：

sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml >/dev/null

独立 BuildKit（buildkitd）

对纯 BuildKit 环境（CI/CD 常见），在 BuildKit 层配置镜像最有效。

/etc/buildkit/buildkitd.toml：

[registry."docker.io"]
  mirrors = ["https://docker.1ms.run", "https://docker-0.unsee.tech"]

重启：sudo systemctl restart buildkit（或按你的 Supervisor 重启）。

三、两种拉取方式的区别（理解之后排障更容易）

1. 守护进程镜像（推荐） 在 daemon.json/config.toml 里配置 registry-mirrors / endpoint 后，你仍然使用原始名称拉取：

docker pull docker.io/library/nginx:alpine

Docker 会自动优先走镜像源，失败再回源官方。

2. 直接用镜像域名拉取（应急/测试） 不改系统配置，直接把镜像域名写在镜像名前缀：

docker pull docker.1ms.run/library/nginx:alpine

注意：不同镜像站的路径规则可能略有差异，通常 library/ 前缀仍需保留。

四、进阶：多镜像回退策略 & 最佳实践

• 多源并行配置：把 2~4 个镜像一起写进配置，Docker/containerd 会在失败时尝试其他端点。
• 保留官方回源：最后一个保留 https://registry-1.docker.io，避免'全部超时'导致业务不可用。
• 按网络就近排序：将你服务器网络访问最快/最稳定的源放在列表前面。
• 仅用于公共镜像：第三方镜像可能记录访问日志，不建议用于企业私有镜像/需要鉴权的仓库。
• 避免 HTTP 明文：尽量使用 HTTPS；除非明确可信且内网使用，否则不要添加到 insecure-registries。
• 登录减限速：必要时执行 docker login 使用自己的 DockerHub 账号以抑制匿名限速（不要把凭据交给第三方域名）。

五、常见问题（FAQ）

Q1：配置后还是慢/报错（TLS/证书/握手失败）？

• 确认镜像 URL 带 https:// 且没有尾部斜杠。
• 同步系统时间并更新 CA：sudo apt-get install --reinstall ca-certificates 或等价命令。
• 公司代理/防火墙可能拦截 SNI，尝试换网络或更换镜像源顺序。
• 临时用'直接用镜像域名拉取'的方式验证镜像站是否可用。

Q2：提示 Too Many Requests / 429？

• 切换到另一个镜像源或添加更多备选。
• 执行 docker login 使用个人账号拉取（仍建议只拉公共镜像）。

Q3：Kubernetes 节点也需要加速？

• 如果集群 runtime 是 containerd，请在每个节点的 /etc/containerd/config.toml 配置同样的 mirrors，然后滚动重启节点的 containerd/kubelet。

Q4：如何确认加速生效？

• docker info 能看到 Registry Mirrors 列表。
• time docker pull busybox:latest 对比前后时延（首次拉取最具参考意义）。

六、批量测速脚本（Linux）

说明：该脚本通过访问 /v2/ 和试拉 busybox:latest 的 manifest 来做'轻量连通/响应'检测，不会大规模下载层文件；实际速度仍受网络波动与镜像站后端缓存影响。

#!/usr/bin/env bash
set -euo pipefail

MIRRORS=(
  "https://docker.1ms.run"
  "https://docker-0.unsee.tech"
  "https://docker.m.daocloud.io"
  "https://ccr.ccs.tencentyun.com"
  "https://hub.xdark.top"
  "https://dhub.kubesre.xyz"
  "https://docker.kejilion.pro"
  "https://docker.xuanyuan.me"
  "https://docker.hlmirror.com"
  "https://run-docker.cn"
  "https://docker.sunzishaokao.com"
  "https://image.cloudlayer.icu"
  "https://docker.tbedu.top"
  "https://hub.crdz.gq"
  "https://docker.melikeme.cn"
)

printf "%-34s %-10s %-s\n" "MIRROR" "V2(ms)" "NOTES"

for m in "${MIRRORS[@]}"; do
  t=$(curl -o /dev/null -s -w "%{time_total}" "${m}/v2/" || echo "fail")
  note=""
  if [ "$t" == "fail" ]; then
    note="connect error"
  else
    # 取毫秒
    t=$(awk -v n="$t" 'BEGIN{printf "%.0f", n*1000}')
    printf "%-34s %-10s %-s\n" "$m" "$t" "$note"
  fi
done

若你无权修改系统全局配置，也可把单个镜像站前缀写入镜像名测试： docker pull docker.1ms.run/library/busybox:latest

七、安全与合规小贴士

• 第三方镜像站只用来拉公共镜像；私有仓库请使用企业自建 Harbor / 官方 DockerHub 私有库 / 公有云镜像服务。
• 不要把企业凭据/令牌用于第三方域名。
• 按需开启镜像内容信任（Docker Content Trust/Notary），在供应链里增加签名校验。
• 生产环境推荐同时准备：镜像加速 + 企业级私有 Registry + 离线缓存（本地 registry mirror） 的组合。

八、故障排查清单（Checklist）

• docker info 是否显示了 Registry Mirrors 并且含你的新镜像源
• curl https://<mirror>/v2/ 是否返回 HTTP 200/401/403（能连通）
• DNS 能否解析镜像站；必要时尝试改用公共 DNS（如 223.5.5.5/119.29.29.29）
• 环境是否存在公司代理/网关拦截（证书替换导致 TLS 校验失败）
• 列表顺序是否把最优镜像放在最前，且保留了 https://registry-1.docker.io 兜底
• 系统时间、CA 证书是否正确

九、一页抄作业（可直接粘贴）

dockerd（/etc/docker/daemon.json）

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker-0.unsee.tech",
    "https://docker.m.daocloud.io"
  ],
  "features": {
    "buildkit": true
  }
}

containerd（/etc/containerd/config.toml）

[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = ["https://docker.1ms.run", "https://docker-0.unsee.tech", "https://registry-1.docker.io"]

Docker Desktop（Settings → Docker Engine）

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker-0.unsee.tech",
    "https://docker.m.daocloud.io"
  ],
  "features": {
    "buildkit": true
  }
}