1. 从一条 docker pull 命令说起仓库到底在解决什么问题如果你已经玩过一阵子 docker大概率有过这种经历本地镜像不够用了一条docker pull nginx:latest就把镜像从远程拉下来自己改了 Dockerfile 构建出新镜像想发给同事要么导出 tar 包传来传去要么推到某个公共平台让别人再拉。这套流程在单机或三五台机器的时候问题不大一旦机器数量上来、环境变得正式缺少一个统一镜像仓库的痛点就特别明显。我第一次意识到这个问题是在帮团队搭测试环境的时候。几个开发各自打包镜像靠微信传 tar 包传到后来都不知道哪个包对应哪个版本集群里镜像标签五花八门回滚的时候根本分不清到底部署的是哪次构建。后来我把镜像统一推到一台内网服务器上所有机器从那儿拉取问题立刻缓解——这就是仓库的威力。本篇是这个 docker 容器系列教程的第三篇专门讲仓库这一层重点说清楚三样东西Docker Hub、私有 Registry、企业级 Harbor。Docker 镜像仓库说白了就是一个“镜像的代码托管平台”。GitHub 管的是源码镜像仓库管的是构建好的成品镜像。机器上执行docker pull、docker push、docker run底层都在跟仓库打交道。你不理解仓库的运作机制很多镜像拉不下来、推不上去、内网部署慢的问题就永远只能靠运气解决。这篇文章适合所有已经能熟练使用 docker run、docker build但对“镜像从哪来、往哪存、团队怎么共享”还一知半解的同学。我会把三种仓库方案的原理、部署方式和实操坑一次讲清楚照着做就能在自己的环境里跑起来。2. 三种仓库三种定位先明白选型逻辑再动手2.1 Docker Hub公共仓库的“默认选项”Docker Hub 是 Docker 官方维护的公共镜像仓库默认情况下所有 docker 命令行工具都会从它拉取镜像。你用docker pull nginx、docker pull mysql:8.0拉到的镜像源头就在这里。它的角色有点像应用商店或者 GitHub 里的公共代码库全球开发者把构建好的镜像推上去其他人直接拉下来用省去自己构建的时间和带宽。Docker Hub 同时支持匿名拉取和登录后推送。匿名拉取就是你不登录、不配置任何认证信息直接 pull 公共镜像这是最最常见的操作。要推送自己的镜像需要注册一个 Docker Hub 账号在命令行执行docker login然后给本地镜像打上你的用户名/镜像名:标签的 tag再执行docker push。不过实际用下来你会发现几个问题。第一公共仓库没有私有性默认推上去的镜像全世界都能看到虽然 Hub 也支持创建 Private Repository但免费账号的私有仓库数量有限。第二国内网络访问 Docker Hub 的速度经常不稳定尤其是拉取比较大的基础镜像时经常出现超时、中断这个我在后面配置镜像加速的章节会细讲。第三企业内网环境往往跟外网隔离拉公共仓库不现实。所以 Docker Hub 适合个人学习、原型验证、以及公开的基础镜像获取不适合作为团队或生产的唯一依赖。2.2 Docker Registry镜像仓库的“极简内核”如果说 Docker Hub 是完整的“商业产品”那 Docker Registry 就是它的“技术内核”。Registry 是 Docker 官方推出的开源项目专门用于存储和分发镜像Docker Hub 底层跑的就是 Registry只是外面包了一层 Web 界面、用户体系、计费等业务功能。你自己在内网部署一个 Registry就等于有了一套最小可用的私有镜像仓库。Registry 的典型部署方式极其简单官方提供了registry:2镜像一条docker run就能把仓库跑起来。默认监听 5000 端口数据存储在容器的/var/lib/registry目录里。你没有 Web 管理界面没有用户登录没有权限控制甚至没有容量配额提醒——它就是一个纯粹的、高性能的镜像存取服务。别小看这个“极简”很多小团队的内网镜像仓库就是从 Registry 起步的。配合 Nginx 做一层反向代理和 HTTPS 加密再手动加一点脚本做定期清理完全能支撑几十个人的日常使用。Registry 的优势是轻量、稳定、资源占用小、没有任何多余功能适合对“够用就行”有明确认知、不想折腾运维系统的场景。不过 Registry 的短板也很突出没有图形化管理界面团队里的人只能靠命令行操作默认权限控制近乎为零谁拿到地址谁就能随意 push 覆盖镜像这在多人协作中很容易出事故没有镜像回收机制删了 tag 磁盘空间也不会自动释放。当你的项目发展到需要给不同角色分配不同权限、需要审计谁动过哪个镜像、需要界面化管理时就要考虑更完整的方案了。2.3 Harbor企业级私有仓库的“全家桶”Harbor 是由 VMware 开源的企业级容器镜像仓库项目它并不是把 Registry 扔掉重写而是在 Registry 的基础上做了一层功能增强自带 Web 管理界面、基于项目的权限控制RBAC、镜像复制同步、漏洞扫描、审计日志、回收站机制、配置备份恢复等等。你可以把 Harbor 理解成“企业版的 Docker Hub 私有化部署方案”。Harbor 底层仍然使用 Docker Registry 来存取镜像但前面罩了一层自己开发的 API 服务和 Web 界面同时集成了 PostgreSQL 存储元数据、Redis 做缓存、Nginx 做入口代理。整套服务通常以 docker compose 的方式一次性拉起装完之后你在浏览器里访问一个管理后台创建项目、添加用户、分配权限、查看镜像列表全部可视化操作学习成本一下子比纯 Registry 低了很多。Harbor 最实用的几个功能我要单独拎出来说。项目级隔离很关键你可以把“前端组”“后端组”“算法组”对应到不同的项目每个项目单独控制谁能拉取、谁能推送避免误操作覆盖别人的镜像。镜像复制功能可以把镜像从一个 Harbor 实例同步到另一个这对两地多机房部署、以及在网络隔离环境下做镜像中转非常有用。漏洞扫描会定期检查镜像里的已知安全漏洞虽然没法替代专业安全工具但在日常自查中能帮你挡住不少明显的问题。付出更多功能的同时Harbor 的系统复杂度也上来了。配置项很多部署文档也长第一次装容易在初始化配置上踩坑。我后面会专门讲一套安装流程和常见报错确保你能一次跑通。2.4 三种方案横向对比与选型建议维度Docker HubRegistryHarbor部署难度无需部署注册即可用一条命令启动中等需配置 yml 文件私有性私有仓库数量受限完全私有完全私有支持项目隔离Web 界面有但管理的不是自己的实例无有功能丰富用户与权限简单按账号区分无RBAC 角色权限控制镜像复制同步不支持需自建方案原生支持资源占用无低中高多服务常驻适用场景个人学习、公开基础镜像小型团队内网企业级、多人协作选型其实不复杂。个人电脑上学习直接用 Docker Hub配好镜像加速即可。团队规模在十人以内、对权限管理没有硬性要求先部署一个 Registry 完全够用。等人数上来了、需要不同角色协作、需要审计和同步能力直接上 Harbor。没有必须从 Registry 迁移到 Harbor 的强制性理由按实际需求来。3. Docker Hub 实操细节与镜像加速配置3.1 拉取、标签与推送的基础操作围绕 Docker Hub 的核心操作只有四个拉取、打标签、推送、登录。拉取最简单直接docker pull 镜像名:标签。这里的镜像名前可以加上命名空间比如library/nginx表示官方仓库里的 nginx默认不写命名空间时docker 会补上library/。企业或个人的镜像则必须带用户名前缀比如你的用户名/my-app:1.0这是 Docker Hub 区分镜像归属的约定。推送自己构建的镜像基本步骤是先给本地镜像打上带用户名的 tag再执行docker push。比如你本地构建了一个镜像叫my-app:latest直接推是推不上去的Docker Hub 不认这个名字。你需要执行docker tag my-app:latest yourname/my-app:latest然后docker push yourname/my-app:latest。第一次推送前必须docker login输入 Docker Hub 的用户名和密码凭证会保存在本机后续推送不用重复输入。打标签这个动作看似简单实际很多新手会忽略它在整个发布流程中的作用。标签既承担了镜像版本的标识功能也承担了环境归属的标识功能。我见过不少团队喜欢用latest标签省事但后果是根本无法追溯当前运行的镜像对应哪一次代码提交。到后面你发现线上出问题、想回退到上一个版本直接傻眼。这里我强烈建议在实际项目里给每个镜像打清晰的版本标签比如v1.2.3、20250115-build001让 tag 既反映语义化版本又带上构建时间信息。3.2 国内网络拉取太慢的解决方案配置镜像加速器Docker Hub 服务器在境外国内直连拉取镜像经常出现超时、走不动的情况。这不是 docker 本身的问题而是网络链路的现实约束。应用商店下载应用时会自动选择最近的 CDNDocker 默认的镜像源却固定指向 Docker Hub 官方地址所以在国内环境下给 docker 配置一个可用的镜像加速器是最常见的做法。镜像加速器的原理是它作为 Docker Hub 的缓存代理提前把常用镜像同步到国内节点你拉镜像时实际从加速器节点获取链路短了速度自然快。目前国内各大云计算厂商基本都提供容器镜像加速服务常见的有阿里云容器镜像服务、腾讯云、华为云等。申请方式大同小异注册账号在控制台的容器镜像服务页面里找到“镜像加速器”会给你一个形如https://xxxx.mirror.aliyuncs.com的专属地址。拿到地址后编辑/etc/docker/daemon.jsonWindows 下 Docker Desktop 在 Settings 里的 Docker Engine 页面编辑加入registry-mirrors配置重启 docker 服务。配置格式如下{ registry-mirrors: [ https://你的专属加速地址.mirror.aliyuncs.com ] }Linux 下执行sudo systemctl daemon-reload sudo systemctl restart docker使配置生效Windows 下点击 Apply Restart 即可。配置完成后执行docker info在输出里能看到Registry Mirrors一项说明加速已生效。需要坦白提醒一句加速器不是万能的。它只对公共镜像生效你自己构建后推送到 Docker Hub 的私有镜像不会因此变快而且加速器也存在时效性部分免费加速地址过一段时间可能不可用。所以在配置完之后建议先拉一个常见镜像比如docker pull alpine:latest实测一下速度确认没问题再投入使用。另外提醒一点配置加速器只是优化网络链路的手段之一如果公司内网有代理或有更复杂的网络策略还需要结合代理配置或者干脆走私有仓库方案这个要根据你的实际环境来调整。3.3 离线环境下的镜像导入导出有些环境没有任何外网连接连加速器都用不了。此时想用 Docker Hub 或其他仓库里的镜像就得想办法先在能联网的机器上把镜像保存成文件再拷贝进内网。docker save和docker load这套命令就是干这个事的。在有网机器上先拉取镜像然后用docker save -o nginx.tar nginx:latest把镜像导出为 tar 文件把 tar 文件拷贝到内网机器执行docker load -i nginx.tar即可导入。导出导入的速度取决于镜像大小和存储介质基础镜像一般几十兆到几百兆实测用 U 盘或者内网共享目录拷贝都比较方便。这种方法适合临时的、小批量的镜像迁移。如果内网机器很多后期还有持续拉取镜像的需求那靠 U 盘拷来拷去会累死运维正确解法就是部署一套内网私有仓库在内网里统一管理镜像。这也是为什么我强烈建议任何正式一点的环境都尽早搭建私有仓库。4. 私有 Registry 的快速搭建与日常使用4.1 一条命令启动你的第一个私有仓库用 Registry 搭一个私有镜像仓库流程简单到让人怀疑是不是漏了什么。只要服务器上装了 docker执行下面这条命令就能启动docker run -d \ --name registry \ -p 5000:5000 \ -v /opt/registry-data:/var/lib/registry \ --restartalways \ registry:2-d表示后台运行--name指定容器名-p 5000:5000把容器的 5000 端口映射到宿主机-v /opt/registry-data:/var/lib/registry把镜像数据持久化到宿主机目录--restartalways保证服务器重启后仓库自动恢复。registry:2 镜像是 Registry 当前的主流版本功能和稳定性都比 registry:2.7 之前的版本完善很多直接用这个标签没问题。启动后用docker ps确认容器在运行状态然后找一台能访问这台服务器的机器测试拉取。假设服务器 IP 是 192.168.1.100执行docker pull 192.168.1.100:5000/nginx:latest如果机器之前没拉过 nginx会看到 docker 尝试从该地址拉取镜像的日志。注意这台测试机器如果想要推送到仓库需要先把本地镜像打上192.168.1.100:5000/nginx:latest这样的完整地址标签再执行docker push。到这里你已经拥有一个功能完整的私有仓库了含持久化、支持跨机器推送和拉取。很多教程到这里就结束但实际生产环境里通常会挂一层 Nginx 做 HTTPS把镜像存到对象存储或云盘这些优化可以在后续需要时逐步加上。4.2 连不上、推不上的常见原因insecure-registries 配置第一次搭 Registry 的人大概率会撞上一个经典报错http: server gave HTTP response to HTTPS client原因很简单docker 客户端默认以 HTTPS 方式访问仓库地址而你搭的私有仓库是纯 HTTP 的没有配置证书客户端一上来就被拒绝。解决方式有两种给仓库配 HTTPS 证书或者在 docker 客户端把该仓库地址标记为“允许非加密访问”。后一种方式是本地和测试环境最省事的方案。编辑 docker 配置文件/etc/docker/daemon.json加入insecure-registries配置例如{ insecure-registries: [ 192.168.1.100:5000 ] }改完重启 docker。如果客户端机器也要推送和拉取那台机器的 docker 也要同步配置。Windows 下 Docker Desktop 用户在 Settings 的 Docker Engine 页面里相同位置配置即可。配置完再执行docker push就不会再报 HTTPS 的错误了。看到这里你可能会问为什么 Registry 不能自动适配 HTTP/HTTPS因为 docker 客户端的安全策略是“默认信任加密连接”对未加密的仓库地址必须由管理员显式声明信任否则就拒绝通信。这是防中间人攻击的一种设计属于刻意为之。真正生产环境里正规做法还是给仓库配 HTTPS 证书让客户端走加密链路insecure-registries更适合内网测试环境用。4.3 数据备份、清理与容量管理Registry 的所有镜像数据都保存在启动时挂载的宿主机目录下比如/opt/registry-data。只要这个目录还在容器删了、机器重启了仓库数据都不会丢。所以备份的核心就是备份这个目录最简单的做法是定期用 tar 打包或者直接对挂载目录做文件系统快照。Registry 的镜像删除比较特殊。你执行docker rmi删除的是本地机器的镜像跟仓库没有关系。如果想删除仓库里的镜像Registry 提供了 REST API比如DELETE /v2/name/manifests/digest但删除后镜像文件并不会立即从磁盘上消失因为 Registry 采用了引用计数机制只有所有引用都被删除后底层的数据块才会在 GC 时被清理。实际维护中我发现Registry 长期使用后磁盘占用膨胀得很明显尤其是频繁推送新版本的团队。官方提供了垃圾回收命令在容器里执行bin/registry garbage-collect /etc/docker/registry/config.yml可以清理掉无引用的镜像数据。但执行 GC 时建议先停止推送操作在低峰期执行否则可能出现正在上传的镜像数据被误清理的情况。更好的方案是直接放弃手动清理等数据量大了升级到 Harbor它有更加完善的回收管理和存储配额控制。5. Harbor 完整部署从下载安装包到推拉镜像5.1 环境准备与安装包选择Harbor 的部署比起 Registry 要复杂一个档次但它带来的功能和体验提升也值回这个复杂度。部署前先确认环境符合要求Linux 服务器一台Docker 和 Docker Compose 插件已安装至少 2 核 CPU、4GB 内存实测 2GB 也能跑但会卡磁盘剩余空间足够存放镜像。Harbor 的发布包分为在线安装包和离线安装包两种。在线安装包体积小但安装过程中会从网络拉取 Harbor 依赖的镜像网络不好时容易失败。离线安装包体积大几百 MB 到 1GB但包含了所有需要的容器镜像安装过程不依赖外网推荐在无法稳定访问外网的生产环境使用。去 Harbor 的 GitHub Releases 页面下载对应版本的离线安装包即可。这里明确说一下Harbor 官方发布了 Docker Compose 部署的完整流程本质上还是一套容器编排。整个 Harbor 服务包含多个容器组件nginx 入口、Harbor 核心 API 服务、注册器管理、数据库PostgreSQL、缓存Redis、以及底层负责存储镜像的 registry 容器。安装脚本install.sh会把它们全部编排启动你不需要逐个手动起容器。5.2 修改 harbor.yml容易踩坑的配置环节hood下载好安装包后解压并进入目录你需要先做一件事复制一份配置文件模板。默认情况下目录里只有harbor.yml.tmpl你需要执行cp harbor.yml.tmpl harbor.yml然后编辑harbor.yml。配置项看着很多但初次部署真正需要改的只有几个。hostname必须改成你的服务器 IP 或域名这个配置项决定了访问 Harbor 的地址写错后面就访问不上。http.port默认 80如果 80 端口被占用改成其他端口比如 8080那访问地址就是http://你的IP:8080。harbor_admin_password是管理员初始密码默认是 Harbor12345建议改成复杂密码。其他配置项比如数据库密码、证书路径初次部署用默认值即可。改配置过程中最容易犯的错误是 YAML 缩进格式不对。Harbor 在安装前会做配置校验如果 yml 文件格式有问题会直接报harbor happened in config validation这样比较抽象的提示而不会告诉你是哪一行出问题。我的经验是改动配置前先备份一份模板改完后可以用在线的 YAML 校验工具验证一下格式缩进必须是空格不允许用 Tab。如果碰到配置校验报错优先检查 hostname 是否格式正确、端口是否与其他服务冲突、以及每行缩进是否保持一致。另外一个容易忽略的坑是 hostname 不能带http://或https://前缀直接写 IP 或域名即可带上前缀会触发配置校验失败。5.3 执行安装脚本并启动整套服务配置完成后在安装包目录里执行sudo ./install.sh。脚本会先检查 Docker 和 Docker Compose 环境然后加载离线镜像、生成 docker-compose.yml、启动所有容器。整个安装过程受机器性能影响一般几分钟到十几分钟不等。安装完用docker ps查看如果能看到harbor-core、harbor-registry、harbor-db、harbor-redis、harbor-nginx等多个容器都处于 Up 状态说明部署成功。接着浏览器访问http://你的IP:80就会进入 Harbor 的 Web 登录页面使用 admin 账号和刚才在 yml 里配置的密码登录。首次登录后建议立即修改密码并创建普通用户账号日常操作不要都用 admin这样管理上更规范也更安全。登录后的操作流程一般是在“项目”模块里新建项目填写项目名称比如 dev-frontend可见性选择私有然后在“成员管理”里把团队成员添加进来分配角色项目管理员、开发者、访客等最后在客户端机器上执行docker login http://你的IP:80输入刚才创建的用户密码登录成功后即可向该项目推送镜像。推送到 Harbor 的镜像地址格式是你的IP:80/项目名/镜像名:标签。比如项目名是dev-frontend本机构建了镜像frontend:1.0先docker tag frontend:1.0 你的IP:80/dev-frontend/frontend:1.0再docker push 你的IP:80/dev-frontend/frontend:1.0。拉取其他机器上的镜像时对应执行docker pull 你的IP:80/dev-frontend/frontend:1.0。整个过程在 Harbor 的 Web 界面上都能实时看到镜像列表更新。5.4 用 docker compose 快速拉起 Harbor 的方式是否可靠很多教程提到用docker compose up -d直接拉起 Harbor这确实是一条可行的路径因为它本质上就是安装脚本内部做的事情。安装脚本会生成一份docker-compose.yml里面已经定义好所有服务的启动参数、端口映射和内部网络。你完全可以自己执行docker compose up -d来启动 Harbor这在需要个性化调参的场景下很有用比如你要修改某个服务的内存限制或增加日志配置。不过我不建议完全脱离官方安装脚本。install.sh除了启动容器还会做配置检查、证书生成、数据目录初始化这些事情这些环节用纯 compose 很容易遗漏导致后续某些功能异常但表面看起来一切正常。更稳妥的做法是先用官方脚本完成部署确认服务完全正常之后再按需调整 compose 文件。想快速尝鲜、临时起一个 Harbor 测试环境用 compose 没毛病但生产环境务必按规范流程走。6. 常见问题与故障排查实录6.1 Harbor 安装报错happened in config validation的排查套路这个错误可能是 Harbor 新手遇到最多的一个问题。安装脚本在解析harbor.yml时发现配置不合法就会直接抛出这条提示但不会详细告诉你哪里不合法。根据我帮人排查的经验80% 的情况出在这几个点第一hostname配置有问题。写成http://192.168.1.100、https://192.168.1.100、后面带端口号或者包含空格都会让校验失败。正确的写法就是裸 IP 或裸域名比如192.168.1.100或harbor.example.com。第二YAML 缩进错误。比如原本要缩进两层的配置只缩进了一层或者混入了 Tab。整个 yml 文件必须统一用空格缩进。第三端口冲突。http.port配置的 80 端口被宿主机上其他进程占用Harbor 在配置初始化阶段会检测到并且拒绝继续。第四配置文件里残留了注释符号的误复制比如把#注释行当成有效配置解析也会报错。排查思路是先从最简单的点开始复制一份干净的harbor.yml.tmpl只改 hostname 和管理员密码两个字段其他保持默认确认能正常安装不行再去检查端口占用用netstat -tlnp | grep :80看看 80 端口是否被占用再不行就把配置文件拿到在线 YAML 格式校验工具里过一遍看格式是否有问题。这套排查顺序基本能覆盖所有情况。6.2 客户端拉取镜像报could not reach the hub ... network is unreachable的解决思路could not reach the hub ([errno 101] network is unreachable). using cached c这类报错常见于拉取镜像时机器无法访问目标仓库地址。原因一般是网络配置问题内网环境没有配置外网访问权限、防火墙拦截了出站流量、或者机器的路由设置有问题。报错里的errno 101是 Linux 系统层面的“网络不可达”错误码说明客户端根本就没能建立到服务器 IP 的网络连接。排查步骤很简单。第一步先确认你具体要访问的是哪个仓库地址。如果是 Docker Hub 的官方地址那就要看这台机器是否有外网访问能力试试ping registry-1.docker.io如果 ping 不通说明链路不通如果有代理上网需要给 docker 配置代理。第二步如果拉的是内网私有仓库检查地址是否写对、对方的服务是否在运行、以及两台机器之间的网络是否连通可以在客户端机器上telnet 你的IP 5000测一下端口。第三步确认网络没问题后重试如果仍然超时再考虑配置合法的镜像加速或改用其他可达的仓库地址。这里要特意提醒一句千万不要各种地方看到教程就盲目改网络代理配置一定要先判断你的实际网络拓扑。docker 的网络访问方式取决于它运行的主机网络环境同一套配置在这台机器能用换到另一台可能直接把网络搞断。处理这类问题最稳妥的方式是从链路层逐层排查而不是靠猜。6.3 私有仓库推送镜像报http: server gave HTTP response to HTTPS client前文已经解释过这个报错的根因是客户端默认用 HTTPS 访问而私有仓库是 HTTP 协议。解决方式有两种一是给仓库配 HTTPS 证书适合生产环境二是在客户端配置insecure-registries适合测试环境。一部分读者还会遇到一个变种报错x509: certificate signed by unknown authority这个是因为你给仓库配了自签名证书但客户端不信任这个证书。解决办法是把自签名证书加入到客户端的信任证书列表或者也通过insecure-registries来绕过证书校验。在生产环境我建议优先配置正规的 HTTPS 证书和可信 CA这能避免很多安全风险。如果只是为了快速联调insecure-registries确实省事但你一定要清楚它意味着镜像传输是不加密的不适合在公网环境使用。6.4 Harbor Web 界面能打开但客户端 docker login 失败现象通常是浏览器访问http://你的IP:80正常但执行docker login http://你的IP:80时报unauthorized: authentication required或超时。网上很多资料会把问题归因于密码错误实际上更常见的原因是 harbor.yml 里配置了 https但客户端用 http 访问或者 docker 客户端没有正确识别 Harbor 使用的端口。docker login的地址语法会决定它使用的协议如果端口不是 443docker 会默认走 HTTP但对 Harbor 来说你需要在地址中显式带上协议。以 80 端口为例正确写法是docker login http://你的IP:80直接写docker login 你的IP:80有时会被 docker 尝试以 HTTPS 访问然后握手失败。另一个常见问题是密码包含特殊字符导致终端解析错误建议先在本地执行echo 复杂密码确认能正常输出再复制进 docker login 交互里。6.5 镜像磁盘空间被占满Harbor 显示只读或推送失败Harbor 的镜像存储默认在数据目录下长期使用后磁盘占用会持续增长。当磁盘占用率达到一定阈值Harbor 的存储驱动可能会进入只读保护模式此时 push 镜像会失败。解决思路分两步先释放磁盘空间再保证未来有足够的增长空间。释放空间最直接的方式是到 Harbor Web 界面的项目的“镜像仓库”里删除旧的镜像 tag 和 artifact然后执行垃圾回收。Harbor 的垃圾回收功能比原生 Registry 友好很多地址在“系统管理 → 垃圾回收”可以手动触发也可以设置定时任务。如果磁盘空间已经满了导致垃圾回收也失败需要先手动清理一些其他大文件腾出最低限度空间再操作。长期规划上建议把 Harbor 的数据目录挂载到大容量磁盘或者接入对象存储这个可以后续再细化。7. 给还在纠结的你几点个人建议回到开头的问题我现在到底该用哪种仓库方案我的建议很直接个人学习阶段Docker Hub 加镜像加速完全够用别在这个阶段折腾私有仓库先把 docker 的基本操作练熟。当你开始跟两三个同事协作经常互相拷 tar 包、在群里发镜像压缩文件的时候就是部署私有仓库的信号此时先上一个 Registry一个小时就能搞定立刻解决协作痛点。当团队人数到了十几个不同项目之间开始需要隔离有人误删了别人的镜像部署文档和安全规范开始被要求那就别犹豫直接上 Harbor把权限体系、复制规则、定期 GC 都配好一劳永逸。还有一个小细节我特别想强调无论用哪种仓库方案都要养成给镜像打明确版本标签的习惯。我见过太多团队在镜像管理上栽跟头不是仓库技术选型的问题而是latest满天飞导致的混乱。仓库本身只是存储和分发的工具真正决定镜像管理是否有序的还是人的操作习惯。Harbor 的部署过程虽然比 Registry 复杂一些但只要配置文件的坑避开了安装脚本跑完基本不会有问题。后续的维护重点其实在数据备份和容量管理上前者靠定期的目录备份后者靠日常的垃圾回收和项目规范。把这套东西跑起来后你会发现团队协作效率会有明显的提升——这也是仓库这一层在整个 docker 容器技术栈里存在的意义。 Docker镜像仓库完全指南：从Docker Hub到Harbor私有仓库实践
1. 从一条 docker pull 命令说起仓库到底在解决什么问题如果你已经玩过一阵子 docker大概率有过这种经历本地镜像不够用了一条docker pull nginx:latest就把镜像从远程拉下来自己改了 Dockerfile 构建出新镜像想发给同事要么导出 tar 包传来传去要么推到某个公共平台让别人再拉。这套流程在单机或三五台机器的时候问题不大一旦机器数量上来、环境变得正式缺少一个统一镜像仓库的痛点就特别明显。我第一次意识到这个问题是在帮团队搭测试环境的时候。几个开发各自打包镜像靠微信传 tar 包传到后来都不知道哪个包对应哪个版本集群里镜像标签五花八门回滚的时候根本分不清到底部署的是哪次构建。后来我把镜像统一推到一台内网服务器上所有机器从那儿拉取问题立刻缓解——这就是仓库的威力。本篇是这个 docker 容器系列教程的第三篇专门讲仓库这一层重点说清楚三样东西Docker Hub、私有 Registry、企业级 Harbor。Docker 镜像仓库说白了就是一个“镜像的代码托管平台”。GitHub 管的是源码镜像仓库管的是构建好的成品镜像。机器上执行docker pull、docker push、docker run底层都在跟仓库打交道。你不理解仓库的运作机制很多镜像拉不下来、推不上去、内网部署慢的问题就永远只能靠运气解决。这篇文章适合所有已经能熟练使用 docker run、docker build但对“镜像从哪来、往哪存、团队怎么共享”还一知半解的同学。我会把三种仓库方案的原理、部署方式和实操坑一次讲清楚照着做就能在自己的环境里跑起来。2. 三种仓库三种定位先明白选型逻辑再动手2.1 Docker Hub公共仓库的“默认选项”Docker Hub 是 Docker 官方维护的公共镜像仓库默认情况下所有 docker 命令行工具都会从它拉取镜像。你用docker pull nginx、docker pull mysql:8.0拉到的镜像源头就在这里。它的角色有点像应用商店或者 GitHub 里的公共代码库全球开发者把构建好的镜像推上去其他人直接拉下来用省去自己构建的时间和带宽。Docker Hub 同时支持匿名拉取和登录后推送。匿名拉取就是你不登录、不配置任何认证信息直接 pull 公共镜像这是最最常见的操作。要推送自己的镜像需要注册一个 Docker Hub 账号在命令行执行docker login然后给本地镜像打上你的用户名/镜像名:标签的 tag再执行docker push。不过实际用下来你会发现几个问题。第一公共仓库没有私有性默认推上去的镜像全世界都能看到虽然 Hub 也支持创建 Private Repository但免费账号的私有仓库数量有限。第二国内网络访问 Docker Hub 的速度经常不稳定尤其是拉取比较大的基础镜像时经常出现超时、中断这个我在后面配置镜像加速的章节会细讲。第三企业内网环境往往跟外网隔离拉公共仓库不现实。所以 Docker Hub 适合个人学习、原型验证、以及公开的基础镜像获取不适合作为团队或生产的唯一依赖。2.2 Docker Registry镜像仓库的“极简内核”如果说 Docker Hub 是完整的“商业产品”那 Docker Registry 就是它的“技术内核”。Registry 是 Docker 官方推出的开源项目专门用于存储和分发镜像Docker Hub 底层跑的就是 Registry只是外面包了一层 Web 界面、用户体系、计费等业务功能。你自己在内网部署一个 Registry就等于有了一套最小可用的私有镜像仓库。Registry 的典型部署方式极其简单官方提供了registry:2镜像一条docker run就能把仓库跑起来。默认监听 5000 端口数据存储在容器的/var/lib/registry目录里。你没有 Web 管理界面没有用户登录没有权限控制甚至没有容量配额提醒——它就是一个纯粹的、高性能的镜像存取服务。别小看这个“极简”很多小团队的内网镜像仓库就是从 Registry 起步的。配合 Nginx 做一层反向代理和 HTTPS 加密再手动加一点脚本做定期清理完全能支撑几十个人的日常使用。Registry 的优势是轻量、稳定、资源占用小、没有任何多余功能适合对“够用就行”有明确认知、不想折腾运维系统的场景。不过 Registry 的短板也很突出没有图形化管理界面团队里的人只能靠命令行操作默认权限控制近乎为零谁拿到地址谁就能随意 push 覆盖镜像这在多人协作中很容易出事故没有镜像回收机制删了 tag 磁盘空间也不会自动释放。当你的项目发展到需要给不同角色分配不同权限、需要审计谁动过哪个镜像、需要界面化管理时就要考虑更完整的方案了。2.3 Harbor企业级私有仓库的“全家桶”Harbor 是由 VMware 开源的企业级容器镜像仓库项目它并不是把 Registry 扔掉重写而是在 Registry 的基础上做了一层功能增强自带 Web 管理界面、基于项目的权限控制RBAC、镜像复制同步、漏洞扫描、审计日志、回收站机制、配置备份恢复等等。你可以把 Harbor 理解成“企业版的 Docker Hub 私有化部署方案”。Harbor 底层仍然使用 Docker Registry 来存取镜像但前面罩了一层自己开发的 API 服务和 Web 界面同时集成了 PostgreSQL 存储元数据、Redis 做缓存、Nginx 做入口代理。整套服务通常以 docker compose 的方式一次性拉起装完之后你在浏览器里访问一个管理后台创建项目、添加用户、分配权限、查看镜像列表全部可视化操作学习成本一下子比纯 Registry 低了很多。Harbor 最实用的几个功能我要单独拎出来说。项目级隔离很关键你可以把“前端组”“后端组”“算法组”对应到不同的项目每个项目单独控制谁能拉取、谁能推送避免误操作覆盖别人的镜像。镜像复制功能可以把镜像从一个 Harbor 实例同步到另一个这对两地多机房部署、以及在网络隔离环境下做镜像中转非常有用。漏洞扫描会定期检查镜像里的已知安全漏洞虽然没法替代专业安全工具但在日常自查中能帮你挡住不少明显的问题。付出更多功能的同时Harbor 的系统复杂度也上来了。配置项很多部署文档也长第一次装容易在初始化配置上踩坑。我后面会专门讲一套安装流程和常见报错确保你能一次跑通。2.4 三种方案横向对比与选型建议维度Docker HubRegistryHarbor部署难度无需部署注册即可用一条命令启动中等需配置 yml 文件私有性私有仓库数量受限完全私有完全私有支持项目隔离Web 界面有但管理的不是自己的实例无有功能丰富用户与权限简单按账号区分无RBAC 角色权限控制镜像复制同步不支持需自建方案原生支持资源占用无低中高多服务常驻适用场景个人学习、公开基础镜像小型团队内网企业级、多人协作选型其实不复杂。个人电脑上学习直接用 Docker Hub配好镜像加速即可。团队规模在十人以内、对权限管理没有硬性要求先部署一个 Registry 完全够用。等人数上来了、需要不同角色协作、需要审计和同步能力直接上 Harbor。没有必须从 Registry 迁移到 Harbor 的强制性理由按实际需求来。3. Docker Hub 实操细节与镜像加速配置3.1 拉取、标签与推送的基础操作围绕 Docker Hub 的核心操作只有四个拉取、打标签、推送、登录。拉取最简单直接docker pull 镜像名:标签。这里的镜像名前可以加上命名空间比如library/nginx表示官方仓库里的 nginx默认不写命名空间时docker 会补上library/。企业或个人的镜像则必须带用户名前缀比如你的用户名/my-app:1.0这是 Docker Hub 区分镜像归属的约定。推送自己构建的镜像基本步骤是先给本地镜像打上带用户名的 tag再执行docker push。比如你本地构建了一个镜像叫my-app:latest直接推是推不上去的Docker Hub 不认这个名字。你需要执行docker tag my-app:latest yourname/my-app:latest然后docker push yourname/my-app:latest。第一次推送前必须docker login输入 Docker Hub 的用户名和密码凭证会保存在本机后续推送不用重复输入。打标签这个动作看似简单实际很多新手会忽略它在整个发布流程中的作用。标签既承担了镜像版本的标识功能也承担了环境归属的标识功能。我见过不少团队喜欢用latest标签省事但后果是根本无法追溯当前运行的镜像对应哪一次代码提交。到后面你发现线上出问题、想回退到上一个版本直接傻眼。这里我强烈建议在实际项目里给每个镜像打清晰的版本标签比如v1.2.3、20250115-build001让 tag 既反映语义化版本又带上构建时间信息。3.2 国内网络拉取太慢的解决方案配置镜像加速器Docker Hub 服务器在境外国内直连拉取镜像经常出现超时、走不动的情况。这不是 docker 本身的问题而是网络链路的现实约束。应用商店下载应用时会自动选择最近的 CDNDocker 默认的镜像源却固定指向 Docker Hub 官方地址所以在国内环境下给 docker 配置一个可用的镜像加速器是最常见的做法。镜像加速器的原理是它作为 Docker Hub 的缓存代理提前把常用镜像同步到国内节点你拉镜像时实际从加速器节点获取链路短了速度自然快。目前国内各大云计算厂商基本都提供容器镜像加速服务常见的有阿里云容器镜像服务、腾讯云、华为云等。申请方式大同小异注册账号在控制台的容器镜像服务页面里找到“镜像加速器”会给你一个形如https://xxxx.mirror.aliyuncs.com的专属地址。拿到地址后编辑/etc/docker/daemon.jsonWindows 下 Docker Desktop 在 Settings 里的 Docker Engine 页面编辑加入registry-mirrors配置重启 docker 服务。配置格式如下{ registry-mirrors: [ https://你的专属加速地址.mirror.aliyuncs.com ] }Linux 下执行sudo systemctl daemon-reload sudo systemctl restart docker使配置生效Windows 下点击 Apply Restart 即可。配置完成后执行docker info在输出里能看到Registry Mirrors一项说明加速已生效。需要坦白提醒一句加速器不是万能的。它只对公共镜像生效你自己构建后推送到 Docker Hub 的私有镜像不会因此变快而且加速器也存在时效性部分免费加速地址过一段时间可能不可用。所以在配置完之后建议先拉一个常见镜像比如docker pull alpine:latest实测一下速度确认没问题再投入使用。另外提醒一点配置加速器只是优化网络链路的手段之一如果公司内网有代理或有更复杂的网络策略还需要结合代理配置或者干脆走私有仓库方案这个要根据你的实际环境来调整。3.3 离线环境下的镜像导入导出有些环境没有任何外网连接连加速器都用不了。此时想用 Docker Hub 或其他仓库里的镜像就得想办法先在能联网的机器上把镜像保存成文件再拷贝进内网。docker save和docker load这套命令就是干这个事的。在有网机器上先拉取镜像然后用docker save -o nginx.tar nginx:latest把镜像导出为 tar 文件把 tar 文件拷贝到内网机器执行docker load -i nginx.tar即可导入。导出导入的速度取决于镜像大小和存储介质基础镜像一般几十兆到几百兆实测用 U 盘或者内网共享目录拷贝都比较方便。这种方法适合临时的、小批量的镜像迁移。如果内网机器很多后期还有持续拉取镜像的需求那靠 U 盘拷来拷去会累死运维正确解法就是部署一套内网私有仓库在内网里统一管理镜像。这也是为什么我强烈建议任何正式一点的环境都尽早搭建私有仓库。4. 私有 Registry 的快速搭建与日常使用4.1 一条命令启动你的第一个私有仓库用 Registry 搭一个私有镜像仓库流程简单到让人怀疑是不是漏了什么。只要服务器上装了 docker执行下面这条命令就能启动docker run -d \ --name registry \ -p 5000:5000 \ -v /opt/registry-data:/var/lib/registry \ --restartalways \ registry:2-d表示后台运行--name指定容器名-p 5000:5000把容器的 5000 端口映射到宿主机-v /opt/registry-data:/var/lib/registry把镜像数据持久化到宿主机目录--restartalways保证服务器重启后仓库自动恢复。registry:2 镜像是 Registry 当前的主流版本功能和稳定性都比 registry:2.7 之前的版本完善很多直接用这个标签没问题。启动后用docker ps确认容器在运行状态然后找一台能访问这台服务器的机器测试拉取。假设服务器 IP 是 192.168.1.100执行docker pull 192.168.1.100:5000/nginx:latest如果机器之前没拉过 nginx会看到 docker 尝试从该地址拉取镜像的日志。注意这台测试机器如果想要推送到仓库需要先把本地镜像打上192.168.1.100:5000/nginx:latest这样的完整地址标签再执行docker push。到这里你已经拥有一个功能完整的私有仓库了含持久化、支持跨机器推送和拉取。很多教程到这里就结束但实际生产环境里通常会挂一层 Nginx 做 HTTPS把镜像存到对象存储或云盘这些优化可以在后续需要时逐步加上。4.2 连不上、推不上的常见原因insecure-registries 配置第一次搭 Registry 的人大概率会撞上一个经典报错http: server gave HTTP response to HTTPS client原因很简单docker 客户端默认以 HTTPS 方式访问仓库地址而你搭的私有仓库是纯 HTTP 的没有配置证书客户端一上来就被拒绝。解决方式有两种给仓库配 HTTPS 证书或者在 docker 客户端把该仓库地址标记为“允许非加密访问”。后一种方式是本地和测试环境最省事的方案。编辑 docker 配置文件/etc/docker/daemon.json加入insecure-registries配置例如{ insecure-registries: [ 192.168.1.100:5000 ] }改完重启 docker。如果客户端机器也要推送和拉取那台机器的 docker 也要同步配置。Windows 下 Docker Desktop 用户在 Settings 的 Docker Engine 页面里相同位置配置即可。配置完再执行docker push就不会再报 HTTPS 的错误了。看到这里你可能会问为什么 Registry 不能自动适配 HTTP/HTTPS因为 docker 客户端的安全策略是“默认信任加密连接”对未加密的仓库地址必须由管理员显式声明信任否则就拒绝通信。这是防中间人攻击的一种设计属于刻意为之。真正生产环境里正规做法还是给仓库配 HTTPS 证书让客户端走加密链路insecure-registries更适合内网测试环境用。4.3 数据备份、清理与容量管理Registry 的所有镜像数据都保存在启动时挂载的宿主机目录下比如/opt/registry-data。只要这个目录还在容器删了、机器重启了仓库数据都不会丢。所以备份的核心就是备份这个目录最简单的做法是定期用 tar 打包或者直接对挂载目录做文件系统快照。Registry 的镜像删除比较特殊。你执行docker rmi删除的是本地机器的镜像跟仓库没有关系。如果想删除仓库里的镜像Registry 提供了 REST API比如DELETE /v2/name/manifests/digest但删除后镜像文件并不会立即从磁盘上消失因为 Registry 采用了引用计数机制只有所有引用都被删除后底层的数据块才会在 GC 时被清理。实际维护中我发现Registry 长期使用后磁盘占用膨胀得很明显尤其是频繁推送新版本的团队。官方提供了垃圾回收命令在容器里执行bin/registry garbage-collect /etc/docker/registry/config.yml可以清理掉无引用的镜像数据。但执行 GC 时建议先停止推送操作在低峰期执行否则可能出现正在上传的镜像数据被误清理的情况。更好的方案是直接放弃手动清理等数据量大了升级到 Harbor它有更加完善的回收管理和存储配额控制。5. Harbor 完整部署从下载安装包到推拉镜像5.1 环境准备与安装包选择Harbor 的部署比起 Registry 要复杂一个档次但它带来的功能和体验提升也值回这个复杂度。部署前先确认环境符合要求Linux 服务器一台Docker 和 Docker Compose 插件已安装至少 2 核 CPU、4GB 内存实测 2GB 也能跑但会卡磁盘剩余空间足够存放镜像。Harbor 的发布包分为在线安装包和离线安装包两种。在线安装包体积小但安装过程中会从网络拉取 Harbor 依赖的镜像网络不好时容易失败。离线安装包体积大几百 MB 到 1GB但包含了所有需要的容器镜像安装过程不依赖外网推荐在无法稳定访问外网的生产环境使用。去 Harbor 的 GitHub Releases 页面下载对应版本的离线安装包即可。这里明确说一下Harbor 官方发布了 Docker Compose 部署的完整流程本质上还是一套容器编排。整个 Harbor 服务包含多个容器组件nginx 入口、Harbor 核心 API 服务、注册器管理、数据库PostgreSQL、缓存Redis、以及底层负责存储镜像的 registry 容器。安装脚本install.sh会把它们全部编排启动你不需要逐个手动起容器。5.2 修改 harbor.yml容易踩坑的配置环节hood下载好安装包后解压并进入目录你需要先做一件事复制一份配置文件模板。默认情况下目录里只有harbor.yml.tmpl你需要执行cp harbor.yml.tmpl harbor.yml然后编辑harbor.yml。配置项看着很多但初次部署真正需要改的只有几个。hostname必须改成你的服务器 IP 或域名这个配置项决定了访问 Harbor 的地址写错后面就访问不上。http.port默认 80如果 80 端口被占用改成其他端口比如 8080那访问地址就是http://你的IP:8080。harbor_admin_password是管理员初始密码默认是 Harbor12345建议改成复杂密码。其他配置项比如数据库密码、证书路径初次部署用默认值即可。改配置过程中最容易犯的错误是 YAML 缩进格式不对。Harbor 在安装前会做配置校验如果 yml 文件格式有问题会直接报harbor happened in config validation这样比较抽象的提示而不会告诉你是哪一行出问题。我的经验是改动配置前先备份一份模板改完后可以用在线的 YAML 校验工具验证一下格式缩进必须是空格不允许用 Tab。如果碰到配置校验报错优先检查 hostname 是否格式正确、端口是否与其他服务冲突、以及每行缩进是否保持一致。另外一个容易忽略的坑是 hostname 不能带http://或https://前缀直接写 IP 或域名即可带上前缀会触发配置校验失败。5.3 执行安装脚本并启动整套服务配置完成后在安装包目录里执行sudo ./install.sh。脚本会先检查 Docker 和 Docker Compose 环境然后加载离线镜像、生成 docker-compose.yml、启动所有容器。整个安装过程受机器性能影响一般几分钟到十几分钟不等。安装完用docker ps查看如果能看到harbor-core、harbor-registry、harbor-db、harbor-redis、harbor-nginx等多个容器都处于 Up 状态说明部署成功。接着浏览器访问http://你的IP:80就会进入 Harbor 的 Web 登录页面使用 admin 账号和刚才在 yml 里配置的密码登录。首次登录后建议立即修改密码并创建普通用户账号日常操作不要都用 admin这样管理上更规范也更安全。登录后的操作流程一般是在“项目”模块里新建项目填写项目名称比如 dev-frontend可见性选择私有然后在“成员管理”里把团队成员添加进来分配角色项目管理员、开发者、访客等最后在客户端机器上执行docker login http://你的IP:80输入刚才创建的用户密码登录成功后即可向该项目推送镜像。推送到 Harbor 的镜像地址格式是你的IP:80/项目名/镜像名:标签。比如项目名是dev-frontend本机构建了镜像frontend:1.0先docker tag frontend:1.0 你的IP:80/dev-frontend/frontend:1.0再docker push 你的IP:80/dev-frontend/frontend:1.0。拉取其他机器上的镜像时对应执行docker pull 你的IP:80/dev-frontend/frontend:1.0。整个过程在 Harbor 的 Web 界面上都能实时看到镜像列表更新。5.4 用 docker compose 快速拉起 Harbor 的方式是否可靠很多教程提到用docker compose up -d直接拉起 Harbor这确实是一条可行的路径因为它本质上就是安装脚本内部做的事情。安装脚本会生成一份docker-compose.yml里面已经定义好所有服务的启动参数、端口映射和内部网络。你完全可以自己执行docker compose up -d来启动 Harbor这在需要个性化调参的场景下很有用比如你要修改某个服务的内存限制或增加日志配置。不过我不建议完全脱离官方安装脚本。install.sh除了启动容器还会做配置检查、证书生成、数据目录初始化这些事情这些环节用纯 compose 很容易遗漏导致后续某些功能异常但表面看起来一切正常。更稳妥的做法是先用官方脚本完成部署确认服务完全正常之后再按需调整 compose 文件。想快速尝鲜、临时起一个 Harbor 测试环境用 compose 没毛病但生产环境务必按规范流程走。6. 常见问题与故障排查实录6.1 Harbor 安装报错happened in config validation的排查套路这个错误可能是 Harbor 新手遇到最多的一个问题。安装脚本在解析harbor.yml时发现配置不合法就会直接抛出这条提示但不会详细告诉你哪里不合法。根据我帮人排查的经验80% 的情况出在这几个点第一hostname配置有问题。写成http://192.168.1.100、https://192.168.1.100、后面带端口号或者包含空格都会让校验失败。正确的写法就是裸 IP 或裸域名比如192.168.1.100或harbor.example.com。第二YAML 缩进错误。比如原本要缩进两层的配置只缩进了一层或者混入了 Tab。整个 yml 文件必须统一用空格缩进。第三端口冲突。http.port配置的 80 端口被宿主机上其他进程占用Harbor 在配置初始化阶段会检测到并且拒绝继续。第四配置文件里残留了注释符号的误复制比如把#注释行当成有效配置解析也会报错。排查思路是先从最简单的点开始复制一份干净的harbor.yml.tmpl只改 hostname 和管理员密码两个字段其他保持默认确认能正常安装不行再去检查端口占用用netstat -tlnp | grep :80看看 80 端口是否被占用再不行就把配置文件拿到在线 YAML 格式校验工具里过一遍看格式是否有问题。这套排查顺序基本能覆盖所有情况。6.2 客户端拉取镜像报could not reach the hub ... network is unreachable的解决思路could not reach the hub ([errno 101] network is unreachable). using cached c这类报错常见于拉取镜像时机器无法访问目标仓库地址。原因一般是网络配置问题内网环境没有配置外网访问权限、防火墙拦截了出站流量、或者机器的路由设置有问题。报错里的errno 101是 Linux 系统层面的“网络不可达”错误码说明客户端根本就没能建立到服务器 IP 的网络连接。排查步骤很简单。第一步先确认你具体要访问的是哪个仓库地址。如果是 Docker Hub 的官方地址那就要看这台机器是否有外网访问能力试试ping registry-1.docker.io如果 ping 不通说明链路不通如果有代理上网需要给 docker 配置代理。第二步如果拉的是内网私有仓库检查地址是否写对、对方的服务是否在运行、以及两台机器之间的网络是否连通可以在客户端机器上telnet 你的IP 5000测一下端口。第三步确认网络没问题后重试如果仍然超时再考虑配置合法的镜像加速或改用其他可达的仓库地址。这里要特意提醒一句千万不要各种地方看到教程就盲目改网络代理配置一定要先判断你的实际网络拓扑。docker 的网络访问方式取决于它运行的主机网络环境同一套配置在这台机器能用换到另一台可能直接把网络搞断。处理这类问题最稳妥的方式是从链路层逐层排查而不是靠猜。6.3 私有仓库推送镜像报http: server gave HTTP response to HTTPS client前文已经解释过这个报错的根因是客户端默认用 HTTPS 访问而私有仓库是 HTTP 协议。解决方式有两种一是给仓库配 HTTPS 证书适合生产环境二是在客户端配置insecure-registries适合测试环境。一部分读者还会遇到一个变种报错x509: certificate signed by unknown authority这个是因为你给仓库配了自签名证书但客户端不信任这个证书。解决办法是把自签名证书加入到客户端的信任证书列表或者也通过insecure-registries来绕过证书校验。在生产环境我建议优先配置正规的 HTTPS 证书和可信 CA这能避免很多安全风险。如果只是为了快速联调insecure-registries确实省事但你一定要清楚它意味着镜像传输是不加密的不适合在公网环境使用。6.4 Harbor Web 界面能打开但客户端 docker login 失败现象通常是浏览器访问http://你的IP:80正常但执行docker login http://你的IP:80时报unauthorized: authentication required或超时。网上很多资料会把问题归因于密码错误实际上更常见的原因是 harbor.yml 里配置了 https但客户端用 http 访问或者 docker 客户端没有正确识别 Harbor 使用的端口。docker login的地址语法会决定它使用的协议如果端口不是 443docker 会默认走 HTTP但对 Harbor 来说你需要在地址中显式带上协议。以 80 端口为例正确写法是docker login http://你的IP:80直接写docker login 你的IP:80有时会被 docker 尝试以 HTTPS 访问然后握手失败。另一个常见问题是密码包含特殊字符导致终端解析错误建议先在本地执行echo 复杂密码确认能正常输出再复制进 docker login 交互里。6.5 镜像磁盘空间被占满Harbor 显示只读或推送失败Harbor 的镜像存储默认在数据目录下长期使用后磁盘占用会持续增长。当磁盘占用率达到一定阈值Harbor 的存储驱动可能会进入只读保护模式此时 push 镜像会失败。解决思路分两步先释放磁盘空间再保证未来有足够的增长空间。释放空间最直接的方式是到 Harbor Web 界面的项目的“镜像仓库”里删除旧的镜像 tag 和 artifact然后执行垃圾回收。Harbor 的垃圾回收功能比原生 Registry 友好很多地址在“系统管理 → 垃圾回收”可以手动触发也可以设置定时任务。如果磁盘空间已经满了导致垃圾回收也失败需要先手动清理一些其他大文件腾出最低限度空间再操作。长期规划上建议把 Harbor 的数据目录挂载到大容量磁盘或者接入对象存储这个可以后续再细化。7. 给还在纠结的你几点个人建议回到开头的问题我现在到底该用哪种仓库方案我的建议很直接个人学习阶段Docker Hub 加镜像加速完全够用别在这个阶段折腾私有仓库先把 docker 的基本操作练熟。当你开始跟两三个同事协作经常互相拷 tar 包、在群里发镜像压缩文件的时候就是部署私有仓库的信号此时先上一个 Registry一个小时就能搞定立刻解决协作痛点。当团队人数到了十几个不同项目之间开始需要隔离有人误删了别人的镜像部署文档和安全规范开始被要求那就别犹豫直接上 Harbor把权限体系、复制规则、定期 GC 都配好一劳永逸。还有一个小细节我特别想强调无论用哪种仓库方案都要养成给镜像打明确版本标签的习惯。我见过太多团队在镜像管理上栽跟头不是仓库技术选型的问题而是latest满天飞导致的混乱。仓库本身只是存储和分发的工具真正决定镜像管理是否有序的还是人的操作习惯。Harbor 的部署过程虽然比 Registry 复杂一些但只要配置文件的坑避开了安装脚本跑完基本不会有问题。后续的维护重点其实在数据备份和容量管理上前者靠定期的目录备份后者靠日常的垃圾回收和项目规范。把这套东西跑起来后你会发现团队协作效率会有明显的提升——这也是仓库这一层在整个 docker 容器技术栈里存在的意义。