registry-mirrors 是什么
registry-mirrors 是守护进程级配置，用来给 Docker Hub 指定镜像加速地址。配置后，docker pull 官方镜像时会优先向加速地址请求，命中缓存就快速返回，未命中则回源拉取。需要强调的是作用范围：它只代理 Docker Hub，其他注册表（自建仓库、各类制品库）不走加速链路，网络排查时不要把它们的问题混在一起。
基本信息
| 配置文件 | /etc/docker/daemon.json（Windows/macOS 在 Docker Desktop 设置中配置） |
|---|---|
| 配置项 | "registry-mirrors": ["https://加速地址"] |
| 生效方式 | 修改后重启 docker 服务 |
| 验证命令 | docker info 输出中的 Registry Mirrors 段落 |
| 作用范围 | 仅 Docker Hub（docker.io）相关拉取 |
| 不作用于 | 自建仓库、其他公共注册表、镜像推送 |
典型使用场景
- 内网或跨境网络环境下加速官方镜像拉取，缩短流水线耗时
- 企业网络只允许访问特定加速地址时统一出口
- 搭建本地缓存仓库，减少重复拉取对外网的占用
- 排查拉取慢：确认当前实际生效的加速地址列表
- 环境迁移后同步调整加速配置，避免仍指向旧地址
配置与验证
配置与验证
{
"registry-mirrors": ["https://mirror.example.com"],
"log-driver": "json-file",
"log-opts": { "max-size": "10m", "max-file": "3" }
}应用与确认
应用与确认
# 修改配置前先备份，JSON 语法错误会导致 daemon 起不来
sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo python3 -m json.tool /etc/docker/daemon.json > /dev/null && echo json-ok
# 重启守护进程并确认生效
sudo systemctl restart docker
docker info | grep -A3 'Registry Mirrors'
# 用小镜像验证拉取链路（观察是否走加速：拉取速度与失败提示会给出线索）
docker pull hello-world常见现象判读
| 现象 | 含义 | 处理方向 |
|---|---|---|
| docker info 无 Registry Mirrors | 配置未生效或文件位置不对 | 确认 daemon.json 路径与语法后重启 |
| 拉取报证书错误 | 加速地址证书异常或地址写错 | 核对地址与证书链 |
| 冷门镜像仍然很慢 | 加速器只缓存热门镜像，需回源 | 属正常现象，可换源或本地缓存 |
| 拉自建仓库也变慢 | 与加速器无关 | 按仓库侧网络与认证排查 |
| 推送失败 | 加速只影响拉取 | 检查仓库认证与网络出口 |
加速地址以所在云厂商或组织提供的实际地址为准。配置多个地址时按顺序尝试，写错一个不会致命，但会拖慢失败重试过程，建议只保留已验证可用的地址。
daemon.json 是 JSON 格式，多一个逗号或少了引号都会让 Docker 守护进程无法启动。改动前备份，改完先用 JSON 校验命令确认再重启。