摘要：# Harbor私有镜像仓库：别光看教程，这些“坑”我帮你踩过了 聊到企业里自己搭Docker镜像仓库，Harbor基本是绕不开的名字。这玩意儿确实香——开源、功能全、界面也还过得去。但说真的，我自己帮不少公司配过，发现很多人照着官方文档一顿操作，最后要…

Harbor私有镜像仓库：别光看教程，这些“坑”我帮你踩过了

聊到企业里自己搭Docker镜像仓库，Harbor基本是绕不开的名字。这玩意儿确实香——开源、功能全、界面也还过得去。但说真的，我自己帮不少公司配过，发现很多人照着官方文档一顿操作，最后要么卡在某个步骤，要么就是跑起来了但总觉得哪里不对劲，用起来提心吊胆的。

今天咱就不说那些“首先安装Docker，然后下载安装包”的废话了。我直接跟你聊聊，在企业真实环境里配Harbor，那些文档里不会写、但能让你少加两天班的细节。

一、先想清楚：你到底需要Harbor的哪些功能？

Harbor功能是多，但别一股脑全装上。很多团队一开始雄心勃勃，把漏洞扫描、镜像签名、复制策略全开了，结果部署阶段就被复杂的配置劝退，或者后期维护成本高得吓人。

我的建议是：分阶段来。

第一阶段（先把仓库跑起来）：核心就三样——镜像存储、用户权限、Web界面。别整那些花里胡哨的，先把开发团队的镜像管起来，让大家能正常push/pull。这阶段，你甚至可以先不考虑HTTPS（测试环境），用HTTP快速验证。

第二阶段（安全加固）：等用顺了，再上HTTPS证书和漏洞扫描。尤其是漏洞扫描，现在成了很多企业的安全合规硬性要求，但初期可以先用手动触发，别一上来就搞全自动，容易把团队吓着。

第三阶段（高阶玩法）：这时候再考虑多数据中心复制、镜像签名这些高级货。说真的，90%的中小企业，到第二阶段就够用了。

二、部署方式选哪个？在线安装包 vs Helm Chart vs 离线包

这是第一个容易纠结的点。

如果你团队里没有专职的K8s运维，我劝你老老实实用在线安装包（就是那个install.sh脚本）。虽然看起来“不云原生”，但它把依赖（Docker Compose）都打包好了，出了问题排查路径清晰，社区里踩过的坑也多。我见过不少团队为了“技术先进性”硬上Helm，结果一个values.yaml文件调了三天还没把服务调通。

但如果你已经在K8s上跑生产了，那Helm Chart确实是更自然的选择。不过这里有个细节：Harbor的Helm Chart默认会装一堆组件（数据库、Redis啥的），如果你的K8s集群里已经有现成的MySQL、Redis，一定要用外部服务！别让Harbor自己再起一套，资源浪费不说，数据备份和监控都得做两套，后期运维能累死你。

至于离线包，主要看网络环境。如果服务器压根不通外网（很多金融、政企客户都这样），那没得选。但如果有条件，我还是建议先用在线方式装，因为后续升级会方便很多。

三、HTTPS证书：别被自签名证书搞崩溃

这是劝退率最高的环节之一。很多教程轻描淡写一句“配置HTTPS证书”，但实际操作时，各种证书错误能让你怀疑人生。

大实话时间： 如果只是内部开发测试用，前期完全可以用HTTP。先让流程跑起来，再解决安全问题。很多团队卡在证书配置上，项目进度一拖再拖，得不偿失。

但生产环境必须上HTTPS。这时候你有几个选择：

1. 用公开的CA证书（比如Let's Encrypt）：最简单，但要求你的Harbor域名能从外网访问（验证用）。很多企业内网环境不满足。
2. 用企业内部CA：如果公司有统一的证书颁发机构，这是最规范的做法。但需要协调安全团队，流程可能比较长。
3. 自签名证书：最灵活，也最容易出问题。关键不在于生成证书，而在于让所有要连接Harbor的机器都信任这个证书。

重点说说自签名证书的坑。你按照文档生成了ca.crt和yourdomain.com.crt，配置好了，Harbor也起来了。然后你在另一台机器上docker login，直接报错：“x509: certificate signed by unknown authority”。

问题出在哪儿？ Docker客户端不认你的自签名CA。

解决办法有两种：

• 简单粗暴版：在每台需要连接Harbor的机器上，把你的ca.crt复制到/etc/docker/certs.d/your-harbor-domain.com目录下（注意目录名要完全匹配你的Harbor域名）。然后重启Docker服务。
• 一劳永逸版：把你的自签名CA证书添加到系统的受信任根证书库。具体命令因操作系统而异（Ubuntu用update-ca-certificates，CentOS用update-ca-trust）。这步做了，不光Docker，所有工具（curl、浏览器）都会认你的证书。

四、存储配置：别把镜像和数据库放一起

Harbor安装时默认会把镜像数据、数据库、Redis数据都放在本地目录。这对于生产环境是极其危险的。

想象一下，你硬盘满了，Harbor服务挂了，你连登录Web界面查日志的机会都没有，因为数据库可能也挂了。

必须做的拆分：

1. 镜像存储：一定要用外部存储。可以是NFS、Ceph、S3兼容的对象存储（比如MinIO）。在harbor.yml里配置storage_service部分。我强烈推荐对象存储，扩展性好，还自带冗余。
2. 数据库/Redis：如果条件允许，也用外部的。至少，要把数据目录挂载到单独的磁盘分区上，别和系统盘挤在一起。

五、权限管理：别让“所有人都是管理员”

Harbor的权限模型其实挺细的：有项目管理员、开发者、访客等角色。但很多团队图省事，给所有人都开管理员权限，或者只用一个共享账号。

这就埋了个大雷。 一旦出问题（比如有人误删了生产镜像），你连是谁操作的都查不到。

正确的做法是：

• 每个开发人员用自己的账号登录。
• 根据项目划分权限。A项目组的人看不到B项目的镜像。
• 敏感操作（比如删除镜像、修改项目设置）只开放给项目管理员。
• 开启操作日志审计（默认就是开的），这样所有操作都有迹可循。

六、日常维护：备份和升级，别等出事再想

Harbor跑起来不是终点。两个事必须提前规划：

1. 备份什么？

• 数据库：这是最重要的。Harbor的用户、项目、权限等元数据全在这里。用pg_dump（如果用的PostgreSQL）定期备份。
• 镜像数据：如果你用的外部存储（比如S3），通常存储服务自己会做冗余。但为了保险，可以定期做快照或启用跨区域复制。
• 配置文件：就是那个harbor.yml，改动了记得备份。

2. 怎么升级？ Harbor版本更新挺快的。小版本升级（比如v2.5.0到v2.5.3）一般比较平滑，照着官方升级指南做就行。 但大版本升级（比如v1.x到v2.x）一定要先在测试环境充分验证。数据库结构可能有变，新功能可能影响现有流程。

七、最后说点“玄学”经验

• 资源给够：别吝啬。Harbor本身不算重，但如果你开了漏洞扫描，那玩意儿吃CPU。内存建议至少8G起步。
• 网络要通：Harbor组件之间（Core、Jobservice、Registry等）通信要顺畅。如果是K8s部署，注意NetworkPolicy别给拦了。
• 日志盯紧：Harbor各组件的日志是分开的（在/var/log/harbor/下）。出问题时别只看Web界面报错，去翻日志，答案八成在里面。
• 社区多用：遇到奇怪的问题，先去GitHub的Issue里搜搜。你踩的坑，大概率已经有人踩过并给出了解决方案。

行了，絮絮叨叨说了这么多，其实核心就一句：Harbor是个好工具，但别把它当黑盒子。了解它的组件、理清你的需求、规划好维护流程，它才能老老实实为你服务。

配置这事儿，就像给新房子装修，图纸画得再漂亮，也得师傅现场能把水管接上、电线排好。希望这些从实战里摸出来的经验，能帮你省下些折腾的时间。要是还有啥具体问题，评论区见。