国内 Docker 镜像加速源配置指南（Windows/Linux/containerd）

1）Windows / macOS（Docker Desktop）

1. 打开 Docker Desktop → Settings → Docker Engine
2. 将配置替换/合并为（按需增减镜像源）：

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

3. 点击 Apply & Restart 生效

验证：Win：docker info | findstr /i "Registry Mirrors"；macOS/Linux：docker info | grep -A 3 "Registry Mirrors"。拉取测试：docker pull hello-world 或 docker pull busybox:latest

2）Linux（dockerd / systemd）

1. 创建/编辑 /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}}

2. 重载并重启：

sudo systemctl daemon-reload
sudo systemctl restart docker

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

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

3）containerd（含 k3s/nerdctl 等）

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

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

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

2. 修改 /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"
      ]

3. 重启：

sudo systemctl restart containerd

4. 验证（任选其一）：

• crictl pull docker.io/library/busybox:latest
• nerdctl --namespace k8s.io pull docker.io/library/busybox:latest

4）独立 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 个镜像一起写进配置，失败自动回退到下一项
• 保留官方回源：最后保留 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/" 2>/dev/null || echo "fail")
  note=""
  if [ "$t" == "fail" ]; then
    note="connect error"
  else
    ms=$(awk -v n="$t" 'BEGIN{printf "%.0f", n*1000}')
    printf "%-34s %-10s %-s\n" "$m" "$ms" "$note"
  fi
done

无法改系统配置？ 可把镜像站前缀写入镜像名验证： docker pull docker.1ms.run/library/busybox:latest

七、安全与合规小贴士

• 第三方镜像站只用于公共镜像；企业与私有镜像请使用 Harbor / 官方私有库 / 公有云镜像服务
• 不要将企业凭据/令牌用于第三方域名
• 供应链安全建议开启 Docker Content Trust/Notary
• 生产建议组合：镜像加速 + 企业级私有 Registry + 本地缓存镜像站（registry mirror）

八、故障排查清单（Checklist）

• docker info 是否显示 Registry Mirrors 且包含你的新镜像源
• curl https://<mirror>/v2/ 返回 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}}