1. 为什么私有化镜像仓库是团队协作的刚需做过容器化落地的朋友大概率都经历过这样的场景开发环境用docker pull拉公共镜像一到生产环境就抓瞎——网络不通、拉取限速、镜像版本漂移、安全审计过不了。更别提团队里十几个开发共用一套镜像谁改了哪个 tag、哪个版本对应哪次构建全靠口头传递出了问题连回滚都找不到基准点。这就是私有镜像仓库存在的意义。它解决的核心问题有三个镜像资产的统一存储与版本管理、内网高速分发、访问控制与安全扫描。而 Harbor 在这个赛道里是目前企业级落地最广泛的开源方案之一。它基于 Docker Registry 做了大量增强提供了 Web 管理界面、基于角色的访问控制、镜像复制、漏洞扫描、审计日志、垃圾回收等一整套能力。这篇文章适合谁看如果你正在做容器化基础设施搭建或者团队规模到了五六个人以上、开始觉得公共仓库不够用又或者你之前用过 Registry 但被它的“裸奔”体验劝退过那这篇内容基本能覆盖你从零到一的全过程。我会把安装、配置、踩坑、调优这几块拆开讲参数怎么算、为什么这么选都给你说明白。需要提前说明的是Harbor 的部署方式有好几种在线安装、离线安装、Helm Chart 部署、Operator 部署。本文聚焦在最通用、最容易复现的离线安装方式上因为生产环境往往不允许直接访问外网离线包能省掉大量依赖下载的麻烦。如果你用的是 Kubernetes 集群Helm 方式会更优雅但底层逻辑是相通的理解了离线安装Helm 那套你也能很快上手。2. 部署前的整体设计与选型考量2.1 版本选择与组件构成Harbor 的版本迭代比较快选版本的时候不要盲目追新。我的建议是选次新稳定版比如当前最新是 2.11.x那 2.10.x 就是比较稳妥的选择。原因很简单新版本刚出来时社区踩坑案例少遇到问题搜不到答案而太老的版本又可能缺少关键特性比如某些扫描器的集成支持。Harbor 的核心组件包括Proxy反向代理层通常由 Nginx 或 Envoy 承担负责流量入口和 TLS 终止Core核心服务处理 API 请求、权限校验、项目管理PortalWeb 管理界面Registry实际存储镜像的组件基于 Docker DistributionDatabase默认用 PostgreSQL存储元数据Redis缓存和任务队列Jobservice异步任务处理比如镜像复制、垃圾回收Trivy漏洞扫描器2.x 版本后默认集成这些组件在离线安装包里都已经打包好了你不需要单独去装。但理解它们各自的职责对后面排查问题非常关键。比如镜像推送失败可能是 Registry 的问题登录报错可能是 Core 或 Database 的问题扫描任务卡住那大概率要看 Jobservice 和 Trivy。2.2 硬件与系统要求Harbor 对资源的要求不算高但也不能太抠。以下是我在实际项目中总结的配置基线规模CPU内存磁盘适用场景测试/小团队2 核4 GB100 GB10 人以下镜像量少中等规模4 核8 GB500 GB30-50 人日常构建频繁生产级8 核16 GB1 TB SSD百人以上多项目并行磁盘这块要重点说一下。镜像存储的膨胀速度往往超出预期一个中等规模的团队每月新增镜像层可能就有几十 GB。而且 Harbor 的垃圾回收不是自动的需要手动触发所以磁盘一定要留足余量。我见过太多团队一开始只给了 200 GB三个月后就告警了。操作系统方面主流的 Linux 发行版都支持内核版本建议 4.x 以上。需要特别注意的是Docker 和 Docker Compose 的版本要匹配 Harbor 的要求。Harbor 2.10 要求 Docker 20.10 和 Docker Compose 2.x。如果你用的是老版本的 docker-compose1.x会直接报错。2.3 网络与域名规划Harbor 默认使用 HTTPS这是强烈建议保持的。虽然可以配置成 HTTP但 Docker 客户端对 HTTP 仓库需要额外配置insecure-registries而且推送镜像时会有安全警告生产环境不建议这么干。域名规划上建议用一个独立的子域名比如harbor.internal.example.com。这里有个关键点Harbor 的域名一旦确定后续修改非常麻烦因为镜像地址里会包含域名改了域名意味着所有镜像的引用路径都要变。所以前期规划时一定要想清楚。证书方面如果有内部 CA用内部 CA 签发即可如果没有可以用自签名证书但需要把 CA 证书分发到所有需要访问 Harbor 的机器上。这一步很多人会漏掉导致docker login时报x509: certificate signed by unknown authority。3. 离线安装的完整实操流程3.1 下载与解压安装包首先去 Harbor 的官方发布页面下载离线安装包。文件名通常形如harbor-offline-installer-v2.10.2.tgz大小在 500 MB 到 1 GB 之间取决于集成的组件版本。下载完成后上传到目标服务器然后解压tar -xzf harbor-offline-installer-v2.10.2.tgz -C /opt/ cd /opt/harbor解压后你会看到这些关键文件harbor.yml.tmpl配置文件模板install.sh安装脚本prepare环境准备脚本common.sh公共函数库harbor.v2.10.2.tar.gz所有组件的镜像包3.2 配置文件的关键参数详解复制模板文件并重命名cp harbor.yml.tmpl harbor.yml然后编辑harbor.yml。这个文件是整个过程的核心我逐段说明关键参数。hostname这是最重要的参数填你的域名或 IP。如果填 IP证书里也要包含这个 IP。hostname: harbor.internal.example.comhttp 和 httpsHarbor 2.x 默认只启用 HTTPS。如果你有证书配置https段如果没有可以先用 HTTP 测试但记得注释掉https段否则启动会失败。http: port: 80 https: port: 443 certificate: /your/cert/path/harbor.crt private_key: /your/cert/path/harbor.keyharbor_admin_password管理员初始密码。建议改成强密码虽然登录后会提示修改但初始密码太弱会有安全风险。harbor_admin_password: YourStrongPassword123!database默认用内置的 PostgreSQL密码也要改。如果你有外部数据库可以配置外部连接但小规模场景没必要。database: password: YourDBPassword456! max_idle_conns: 50 max_open_conns: 100data_volume数据存储路径。默认是/data建议改成独立挂载的大磁盘路径比如/data/harbor。data_volume: /data/harbortrivy漏洞扫描配置。默认是开启的ignore_unfixed设为true可以忽略那些没有修复版本的漏洞减少噪音。trivy: ignore_unfixed: true skip_update: false insecure: falsejobservice异步任务配置。max_job_workers控制并发任务数默认 10如果镜像复制任务多可以适当调大。jobservice: max_job_workers: 10log日志配置。level建议设为info排查问题时可以临时改成debug。rotate_count和rotate_size控制日志轮转避免日志把磁盘写满。log: level: info local: rotate_count: 50 rotate_size: 200M3.3 执行安装与验证配置文件改好后执行安装脚本./install.sh这个脚本会做几件事检查环境、加载镜像、生成 docker-compose 文件、启动所有容器。整个过程大概需要 2-5 分钟取决于机器性能。安装完成后用docker compose ps查看容器状态。正常情况下你会看到 9 个左右的容器在运行docker compose ps如果某个容器状态是Restarting或Exit那就要看日志了docker compose logs -f service_name验证安装是否成功最直接的方式是访问 Web 界面https://harbor.internal.example.com。用admin和你设置的密码登录能看到项目列表就说明核心服务正常了。然后测试镜像推送。先登录docker login harbor.internal.example.com打标签并推送docker tag nginx:latest harbor.internal.example.com/library/nginx:latest docker push harbor.internal.example.com/library/nginx:latest推送成功后在 Web 界面刷新应该能看到library/nginx这个仓库和对应的 tag。注意如果docker login报证书错误需要把 Harbor 的 CA 证书放到/etc/docker/certs.d/harbor.internal.example.com/目录下然后重启 Docker 服务。4. 生产环境必须做的配置调优4.1 存储后端的选择与配置Harbor 默认把镜像存在本地文件系统这对小规模场景够用但生产环境建议用对象存储。原因有三容量扩展方便、多节点共享存储、数据可靠性更高。Harbor 支持 S3 兼容的对象存储、Azure Blob、GCS、Swift 等。以 S3 兼容存储为例在harbor.yml中配置storage_service: s3: accesskey: your_access_key secretkey: your_secret_key region: us-west-1 bucket: harbor-images endpoint: https://s3.internal.example.com secure: true v4auth: true chunksize: 5242880 rootdirectory: /harbor这里有个坑chunksize默认是 5 MB如果网络带宽充足可以调大到 10 MB 或 20 MB能显著提升大镜像的推送速度。但也不能太大否则单个分片上传失败重试的成本会很高。配置对象存储后需要重新执行./prepare和docker compose up -d让配置生效。已有的本地镜像不会自动迁移需要手动处理或者重新推送。4.2 垃圾回收与配额管理Harbor 的垃圾回收GC是手动触发的这一点很多人不知道。镜像删除后实际占用的磁盘空间不会立即释放需要执行 GC 才能回收。GC 的操作路径是系统管理 - 垃圾回收 - 立即执行。建议配置成定时任务比如每周日凌晨执行一次。但要注意GC 执行期间仓库会进入只读模式所以一定要选在业务低峰期。配额管理也很重要。Harbor 支持项目级别的存储配额可以防止某个项目把磁盘写满。在项目设置里配置配额比如限制每个项目最多 50 GB。超过配额后推送会被拒绝这样能倒逼团队清理无用镜像。4.3 高可用与备份策略单节点 Harbor 存在单点故障风险。如果对可用性要求高可以部署多节点集群前面挂负载均衡。但 Harbor 的多节点部署有个前提必须使用共享存储后端对象存储或共享文件系统否则各节点数据不一致。备份策略上需要备份的东西包括数据库PostgreSQL 的数据包含用户、项目、权限、镜像元数据配置文件harbor.yml和证书镜像数据如果用的是本地存储需要备份/data/harbor目录如果用对象存储备份策略由存储层负责数据库备份可以用pg_dump建议每天执行一次保留最近 7 天的备份。恢复时先停 Harbor恢复数据库再启动。5. 常见问题排查与避坑经验5.1 安装阶段的高频报错报错一Error response from daemon: Get https://...: x509: certificate signed by unknown authority这是证书问题。解决方法有两种一是把 CA 证书放到 Docker 的信任目录二是配置insecure-registries不推荐。具体操作mkdir -p /etc/docker/certs.d/harbor.internal.example.com cp harbor.crt /etc/docker/certs.d/harbor.internal.example.com/ca.crt systemctl restart docker报错二Failed to initialize database: pq: password authentication failed数据库密码不对。检查harbor.yml里的database.password是否和实际一致。如果之前装过又重装可能有残留的数据卷需要先清理docker compose down -v rm -rf /data/harbor/database报错三port is already allocated端口被占用。Harbor 默认用 80 和 443如果这两个端口被 Nginx 或其他服务占了需要改harbor.yml里的端口或者先停掉占用端口的服务。5.2 运行阶段的典型故障故障一镜像推送成功但 Web 界面看不到这种情况通常是 Core 服务和 Registry 之间的通信有问题。检查 Core 的日志docker compose logs core | grep -i error常见原因是 Redis 连接失败或者数据库连接池满了。如果是连接池问题调大database.max_open_conns。故障二漏洞扫描一直处于Pending状态扫描任务依赖 Jobservice 和 Trivy。先检查这两个容器是否正常运行然后看 Jobservice 的日志。如果 Trivy 的漏洞库更新失败因为离线环境无法访问外网需要手动更新漏洞库或者配置离线更新源。故障三磁盘满了导致 Harbor 无法启动这是最棘手的情况。Harbor 的数据库和 Redis 对磁盘空间敏感磁盘满了会直接导致服务崩溃。应急处理步骤清理 Docker 的悬空镜像和停止的容器docker system prune -a清理 Harbor 的日志文件/var/log/harbor/下的旧日志如果还是不够手动删除一些大的无用镜像仓库然后执行 GC预防措施是配置磁盘监控告警阈值设在 80%留出处理时间。5.3 独家避坑技巧汇总问题场景排查思路解决方案登录报 401检查密码、检查数据库连接重置 admin 密码或检查 DB 日志推送超时检查网络带宽、检查存储后端调大 chunksize、检查对象存储连通性复制任务失败检查目标仓库连通性、检查凭证重新配置复制规则、检查防火墙Web 界面卡顿检查数据库性能、检查 Redis优化 DB 索引、增加 Redis 内存证书过期检查证书有效期更新证书后重启 Proxy 容器还有一个容易被忽略的点Harbor 的时区配置。默认是 UTC如果团队在国内日志时间会对不上。可以在harbor.yml里配置timezone: Asia/Shanghai或者在 docker-compose 文件里给容器加TZ环境变量。另外Harbor 的 API 非常完善很多操作可以通过 API 自动化。比如批量创建项目、批量添加用户、查询镜像列表等。如果你在做 CI/CD 集成建议直接调 API比在界面上点来点去高效得多。API 的认证方式支持 Basic Auth 和 SessionCI 场景下用 Basic Auth 更方便。最后说一个关于升级的经验。Harbor 的跨大版本升级不能跳级比如从 2.8 升到 2.10需要先升到 2.9 再升到 2.10。升级前一定要备份数据库和配置文件升级过程中 Harbor 会不可用要安排好维护窗口。升级完成后记得检查所有容器的状态和日志确认没有异常报错。
