在 CentOS 7 上装好 Docker兴冲冲地跑第一条docker pull结果进度条走到一半就停住过一会儿直接甩一个 TLS handshake timeout。这个场景我见过太多次了。Docker 默认从官方公共仓库拉镜像服务器和这个仓库之间隔着一大段跨地区链路抖动和超时就是常态。换镜像源这个操作本质上就是告诉 Docker 守护进程先去一个更近、更可靠的仓库拿数据。它不涉及重装 Docker不改系统内核参数核心只是在/etc/docker/daemon.json里加一个registry-mirrors配置然后重启守护进程。这篇文章就按生产环境里验证过的顺序把原理、配置、验证、排查一次讲全。适合刚上手 Docker 的运维新手也适合被这个问题反复折腾过的老手。1. 换源之前先搞清楚 Docker 拉镜像到底慢在哪儿1.1 一次 docker pull 背后发生了什么很多人以为docker pull就是简单地从某个网址下载一个文件其实不是。你敲下命令之后Docker 客户端先把请求交给本机的 dockerd 守护进程然后由 dockerd 去连接镜像仓库先拉取 manifest 元数据再根据 manifest 里列出的层列表一层一层地并发下载镜像层。每一层下载完成之后还要做校验、解压、落盘到/var/lib/docker对应的存储驱动目录。整个过程里任何一层超时或中断Docker 都会重试但重试到一定次数就会直接失败。这里最容易出问题的环节是第一步和第二步也就是“连接仓库解析元数据”和“下载镜像层”。Docker 默认连接的官方公共仓库服务器在全球多个地区部署但从你所在的网络环境去访问它走的是一条距离远、跨区域、中间经过大量公网节点的链路。这条链路的特征是延迟高、丢包率不稳定尤其在下行带宽不高或者高峰期的时候表现就是docker pull卡在一个百分比上不动最后报net/http: TLS handshake timeout或者dial tcp: i/o timeout之类的错误。这类问题和你本机配置关系不大你已经把 Docker 装好、启动正常说明系统环境和驱动都没问题。问题主要出在“默认仓库离你太远”这件事上。既然网络链路不可控能做的就是让 Docker 不要每次穿越那么远的距离去拿数据。这跟你在手机上选择一个就近的内容分发节点加速下载是一个道理不是把路修好了而是换了一条更近的路。1.2 镜像源在 Docker 架构里处于什么位置Docker 提供了一套官方机制来支持这个需求叫 registry mirror也就是镜像源或者叫镜像加速地址。它的实现方式是这样的在 Docker 的守护进程配置里可以声明一个或多个镜像仓库地址。当 Docker 需要从官方公共仓库拉取镜像时它会先去这些镜像源地址询问。镜像源本质上是一个带缓存能力的仓库服务它背后也连接着官方公共仓库的数据。如果你的镜像在镜像源上有缓存它就直接把缓存的层数据返回给你如果没有缓存它会自己去官方仓库拉取一次然后在本地存一份再把数据交给你。这个机制很关键它意味着镜像源不是一个简单的 DNS 转发而是一个中转仓库。第一次通过某个镜像源拉取一个冷门镜像时这个镜像源自己也要去上游取数据所以首次拉取可能不会像你想象的那样快但你拉完之后这份镜像层数据就留在了镜像源那边。第二次再拉同一个镜像或者同一台服务器上再拉一次速度就会明显快很多因为直接从镜像源本地读取了。这里还要澄清一个常见的误解registry-mirror 只对官方公共仓库的镜像生效。如果你平时还会从其他公开仓库或者公司内部的私有仓库拉镜像那部分流量的路径和镜像源没有关系Docker 会根据镜像完整名称里的仓库地址去直接连接对应的仓库服务器。镜像源只管那种不写仓库地址、直接用镜像名拉取的默认场景。1.3 换源能解决什么不能解决什么把话说清楚换源解决的是默认仓库访问链路差导致的超时、断流、重试失败。它能不能让你的拉取速度变成百兆满速不一定。镜像源本地缓存命中的情况下速度确实可以很高尤其是那些被大量用户反复拉取的热门镜像镜像源基本都有命中拉取体验和本地仓库几乎没区别。但如果是一个很偏门的镜像镜像源第一次也要回源速度就取决于镜像源到上游之间的链路以及镜像源本身的出口带宽。换源解决不了的另一类问题是镜像体积问题。一个几个 GB 的机器学习镜像就算源再好网络再快传输时间摆在那里。合理的做法是换用更小的基础镜像、精简安装包、采用多阶段构建这些我放到后面细说。还有一点要认清镜像源服务本身也可能出故障或者有时候某个镜像源因为政策调整、资源紧张而临时不可用。所以生产环境里我建议至少配两个镜像源做好回退而不是把宝押在一个地址上。2. 准备工作确认 Docker 版本、找到 daemon.json2.1 先在 CentOS 7 上确认 Docker 的安装形态CentOS 7 上装 Docker 的来源不太一样有的是用官方仓库装的 docker-ce有的是从系统自带的 extras 源里装的旧版本 Docker 1.13还有一些是通过公司内部脚本或者二进制方式装的。不同安装来源配置文件的行为有一点点差异但大部分场景下/etc/docker/daemon.json这个文件都是有效的。动手之前你先跑几条命令确认状态docker --version systemctl status docker第一行能让你知道 Docker 版本。第二行能让你确认守护进程是不是正常运行。如果systemctl status docker显示 active (running)说明服务正常接下来只用改配置然后重启。如果守护进程本身就没起来那换源之前得先把启动问题查清楚否则后面修改配置、重启服务会分不清是配置的问题还是原本就没起来的问题。CentOS 7 的进程管理用的是 systemd所以后面所有操作都是systemctl这一套命令。这本身是个小地方但我知道有人在 Ubuntu 上习惯了service docker restart在 CentOS 7 上也能用两者兼容不过既然系统层是 systemd统一用systemctl更不容易出岔子。2.2 daemon.json 是真正要动刀的文件Docker 的守护进程 dockerd 在启动时会读取配置文件默认路径就是/etc/docker/daemon.json。这个文件是可选的如果不存在Docker 就用内置的默认参数启动如果存在Docker 会把文件里的内容解析出来覆盖对应的默认参数。注意这是一个 JSON 格式的纯文本文件不是 shell 脚本也不是键值对配置文件。这个格式区别很重要我在后面排查部分会专门讲因为很多人就是栽在这个细节上。如果/etc/docker/daemon.json不存在不要慌直接创建一个就行。创建的时候注意文件权限和属主正常应该是 root 所有权限建议 644ls -l /etc/docker/daemon.json如果你看到权限显示-rw-r--r-- 1 root root那就没问题。万一之前被什么工具写过权限变成了 600 或者其他奇怪的值Docker 只要能读就行但为了方便后续维护还是建议统一成 644。还有一个历史遗留问题要提醒一下。CentOS 7 上有些老版本 Docker 使用/etc/sysconfig/docker这个文件来配置启动参数里面可能写着一行OPTIONS--registry-mirrorhttps://...。如果你用的是新版本 Docker这个文件不一定生效了因为新版 Docker 优先读取 daemon.json。建议把 daemon.json 作为唯一的配置入口不要在两边同时配置同一批参数不然以后排查问题你会被自己绕晕。2.3 动手前先把原配置备份好改系统配置文件有一个好习惯先备份。daemon.json可能已经被之前的运维配置过里面有存储驱动、日志轮转、网络相关参数。如果不做备份就直接覆盖改坏了想还原很麻烦。备份命令很简单cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date %F)这条命令会把原文件复制成一个带日期后缀的备份文件。如果文件不存在也没关系后面创建新文件本身就是初始状态。另外我建议你在改配置之前先跑一次docker info把输出保存到本地文件里。这样可以记录配置修改前的状态万一改完出问题你能对比前后差异快速定位是哪里改坏了。备份不是形式主义。我见过不止一次因为 daemon.json 写错导致整个 Docker 服务起不来的情况。这时候备份文件就是保命符复制回去重启基本就能恢复。3. 核心操作三步把镜像源换掉3.1 拿到可用的镜像加速地址换源的第一步不是写配置而是先拿到一个真实可用的镜像加速地址。现在国内主流的云厂商都提供容器镜像服务里面有“镜像加速器”或者类似功能的页面。你需要注册并登录某云厂商的控制台然后在容器镜像服务相关的菜单里找到镜像加速器入口。这个页面通常会显示一个 HTTPS 地址格式一般是https://一个私有ID.xxx.xxx/v2/也有的服务给你的地址不带/v2/后缀。拿到这个地址之后原样复制保存不要自己补路径也不要删掉某个部分。每个镜像源的路径规则不同以服务商给出来的为准。有一点需要特别提醒这个加速地址通常会和个人账号绑定绑定后会生成一个专属二级域名所以不要随便拿别人的地址来用。这也是为什么我不能直接给你一个通用的、随便填就能用的具体地址你需要去你自己的云厂商控制台里拿到属于自己的那一个。如果实在不想注册账号也可以找一些公共的镜像源代替但公共源主要靠社区维护可靠性参差不齐生产环境我还是建议用商业云厂商提供的服务至少出了故障有人处理。3.2 编辑 daemon.json写成合法 JSON拿到地址之后开始编辑配置文件。先看一下文件里面有没有已经存在的配置内容cat /etc/docker/daemon.json如果文件是空的或者不存在直接创建并写入下面这样的内容{ registry-mirrors: [ https://xxxx.mirror.example.com/v2/ ] }把https://xxxx.mirror.example.com/v2/替换成你自己拿到的镜像加速地址。如果文件里面已经有其他配置项比如这样的{ storage-driver: overlay2, log-driver: json-file, max-concurrent-downloads: 5 }那你不要删除这些已有项只需要在 JSON 对象里追加一个registry-mirrors键像这样{ storage-driver: overlay2, log-driver: json-file, max-concurrent-downloads: 5, registry-mirrors: [ https://xxxx.mirror.example.com/v2/ ] }JSON 格式有几个容易踩的坑我在这里提前说清楚。第一所有键和字符串值必须用英文双引号不能用单引号也不能不写引号。第二对象和数组的末尾不能有逗号比如最后一个键值对后面加个逗号JSON 解析器直接报错。第三JSON 里不允许出现注释很多人习惯写//注释这在 JSON 里是非法的。写完配置之后先做一次语法校验用 Python 或者 jq 都行python -m json.tool /etc/docker/daemon.json如果文件合法这条命令会输出格式化后的 JSON 内容如果文件不合法它会明确指出第几行第几个字符附近有错误这样排查起来非常方便。有 jq 的话也可以jq . /etc/docker/daemon.json我每次改完都会先做这一步五秒钟的事能避免后面重启服务时吃一个莫名其妙的亏。如果以后要追加第二个镜像源直接在数组里加一个字符串用英文逗号分隔{ registry-mirrors: [ https://aaaa.mirror.example.com/v2/, https://bbbb.mirror.example.com/v2/ ] }Docker 会按数组顺序尝试镜像源排在前面的是首选后面的作为回退。建议把可靠性更高的源放前面把备用的放后面。3.3 重启守护进程让配置真正生效配置写完之后需要让 Docker 守护进程重新加载配置。这里执行两条命令systemctl daemon-reload systemctl restart docker第一条命令systemctl daemon-reload在只改了 daemon.json 的情况下不是必须的它的作用是让 systemd 重新读取 service 单元文件。Docker 的 service 单元文件一般不会变但多执行一次没有副作用我习惯每次改配置都带着它省得哪天改了别的地方忘记。第二条命令是真正的重启动作dockerd 会带着新的配置重新启动。重启之后立即检查服务状态systemctl status docker如果看到 active (running)说明服务正常起来了。如果这里报错说明 daemon.json 里有问题赶紧看错误信息journalctl -u docker -n 50正常情况下错误信息会非常直白比如Error loading config file /etc/docker/daemon.json: invalid character...这说明 JSON 格式有问题回到上一步用python -m json.tool检查。还有一种是端口冲突或者网络桥接初始化失败但那和换源无关需要单独排查。记住一个原则重启失败时先去日志里看具体报错别盲目地反复重启那是浪费生命。3.4 用 docker info 确认镜像源是否加载重启成功之后不要急着拉镜像先确认镜像源确实被 Dockerd 加载了。查看方式很简单docker info | grep -A 2 Registry Mirrors输出里如果出现你配置的地址说明镜像源已经生效。比如Registry Mirrors: https://xxxx.mirror.example.com/v2/如果这一行下面什么地址都没有那说明配置没生效可能的原因我放在后面的排查部分详细讲。这里还可以用 Docker 的格式化输出功能直接以 JSON 形式查看docker info --format {{json .RegistryConfig.Mirrors}}输出类似[https://xxxx.mirror.example.com/v2/]。这种方式适合在写脚本时自动判断镜像源是否配置成功比 grep 更好编程处理。这里有个小知识点如果 Docker 版本比较老docker info里可能显示的是Registry Mirrors这个列表如果版本比较新可能还会有RegistryConfig相关的字段。字段名字随着版本有过调整但grep -A 2 Registry Mirrors这个方式基本通用我在 CentOS 7 上从 Docker 1.13 到新版 Docker CE 都验证过。4. 换源后的验证别急着 pull先看两个指标4.1 拉取测试用一个小镜像做冒烟镜像源确认生效之后做一次真正的拉取测试。不要上来就拉一个巨大的镜像先用小镜像做个冒烟。我推荐busybox或者hello-world体积小拉取速度快如果出了错也容易看出来是网络问题还是配置问题docker pull busybox:1.36执行之后观察输出。正常情况下Docker 会先解析 manifest然后开始一层一层下载。你注意看拉取速度如果速度明显比之前快说明镜像源在网络层面确实起作用了。如果还是慢吞吞的或者直接超时那说明你配置的镜像源本身也有问题或者这个镜像源当前的链路状况也不好。测试完成后如果你不想留下来占空间可以把测试镜像删掉docker image rm busybox:1.36如果连hello-world这种几百 KB 的镜像都拉不下来那问题基本不在镜像源而在于服务器本身的网络出口或者 DNS。这时候先排查基础网络不通的话后面所有优化都没意义。4.2 观察缓存命中第一次慢、第二次快才是常态很多人换完源之后第一次拉某个镜像还是觉得不够快就开始怀疑是不是配置没生效。这是一个常见的误解。镜像源是带缓存的但缓存是需要“预热”的。你第一次通过新的镜像源拉取某个镜像如果这个镜像在这个源上是缓存冷场状态镜像源自己要去上游仓库回源拿数据然后把数据转交给你这个首拉过程的确可能不够惊艳。但第二次再拉同一个镜像结果就会完全不同。因为镜像的层数据已经在镜像源本地磁盘上了Docker 直接从镜像源读取速度快一个量级。所以判断一个镜像源好不好用不能只看第一次拉取的速度要看第二次、第三次的命中表现。这就好比你到了一个新城市第一次去某家餐厅吃饭要排队等位但你成为会员之后再去人家直接给你预留了位置。这个机制也影响你的使用习惯。如果你的业务里经常要拉取固定的几个镜像可以事先在一个低峰期把它们全部拉一遍相当于给镜像源做预热。之后真正上线需要的时候速度就有了保证。4.3 registry-mirror 与私有仓库的边界验证完之后我还想强调一下 registry-mirror 的作用边界。如果你在生产环境里除了官方公共仓库的镜像还用了公司内部的私有仓库比如某个内部自建的容器镜像服务这些私有仓库的拉取路径完全不受 registry-mirror 影响。Docker 判断是否是官方默认仓库的依据是镜像完整名称如果镜像名里带了私有仓库的域名前缀比如registry.internal.example.com/team/app:latest它就会直接去访问那个域名跳过镜像源。反过来如果你想给私有仓库配置加速或者绕过 HTTPS 校验那是另一个配置项叫insecure-registries和 registry-mirror 完全是两回事。insecure-registries是用来允许 Docker 访问 HTTP 协议或者证书不受信任的仓库的不是用来加速的。很多人把这两个配置搞混结果在 daemon.json 里写错了位置服务起不来这里特别提醒一下。5. 常见问题与排查技巧实录5.1 Docker 服务起不来daemon.json 写坏了换源之后最让人头疼的问题就是 Docker 服务直接起不来。这种问题九成以上是 daemon.json 语法错误导致的。典型报错是这样的failed to start daemon: Error loading config file /etc/docker/daemon.json: invalid character } looking for beginning of object key string看到invalid character开头的报错别怀疑就是 JSON 解析失败。常见错误原因有这么几类字符串用了单引号、键值对结尾多了逗号、文件里存在注释、括号不匹配。我整理了一张速查表错误场景错误写法举例正确写法键名没有引号registry-mirrors: []写成了registry-mirrors: []registry-mirrors: []字符串用单引号https://xxxhttps://xxx数组末尾多逗号[https://a, https://b,][https://a, https://b]末尾多逗号{registry-mirrors: [],}{registry-mirrors: []}文件里有注释// 这是注释删除注释出现这类报错的处理方式很简单把备份文件复制回去先让服务恢复正常cp /etc/docker/daemon.json.bak.$(date %F) /etc/docker/daemon.json systemctl restart docker服务恢复之后再用python -m json.tool检查你修改前的原文件找出语法问题重新改。我给你的建议是每次修改完都先做语法校验再重启服务磨刀不误砍柴工。5.2 改了配置、重启了docker info 里还是空的明明在 daemon.json 里写好了 registry-mirrors重启服务后docker info里Registry Mirrors却什么都没有。这种问题也很常见原因通常有三个。第一个原因是文件路径不对。Docker 读取的配置路径是/etc/docker/daemon.json不是/root/daemon.json也不是/etc/daemon.json。有些人习惯把配置放在自己目录下然后忘了移动结果改了个寂寞。确认路径用ls -l /etc/docker/daemon.json看一眼。第二个原因是改完配置后没有重启服务。daemon.json 是在 dockerd 启动时读取的光改文件不重启配置永远不生效。虽然听起来像是废话但真有人在这个问题上卡住过。执行systemctl restart docker之后再看。第三个原因是 Docker 的启动方式不是通过 systemd。有些场景下 Docker 是通过命令行手动启动的比如直接执行了dockerd命令或者用了其他进程守护工具来启动。这种情况下 systemctl 重启的可能是另一个服务或者根本没有 systemd 单元在工作。用这条命令确认一下ps -ef | grep dockerd看看 dockerd 进程的启动命令和父进程如果是手工启动的你需要找到它启动时指定的配置文件路径或者干脆改成通过 systemd 管理统一配置入口。这个问题在接手别人环境时特别容易踩到因为表面上看起来 systemctl 能查到一个 docker 服务实际上真正跑着的 dockerd 根本不是这个服务拉起来的。5.3 换了源还是慢甚至直接拉取失败有时候配置是成功的镜像源也生效了但拉镜像依然慢或者报dial tcp: connection refused。这时候要区分是镜像源地址本身有问题还是镜像源到上游的回源链路有问题。如果报connection refused大概率是你配置的镜像源地址不对或者提供镜像源的服务商这个地址已经停用了。检查一下你复制的地址是不是有拼写错误是不是把某个账号专属的地址写成了别人的公共地址。还有一点镜像源路径有的要求带/v2/有的不需要如果你拿到的原始地址没有这个后缀不要自己加。如果报的是timeout或者速度持续上不去那可能是镜像源服务本身压力大或者你服务器的网络到镜像源之间的链路也不怎么样。处理思路就是多配几个镜像源。我之前说过在 registry-mirrors 数组里把两三个可靠地址都放进去Docker 会在一个源不可用时自动尝试下一个。这比单点配置要稳得多。还有种被忽视的场景拉取失败报no space left on device。这不是镜像源的问题而是/var/lib/docker所在分区满了。很多人一看到拉取失败就怀疑源不对劲其实看看磁盘使用率能省去大把排查时间df -h /var/lib/docker镜像下载需要临时空间解压还需要额外空间分区满了之后一切拉取都会失败。记住换源只是换了一条路路通了你还要确认车有油。磁盘空间、网络出口、DNS 解析这些都是拉镜像链路的一部分。5.4 DNS 解析与本地缓存的隐藏坑镜像源域名同样依赖 DNS 解析。如果服务器上配置的 DNS 有问题或者镜像源域名的解析结果被本地 hosts 文件污染拉取一样会失败。排查时可以用getent hosts 你的镜像源域名看看能不能正常解析出 IP。如果解析不出来检查/etc/resolv.conf里的 DNS 配置。这一步在 CentOS 7 上经常被忽略因为很多人想当然认为域名解析是自动好的但内网环境里 DNS 配置经常被改坏。再补充一个本地缓存相关的坑。Docker 在本地也有镜像层缓存如果你之前用旧配置拉取过某个镜像本地已经有层数据那么即使镜像源配置有问题重新拉取时可能因为命中本地缓存而看起来成功了这会影响你对镜像源是否生效的判断。想彻底验证镜像源的网络路径可以先用docker image rm删除测试镜像再重新拉取确保流量真正走了一次镜像源。6. 换源只是第一步拉镜像提速还有几个方向6.1 镜像体积才是治本因素镜像源解决的是网络路径问题但决定拉取耗时的另一个大头是镜像体积。一个基础镜像动不动几百 MB里面塞了很多你用不到的包这种镜像就算从内网仓库拉耗时也下不去。真正优雅的做法是在镜像构建阶段就控制体积。首选方案是尽量使用精简版基础镜像比如各种alpine版本或者官方镜像带的-slim标签。同样的软件基础镜像体积可以差好几倍。其次是在 CI/CD 构建阶段使用多阶段构建最终只把运行所需的文件拷贝进产物镜像构建工具和中间层全部丢弃。这样最终交付的镜像只有运行时环境加你的应用代码体积能小一个数量级。我还有一个小经验妥善处理镜像构建缓存。反复构建同一个应用时尽量让变动的层保持在最上层公共依赖放到前面的层这样后续构建能复用缓存构建时间和拉取时间都会缩短。这些和换源配合起来才是完整意义上的“拉镜像快”。6.2 标签策略会影响缓存命中率镜像源缓存是按层存储的层与层之间靠内容寻址。如果你总是用latest标签而你的应用每次构建都会产生新的层那镜像源缓存几乎不可能命中因为它要回源去拿最新的层数据。更合理的做法是生产环境明确指定镜像版本标签最好用带业务版本号的标签比如app-server:2.3.0而不是app-server:latest。对于不可变部署甚至可以直接用镜像 digest 来引用。这样同一个版本号对应的层数据是固定的镜像源只需要回源一次之后所有节点拉取都是缓存命中体验会非常稳定。在 CI 流程里也建议把镜像标签跟代码提交信息或者构建号绑定。这样每次发布一个新的标签就代表一组新的层数据而旧标签还能继续被缓存命中方便回滚时快速拉取旧版本镜像。6.3 把配置管理固化到交付流程里最后说一个运维层面的建议。daemon.json 的配置不只在单台服务器上改一次就完了等你需要批量部署新机器的时候手工一个个改会把人逼疯。我在实际工作中会把配置内容固化到配置管理工具或者初始化脚本里保证每台服务器创建出来daemon.json 就已经是正确的。一个简单的做法是用 Python 脚本幂等地更新 daemon.json脚本每次执行之前先读取现有文件合并配置项再原子写回python - EOF import json import os path /etc/docker/daemon.json data json.load(open(path)) if os.path.exists(path) else {} data[registry-mirrors] [ https://aaaa.mirror.example.com/v2/, https://bbbb.mirror.example.com/v2/ ] with open(path, w) as f: json.dump(data, f, indent2, ensure_asciiFalse) f.write(\n) EOF这段脚本的好处是不管目标文件之前有没有内容、有没有其他配置项它都能安全地插入 registry-mirrors而且用 Python 的 JSON 序列化器输出格式一定合法不会犯手写 JSON 的语法错误。批量推到所有节点之后再统一执行systemctl restart docker就能保证整个集群的 Docker 配置保持一致。最后再分享一个小习惯每次改完 Docker 配置我都会保存一份修改记录记录改了哪个文件、哪个键、为什么改。等某一天服务器集群里出现诡异问题时翻一翻记录会省掉大量猜测时间。换源这个操作本身不难难的是把它纳入一套可控、可重复的流程里这样它才不会成为下一次故障的源头。