Docker 镜像加速器配置:拉取超时、403 与 Containerd 排障
简答:Docker 镜像加速器要先按运行时选择入口:Engine 改 daemon.json,Desktop 在 Settings > Docker Engine。
定义:Docker 镜像加速器是为镜像拉取提供额外访问入口的配置,不等同于私有镜像仓库、镜像代理,也不代表某个公共地址会长期有效。
先看运行时:Docker 镜像加速器配置入口速查
如果你遇到 Docker Hub 拉取超时、连接失败或速度不稳定,先不要直接复制网上流传的地址。公共地址可能受账号、地域、云环境、镜像范围或服务状态限制;本文不罗列未经当前环境验证的公共地址,而是给出配置入口、验证方法和故障判定标准。
| 运行环境 | 配置入口 | 改完后怎么验证 | 关键限制 |
|---|---|---|---|
| Linux Docker Engine | /etc/docker/daemon.json;Rootless 模式通常是 ~/.config/docker/daemon.json | docker info、docker pull hello-world | 不能让 JSON 字段与 dockerd 启动参数重复 |
| Docker Desktop | Settings > 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 模式应先确认当前用户服务和配置目录。下面的地址是占位符,必须替换为你从对应服务控制台、企业仓库或内部代理获得的地址,不能把占位符原样保存。
- 先确认 Docker CLI 连接到哪一个 Engine:
docker context show docker info - 备份已有配置,并创建目录:
sudo mkdir -p /etc/docker sudo cp -a /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null || true - 在已有 JSON 中加入
registry-mirrors。如果文件已有其他字段,注意逗号和括号:{ "registry-mirrors": [ "https://替换为实际镜像加速器地址" ] } - 先校验 JSON,再重载并重启 Docker:
python3 -m json.tool /etc/docker/daemon.json sudo systemctl daemon-reload sudo systemctl restart docker - 查看 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 配置。
- 打开 Docker Desktop。
- 进入 Settings > Docker Engine。
- 在现有 JSON 中加入配置,示例为:
{ "registry-mirrors": [ "https://替换为实际镜像加速器地址" ] } - 点击应用配置,等待 Docker Desktop 重新加载 Engine。
- 在 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 --versionContainerd 官方文档已经区分 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 100Containerd 的 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 上建议按以下顺序确认:
- 确认软件包和服务是否存在:
opkg list-installed | grep -E 'dockerd|docker|containerd' ls /etc/init.d/ | grep -E 'docker|containerd' - 查看服务脚本或启动参数,确认实际读取的配置文件:
grep -R "config-file\|daemon.json\|containerd" /etc/init.d /etc/config 2>/dev/null - 修改后查看系统日志和服务状态:
/etc/init.d/dockerd restart logread | grep -iE 'docker|dockerd|containerd' - 最后从路由器本机执行实际拉取,区分 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 exceeded | DNS、出口、代理、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/ 返回 401 | Registry 可达但需要认证 | 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 结果为准。
配置完成后的自查顺序
- 确认运行时:执行
docker context show、docker info或containerd --version,不要把 Docker Engine 和 Containerd 当成同一个配置入口。 - 确认配置文件:检查当前服务实际读取的路径,JSON 使用 JSON 校验,TOML 使用对应服务启动检查。
- 确认没有重复参数:检查 systemd 的
ExecStart、Docker Desktop 设置和配置文件,避免同一选项重复定义。 - 确认网络链路:先做 DNS,再做 HTTPS,再判断认证和权限;必要时检查代理 CA、MTU 和默认路由。
- 确认 Registry 范围:Docker Hub 的镜像加速配置不能自动覆盖其他 Registry,目标仓库不同就按仓库单独验证。
- 确认镜像版本:开发环境可以临时拉取 Tag,生产环境使用明确版本 Tag 或 Digest,并优先使用可控仓库。
如果仍然失败,推荐按“运行时 → 配置格式 → 服务日志 → DNS → HTTPS → 认证权限 → 实际拉取”的顺序排查。这个顺序可以避免把 DNS 或出口问题误判成镜像加速器失效。
参考资料
- Docker daemon 配置概览:配置文件位置、JSON 与启动参数冲突规则。
- Docker Desktop 设置:Docker Engine 配置入口与 Desktop 运行设置。
- Docker daemon 代理配置:daemon.json、systemd drop-in 和 Docker Desktop 代理限制。
- Docker Hub 镜像缓存:registry-mirrors 的适用范围和镜像缓存机制。
- containerd Registry Configuration:Containerd 1.x、2.x、config_path 与 hosts.toml。
- OpenWrt dockerd 软件包页面:OpenWrt 软件包信息与适用版本范围。
常见问题
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;如果服务没有同步新内容,继续重试不会自动改变缓存,生产镜像应同步到可控仓库。
相关阅读
参考资料
- Docker daemon 配置概览
- Docker Desktop 设置
- Docker daemon 代理配置
- Docker Hub 镜像缓存
- containerd Registry Configuration
- OpenWrt dockerd 软件包页面(openwrt.org)