1. 镜像仓库方案选型与整体设计思路最近不少团队都在折腾镜像仓库和CI/CD集成这套东西原因也很直接本地开发时docker pull还能凑合一旦上了流水线和多节点部署镜像拉取慢、版本管理混乱、权限失控这些问题全冒出来了。我前后帮几个团队搭过完整的镜像仓库体系这里把踩过的坑和沉淀下来的方案一次性讲清楚希望能帮你少走弯路。先说结论镜像仓库的核心价值不只是“存镜像”它实际上承担了三个关键职责制品资产化管理、环境一致性保障、与CI/CD流水线的自动衔接。很多团队一开始只把它当个“网盘”来用结果后面排查生产事故时找不到究竟是哪个镜像在跑那种痛苦我体会过。先看方案选型。目前主流镜像仓库方案基本就是四个方向Docker Registry、Harbor、阿里云镜像仓库ACR、以及Nexus。它们各自有自己的适用场景。方案是否自带UI权限控制镜像复制垃圾回收适用场景Docker Registry无简单账号无手动测试环境、技术验证Harbor有基于项目的RBAC支持支持企业生产、多团队协作阿里云ACR有RAM 命名空间支持免运维阿里云用户、混合云场景Nexus有仓库级权限一般一般已有Nexus生态、多制品类型国内网络环境还有一个很实际的问题就是直接从Docker Hub拉镜像经常不靠谱。所以方案里必须考虑两层一层是上游加速与镜像缓存另一层是私有制品库。企业里做得比较舒服的做法是构建机配好国内镜像加速器比如阿里云、腾讯云、中科大源同时私有仓库做一层“拉取代理”能力也就是让Harbor去上游拉一次然后缓存到本地这样后续所有节点都从内网仓库拿镜像速度稳定且流量可控。关于2026年国内镜像仓库地址的变化没必要追最新域名因为这类地址本来就经常调整正确做法是在Harbor里配多个上游镜像源主备切换而不是把所有鸡蛋放进一个篮子。这比手工改/etc/docker/daemon.json里的registry-mirrors要优雅得多毕竟你不可能让每台机器都去维护一份变了就失效的地址列表。我最终采用的架构是GitLab GitLab Runner Harbor 可选K8s。GitLab负责代码托管和CI编排Runner负责执行构建任务Harbor统一收口制品并做权限和复制。选这套组合的原因很朴素开源免费、资料多、出了问题社区里基本都能搜到解答而且它对机房部署还是云上部署都一视同仁。工具选型其实是“用已有资产 补齐短板”的思路而不是追求最强功能。比如你已经有GitLab了就没必要再引入一套Jenkins只要Runner能跑容器docker build的能力就天然具备。Harbor是这里面唯一需要新装的组件它解决的是Registry本身的UI、权限、复制和回收这四件事。2. 私有镜像仓库搭建与配置详解2.1 用Harbor自建仓库的完整步骤Harbor的部署方式现在最推荐的是用Docker Compose方式跑官方提供了install.sh脚本。虽然Harbor也有Helm Chart可以上K8s但对于大多数团队来说一台4C8G的虚拟机就够撑起几百个镜像的日构建量了。先说环境准备和工作目录规划。我习惯把所有与Harbor相关的数据都放在一个独立目录下方便备份也方便迁移。部署之前需要确认机器上已经装好了Docker和Docker Compose插件版本尽量新一些Harbor对Compose V2的支持更友好。# 以 root 或具备 docker 权限的账号执行 mkdir -p /opt/harbor cd /opt/harbor # 下载并解压版本号按官方发布为准我写这篇时用的是 2.10.x wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz tar zxvf harbor-offline-installer-v2.10.0.tgz cd harbor-offline-installer-v2.10.0这里解释一下为什么要用offline安装包。在线版installer虽然体积小但安装过程中需要去Docker Hub拉取好几个镜像国内网络条件下一旦超时就会中断排查起来很烦。离线包把所需镜像全部打好装完本地就有了一次到位。接下来配置harbor.yml。最省事的做法是复制模板再改cp harbor.yml.tmpl harbor.yml vi harbor.yml核心配置项就三个地方要动hostname、https证书、harbor_admin_password。hostname一定要填你内网DNS能解析到的地址或者至少是各节点通过/etc/hosts能访问到的地址不要随手填个IP然后后面到处去改客户端配置。hostname: registry.example.internal http: port: 80 https: port: 443 certificate: /data/certs/registry.crt private_key: /data/certs/registry.key harbor_admin_password: YourStrongPasswordHere database: password: root123 data_volume: /data/harbor关于HTTPS证书生产环境我强烈建议直接对接公司内部的CA或者用Let‘s Encrypt签发的证书不要用自签名证书。如果你非要自签名那就必须把证书分发给所有要登录这台仓库的机器并在dockerd的配置里指定否则后面流水线里docker login会时不时报x509错误排查成本很高。证书准备好了就执行安装./install.sh # 安装成功后浏览器或命令行验证 docker ps | grep harbor登录Harbor界面后第一件事是创建项目。建议按团队或者业务线来划分项目比如frontend-service、backend-service、data-pipeline每个项目设置不同的访问级别。公开项目适合放基础镜像私有项目和特定项目成员绑定保证生产镜像不能被随便拉取。2.2 HTTPS证书与Docker客户端信任链配置这部分是很多人会漏掉的细节。Harbor虽然能用HTTP跑但Docker从1.13版本之后默认就只允许HTTPS方式的registry。你如果真要开HTTP就必须在每台客户端机器的dockerd配置里加上insecure-registries然后重启Docker。生产环境我从来不用insecure方式原因有两个镜像内容可能被篡改而且某些安全扫描工具会直接报警。正规操作是把Harbor服务器上的CA证书同步到各客户端的系统信任区# 在客户端机器上 sudo mkdir -p /etc/docker/certs.d/registry.example.internal sudo cp /data/certs/ca.crt /etc/docker/certs.d/registry.example.internal/ca.crt # 验证登录 docker login registry.example.internal -u admin这里有一个容易被忽略的坑如果Harbor用的证书是由私有CA签发的你必须让客户端信任那个根CA而不是信任服务器证书本身。很多新手把registry.crt复制过去当作ca.crt使用然后一直报错。正确的做法是签发服务器证书的同时生成一个ca.crt把ca.crt分发下去。2.3 配置上游镜像加速与复制规则回到文章开头提到的国内镜像源问题。Harbor有一个官方功能叫Registries可以配置远端仓库作为代理缓存。新建一个Registries配置类型选Docker HubURL填https://registry-1.docker.io访问凭证用你的Docker Hub账号没有就先注册一个。开启代理缓存以后你在Harbor项目里看到的镜像本地没有时会先去上游拉拉回来缓存住下次直接命中。同理像gcr.io、quay.io这些访问不稳定的源也可以配置对应的远端代理这样CI构建时不用改任何代码就能稳定拉取基础镜像。下面是配置远程仓库的注意点远端仓库凭证尽量使用只读账号避免泄露写权限。代理缓存项目要设置“最大缓存容量”防止镜像越积越多把磁盘打满。复制规则按需开启比如从测试仓库复制到生产仓库或者做跨机房同步。我实际使用下来Harbor的复制规则非常适合“开发环境随意构建、生产环境定向发布”的流程。开发环境项目不设回收策略小版本随便打生产环境项目只允许从开发环境复制过来的镜像被部署逻辑上就用规则隔离开了。3. CI/CD流水线接入镜像仓库的完整实现3.1 GitLab Runner与Docker Engine配置避坑接入CI/CD之前先要保证Runner能以Docker方式执行任务。GitLab Runner有两种执行器Shell执行器和Docker执行器。强烈建议用Docker执行器因为每次CI都能在一个全新容器中跑环境隔离非常干净。Runner注册时有个关键参数是executor选择docker之后还需要配置docker image也就是CI任务默认跑在哪个基础镜像里。我常用的配置是gitlab-runner register \ --url https://gitlab.example.internal \ --token YOUR_RUNNER_TOKEN \ --executor docker \ --docker-image docker:stable \ --docker-privileged true \ --docker-volumes /var/run/docker.sock:/var/run/docker.sock这里有两个坑必须说明。第一个坑docker:dindDocker in Docker与挂载宿主docker.sock是两种不同玩法。如果你选了docker:dind方案要在services里声明一个docker:dind的service并设置DOCKER_HOST指向它如果挂载宿主的/var/run/docker.sock那CI任务里执行的docker命令其实直接操作的是宿主机的Docker守护进程。两种方式各有适用场景dind隔离性强适合需要严格控制构建环境的场景socket共享性能好配置简单但CI任务拥有宿主机root权限要求Runner机器是可信环境。第二个坑当挂载了宿主docker.sock后在CI里执行docker build之前必须先登录私有仓库。Runner机器上虽然可能已经手动登录过但CI执行环境是新起的容器登录信息不会自动带进来。所以每一段需要推送镜像的job里都要执行一次docker login而且不能把密码明文写在仓库里要用GitLab CI/CD Variables注入。3.2 编写.gitlab-ci.yml实现镜像构建与推送我现在给出的模板基本是我多个项目里提炼出来的通用版本。它实现的事情是代码推送后触发流水线构建Docker镜像打上分支名和短提交SHA的标签推送到Harbor然后可选地触发部署。stages: - build - deploy variables: HARBOR_REGISTRY: registry.example.internal HARBOR_PROJECT: demo/app IMAGE_NAME: $HARBOR_REGISTRY/$HARBOR_PROJECT:$CI_COMMIT_SHORT_SHA build-image: stage: build image: docker:stable services: - docker:dind script: - docker build -t $IMAGE_NAME . - docker login -u $HARBOR_USERNAME -p $HARBOR_PASSWORD $HARBOR_REGISTRY - docker push $IMAGE_NAME only: - main - develop - /^release\/.*$/如果之前的Runner配置是共享socket方案这里services那一段要删掉改成直接使用宿主Docker。下面这种写法是我在另一类项目里的用法build-image-socket: stage: build image: docker:20.10.24 script: - docker info - docker build -t $IMAGE_NAME . - echo $HARBOR_PASSWORD | docker login --username $HARBOR_USERNAME --password-stdin $HARBOR_REGISTRY - docker push $IMAGE_NAME这两个模板的核心差异反映了你的Runner架构选型没有谁绝对好关键看你对“隔离性”和“构建速度”的取舍。docker:dind模式下每次构建都要从零启动一层Docker环境冷启动时间多3-5秒socket模式下构建直接复用宿主机的镜像缓存速度明显快一截。3.3 镜像Tag策略与版本回滚联动流水线构建没问题之后另一个容易被忽略的是镜像命名策略。如果你每次构建都是latest那恭喜你踩进了最经典的运维泥潭。等线上出问题想回滚时会发现所有节点拉下来的都是最新版根本不知道上一版到底长什么样。我的做法是至少打两个标签短SHA标签如$CI_COMMIT_SHORT_SHA保证每个提交有唯一制品适合回滚定位到确切代码。分支语义标签如main-latestdevelop-latest方便开发环境部署拿到当前分支最新构建。生产环境需要发布时再做一步重打标签docker pull registry.example.internal/demo/app:2f3a9c docker tag registry.example.internal/demo/app:2f3a9c registry.example.internal/demo/app:release-20260520 docker push registry.example.internal/demo/app:release-20260520这样“线上跑的是哪个版本”这个问题每次都有一个明确可追踪的答案。后续你想用K8s做滚动发布也好用单机docker compose重启也好只需要把部署文件里的镜像地址改成对应的tag即可。3.4 关联K8s配置更新与自动部署如果你的目标环境是Kubernetes那CI/CD到推送镜像这一步还没完。常见做法是更新K8s工作负载的镜像字段让集群拉取新镜像完成滚动更新。操作上最简单的方式是利用kubectl命令直接设置镜像- kubectl set image deployment/app app$IMAGE_NAME --record - kubectl rollout status deployment/app --timeout120s这样做的优点是直观缺点是如果配置项多了不方便统一管理。更工程化的做法是用Helm或Kustomize维护部署清单CI里将镜像地址作为参数渲染然后apply。个人经验是团队没有专职运维的时候kubectl set image就已经够用超过三套环境还在手动改YAML就该考虑Helm了。还有一个经常因为权限不足导致失败的点Runner里执行kubectl需要kubeconfig而这个config不能直接挂进任意CI任务否则任何人往仓库里推代码都能在集群里执行命令。正确做法是把kubeconfig内容放在GitLab的变量中在deploy job里写入临时文件再用KUBECONFIG环境变量指定。我的K8s部署job大概长这样deploy-k8s: stage: deploy image: bitnami/kubectl:latest script: - printf %s $KUBE_CONFIG | base64 -d /tmp/kubeconfig - export KUBECONFIG/tmp/kubeconfig - kubectl set image deployment/app app$IMAGE_NAME -n production - kubectl rollout status deployment/app -n production4. Maven配置多镜像仓库与镜像仓库关联场景这个话题在热词里出现得很集中我单独拿出来说。很多Java项目构建时面对的问题不是Docker镜像拉取而是Maven依赖下载慢或者某个私服挂了导致构建失败。处理方式和Docker镜像加速是同一个思路配置多仓库镜像优先本地私服二级回退中央仓库或CDN加速源。在settings.xml中配置多个mirror和一个自定义仓库组的例子如下settings mirrors mirror idnexus-public/id mirrorOf*/mirrorOf urlhttps://maven.internal.example/repository/maven-public//url /mirror /mirrors profiles profile iddefault/id repositories repository idcentral/id urlhttps://repo1.maven.org/maven2//url /repository repository idnexus-group/id urlhttps://maven.internal.example/repository/maven-public//url /repository /repositories /profile /profiles activeProfiles activeProfiledefault/activeProfile /activeProfiles /settings这里最关键的配置是mirrorOf匹配规则。如果你配成mirrorOf*则所有依赖请求都会先走NexusNexus没有的会通过它配置的proxy远程仓库去下载并缓存。如果Nexus配置了外网仓库代理构建速度会越来越快因为常用依赖都被缓存住了。在GitLab CI里我用一段before_script来动态生成settings.xml避免把服务器密码提交到仓库before_script: - mkdir -p ~/.m2 - sed s|NEXUS_PLACEHOLDER|$NEXUS_URL|g; s|NEXUS_USERNAME_PLACEHOLDER|$NEXUS_USERNAME|g; s|NEXUS_PASSWORD_PLACEHOLDER|$NEXUS_PASSWORD|g ci/settings.xml.tpl ~/.m2/settings.xml模板文件里预置好结构变量从GitLab CI/CD Variables里动态填充。这样既保证了凭据的安全性又让每个开发者本环境和CI环境保持同构。多镜像仓库配置的隐性收益常被忽略它能让“依赖锁定”成为可能。你在settings.xml里固定了仓库顺序之后CI构建的依赖解析每次都是从同一优先级的库拿货而不是今天命中中央仓库、明天命中镜像源的后端降低了“构建可复现性”被破坏的概率。5. 常见问题与排查技巧实录5.1 docker login成功但docker push总是401或403这是我们在切换Harbor之后遇到频率最高的问题。我梳理了一下基本就是三种情况表象可能原因动作push返回401用户名或密码错误Harbor项目不存在检查账号权限确认项目名和镜像路径是否匹配push返回403用户不属于该项目的member项目配额满在Harbor项目成员中加人或删除旧镜像某些标记能push某些不能镜像名称格式不符Harbor的仓库权限规则规范项目名/镜像名映射避免/分隔层级过深还有一种隐蔽情况构建机与Harbor之间存在反向代理或网关代理层缓存了401响应。表现为第一台机器push没问题第二台机器随机401。处理方式是在Nginx的缓存配置中排除$upstream_status401的场景。5.2 流水线构建Docker镜像时缓存失效导致构建缓慢很多团队用docker build做镜像构建每次从头执行。那是因为没有利用BuildKit的层缓存。要解决这个不是靠镜像仓库而是优化构建步骤的顺序。Dockerfile里依赖安装层的指令尽量往前放应用代码复制层往后放这样只要依赖文件不变中间层缓存都能命中。启用BuildKit也很简单在CI里设置环境变量variables: DOCKER_BUILDKIT: 1然后配合docker buildx做多阶段构建和缓存导出效果更明显。构建机本地也会生成缓存目录如果CI执行环境是新建容器建议在runner配置里挂载一个持久化volume作为docker的缓存目录避免每次构建清空一切。5.3 镜像仓库占用空间暴涨的清理策略Harbor默认允许同一镜像累积多个tag时间一长仓库的占用空间快速上涨。我见过一个团队因此被磁盘打满导致所有CI推送直接失败。这属于规划期没定义回收策略的典型反弹。Harbor自带的清理策略可以按时间或按保留数量自动清理策略类型按天数保留比如保留最近90天。策略类型按数量保留比如每个仓库保留最近30个tag。也可以设置“无tag”的镜像清理避免重复构建留下孤儿镜像。不过这只是控制未来失控已经占满的情况需要手动触发垃圾回收。Harbor界面里可以提供Garbage Collection操作它就是清理未被任何manifest引用的blob层。执行GC前要停止仓库的写入操作所以选业务低峰期执行。还有一个细节你要知道镜像的层blob是共享的多个镜像如果共用层磁盘不会重复占用GC回收的是没有镜像引用的孤层。有些管理员不知道这一点手动删了某个镜像但磁盘空间没降其实就是层仍然被其他镜像引用着这是正常现象。5.4 多机房或混合云场景下镜像同步复制当你的团队跨地域协作或者公有云和自建机房并存时镜像仓库的同步问题会逐渐凸显。核心思路是采用“主从复制”而非“双活”在主站点配置复制规则推送到Harbor的镜像自动复制到从仓库。从仓库通常是只读的供远端集群拉取。复制规则里有一个关键参数叫覆盖模式。覆盖会同步内容变化容易覆盖掉远端环境经过热修复后的镜像不覆盖会在同名镜像存在时跳过适合保护已部署制品。我用的是“不覆盖”模式配合从站点的保留策略避免远端生产环境的镜像被意外改动。混合云场景下从站点通常选择云厂商的容器镜像服务比如阿里云ACR这样远端K8s集群拉取镜像走内网速度快且不产生公网流量费。Harbor到ACR之间复制时Registry类型选择“Aliyun ACR”填入对应的同步账号与地域Endpoint即可。6. 一些真实的优化心得整套体系搭建和运行一段时间以后我复盘下来觉得最值钱的经验其实不在某条命令或某个配置而在于把“镜像制品管理”当成工程文化的一部分来建设。比如镜像命名规范应该写进团队的工程文档让它和代码规范同等重要。一个清晰的命名规则像“地址/项目/服务名:环境-提交号”这种一眼就能看出镜像是干嘛的。我见过一个团队把镜像名起成app-new-final-2坦白讲这种名字以后回滚时你根本不知道它对应哪个代码版本。再比如CI/CD变量的管理。不要什么都往代码仓库里塞尤其Harbor密码、kubeconfig这些敏感信息一律通过GitLab的Protected Variables按分支保护。这样即使某个开发分支被恶意提交也无法通过流水线读取到生产环境的密钥。还有一个比较有价值的体验把镜像仓库监控接入告警。Harbor本身有一些基础指标接口磁盘使用率、仓库镜像数量、上传下载流量等等。用Prometheus抓一下再配上Alertmanager的规则磁盘到80%时提前收到通知就能在大规模故障前留出操作缓冲。这个不复杂但对运维体感提升非常明显。如果你只在本地玩一玩那Docker Registry足够了一旦进入多人协作、多环境发布的阶段强烈建议直接上Harbor。整套成本也就是一台低配服务器加上几小时的配置时间但它能换来的是稳定的构建链路和清晰可追溯的制品管理体系。
镜像仓库选型与Harbor实战：从搭建到CI/CD集成全指南
1. 镜像仓库方案选型与整体设计思路最近不少团队都在折腾镜像仓库和CI/CD集成这套东西原因也很直接本地开发时docker pull还能凑合一旦上了流水线和多节点部署镜像拉取慢、版本管理混乱、权限失控这些问题全冒出来了。我前后帮几个团队搭过完整的镜像仓库体系这里把踩过的坑和沉淀下来的方案一次性讲清楚希望能帮你少走弯路。先说结论镜像仓库的核心价值不只是“存镜像”它实际上承担了三个关键职责制品资产化管理、环境一致性保障、与CI/CD流水线的自动衔接。很多团队一开始只把它当个“网盘”来用结果后面排查生产事故时找不到究竟是哪个镜像在跑那种痛苦我体会过。先看方案选型。目前主流镜像仓库方案基本就是四个方向Docker Registry、Harbor、阿里云镜像仓库ACR、以及Nexus。它们各自有自己的适用场景。方案是否自带UI权限控制镜像复制垃圾回收适用场景Docker Registry无简单账号无手动测试环境、技术验证Harbor有基于项目的RBAC支持支持企业生产、多团队协作阿里云ACR有RAM 命名空间支持免运维阿里云用户、混合云场景Nexus有仓库级权限一般一般已有Nexus生态、多制品类型国内网络环境还有一个很实际的问题就是直接从Docker Hub拉镜像经常不靠谱。所以方案里必须考虑两层一层是上游加速与镜像缓存另一层是私有制品库。企业里做得比较舒服的做法是构建机配好国内镜像加速器比如阿里云、腾讯云、中科大源同时私有仓库做一层“拉取代理”能力也就是让Harbor去上游拉一次然后缓存到本地这样后续所有节点都从内网仓库拿镜像速度稳定且流量可控。关于2026年国内镜像仓库地址的变化没必要追最新域名因为这类地址本来就经常调整正确做法是在Harbor里配多个上游镜像源主备切换而不是把所有鸡蛋放进一个篮子。这比手工改/etc/docker/daemon.json里的registry-mirrors要优雅得多毕竟你不可能让每台机器都去维护一份变了就失效的地址列表。我最终采用的架构是GitLab GitLab Runner Harbor 可选K8s。GitLab负责代码托管和CI编排Runner负责执行构建任务Harbor统一收口制品并做权限和复制。选这套组合的原因很朴素开源免费、资料多、出了问题社区里基本都能搜到解答而且它对机房部署还是云上部署都一视同仁。工具选型其实是“用已有资产 补齐短板”的思路而不是追求最强功能。比如你已经有GitLab了就没必要再引入一套Jenkins只要Runner能跑容器docker build的能力就天然具备。Harbor是这里面唯一需要新装的组件它解决的是Registry本身的UI、权限、复制和回收这四件事。2. 私有镜像仓库搭建与配置详解2.1 用Harbor自建仓库的完整步骤Harbor的部署方式现在最推荐的是用Docker Compose方式跑官方提供了install.sh脚本。虽然Harbor也有Helm Chart可以上K8s但对于大多数团队来说一台4C8G的虚拟机就够撑起几百个镜像的日构建量了。先说环境准备和工作目录规划。我习惯把所有与Harbor相关的数据都放在一个独立目录下方便备份也方便迁移。部署之前需要确认机器上已经装好了Docker和Docker Compose插件版本尽量新一些Harbor对Compose V2的支持更友好。# 以 root 或具备 docker 权限的账号执行 mkdir -p /opt/harbor cd /opt/harbor # 下载并解压版本号按官方发布为准我写这篇时用的是 2.10.x wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz tar zxvf harbor-offline-installer-v2.10.0.tgz cd harbor-offline-installer-v2.10.0这里解释一下为什么要用offline安装包。在线版installer虽然体积小但安装过程中需要去Docker Hub拉取好几个镜像国内网络条件下一旦超时就会中断排查起来很烦。离线包把所需镜像全部打好装完本地就有了一次到位。接下来配置harbor.yml。最省事的做法是复制模板再改cp harbor.yml.tmpl harbor.yml vi harbor.yml核心配置项就三个地方要动hostname、https证书、harbor_admin_password。hostname一定要填你内网DNS能解析到的地址或者至少是各节点通过/etc/hosts能访问到的地址不要随手填个IP然后后面到处去改客户端配置。hostname: registry.example.internal http: port: 80 https: port: 443 certificate: /data/certs/registry.crt private_key: /data/certs/registry.key harbor_admin_password: YourStrongPasswordHere database: password: root123 data_volume: /data/harbor关于HTTPS证书生产环境我强烈建议直接对接公司内部的CA或者用Let‘s Encrypt签发的证书不要用自签名证书。如果你非要自签名那就必须把证书分发给所有要登录这台仓库的机器并在dockerd的配置里指定否则后面流水线里docker login会时不时报x509错误排查成本很高。证书准备好了就执行安装./install.sh # 安装成功后浏览器或命令行验证 docker ps | grep harbor登录Harbor界面后第一件事是创建项目。建议按团队或者业务线来划分项目比如frontend-service、backend-service、data-pipeline每个项目设置不同的访问级别。公开项目适合放基础镜像私有项目和特定项目成员绑定保证生产镜像不能被随便拉取。2.2 HTTPS证书与Docker客户端信任链配置这部分是很多人会漏掉的细节。Harbor虽然能用HTTP跑但Docker从1.13版本之后默认就只允许HTTPS方式的registry。你如果真要开HTTP就必须在每台客户端机器的dockerd配置里加上insecure-registries然后重启Docker。生产环境我从来不用insecure方式原因有两个镜像内容可能被篡改而且某些安全扫描工具会直接报警。正规操作是把Harbor服务器上的CA证书同步到各客户端的系统信任区# 在客户端机器上 sudo mkdir -p /etc/docker/certs.d/registry.example.internal sudo cp /data/certs/ca.crt /etc/docker/certs.d/registry.example.internal/ca.crt # 验证登录 docker login registry.example.internal -u admin这里有一个容易被忽略的坑如果Harbor用的证书是由私有CA签发的你必须让客户端信任那个根CA而不是信任服务器证书本身。很多新手把registry.crt复制过去当作ca.crt使用然后一直报错。正确的做法是签发服务器证书的同时生成一个ca.crt把ca.crt分发下去。2.3 配置上游镜像加速与复制规则回到文章开头提到的国内镜像源问题。Harbor有一个官方功能叫Registries可以配置远端仓库作为代理缓存。新建一个Registries配置类型选Docker HubURL填https://registry-1.docker.io访问凭证用你的Docker Hub账号没有就先注册一个。开启代理缓存以后你在Harbor项目里看到的镜像本地没有时会先去上游拉拉回来缓存住下次直接命中。同理像gcr.io、quay.io这些访问不稳定的源也可以配置对应的远端代理这样CI构建时不用改任何代码就能稳定拉取基础镜像。下面是配置远程仓库的注意点远端仓库凭证尽量使用只读账号避免泄露写权限。代理缓存项目要设置“最大缓存容量”防止镜像越积越多把磁盘打满。复制规则按需开启比如从测试仓库复制到生产仓库或者做跨机房同步。我实际使用下来Harbor的复制规则非常适合“开发环境随意构建、生产环境定向发布”的流程。开发环境项目不设回收策略小版本随便打生产环境项目只允许从开发环境复制过来的镜像被部署逻辑上就用规则隔离开了。3. CI/CD流水线接入镜像仓库的完整实现3.1 GitLab Runner与Docker Engine配置避坑接入CI/CD之前先要保证Runner能以Docker方式执行任务。GitLab Runner有两种执行器Shell执行器和Docker执行器。强烈建议用Docker执行器因为每次CI都能在一个全新容器中跑环境隔离非常干净。Runner注册时有个关键参数是executor选择docker之后还需要配置docker image也就是CI任务默认跑在哪个基础镜像里。我常用的配置是gitlab-runner register \ --url https://gitlab.example.internal \ --token YOUR_RUNNER_TOKEN \ --executor docker \ --docker-image docker:stable \ --docker-privileged true \ --docker-volumes /var/run/docker.sock:/var/run/docker.sock这里有两个坑必须说明。第一个坑docker:dindDocker in Docker与挂载宿主docker.sock是两种不同玩法。如果你选了docker:dind方案要在services里声明一个docker:dind的service并设置DOCKER_HOST指向它如果挂载宿主的/var/run/docker.sock那CI任务里执行的docker命令其实直接操作的是宿主机的Docker守护进程。两种方式各有适用场景dind隔离性强适合需要严格控制构建环境的场景socket共享性能好配置简单但CI任务拥有宿主机root权限要求Runner机器是可信环境。第二个坑当挂载了宿主docker.sock后在CI里执行docker build之前必须先登录私有仓库。Runner机器上虽然可能已经手动登录过但CI执行环境是新起的容器登录信息不会自动带进来。所以每一段需要推送镜像的job里都要执行一次docker login而且不能把密码明文写在仓库里要用GitLab CI/CD Variables注入。3.2 编写.gitlab-ci.yml实现镜像构建与推送我现在给出的模板基本是我多个项目里提炼出来的通用版本。它实现的事情是代码推送后触发流水线构建Docker镜像打上分支名和短提交SHA的标签推送到Harbor然后可选地触发部署。stages: - build - deploy variables: HARBOR_REGISTRY: registry.example.internal HARBOR_PROJECT: demo/app IMAGE_NAME: $HARBOR_REGISTRY/$HARBOR_PROJECT:$CI_COMMIT_SHORT_SHA build-image: stage: build image: docker:stable services: - docker:dind script: - docker build -t $IMAGE_NAME . - docker login -u $HARBOR_USERNAME -p $HARBOR_PASSWORD $HARBOR_REGISTRY - docker push $IMAGE_NAME only: - main - develop - /^release\/.*$/如果之前的Runner配置是共享socket方案这里services那一段要删掉改成直接使用宿主Docker。下面这种写法是我在另一类项目里的用法build-image-socket: stage: build image: docker:20.10.24 script: - docker info - docker build -t $IMAGE_NAME . - echo $HARBOR_PASSWORD | docker login --username $HARBOR_USERNAME --password-stdin $HARBOR_REGISTRY - docker push $IMAGE_NAME这两个模板的核心差异反映了你的Runner架构选型没有谁绝对好关键看你对“隔离性”和“构建速度”的取舍。docker:dind模式下每次构建都要从零启动一层Docker环境冷启动时间多3-5秒socket模式下构建直接复用宿主机的镜像缓存速度明显快一截。3.3 镜像Tag策略与版本回滚联动流水线构建没问题之后另一个容易被忽略的是镜像命名策略。如果你每次构建都是latest那恭喜你踩进了最经典的运维泥潭。等线上出问题想回滚时会发现所有节点拉下来的都是最新版根本不知道上一版到底长什么样。我的做法是至少打两个标签短SHA标签如$CI_COMMIT_SHORT_SHA保证每个提交有唯一制品适合回滚定位到确切代码。分支语义标签如main-latestdevelop-latest方便开发环境部署拿到当前分支最新构建。生产环境需要发布时再做一步重打标签docker pull registry.example.internal/demo/app:2f3a9c docker tag registry.example.internal/demo/app:2f3a9c registry.example.internal/demo/app:release-20260520 docker push registry.example.internal/demo/app:release-20260520这样“线上跑的是哪个版本”这个问题每次都有一个明确可追踪的答案。后续你想用K8s做滚动发布也好用单机docker compose重启也好只需要把部署文件里的镜像地址改成对应的tag即可。3.4 关联K8s配置更新与自动部署如果你的目标环境是Kubernetes那CI/CD到推送镜像这一步还没完。常见做法是更新K8s工作负载的镜像字段让集群拉取新镜像完成滚动更新。操作上最简单的方式是利用kubectl命令直接设置镜像- kubectl set image deployment/app app$IMAGE_NAME --record - kubectl rollout status deployment/app --timeout120s这样做的优点是直观缺点是如果配置项多了不方便统一管理。更工程化的做法是用Helm或Kustomize维护部署清单CI里将镜像地址作为参数渲染然后apply。个人经验是团队没有专职运维的时候kubectl set image就已经够用超过三套环境还在手动改YAML就该考虑Helm了。还有一个经常因为权限不足导致失败的点Runner里执行kubectl需要kubeconfig而这个config不能直接挂进任意CI任务否则任何人往仓库里推代码都能在集群里执行命令。正确做法是把kubeconfig内容放在GitLab的变量中在deploy job里写入临时文件再用KUBECONFIG环境变量指定。我的K8s部署job大概长这样deploy-k8s: stage: deploy image: bitnami/kubectl:latest script: - printf %s $KUBE_CONFIG | base64 -d /tmp/kubeconfig - export KUBECONFIG/tmp/kubeconfig - kubectl set image deployment/app app$IMAGE_NAME -n production - kubectl rollout status deployment/app -n production4. Maven配置多镜像仓库与镜像仓库关联场景这个话题在热词里出现得很集中我单独拿出来说。很多Java项目构建时面对的问题不是Docker镜像拉取而是Maven依赖下载慢或者某个私服挂了导致构建失败。处理方式和Docker镜像加速是同一个思路配置多仓库镜像优先本地私服二级回退中央仓库或CDN加速源。在settings.xml中配置多个mirror和一个自定义仓库组的例子如下settings mirrors mirror idnexus-public/id mirrorOf*/mirrorOf urlhttps://maven.internal.example/repository/maven-public//url /mirror /mirrors profiles profile iddefault/id repositories repository idcentral/id urlhttps://repo1.maven.org/maven2//url /repository repository idnexus-group/id urlhttps://maven.internal.example/repository/maven-public//url /repository /repositories /profile /profiles activeProfiles activeProfiledefault/activeProfile /activeProfiles /settings这里最关键的配置是mirrorOf匹配规则。如果你配成mirrorOf*则所有依赖请求都会先走NexusNexus没有的会通过它配置的proxy远程仓库去下载并缓存。如果Nexus配置了外网仓库代理构建速度会越来越快因为常用依赖都被缓存住了。在GitLab CI里我用一段before_script来动态生成settings.xml避免把服务器密码提交到仓库before_script: - mkdir -p ~/.m2 - sed s|NEXUS_PLACEHOLDER|$NEXUS_URL|g; s|NEXUS_USERNAME_PLACEHOLDER|$NEXUS_USERNAME|g; s|NEXUS_PASSWORD_PLACEHOLDER|$NEXUS_PASSWORD|g ci/settings.xml.tpl ~/.m2/settings.xml模板文件里预置好结构变量从GitLab CI/CD Variables里动态填充。这样既保证了凭据的安全性又让每个开发者本环境和CI环境保持同构。多镜像仓库配置的隐性收益常被忽略它能让“依赖锁定”成为可能。你在settings.xml里固定了仓库顺序之后CI构建的依赖解析每次都是从同一优先级的库拿货而不是今天命中中央仓库、明天命中镜像源的后端降低了“构建可复现性”被破坏的概率。5. 常见问题与排查技巧实录5.1 docker login成功但docker push总是401或403这是我们在切换Harbor之后遇到频率最高的问题。我梳理了一下基本就是三种情况表象可能原因动作push返回401用户名或密码错误Harbor项目不存在检查账号权限确认项目名和镜像路径是否匹配push返回403用户不属于该项目的member项目配额满在Harbor项目成员中加人或删除旧镜像某些标记能push某些不能镜像名称格式不符Harbor的仓库权限规则规范项目名/镜像名映射避免/分隔层级过深还有一种隐蔽情况构建机与Harbor之间存在反向代理或网关代理层缓存了401响应。表现为第一台机器push没问题第二台机器随机401。处理方式是在Nginx的缓存配置中排除$upstream_status401的场景。5.2 流水线构建Docker镜像时缓存失效导致构建缓慢很多团队用docker build做镜像构建每次从头执行。那是因为没有利用BuildKit的层缓存。要解决这个不是靠镜像仓库而是优化构建步骤的顺序。Dockerfile里依赖安装层的指令尽量往前放应用代码复制层往后放这样只要依赖文件不变中间层缓存都能命中。启用BuildKit也很简单在CI里设置环境变量variables: DOCKER_BUILDKIT: 1然后配合docker buildx做多阶段构建和缓存导出效果更明显。构建机本地也会生成缓存目录如果CI执行环境是新建容器建议在runner配置里挂载一个持久化volume作为docker的缓存目录避免每次构建清空一切。5.3 镜像仓库占用空间暴涨的清理策略Harbor默认允许同一镜像累积多个tag时间一长仓库的占用空间快速上涨。我见过一个团队因此被磁盘打满导致所有CI推送直接失败。这属于规划期没定义回收策略的典型反弹。Harbor自带的清理策略可以按时间或按保留数量自动清理策略类型按天数保留比如保留最近90天。策略类型按数量保留比如每个仓库保留最近30个tag。也可以设置“无tag”的镜像清理避免重复构建留下孤儿镜像。不过这只是控制未来失控已经占满的情况需要手动触发垃圾回收。Harbor界面里可以提供Garbage Collection操作它就是清理未被任何manifest引用的blob层。执行GC前要停止仓库的写入操作所以选业务低峰期执行。还有一个细节你要知道镜像的层blob是共享的多个镜像如果共用层磁盘不会重复占用GC回收的是没有镜像引用的孤层。有些管理员不知道这一点手动删了某个镜像但磁盘空间没降其实就是层仍然被其他镜像引用着这是正常现象。5.4 多机房或混合云场景下镜像同步复制当你的团队跨地域协作或者公有云和自建机房并存时镜像仓库的同步问题会逐渐凸显。核心思路是采用“主从复制”而非“双活”在主站点配置复制规则推送到Harbor的镜像自动复制到从仓库。从仓库通常是只读的供远端集群拉取。复制规则里有一个关键参数叫覆盖模式。覆盖会同步内容变化容易覆盖掉远端环境经过热修复后的镜像不覆盖会在同名镜像存在时跳过适合保护已部署制品。我用的是“不覆盖”模式配合从站点的保留策略避免远端生产环境的镜像被意外改动。混合云场景下从站点通常选择云厂商的容器镜像服务比如阿里云ACR这样远端K8s集群拉取镜像走内网速度快且不产生公网流量费。Harbor到ACR之间复制时Registry类型选择“Aliyun ACR”填入对应的同步账号与地域Endpoint即可。6. 一些真实的优化心得整套体系搭建和运行一段时间以后我复盘下来觉得最值钱的经验其实不在某条命令或某个配置而在于把“镜像制品管理”当成工程文化的一部分来建设。比如镜像命名规范应该写进团队的工程文档让它和代码规范同等重要。一个清晰的命名规则像“地址/项目/服务名:环境-提交号”这种一眼就能看出镜像是干嘛的。我见过一个团队把镜像名起成app-new-final-2坦白讲这种名字以后回滚时你根本不知道它对应哪个代码版本。再比如CI/CD变量的管理。不要什么都往代码仓库里塞尤其Harbor密码、kubeconfig这些敏感信息一律通过GitLab的Protected Variables按分支保护。这样即使某个开发分支被恶意提交也无法通过流水线读取到生产环境的密钥。还有一个比较有价值的体验把镜像仓库监控接入告警。Harbor本身有一些基础指标接口磁盘使用率、仓库镜像数量、上传下载流量等等。用Prometheus抓一下再配上Alertmanager的规则磁盘到80%时提前收到通知就能在大规模故障前留出操作缓冲。这个不复杂但对运维体感提升非常明显。如果你只在本地玩一玩那Docker Registry足够了一旦进入多人协作、多环境发布的阶段强烈建议直接上Harbor。整套成本也就是一台低配服务器加上几小时的配置时间但它能换来的是稳定的构建链路和清晰可追溯的制品管理体系。
