1. 为什么你需要一个自己的Harbor镜像仓库如果你已经用了一段时间Docker或者正在团队里搞容器化那你肯定遇到过下面这些让人头疼的事儿从Docker Hub拉镜像速度慢得像蜗牛特别是那些大镜像一个上午就耗在等待上了团队内部开发了一堆微服务每个服务都有自己的镜像版本管理混乱谁手滑删了latest标签整个测试环境可能就崩了更别提安全问题了直接把业务镜像推到公共仓库心里总是不踏实。这时候一个搭建在自己服务器上的私有镜像仓库就成了刚需。Harbor就是这个领域的“明星选手”。它不是一个简单的镜像存储服务器而是一个企业级的、开源的容器镜像仓库解决方案。你可以把它理解为你公司内部的“Docker Hub Pro Max版”。它原生支持镜像的存储、分发、安全扫描、漏洞分析、权限管理、镜像复制甚至还能做Helm Chart仓库。对于中小团队或者个人开发者来说自己搭一套Harbor意味着你彻底掌控了镜像的生命周期构建、测试、发布的流程可以变得非常清晰和自动化。我见过不少团队一开始图省事用Docker自带的registry:2镜像搭个简易仓库。初期确实够用但一旦镜像数量上来、团队成员增多没有UI界面、没有权限控制、没有安全审计的短板就暴露无遗后期迁移到Harbor反而更麻烦。所以如果你的项目已经步入正轨或者你预见到未来会有这些需求那么从一开始就选择Harbor绝对是笔划算的投资。这篇教程就是带你从零开始手把手搭建一个生产可用的Harbor服务我会把每一步的原理、可能遇到的坑以及我趟过的雷都给你讲清楚。2. 部署前准备环境、资源与关键决策在真正动手安装之前充分的准备工作能避免你掉进无数个坑里。这一部分我们不仅要检查环境更要理解每个要求背后的原因。2.1 硬件与操作系统要求Harbor本身对资源要求并不苛刻但你需要根据预期的镜像存储量和并发访问量来规划。CPU与内存对于一个小型团队或测试环境2核4GB内存是起步配置。如果镜像数量庞大超过数千个或需要启用漏洞扫描等重度功能建议配置4核8GB或更高。内存不足会导致Harbor的UI组件特别是Core和Jobservice响应缓慢甚至崩溃。磁盘空间这是最重要的资源。你需要预估单个镜像的平均大小 × 镜像数量 × 保留的版本数。例如一个200MB的基础镜像团队有20个服务每个服务保留10个历史版本那么仅这部分就需要约 200MB * 20 * 10 40GB。这还不包括镜像的层Layer去重存储带来的节省以及日志、数据库等开销。强烈建议预留至少100GB的专用存储空间并确保有便捷的扩容方案。磁盘I/O性能也很关键使用SSD能显著提升镜像推送和拉取的速度。操作系统官方主要支持Linux发行版。我强烈推荐使用Ubuntu 20.04/22.04 LTS或CentOS/RHEL 7/8。这些系统有长期支持社区资料丰富能减少因系统版本过新或过旧带来的兼容性问题。本文将以Ubuntu 22.04 LTS为例进行演示其他系统的命令会有细微差别但核心逻辑一致。2.2 软件依赖安装与配置Harbor的运行依赖于Docker和Docker Compose。它本质上是一组通过Docker Compose编排起来的容器。安装Docker这是基石。不要使用系统默认的、过旧的Docker版本。# 更新软件包索引 sudo apt-get update # 安装必要的依赖允许apt通过HTTPS使用仓库 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置Docker稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 再次更新并安装Docker引擎 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装后将当前用户加入docker组避免每次都要sudo。sudo usermod -aG docker $USER # 退出当前终端并重新登录使组生效验证安装docker --version和docker compose version注意是compose不是docker-compose。安装Docker Compose独立版本虽然Docker现在内置了docker compose插件但Harbor的安装脚本和部分文档仍可能依赖独立的docker-compose带短横线命令。为了兼容性我们两者都装。# 下载Docker Compose的稳定版本例如v2.20.0 sudo curl -L https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 赋予可执行权限 sudo chmod x /usr/local/bin/docker-compose # 验证 docker-compose --version注意这里有一个常见的混淆点。docker compose插件和docker-compose独立二进制文件命令功能几乎相同但并非100%兼容所有历史脚本。Harbor的install.sh脚本通常会检查docker-compose命令。确保两个命令都能用是最稳妥的。2.3 关键决策安装模式与证书这是安装前最重要的选择题决定了你后续的使用方式和安全性。安装模式Harbor提供在线和离线安装包。我强烈推荐下载离线安装包。在线安装包在安装过程中会从互联网拉取所有Docker镜像如果你的服务器网络不稳定或者处于内网环境这个过程极易失败。离线安装包约1GB包含了所有必需的镜像部署过程完全离线稳定可靠。前往 Harbor GitHub Releases 页面下载最新稳定版如v2.8.0的离线安装包文件名类似harbor-offline-installer-v2.8.0.tgz。HTTP vs HTTPS对于任何生产或准生产环境必须使用HTTPS。使用HTTP会导致Docker客户端在推送/拉取镜像时报错默认需要安全连接你需要修改所有客户端Docker守护进程的配置这是巨大的安全隐患和管理负担。方案一推荐用于正式环境使用受信任的CA签发的证书如 Let‘s Encrypt。这需要你有自己的域名并将该域名解析到Harbor服务器的IP。方案二测试/内部环境使用自签名证书。这是本篇教程采用的方式因为它不依赖外部域名和CA适合快速搭建内部测试环境。你需要生成证书并在所有访问Harbor的客户端机器上信任该证书。3. 步步为营Harbor离线安装与基础配置假设你已经将下载好的harbor-offline-installer-v2.8.0.tgz上传到了服务器的/opt目录下。3.1 解压与准备配置文件# 切换到安装目录 cd /opt # 解压离线安装包 tar xzvf harbor-offline-installer-v2.8.0.tgz # 进入解压后的目录 cd harbor解压后你会看到几个关键文件其中harbor.yml.tmpl是配置模板。我们需要复制它并生成我们自己的配置文件。cp harbor.yml.tmpl harbor.yml现在用文本编辑器如vim或nano打开harbor.yml。下面是一个针对自签名证书场景的最小化配置示例我会逐段解释# 设置 Harbor 服务器的主机名。这是最重要的配置之一 # 如果你有域名就写域名如 harbor.yourcompany.com。 # 如果是内网IP测试就写IP地址如 192.168.1.100但注意证书需要匹配。 hostname: your.harbor.domain # 请务必修改为你服务器的IP或域名 # HTTP相关配置因为我们用HTTPS所以可以禁用或保留一个端口给重定向 http: port: 80 # HTTP端口可以关闭或用于重定向到HTTPS # HTTPS配置 - 这是核心 https: port: 443 # HTTPS端口 # 证书和私钥的路径。我们将自己生成放在当前目录下。 certificate: /opt/harbor/your.harbor.domain.crt private_key: /opt/harbor/your.harbor.domain.key # Harbor管理员用户的初始密码。安装后一定要改 harbor_admin_password: Harbor12345 # 请修改为强密码 # Harbor的数据持久化目录 data_volume: /data # Harbor的日志配置 log: level: info # 日志级别info, debug, error, warning local: rotate_count: 50 # 保留的日志文件个数 rotate_size: 200M # 每个日志文件大小 location: /var/log/harbor # 日志存储路径 # 其他组件可以暂时保持默认 # ...关键提示hostname配置必须与后续生成证书时使用的Common Name (CN)完全一致否则客户端会报证书域名不匹配的错误。如果使用IP这里就填IP证书CN也必须是这个IP。3.2 生成自签名证书用于HTTPS我们在Harbor目录下生成证书。首先创建一个目录存放证书并进入。mkdir -p /opt/harbor/certs cd /opt/harbor/certs假设你的hostname配置为192.168.1.100请替换为你的实际IP或域名。生成根证书私钥和自签名根证书充当自己的CAopenssl genrsa -out ca.key 4096 openssl req -x509 -new -nodes -sha512 -days 3650 \ -subj /CCN/STBeijing/LBeijing/Oexample/OUPersonal/CN192.168.1.100 \ -key ca.key \ -out ca.crt-subj参数里的信息可以根据需要修改但CN必须设置为你的 Harbor 主机地址IP或域名。-days 3650表示证书10年有效测试环境可以设短点。生成服务器证书签名请求CSR和私钥openssl genrsa -out your.harbor.domain.key 4096 openssl req -sha512 -new \ -subj /CCN/STBeijing/LBeijing/Oexample/OUPersonal/CN192.168.1.100 \ -key your.harbor.domain.key \ -out your.harbor.domain.csr生成x509 v3扩展文件这个文件告诉OpenSSL这个证书是用于服务器身份验证的。cat v3.ext -EOF authorityKeyIdentifierkeyid,issuer basicConstraintsCA:FALSE keyUsage digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment extendedKeyUsage serverAuth subjectAltName alt_names [alt_names] DNS.1192.168.1.100 # 如果你的hostname是域名可以同时添加IP和域名 # DNS.1harbor.yourcompany.com # IP.1192.168.1.100 EOF重要[alt_names]部分必须包含你的hostname。如果是IP就写IP.1如果是域名就写DNS.1。可以同时写多个。使用自签CA签发服务器证书openssl x509 -req -sha512 -days 3650 \ -extfile v3.ext \ -CA ca.crt -CAkey ca.key -CAcreateserial \ -in your.harbor.domain.csr \ -out your.harbor.domain.crt转换证书格式供Docker使用Docker客户端需要一种特定格式的证书。openssl x509 -inform PEM -in your.harbor.domain.crt -out your.harbor.domain.cert将证书复制到Docker和系统信任库在Harbor服务器本机# 复制服务器证书和密钥到Harbor配置指定的路径我们之前配置在/opt/harbor/ cp your.harbor.domain.crt /opt/harbor/ cp your.harbor.domain.key /opt/harbor/ # 复制CA根证书和服务器证书到Docker证书目录 mkdir -p /etc/docker/certs.d/192.168.1.100/ # 目录名必须是你的Harbor主机地址 cp your.harbor.domain.cert /etc/docker/certs.d/192.168.1.100/ cp ca.crt /etc/docker/certs.d/192.168.1.100/ # 将CA根证书添加到系统信任库Ubuntu cp ca.crt /usr/local/share/ca-certificates/192.168.1.100.crt sudo update-ca-certificates完成这些步骤后Harbor服务器本机的Docker客户端就已经信任了这个自签名证书。3.3 执行安装脚本现在一切准备就绪。回到Harbor目录执行安装脚本。cd /opt/harbor sudo ./install.sh这个脚本会做以下几件事解析harbor.yml配置文件。为各个组件PostgreSQL, Redis, Core, Jobservice, Portal, Registry等准备环境配置文件。通过docker-compose命令拉取并启动所有容器离线包已包含镜像所以很快。安装成功的标志是最后看到类似下面的输出并且所有容器状态都是Up✔ ----Harbor has been installed and started successfully.----你可以通过docker-compose ps命令来查看所有容器的运行状态。3.4 防火墙与SELinux配置如果服务器开启了防火墙需要放行Harbor使用的端口默认80和443。# 如果使用ufwUbuntu sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw reload # 如果使用firewalldCentOS/RHEL sudo firewall-cmd --permanent --add-port80/tcp sudo firewall-cmd --permanent --add-port443/tcp sudo firewall-cmd --reload对于CentOS/RHEL系统如果开启了SELinux需要调整策略以允许Docker容器访问宿主机目录。# 临时设置为宽松模式重启失效 sudo setenforce 0 # 永久禁用需要重启 sudo sed -i s/^SELINUXenforcing$/SELINUXpermissive/ /etc/selinux/config注意生产环境不建议直接禁用SELinux而是应该配置正确的SELinux策略。这里为了简化采用宽松模式。4. 安装后的关键操作与验证安装完成只是第一步要让Harbor真正可用还需要进行一些关键配置和验证。4.1 访问Web界面与初始化登录打开浏览器访问https://your.harbor.domain或https://192.168.1.100。由于使用的是自签名证书浏览器会显示安全警告选择“高级”-“继续前往”即可。使用默认用户名admin和你在harbor.yml中配置的harbor_admin_password例如Harbor12345登录。登录后第一件事立即修改管理员密码在右上角用户下拉菜单 - “修改密码”中完成。4.2 创建项目与配置用户权限Harbor的核心管理单元是“项目”。镜像必须属于某个项目。创建项目点击“项目” - “新建项目”。项目名称例如dev开发环境、test测试环境、prod生产环境或者按团队划分如team-a。访问级别公开任何能访问Harbor的人包括未登录用户都可以拉取此项目下的镜像。适合存放公共基础镜像。私有只有被授权的用户才能拉取和推送。这是最常用的设置。存储配额可以设置项目可使用的最大存储空间防止某个项目占用全部磁盘。创建用户与分配权限点击“用户管理” - “新建用户”。填写用户名、邮箱、密码等信息。创建用户后进入具体的项目如dev点击“成员” - “ 用户”。选择刚才创建的用户并分配角色项目管理员拥有项目的全部管理权限。维护人员可以推送、拉取镜像管理项目内的Helm Chart等。开发人员可以推送、拉取镜像。访客只能拉取镜像。 这种基于项目的RBAC基于角色的访问控制权限模型非常灵活能满足团队协作的需求。4.3 客户端Docker配置信任自签名证书要让其他机器上的Docker客户端能推送/拉取镜像必须让它们信任Harbor服务器的自签名CA证书。从Harbor服务器获取CA证书将之前生成的ca.crt文件拷贝到客户端机器上。你可以用scp命令# 在客户端机器执行从服务器下载ca.crt scp your_username192.168.1.100:/opt/harbor/certs/ca.crt .在客户端配置Docker信任该证书Linux/macOS# 创建对应Harbor主机地址的目录 sudo mkdir -p /etc/docker/certs.d/192.168.1.100/ # 将ca.crt复制进去 sudo cp ca.crt /etc/docker/certs.d/192.168.1.100/ # 重启Docker服务 sudo systemctl restart dockerWindows (Docker Desktop)将ca.crt文件复制到C:\ProgramData\Docker\certs.d\192.168.1.100\目录下如果目录不存在则创建。重启Docker Desktop。4.4 基础功能测试推送与拉取镜像现在让我们进行最关键的测试验证整个链路是否通畅。登录到Harbor在客户端机器上使用Docker命令登录。docker login 192.168.1.100输入用户名如admin和密码。如果成功会显示Login Succeeded。标记一个本地镜像我们以官方的nginx:alpine小镜像为例。# 先拉取一个测试镜像 docker pull nginx:alpine # 按照 Harbor 的镜像命名规范重新标记 # 格式Harbor主机地址/项目名称/镜像名称:标签 docker tag nginx:alpine 192.168.1.100/library/nginx:alpine这里我们把镜像推送到library这个默认的公开项目。你也可以推送到自己创建的私有项目如192.168.1.100/dev/nginx:alpine。推送镜像到Harbordocker push 192.168.1.100/library/nginx:alpine如果一切配置正确你会看到镜像层被一层层上传。完成后在Harbor的Web界面进入“library”项目就能看到刚刚推送的nginx镜像。从Harbor拉取镜像# 先删除本地已标记的镜像 docker rmi 192.168.1.100/library/nginx:alpine # 从Harbor拉取 docker pull 192.168.1.100/library/nginx:alpine如果能成功拉取说明整个安装、配置、网络、证书全部环节都已打通。5. 生产环境进阶配置与优化基础安装完成后Harbor已经可以工作。但要用于生产环境还需要考虑高可用、性能、安全和维护。5.1 配置外部数据库与Redis默认安装使用容器内的PostgreSQL和Redis。这对于测试没问题但在生产环境强烈建议使用外部的、有专人维护的数据库和Redis实例。这能带来更好的性能、可靠性和数据安全性。修改harbor.yml中的相关部分# 外部数据库配置 external_database: harbor: host: harbor-db-host # 你的数据库主机IP或域名 port: 5432 # PostgreSQL默认端口 db_name: harbor username: harbor password: your_strong_db_password ssl_mode: disable # 生产环境建议启用SSL max_idle_conns: 50 max_open_conns: 100 # 外部Redis配置 external_redis: host: redis-host # 你的Redis主机IP或域名 port: 6379 password: your_strong_redis_password registry_db_index: 1 jobservice_db_index: 2 chartmuseum_db_index: 3 clair_db_index: 4 trivy_db_index: 5配置后需要运行./prepare脚本更新配置然后停止并重新启动Harbordocker-compose down -v和docker-compose up -d。注意迁移数据需要额外步骤官方文档有详细说明务必在测试环境演练。5.2 启用漏洞扫描Trivy安全是Harbor的一大亮点。集成漏洞扫描器后每当有镜像被推送到仓库Harbor可以自动或手动触发扫描并生成漏洞报告。在harbor.yml中启用Trivytrivy: # 启用漏洞扫描 enabled: true # 忽略未修复的漏洞 ignore_unfixed: false # 安全级别可设置为“high,critical”只关注高危漏洞 severity: unknown,low,medium,high,critical # 扫描超时时间 timeout: 5m更新配置并重启sudo ./prepare --with-trivy sudo docker-compose down -v sudo docker-compose up -d重启后在项目下的镜像列表中点击镜像在“漏洞”标签页就可以手动触发扫描或查看历史扫描报告。你还可以在项目配置中设置“自动扫描镜像”实现安全左移。5.3 配置日志与数据持久化默认的日志和数据都存储在/data目录下。你需要确保这个目录所在磁盘空间充足并考虑备份策略。日志日志路径在harbor.yml的log.local.location中配置。生产环境建议将日志收集到集中的日志平台如ELK Stack进行分析。可以修改配置让容器日志直接输出到stdout/stderr然后由Docker的日志驱动如json-file,syslog,journald或第三方工具如Fluentd收集。数据data_volume配置了镜像和Chart的存储路径。对于大规模部署可以考虑使用网络存储如NFS、Ceph、云存储作为后端并通过Docker卷插件或修改registry组件的配置来实现。这涉及到更复杂的配置需要参考Harbor和对应存储的官方文档。5.4 日常维护与故障排查启停服务# 停止Harbor cd /opt/harbor docker-compose down # 启动Harbor docker-compose up -d # 查看日志跟踪Core组件日志 docker-compose logs -f core修改配置任何对harbor.yml的修改都需要运行./prepare脚本使配置生效然后重启服务。sudo ./prepare sudo docker-compose down -v sudo docker-compose up -d备份与恢复Harbor的备份主要包括两部分1) 数据库数据镜像元数据、用户信息等2) 存储卷中的镜像文件。官方提供了harbor.yml中关于备份的配置说明和迁移工具。定期备份/data目录和数据库是必须的。常见问题排查无法登录Web界面检查core、portal、postgresql容器是否正常运行 (docker-compose ps)。查看core容器的日志 (docker-compose logs core)。Docker客户端登录/推送失败x509: certificate signed by unknown authority客户端没有正确安装/信任CA证书。检查证书目录和文件权限。Get https://.../v2/: dial tcp ...:443: connect: connection refused防火墙未放行443端口或Harbor服务未启动。denied: requested access to the resource is denied1) 未登录或登录已过期 (docker login)。2) 用户对该项目没有推送权限。3) 镜像名称中的项目名拼写错误。磁盘空间不足Harbor不会自动清理旧的镜像层。需要定期手动或在CI/CD流水线中清理无用镜像。可以通过Web界面删除镜像标签或者使用Harbor API结合GC垃圾回收来清理物理存储。注意删除镜像标签后需要手动执行Registry的垃圾回收命令才能真正释放磁盘空间这需要在Harbor服务器上操作且服务会短暂中断。6. 集成到CI/CD流水线Harbor搭建好后最大的价值在于无缝集成到你的开发运维流程中。这里以Jenkins Pipeline为例展示一个简单的推送镜像的步骤。在你的Jenkinsfile或Pipeline脚本中pipeline { agent any environment { HARBOR_REGISTRY 192.168.1.100 HARBOR_PROJECT dev IMAGE_NAME my-app // 使用Jenkins的凭据ID来安全地存储Harbor密码 HARBOR_CREDENTIALS credentials(harbor-credentials-id) } stages { stage(Build Push Image) { steps { script { // 1. 构建Docker镜像 docker.build(${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:${BUILD_NUMBER}) // 2. 登录Harbor sh echo \$HARBOR_CREDENTIALS_PSW | docker login ${HARBOR_REGISTRY} -u \$HARBOR_CREDENTIALS_USR --password-stdin // 3. 推送镜像 docker.image(${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:${BUILD_NUMBER}).push() // 4. 可选推送latest标签 sh docker tag ${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:${BUILD_NUMBER} ${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:latest sh docker push ${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:latest } } } } post { always { // 清理工作空间登出Docker可选 sh docker logout ${HARBOR_REGISTRY} } } }这个流水线会在每次构建时生成一个带构建编号的镜像标签推送到Harbor同时更新latest标签。在实际生产中你还需要加入漏洞扫描结果检查、测试环境自动部署等环节。7. 我踩过的那些坑与避坑指南最后分享几个我在多次部署Harbor过程中遇到的典型问题希望能帮你节省时间。证书的“主机名/IP不匹配”陷阱这是最常见的问题。harbor.yml中的hostname、生成证书时-subj参数里的CN、v3.ext文件里的subjectAltName以及客户端访问时使用的地址四者必须完全一致。哪怕一个是域名一个是IP都会导致失败。最稳妥的测试方法是在客户端用curl -vk https://your.harbor.domain先测试证书是否被信任再测试Docker。离线安装包版本与Docker Compose的兼容性曾经遇到过用较新版本的docker-composev2.x去安装一个旧版本Harborv1.x因为Compose文件语法不兼容导致启动失败。确保你的Docker Compose版本与Harbor版本大致匹配。如果遇到启动失败查看docker-compose logs输出的具体错误信息。磁盘空间耗尽导致服务异常Harbor的Registry组件在磁盘满时行为不可预测可能导致推送失败或UI显示异常。一定要设置监控告警监控/data目录的磁盘使用率。定期清理无用镜像并在规划时预留足够的缓冲空间比如用到70%就告警。忘记配置客户端证书在另一台机器上兴致勃勃地测试结果docker login一直报证书错误。切记每一台需要访问Harbor的Docker客户端机器都必须按照步骤4.3配置信任证书。这是一个很容易遗漏的步骤。修改配置后未重启所有服务修改harbor.yml后只运行了./prepare但没有执行docker-compose down -v docker-compose up -d导致新配置不生效。prepare脚本只生成容器的配置文件必须重启容器才能加载新配置。使用“localhost”或“127.0.0.1”作为hostname如果你在服务器本机用Docker客户端测试这么配置可能暂时能通。但一旦其他机器要访问就会完全失败。从一开始就使用服务器在网络中可被其他客户端访问的IP地址或域名进行配置避免后续修改带来的麻烦。Harbor的安装难点不在于点击按钮而在于对网络、证书、存储这些基础设施的理解和正确配置。按照上面的步骤耐心地走一遍遇到问题多查日志docker-compose logs [服务名]你一定能搭建起一个稳定可靠的私有镜像仓库。当你的团队能顺畅地从内网秒拉镜像当CI/CD流水线自动将构建好的镜像推送到仓库并触发安全扫描时你会觉得这一切的折腾都是值得的。