Docker 配置镜像加速：覆盖 Desktop、Linux、NAS 与 BuildKit
Docker Desktop、标准 Linux Docker Engine 和多数基于 Linux 的 NAS 可以通过 daemon 的 registry-mirrors 配置 Docker Hub 镜像加速。使用 docker-container driver 的独立 BuildKit builder 需要单独配置。临时代理完整镜像名适合排障，但不应代替长期、受控的镜像供应方案。
适用范围与验证边界
这份教程覆盖：
- Windows 与 macOS 的 Docker Desktop。
- 使用 systemd 管理 Docker Engine 的 Linux。
- 以绿联 UGOS Pro 为参考、能够通过 SSH 识别 Docker daemon 的 NAS。
- Docker CLI、Compose 与
docker buildx的验证方法。 - 不修改全局配置时的临时代理镜像名。
文中的端点探测只证明 /v2/ 入口与 TLS 链路在核验时可达，没有在当前环境执行真实镜像拉取，也没有证明 token、manifest、blob、大镜像层和限流策略始终可用。最终结果应以目标机器上的 pull、run 和构建测试为准。
镜像源怎么选
按可控性排序，建议优先选择：
- 云厂商控制台分配的个人或企业专属 Docker Hub 加速地址。
- 企业内部 Harbor、Nexus 或 Docker Distribution pull-through cache。
- 限制访问范围并持续维护的自建代理。
- 第三方公共代理，仅用于公开镜像的临时排障和交叉验证。
不要一次加入大量公共地址。失效地址会增加等待时间，也会让故障归因变得困难。先选一个地址完成端点、daemon、拉取和运行验证，再决定是否保留。
2026-09-02 对三个候选端点执行了 /v2/ 协议探测：
| 地址 | 探测响应 | 能证明什么 |
|---|---|---|
https://docker.m.daocloud.io | HTTP 401，包含 Registry V2 与 Bearer challenge | 入口可达，未验证镜像拉取 |
https://docker.1panel.live | HTTP 200，包含 Registry V2 标头 | 入口可达，未验证镜像拉取 |
https://docker.1ms.run | HTTP 401，包含 Registry V2 与 Bearer challenge | 入口可达，未验证镜像拉取 |
下文用 https://docker.m.daocloud.io 展示配置结构。公共服务状态可能变化，实际使用时应替换为在目标网络中验证过、并符合组织安全要求的地址。
三种使用方式
| 方式 | 镜像写法 | 影响范围 | 典型用途 |
|---|---|---|---|
| daemon mirror | docker pull alpine:3.21 | Docker daemon 的 Docker Hub 拉取 | 长期使用，Compose 不改镜像名 |
| 代理完整镜像名 | docker pull docker.m.daocloud.io/library/alpine:3.21 | 当前命令或显式引用 | 临时排障，不重启 daemon |
| BuildKit mirror | Dockerfile 仍写 FROM alpine:3.21 | 指定的独立 builder | docker-container driver 构建 |
registry-mirrors 只处理逻辑上的 docker.io。ghcr.io/example/app、quay.io/... 或 mcr.microsoft.com/... 不会被自动改写到 Docker Hub mirror。
Windows 与 macOS：Docker Desktop
Windows 与 macOS 使用相同的 Docker Desktop 配置入口：
- 启动 Docker Desktop。
- 打开
Settings，进入Docker Engine。 - 把
registry-mirrors合并到现有 JSON。 - 保留已有的代理、DNS、
insecure-registries、日志和地址池配置。 - 点击
Apply & Restart，等待 Docker Desktop 恢复运行。
最小配置如下：
{
"registry-mirrors": [
"https://docker.m.daocloud.io"
]
}已有配置时只增加字段，例如：
{
"features": {
"buildkit": true
},
"registry-mirrors": [
"https://docker.m.daocloud.io"
]
}macOS 验证
docker info | sed -n '/Registry Mirrors/,+5p'
docker pull alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-releaseWindows PowerShell 验证
docker info | Select-String "Registry Mirrors" -Context 0,5
docker pull alpine:3.21
docker run --rm alpine:3.21 cat /etc/alpine-releaseDocker 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 服务。生产机应先记录容器状态并安排维护窗口：
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 编辑配置：
sudoedit /etc/docker/daemon.json文件不存在或为空时使用最小配置：
{
"registry-mirrors": [
"https://docker.m.daocloud.io"
]
}文件已有其他字段时，只合并 registry-mirrors，不要覆盖原配置，也不要创建第二个同名键。
校验后再重启
安装了 jq 时先检查 JSON：
sudo jq empty /etc/docker/daemon.json再让 Docker 校验 daemon 配置：
sudo dockerd --validate --config-file=/etc/docker/daemon.json校验通过后重启并检查状态：
sudo systemctl restart docker
sudo systemctl status docker --no-pager
docker info | sed -n '/Registry Mirrors/,+5p'服务启动失败时先查看日志，不要连续重启：
sudo journalctl -u docker -n 100 --no-pager常见原因包括 JSON 逗号或引号错误、字段重复，以及同一个 daemon 选项同时出现在启动参数和 daemon.json 中。
NAS：以绿联 UGOS Pro 为参考
绿联不同型号、UGOS Pro 版本和 Docker 应用版本可能使用不同菜单与服务管理方式。设备的 Docker 应用如果明确提供“镜像加速”或 Registry Mirror 设置，应优先使用界面入口，并保留已有配置。
没有明确入口时，可以临时启用 SSH 识别运行方式。不要根据其他型号的截图猜测配置文件或服务名。
- 记录关键容器、端口、Compose 项目和数据卷。
- 在设备的终端或 SSH 设置中临时启用 SSH，只允许可信局域网访问。
- 使用普通管理员账号登录，需要时再通过
sudo提权。
ssh <用户名>@<NAS-IP>
sudo -i使用自定义 SSH 端口时：
ssh -p <SSH端口> <用户名>@<NAS-IP>
sudo -i先识别 Docker 版本、配置和服务管理方式：
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或未知守护进程。 - 使用 UGOS Pro 界面重启 Docker 应用；没有独立入口时，在维护窗口重启 NAS。
- 固件或 Docker 应用升级后，重新检查 mirror 配置。
- 完成后关闭不再需要的 SSH 服务。
不修改全局配置：直接使用代理镜像名
Docker Hub 官方镜像需要补上 library/：
docker pull docker.m.daocloud.io/library/alpine:3.21
docker run --rm \
docker.m.daocloud.io/library/alpine:3.21 \
cat /etc/alpine-release组织或用户镜像保留原路径：
docker pull docker.m.daocloud.io/oven/bun:1.2.19-alpine本地镜像名会包含代理 hostname。既有脚本必须使用普通名称时，可以显式增加本地标签：
docker tag \
docker.m.daocloud.io/library/alpine:3.21 \
alpine:3.21标签转换不会让后续 docker pull alpine:3.21 永久使用代理。长期使用仍应配置 daemon mirror，或者使用组织管理的 Registry。
Docker Compose 如何使用 mirror
daemon mirror 生效后，Compose 文件不需要改写镜像名：
services:
web:
image: nginx:1.27-alpine按顺序检查配置、拉取、启动与状态：
docker compose config
docker compose pull
docker compose up -d
docker compose psCompose 文件显式使用其他 Registry 时，Docker Hub mirror 不参与拉取。不要把官方镜像替换为来源不明的同名镜像。
独立 BuildKit builder
Docker Desktop 的默认 docker driver 通常跟随 daemon 设置。docker-container driver 会启动独立 BuildKit daemon，不能假设该 builder 自动继承 registry-mirrors。
先识别当前 builder：
docker buildx ls
docker buildx inspect --bootstrap如果 DRIVER 是 docker-container，在当前目录创建 buildkitd.toml：
[registry."docker.io"]
mirrors = ["docker.m.daocloud.io"]使用新名称创建 builder，避免覆盖已有 builder 和缓存：
docker buildx create \
--name cn-mirror \
--driver docker-container \
--buildkitd-config ./buildkitd.toml \
--use \
--bootstrap
docker buildx inspect cn-mirror --bootstrap
docker buildx build --pull --progress=plain --load .如果 docker pull 成功，但构建仍在 load metadata 阶段访问 registry-1.docker.io 并超时，应先检查 builder driver 和 buildkitd.toml。docker build --network=host 通常不能修复 FROM 元数据解析，因为解析发生在构建容器网络生效之前。
分层验证结果
1. Registry 端点
curl -sSI https://docker.m.daocloud.io/v2/HTTP 200，或者带有 Docker-Distribution-Api-Version: registry/2.0 和合理 Bearer challenge 的 HTTP 401，都可能是 Registry V2 的正常响应。这里成功只表示入口可达。
2. daemon 是否加载 mirror
docker infoRegistry Mirrors 中出现目标地址，表示 daemon 已读取配置，但不能单独证明实际拉取一定经过该地址。需要结合真实拉取、daemon 日志或自建 mirror 日志确认流量路径。
3. 镜像拉取与容器运行
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 版本后正常退出。
4. Compose 与 BuildKit
docker compose pull
docker compose up -d
docker compose ps
docker buildx imagetools inspect alpine:3.21pull 成功而 buildx 失败时，先确认 builder 是否独立运行，不要一次替换所有 mirror 地址。
常见问题
| 现象 | 主要判断 | 处理方式 |
|---|---|---|
/v2/ 返回 401 | Registry 正常发起 Bearer 鉴权的常见行为 | 检查 Registry V2 标头和 token realm |
docker info 没有目标 mirror | Desktop 未应用、daemon 未重启或 JSON 未加载 | 检查 JSON，执行 Apply & Restart 或查看服务日志 |
| 代理完整名称能拉取，普通名称失败 | 代理可达，但 daemon mirror 未生效 | 确认编辑的是当前 daemon 配置，并检查 Registry Mirrors |
docker pull 成功，buildx 失败 | 独立 BuildKit 没有 mirror 配置 | 检查 driver，并配置 buildkitd.toml |
| 其他 Registry 仍超时 | Docker Hub mirror 不处理该 Registry | 使用对应 Registry 的合规出口、企业同步或离线导入 |
| HTTP 429 | 上游或代理限流 | 降低频率，使用合规认证或企业缓存 |
| Linux Docker 重启失败 | JSON 无效或配置项冲突 | 运行 jq、dockerd --validate，查看日志并恢复备份 |
| NAS 修改后没有变化 | 配置文件不是当前 Docker 应用读取的位置，或升级覆盖了配置 | 识别真实 daemon，用 UGOS Pro 界面重启并复查 |
镜像配置回滚
Docker Desktop 中，从 Settings -> Docker Engine 删除本次增加的失效 mirror，保留其他配置，然后点击 Apply & Restart。
Linux 与确认使用标准 Docker Engine 的 NAS，可以恢复修改前备份：
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：
docker buildx use default没有确认缓存和配置归属前，不要直接删除旧 builder。
安全与维护
- 不要通过第三方公共代理访问 Docker Hub 私有仓库或发送私有仓库凭据。
- 公共代理可以观察来源 IP、镜像名称和访问频率；敏感业务应使用企业 Registry 或受控代理。
- 生产部署应固定镜像 tag，关键镜像进一步固定 digest，并保留来源、升级和回滚记录。
- 公共代理可用性会随运营方、网络、地区和时段变化，应定期执行端点与小镜像拉取检查。
- mirror 不会消除 Docker Hub 的拉取限制和镜像许可证义务。
- 企业或离线环境需要稳定缓存时，应使用 Harbor、Nexus 或 Docker Distribution pull-through cache。
总结
长期配置应优先使用专属地址、企业 Registry 或受控代理，并把 mirror 合并到实际 daemon 的 JSON 中。端点响应不等于镜像可用；至少要完成 docker info、docker pull、docker run 和实际构建验证。独立 BuildKit builder、非 Docker Hub Registry 和 NAS 固件管理路径需要分别处理。