路由配置网标志路由配置网ROUTECFG.COM

Docker 镜像加速器配置:拉取超时、403 与 Containerd 排障

更新于 2026-10-24 · routecfg.com

简答:Docker 镜像加速器要先按运行时选择入口:Engine 改 daemon.json,Desktop 在 Settings > Docker Engine。

定义:Docker 镜像加速器是为镜像拉取提供额外访问入口的配置,不等同于私有镜像仓库、镜像代理,也不代表某个公共地址会长期有效。

先看运行时:Docker 镜像加速器配置入口速查

如果你遇到 Docker Hub 拉取超时、连接失败或速度不稳定,先不要直接复制网上流传的地址。公共地址可能受账号、地域、云环境、镜像范围或服务状态限制;本文不罗列未经当前环境验证的公共地址,而是给出配置入口、验证方法和故障判定标准。

运行环境配置入口改完后怎么验证关键限制
Linux Docker Engine/etc/docker/daemon.json;Rootless 模式通常是 ~/.config/docker/daemon.jsondocker info、docker pull hello-world不能让 JSON 字段与 dockerd 启动参数重复
Docker DesktopSettings > Docker Engine应用配置后执行 docker info 和 docker pull操作的是 Docker Desktop 管理的 Engine,不一定是 WSL 或远程主机
Containerd 2.x/etc/containerd/config.toml 与 /etc/containerd/certs.d/docker.io/hosts.toml重启 Containerd,查看 systemctl status 和实际拉取结果使用 io.containerd.cri.v1.images 配置段
Containerd 1.x/etc/containerd/config.toml 与 certs.d/docker.io/hosts.toml重启 Containerd,再用实际运行时拉取镜像使用 io.containerd.grpc.v1.cri 配置段
OpenWrt 上的 dockerd以已安装软件包和服务脚本的实际配置为准logread、服务状态和实际拉取不同固件与软件包不保证使用相同路径,不能直接套用普通发行版命令

Docker 官方文档列出了 Docker Engine 的常规、Rootless 和 Windows 配置文件位置,并说明 JSON 配置与启动参数不能重复定义同一个选项。Docker daemon 配置文档可用于核对当前环境。

Linux Docker Engine:daemon.json 配置与验证

普通 Linux Docker Engine 通常使用 /etc/docker/daemon.json;Rootless 模式应先确认当前用户服务和配置目录。下面的地址是占位符,必须替换为你从对应服务控制台、企业仓库或内部代理获得的地址,不能把占位符原样保存。

  1. 先确认 Docker CLI 连接到哪一个 Engine:
    docker context show
    docker info
  2. 备份已有配置,并创建目录:
    sudo mkdir -p /etc/docker
    sudo cp -a /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null || true
  3. 在已有 JSON 中加入 registry-mirrors。如果文件已有其他字段,注意逗号和括号:
    {
      "registry-mirrors": [
        "https://替换为实际镜像加速器地址"
      ]
    }
  4. 先校验 JSON,再重载并重启 Docker:
    python3 -m json.tool /etc/docker/daemon.json
    sudo systemctl daemon-reload
    sudo systemctl restart docker
  5. 查看 Docker 是否读取了配置,并做实际拉取:
    docker info
    docker pull hello-world

在 docker info 输出中查找 Registry Mirrors。如果看不到该字段,先检查当前 Docker Context、配置文件路径、JSON 格式和服务日志,不要直接更换地址。

Docker 官方说明,Docker Hub 镜像可以通过 registry-mirrors 使用镜像缓存或镜像代理;该机制不能简单理解为所有仓库的通用加速。Docker Hub 镜像缓存文档明确说明,其他私有 Registry 不能按同一方式被镜像。

Windows 和 macOS:Docker Desktop 怎么配置

使用 Docker Desktop 时,不要直接把 Linux 的 /etc/docker/daemon.json 当成宿主机文件修改。Docker 官方设置页说明,Docker Desktop 可以在 Dashboard 的 Settings 中编辑 Docker Engine 配置。

  1. 打开 Docker Desktop。
  2. 进入 Settings > Docker Engine。
  3. 在现有 JSON 中加入配置,示例为:
    {
      "registry-mirrors": [
        "https://替换为实际镜像加速器地址"
      ]
    }
  4. 点击应用配置,等待 Docker Desktop 重新加载 Engine。
  5. 在 PowerShell、Windows Terminal 或 macOS Terminal 中执行:
    docker context show
    docker info
    docker pull hello-world

Windows 使用 WSL 2 时,重点是确认终端中的 Docker CLI 连接到 Docker Desktop 的 Engine,而不是另一套独立 Docker 服务。macOS 也可能连接到远程 Context,因此 docker context show 比只看配置文件更可靠。

Docker Desktop 的代理设置不应照搬 Linux 的 daemon 代理配置。Docker 官方文档明确说明,写入 daemon.json 的代理配置会被 Docker Desktop 忽略;Desktop 应在其设置中的代理相关入口配置。可参考 Docker daemon 代理配置文档和Docker Desktop 设置文档。

Containerd 1.x 与 2.x:先查版本再写 hosts.toml

Containerd 的镜像配置不能直接复制 Docker 的 registry-mirrors。先执行版本检查:

containerd --version

Containerd 官方文档已经区分 1.x 和 2.x 的 CRI 配置段,并推荐使用 config_path 指向包含 hosts.toml 的目录。参考containerd Registry Configuration 文档。

Containerd 2.x 配置段

version = 3

[plugins."io.containerd.cri.v1.images".registry]
  config_path = "/etc/containerd/certs.d"

Containerd 1.x 配置段

version = 2

[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"

不要把两段同时写入同一个配置文件。确认版本和配置段后,创建 Docker Hub 对应目录:

sudo mkdir -p /etc/containerd/certs.d/docker.io

创建 hosts.toml,地址必须替换:

sudo tee /etc/containerd/certs.d/docker.io/hosts.toml >/dev/null <<'EOF'
server = "https://registry-1.docker.io"

[host."https://替换为实际镜像加速器地址"]
  capabilities = ["pull", "resolve"]
EOF

重启并查看日志:

sudo systemctl restart containerd
sudo systemctl status containerd --no-pager
sudo journalctl -u containerd --no-pager -n 100

Containerd 的 hosts.toml 可以定义多个 Host;官方文档说明会按配置顺序尝试 Host,之后再使用 server 作为回退。对于生产环境,仍应优先使用自己控制的仓库或代理,而不是把多个公共地址当成可靠的故障切换机制。

镜像加速器、代理和私有仓库怎么选

“镜像加速器”“镜像源”“镜像代理”和“私有仓库”解决的问题不同。先按镜像来源、是否需要权限、是否用于生产环境来选择。

方案配置对象适用场景限制与判断方法
Docker Hub 镜像加速器registry-mirrors 或 Containerd Host个人开发、临时拉取 Docker Hub 公共镜像只针对相应 Registry;先看服务范围,再用实际 docker pull 验证
HTTP/HTTPS 代理Docker daemon 的 proxies 或 systemd 环境变量需要统一出口、企业代理或办公网络访问控制代理必须允许 Registry 请求;HTTPS 检查还涉及代理 CA 证书
私有镜像仓库内部 Registry、企业云仓库或同步仓库生产部署、权限管理、审计和固定版本需要维护同步、权限、存储和证书
本地镜像缓存Registry pull-through cache多台 Docker 主机重复拉取同一批公共镜像需要自行维护缓存和上游访问权限

如果目标镜像来自 ghcr.io、quay.io 或其他 Registry,不能默认认为 Docker Hub 的 registry-mirrors 会生效。应按目标 Registry 单独配置代理、Containerd Host 或私有同步仓库。

Docker daemon 使用代理时,Linux 可以在 daemon.json 中配置:

{
  "proxies": {
    "http-proxy": "http://替换为代理地址:<端口>",
    "https-proxy": "http://替换为代理地址:<端口>",
    "no-proxy": "localhost,127.0.0.1,.example.org"
  }
}

配置后重启 Docker。也可以使用 systemd drop-in:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf >/dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://替换为代理地址:<端口>"
Environment="HTTPS_PROXY=http://替换为代理地址:<端口>"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

端口使用设置页或代理管理员提供的值,不要把示例占位符直接用于生产。代理证书替换了 Registry 的证书链时,应安装企业代理提供的 CA,而不是关闭 TLS 校验。

OpenWrt 与 NAS:不要套用未经确认的路径

OpenWrt 可以提供 dockerd 软件包,但固件版本、软件源和服务管理方式会影响实际配置入口。OpenWrt 的 dockerd 软件包页面只能证明该软件包信息,不足以证明所有固件都使用同一个配置路径。

在 OpenWrt 上建议按以下顺序确认:

  1. 确认软件包和服务是否存在:
    opkg list-installed | grep -E 'dockerd|docker|containerd'
    ls /etc/init.d/ | grep -E 'docker|containerd'
  2. 查看服务脚本或启动参数,确认实际读取的配置文件:
    grep -R "config-file\|daemon.json\|containerd" /etc/init.d /etc/config 2>/dev/null
  3. 修改后查看系统日志和服务状态:
    /etc/init.d/dockerd restart
    logread | grep -iE 'docker|dockerd|containerd'
  4. 最后从路由器本机执行实际拉取,区分 Docker 配置问题和 DNS、默认路由、出口策略问题。

如果 OpenWrt 只是旁路由或 DNS 网关,而 Docker 实际运行在另一台主机上,那么路由器上的 DNS、分流和 MTU 只能影响链路,不能替代目标主机上的 Docker Engine 或 Containerd 配置。可以继续参考站内的OpenWrt DNS 边界:解析、缓存与泄漏排查,把解析、默认网关和镜像仓库访问分开检查。

NAS 厂商的图形界面也不应直接套用 /etc/docker/daemon.json。先在 NAS 的 Docker 应用设置中确认它使用的是 Docker Engine、Containerd 还是厂商代理,再执行实际拉取验证。

报错速查:一条命令先判断哪一层出问题

现象优先怀疑先执行的验证处理方向
JSON parse error、配置保存失败逗号、引号、括号或注释错误python3 -m json.tool /etc/docker/daemon.json恢复备份后逐项加入字段,不要在 JSON 中写注释
duplicate directive、ExecStart 重复同一选项同时写在启动参数和 JSON 中systemctl cat docker保留一个配置入口,按照 Docker 官方 daemon 文档处理
403 Forbidden账号、地域、云环境或访问范围限制docker pull hello-world,并查看服务文档确认地址是否仅适用于特定网络,必要时改用适用的代理或私有仓库
i/o timeout、context deadline exceededDNS、出口、代理、MTU 或 Registry 不可达getent hosts <仓库主机名>、curl -I --connect-timeout 10 <仓库地址>/v2/先区分解析、TCP、TLS 和认证阶段,不要只重复重启 Docker
x509 certificate signed by unknown authority企业代理或私有仓库 CA 未被信任curl -Iv <仓库地址>安装正确 CA,避免用关闭 TLS 校验替代证书配置
/v2/ 返回 401Registry 可达但需要认证curl -I <仓库地址>/v2/401 不等于网络故障;继续检查登录、权限和实际拉取
latest 内容滞后缓存或加速器未同步最新内容改用明确 Tag 或 Digest 对比生产环境固定版本,并同步到可控的私有仓库

检查镜像加速器或代理地址时,若地址中包含路径,不能把完整 URL 直接当作 DNS 主机名。可以先提取主机名:

MIRROR_URL='https://替换为实际地址'
MIRROR_HOST=$(printf '%s\n' "$MIRROR_URL" | sed -E 's#^https?://([^/]+).*#\1#')
printf '%s\n' "$MIRROR_HOST"
getent hosts "$MIRROR_HOST"
curl -I --connect-timeout 10 "$MIRROR_URL/v2/"

/v2/ 返回 401 可能表示 HTTPS 入口可达但需要认证;是否能拉取镜像,仍要以登录状态和实际 docker pull 结果为准。

配置完成后的自查顺序

  1. 确认运行时:执行 docker context show、docker info 或 containerd --version,不要把 Docker Engine 和 Containerd 当成同一个配置入口。
  2. 确认配置文件:检查当前服务实际读取的路径,JSON 使用 JSON 校验,TOML 使用对应服务启动检查。
  3. 确认没有重复参数:检查 systemd 的 ExecStart、Docker Desktop 设置和配置文件,避免同一选项重复定义。
  4. 确认网络链路:先做 DNS,再做 HTTPS,再判断认证和权限;必要时检查代理 CA、MTU 和默认路由。
  5. 确认 Registry 范围:Docker Hub 的镜像加速配置不能自动覆盖其他 Registry,目标仓库不同就按仓库单独验证。
  6. 确认镜像版本:开发环境可以临时拉取 Tag,生产环境使用明确版本 Tag 或 Digest,并优先使用可控仓库。

如果仍然失败,推荐按“运行时 → 配置格式 → 服务日志 → DNS → HTTPS → 认证权限 → 实际拉取”的顺序排查。这个顺序可以避免把 DNS 或出口问题误判成镜像加速器失效。

参考资料

常见问题

Docker 镜像加速器配置后,为什么 docker info 看不到 Registry Mirrors?

先执行 docker context show,确认当前命令连接到目标 Docker Engine,再检查 JSON 路径、字段名和服务日志。如果实际运行时是 Containerd,不会通过 Docker 的 Registry Mirrors 字段显示,应改查 config_path、hosts.toml 和 Containerd 日志。

Windows 和 macOS 可以直接修改 /etc/docker/daemon.json 吗?

如果使用 Docker Desktop,应进入 Settings > Docker Engine 编辑配置,不要直接套用 Linux 路径。只有当 Docker CLI 实际连接到独立 Linux Engine 或远程主机时,才按那台主机的 daemon.json 配置。

Containerd 2.x 还能使用 io.containerd.grpc.v1.cri 配置段吗?

不能直接按版本 1.x 示例套用。先执行 containerd --version;Containerd 2.x 使用 version = 3 和 io.containerd.cri.v1.images.registry,Containerd 1.x 使用 version = 2 和 io.containerd.grpc.v1.cri.registry,具体配置应以官方 hosts 文档为准。

Docker 镜像加速器返回 403,应该怎么处理?

403 优先检查地址是否绑定特定账号、地域、云环境或网络范围,不要继续重复修改 JSON。若当前机器不满足服务条件,应改用适用的代理、私有仓库或同步方案,并用实际 docker pull 验证。

访问镜像仓库的 /v2/ 返回 401,是不是加速器坏了?

不一定。401 通常表示 HTTPS 入口已经可达,但 Registry 要求认证;它与 DNS 失败、连接超时或证书错误不同。继续检查登录状态、访问权限和实际 docker pull 结果。

配置多个 registry-mirrors 能不能保证自动切换?

不能仅凭配置多个地址就保证按预期故障切换。Docker 的 registry-mirrors 主要针对 Docker Hub,其他 Registry 需要单独配置;生产环境更适合使用可控的私有仓库或代理,并逐个验证地址。

Docker 镜像加速器配置后,latest 还是旧版本怎么办?

先确认该加速器或缓存是否同步最新内容。不要用 latest 判断生产版本,改用明确 Tag 或 Digest;如果服务没有同步新内容,继续重试不会自动改变缓存,生产镜像应同步到可控仓库。

相关阅读

参考资料

  1. Docker daemon 配置概览
  2. Docker Desktop 设置
  3. Docker daemon 代理配置
  4. Docker Hub 镜像缓存
  5. containerd Registry Configuration
  6. OpenWrt dockerd 软件包页面(openwrt.org)
读者交流群(DNS · TUN · Clash 规则配置交流):t.me/routecfg_chat