之前在帮一个团队搭CI/CD流水线时遇到一个特别典型的场景代码构建都很快但到了镜像推送环节就卡住动不动超时、鉴权失败、磁盘写满整条流水线直接红灯。排查下来问题基本都出在镜像仓库这一层——大家对构建脚本、部署编排研究很多却很少有人把镜像仓库当成一个正经的基础设施来规划。这篇就把我这些年做镜像仓库与CI/CD集成积累的经验梳理一遍从仓库选型、国内网络环境下的拉取配置到自建本地仓库的完整实操再到GitLab CI里对接Docker的细节和坑一次性讲透。1. 镜像仓库在CI/CD流水线中的角色与方案选型1.1 为什么说镜像仓库是流水线的“中转枢纽”一条完整的交付链路通常是代码提交触发构建构建产物打成一个镜像镜像推到仓库然后测试环境拉取部署验证通过后再推到生产集群。你会发现镜像仓库正好卡在CI和CD的中间左边是持续集成右边是持续交付两头都依赖它。如果仓库不稳定CI阶段推送失败会阻塞后续所有步骤CD阶段拉取失败则直接导致发布中断。2022年我们线上环境出过一次事故就是自建仓库的存储盘被日志和残留镜像打满导致新版本无法推送发布窗口整体后移了两个小时。从那之后我就把镜像仓库当成了跟Git服务同等重要的基础设施去对待而不是“能用就行”。这里要澄清一个本质认知镜像仓库不只是存放镜像的网盘。它还需要具备四个核心能力——权限隔离哪个团队能推、谁能拉、镜像不可变性同一个tag不能随意覆盖、版本清理策略防止存储膨胀、安全扫描能力发现漏洞。选型时把这四个能力放在一起评估才能匹配流水线的需求。1.2 主流镜像仓库选型对比与场景适配市面上的镜像仓库方案不少我用表格整理一下主流选项的定位方便你按团队规模直接选方案部署成本权限模型镜像扫描推荐场景Docker Hub零部署简单公私可见有但受限个人项目、公开镜像分发阿里云容器镜像服务ACR托管免运维账号/命名空间隔离支持已有阿里云账号的中小团队Harbor中高需维护K8s或VMRBAC、Robot账户集成Trivy等中大型团队私有化交付Registry 2低单容器即可极简token无测试环境、临时搭建我的建议很简单如果团队没有专职运维优先用云厂商的托管仓库你不需要考虑存储扩容、高可用、证书轮换这些琐事。如果公司对数据合规有要求镜像只能在内部网络流转那就老老实实自建Harbor。Harbor的Robot账户机制非常适合CI/CD场景——你不需要把真实用户密码放到流水线变量里而是创建一个只有推送权限的机器人账户即使泄露了也限定在指定仓库内。1.3 从热词看团队的三个真实诉求最近看到一些关于国内镜像仓库、maven多仓库配置、GitLab CI Docker集成、自建本地仓库的讨论这背后对应着几个非常现实的痛点拉取不到官方镜像受网络环境影响直接拉取Docker Hub上的镜像经常超时。这就引出了两个方向一是配镜像加速器二是自建仓库定期同步需要的镜像到内网。构建依赖下载慢Java项目构建时Maven要拉依赖NPM项目要拉包如果只配置单一仓库一旦源不稳定整个构建就卡死。所以才需要“配置多个镜像仓库”做冗余。CI执行器不会用很多人用GitLab CI但搞不清楚Docker executor和Shell executor的区别更不知道该怎么在流水线里跑docker build于是整个CI就是一堆shell脚本硬拼既不隔离也不可复现。这三个诉求基本就是这篇文章想解决的核心问题。下面我按“仓库访问配置→自建仓库实操→CI/CD集成实战”的顺序逐一展开讲。2. 国内网络环境下的镜像仓库访问与配置实践2.1 Docker守护进程配置镜像加速器先说最基础也最刚需的一件事让Docker能够稳定地拉取官方镜像。在Docker的配置里有一个专门用来做拉取加速的字段叫registry-mirrors它允许你给Docker daemon指定一个镜像加速地址。当执行docker pull时Docker会优先从你配置的加速器拉取加速器上没有才回源到Docker Hub。我以Linux环境为例配置文件通常在/etc/docker/daemon.json。你在网上能找到各种加速地址但我建议优先选择云厂商提供的标准加速服务因为它们有专门的基础设施保障稳定性比那些来路不明的公共加速源好得多。下面是一个配置示例{ registry-mirrors: [ https://你的专属加速地址.mirror.aliyuncs.com, https://docker.m.daocloud.io ] }配置完成后执行sudo systemctl restart docker然后跑一下docker info在输出里你会看到Registry Mirrors这一项确认配置生效。这里有个细节必须提醒加速器只对Docker Hub上的镜像生效比如nginx、redis这种没有完整仓库地址的官方镜像。对于第三方镜像仓库比如gcr.io/、quay.io/开头的镜像加速器是不管的你只能通过其他方式处理比如用代理或者直接把镜像同步到自己的仓库。2.2 Maven项目配置多个镜像仓库的完整方案热词里提得很多的是“Maven配置多个镜像仓库”。做Java开发的同学应该深有体会settings.xml里配置的mirror只生效一个多个mirror写上去之后Maven会按照顺序从上往下检查如果第一个配置了mirrorOf*/mirrorOf它就会拦截所有仓库请求后面的根本不会用到。所以正确的多仓库配置思路有两个。第一个思路是用多个mirror按规则分流比如中央仓库走一个内部私服其它公共仓库走另一个加速源。示例配置如下mirrors mirror idinternal-repo/id mirrorOfcentral/mirrorOf urlhttps://maven.internal.example.com/repository/maven-public//url /mirror mirror idaliyun/id mirrorOfexternal:http:*/mirrorOf urlhttps://maven.aliyun.com/repository/central/url /mirror /mirrorsexternal:http:*这个通配符值得留意它匹配的是所有走HTTP协议的仓库请求。这样配置之后Maven内部使用HTTP协议访问外部仓库时就会自动走阿里云的源而不再直连Apache的Maven中央仓库。这种做法的初衷是让构建更稳定同时也不影响内网私服的优先级。第二个思路是用profile实现环境隔离切换。比如你本地开发时想快速拉依赖直接用阿里云源而在公司CI环境里又要强制走内网Nexus私服。这时可以把不同仓库源定义到不同的profile里启动命令通过-P参数指定激活哪个。profiles profile idci/id repositories repository idnexus/id urlhttp://nexus.internal.example.com/repository/maven-public//url /repository /repositories /profile /profiles执行时用mvn clean package -Pci就会激活ci profile。这种方式的好处是灵活而且干净——配置脚本里不需要写死一堆仓库地址切换环境只需要换参数。2.3 拉取镜像时如何规避“超时”这类问题除了加速器还有一个实操细节docker pull超时的处理。默认情况下Docker拉取大镜像时如果连接不稳定很容易报i/o timeout。你可以在/etc/docker/daemon.json里加上两个参数{ max-concurrent-downloads: 3, max-download-attempts: 5 }第一个参数限制并发下载数防止多个镜像同时拉取把带宽占满第二个参数让Docker在下载失败时多尝试几次。这两个配置能显著降低CI环境中镜像拉取的整体失败率。我自己实践下来把max-concurrent-downloads调低后拉取大镜像的稳定性反而提升了因为带宽竞争小了单个连接的下载速度更快。3. 自建本地镜像仓库的完整实操记录3.1 部署方案选择Registry还是Harbor如果只是测试环境用或者团队规模很小用官方registry:2镜像起一个容器就够了命令极其简单docker run -d -p 5000:5000 --name registry \ -v /data/registry:/var/lib/registry \ -e REGISTRY_STORAGE_DELETE_ENABLEDtrue \ registry:2但要注意Registry 2没有Web界面没有权限控制唯一的认证机制是基于token的极简方案生产环境基本不推荐。如果公司有一个“内网仓库”的硬性需求我更建议直接上Harbor。Harbor部署需要Docker Compose目前新版本支持以Helm方式部署到K8s。我这边用的是较稳定的方式在目标机器上装好Docker Compose然后下载Harbor的离线安装包解压后修改harbor.yml配置hostname: registry.internal.example.com http: port: 80 https: port: 443 certificate: /data/cert/registry.crt private_key: /data/cert/registry.key harbor_admin_password: 初始密码部署后请立即修改 database: password: 数据库密码 data_volume: /data/harbor配置保存后执行./install.sh等大概一两分钟就能起来。Harbor自带一套完整的RBAC体系你可以创建项目Project然后在项目里配置Robot账户。Robot账户的权限可以精确到“推送”或者“拉取”这种方式特别适合CI/CD流水线使用。3.2 为本地仓库配置HTTPS证书无论用Registry还是Harbor一旦你把它接入CI/CD就必须考虑HTTPS的问题。Docker默认要求仓库走HTTPS除非你在daemon.json里显式把仓库地址加入insecure-registries列表。但生产环境千万别这么干因为明文传输镜像相当于把你的应用代码和配置裸奔在网络上。最省事的方式是搭建一个内部CA然后给仓库签发证书。我把关键步骤列出来# 1. 生成CA私钥 openssl genrsa -out ca.key 4096 # 2. 生成CA证书 openssl req -x509 -new -nodes -key ca.key -days 3650 -out ca.crt # 3. 生成仓库服务器私钥 openssl genrsa -out registry.key 2048 # 4. 生成CSR注意Common Name要填仓库域名 openssl req -new -key registry.key -out registry.csr然后还要创建一个SAN扩展文件因为现在的Docker客户端会校验证书的Subject Alternative Name而不只是Common Name。SAN文件内容如下subjectAltName DNS:registry.internal.example.com, IP:192.168.1.100再执行openssl x509 -req -in registry.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out registry.crt -days 825 -extfile san.ext生成证书之后把ca.crt分发到每一台需要访问仓库的机器上。Linux下放到/etc/docker/certs.d/registry.internal.example.com:443/ca.crt这个路径注意目录名必须是“仓库域名:端口”的格式Docker启动时才会自动信任。配置好之后重启Docker再推送镜像就不会报证书错误了。3.3 镜像推送拉取与垃圾回收、存储清理实战本地仓库跑通之后日常工作中有几个操作是必须熟练的。推送镜像到自建仓库的标准姿势是先tag再pushdocker tag nginx:latest registry.internal.example.com/team-a/nginx:v1.2.0 docker push registry.internal.example.com/team-a/nginx:v1.2.0注意仓库地址路径是/项目名/镜像名:版本号三层结构。项目名用来做权限隔离镜像名用来标识应用版本号则对应流水线里的构建ID或git commit SHA。关于GC垃圾回收这是个高频但容易被忽略的操作。Docker Registry在删除镜像清单时并不会立刻释放底层存储需要手动执行垃圾回收。Harbor在Web界面上就能触发GCRegistry 2则需要操作底层存储有些复杂。我的建议是给GC配一个定时任务比如每周执行一次并且执行前先确认没有正在进行的推送任务否则可能影响流水线。另一个实战教训是存储清理策略。仓库跑久了最大的问题不是镜像数量多而是“过期镜像没人删”。我分享一个简单策略CI流水线里每次构建都用commit SHA作为标签保留最近30天的构建产物对于latest标签永远只允许最新构建覆盖。然后在仓库侧配置保留策略超过30天且不是稳定版本标签的镜像自动清理。Harbor内置了这个能力不需要额外开发。4. CI/CD流水线中集成镜像仓库的实战细节4.1 GitLab CI里跑Docker构建的几种姿势很多人一开始会把GitLab Runner直接装在宿主机上然后在gitlab-ci.yml里直接执行docker build这就是最常见的Shell executor方式。它的问题在于Runner进程本身没有做隔离每个CI任务直接在宿主机上操作Docker socket只要有一个任务在构建脚本里执行了危险操作宿主环境就暴露了。更推荐的方式是用Docker executor跑CI并在里面启用Docker-in-Docker简称dind。简单来说每个CI任务启动一个带Docker CLI的容器再通过服务容器service启动一个Docker daemon任务里的docker build实际是连接到这个服务容器上执行。配置gitlab-ci.yml时大致长这样variables: DOCKER_TLS_CERTDIR: build-image: image: docker:26 services: - docker:26-dind script: - docker build -t registry.example.com/app:$CI_COMMIT_SHA . - docker push registry.example.com/app:$CI_COMMIT_SHADOCKER_TLS_CERTDIR这个变量很关键它关闭了dind的TLS认证简化了本地通信。但要注意如果你对安全要求比较高还是建议保留TLS。另外还有一条路线是用kaniko替代dindkaniko不需要Docker daemon直接在容器内部完成镜像构建安全性和可复现性都更好。如果团队用GitLab CI并且对容器安全有执念优先投入kaniko不会错。4.2 流水线中镜像的登录凭据管理与标签规范镜像推送到仓库必然要处理登录凭证。这里有一个原则不要把真实账号密码写在CI配置里。GitLab CI提供了CI/CD Variables功能你可以把Harbor的Robot账户的用户名和密码存成变量然后在配置里这样使用build-image: script: - echo $REGISTRY_PASSWORD | docker login $REGISTRY_URL --username $REGISTRY_USERNAME --password-stdin - docker build -t $REGISTRY_URL/$PROJECT_NAME/app:$CI_COMMIT_SHA . - docker push $REGISTRY_URL/$PROJECT_NAME/app:$CI_COMMIT_SHA--password-stdin是必须的因为你如果用--password把密码直接拼在命令行里密码会出现在日志和进程列表里这是最基础的安全红线。标签规范方面我强烈建议区分“临时构建产物”和“正式发布版本”。临时产物一律用$CI_COMMIT_SHA即git提交哈希做标签这样每次提交都有唯一产物方便回滚时精确定位。正式发布则由人工触发或版本标签触发格式用v1.2.0这样的语义化版本。两套标签并行互不干扰。你还可以把CI_PIPELINE_ID拼进去但哈希已经足够不必再增加复杂度。4.3 构建缓存与多架构镜像的坑CI里构建镜像最怕两件事一是每次全量重新下载依赖二是只构建amd64架构的镜像导致后续在ARM服务器上跑不起来。依赖缓存这块Docker构建时的COPY指令非常关键。假设你的项目是Node.js你需要在Dockerfile里把package.json单独复制进镜像先执行npm install再复制其余代码。这样只要package.json没变Docker就会命中之前的层缓存整个镜像构建能快很多。否则你把所有代码一次性复制进去任何文件变了都会导致依赖重新安装CI速度直接慢一半以上。同样的道理适用于Maven的pom.xml先复制、后mvn package。多架构镜像方面现在的构建工具也都支持。docker buildx的buildx build命令可以一次构建多个平台的镜像然后用一个清单manifest把它们关联起来。以GitLab CI为例build-image: image: docker:26 services: - docker:26-dind script: - docker buildx create --use - docker buildx build --platform linux/amd64,linux/arm64 \ -t $REGISTRY_URL/$PROJECT_NAME/app:$CI_COMMIT_SHA \ --push .如果你用Harbor作为仓库开启Harbor的Proxy Cache功能还能让Harbor自动缓存外网镜像。这样CI在拉取镜像时只需要从Harbor内网拉速度很快也绕开了外网抖动的影响。4.4 镜像安全扫描与版本清理的落地前文提到仓库侧的保留策略这里再讲下安全扫描。Docker镜像扫描的工具比较多Harbor集成了Trivy可以在镜像推送完成后自动扫描漏洞。CI阶段同样可以接入Trivy让流水线在“高危漏洞数量超标”时直接失败把不安全的镜像挡在仓库外面。接Trivy到GitLab CI的配置片段大致如下scan-image: image: aquasec/trivy script: - trivy image --exit-code 1 --severity HIGH,CRITICAL $REGISTRY_URL/$PROJECT_NAME/app:$CI_COMMIT_SHA--exit-code 1的意思是如果发现了高危或严重级别的漏洞就返回非零退出码CI任务失败。实际用的时候建议先跑一次不带--exit-code的扫瞄看看历史遗留漏洞有多少再决定阈值怎么设置。一上来就要求零漏洞很可能把CI堵死反而不利于团队推进。存储清理这块我上面讲过一次这次补充一个容易踩的坑不要直接用delete API删镜像。Registry原生的API删的是manifest但blob还在存储里空间并不会立刻释放。你需要去仓库后台触发GC或者用Harbor自动触发。否则你把镜像删了一大批磁盘用量却纹丝不动排障时很容易被误导。5. 常见问题与排查技巧实录5.1 CI里docker push时报unauthorized的排查思路这个报错几乎是必踩的坑。大概率的锅在登录时机不对你在某个job里登录了仓库但GitLab CI的Docker executor里每个job都是全新容器上一个job的登录状态不会保留。解决方案就是上面写的在需要推送的job里先执行docker login。另一种可能是指定镜像仓库地址有问题。比如你登录的是registry.example.com但push时写成了registry.example.com/team/app:tag路径前缀不一致也会导致鉴权失败。用Robot账户时尤其要注意Robot账户通常只被授权到指定的项目路径你push到别的项目下就会unauthorized。5.2 自建仓库磁盘快速增长的处理镜像仓库的存储膨胀有几个常见原因大量历史构建标签堆积、GC策略没配置、日志文件过大。我从实际的经历看大部分团队的镜像仓库磁盘打满都是第一类原因导致的——代码仓库用久了构建产物堆积如山又没有保留策略。处理的策略也很朴素先在Harbor把自动清理策略打开只保留最近30天的未引用镜像再手动触发一次GC。定期加一个定时任务检查du -sh /data/harbor观察增长曲线。如果每个月都膨胀得厉害优先检查流水线里是不是每次构建都生成了不可重复的大镜像。我见过一个团队因为构建脚本里把整个node_modules打成镜像每个镜像体积5GB起步仓库不爆才怪。5.3 加速器拉不到第三方仓库镜像的替代方案如果有一批外部镜像需要在内网环境使用我的做法是“镜像同步”用一条流水线定期把需要的外部镜像拉到本地重新tag之后推送到自建仓库。具体可以用一个简单的shell脚本在CI里跑docker pull gcr.io/foo/bar:v1.0 docker tag gcr.io/foo/bar:v1.0 registry.internal.example.com/mirrors/foo-bar:v1.0 docker push registry.internal.example.com/mirrors/foo-bar:v1.0这样既绕开了拉取超时的网络问题也让内网所有主机都能从同一个源拉镜像。更重要的是这个同步过程可以审计、可以回滚配合仓库的Robot账户只用推送权限整体安全性也可控。5.4 自建仓库启动失败后的恢复经验有一次Harbor的数据库所在磁盘满了导致Harbor启动后反复重启所有流水线都拉不到镜像。那次排查花了不少时间后来总结了一个经验基础设施必须带监控仓库磁盘使用率超过80%就要产生告警。磁盘写满导致服务故障不一定发生在写入时更可能在后台GC之类操作时触发连锁反应届时修复成本就高了。另外我强烈建议在部署Harbor时把data_volume挂到独立磁盘或者独立存储路径至少和系统盘分离这样即使系统盘满了仓库核心数据也不会立刻受牵连。就我自己的实践体会镜像仓库和CI/CD集成的核心不在于“搭起来能跑”而在于后续的可见性和治理。把镜像的标签策略定好把仓库的保留策略配好把Robot账户的权限缩到最小再把CI和仓库之间的访问链路用HTTPS加固整套体系基本上就能稳定运转下去。你在做这一套的时候踩过的坑大概率不会跳出上面这几个方向照着排查思路来能省不少折腾的时间。