1. 项目概述为什么需要一个私有的Docker Registry在容器化开发和部署的日常工作中我们频繁地与Docker Hub这样的公共镜像仓库打交道。docker pull ubuntu:latest或docker pull nginx这样的命令早已成为肌肉记忆。然而当项目进入深水区特别是涉及到企业级应用、专有软件或对安全、速度有更高要求的场景时公共仓库的局限性就暴露无遗。镜像拉取速度受制于网络敏感的商业代码或算法模型镜像绝不可能上传到公共空间团队内部共享测试镜像也颇为不便。这时搭建一个私有Docker Registry就从一个“可选项”变成了“必选项”。私有Registry简单说就是你自己搭建和维护的一个Docker镜像仓库服务器。它完全由你掌控部署在内网或你信任的云服务器上。你可以把团队开发的应用镜像、基础环境镜像、甚至是第三方镜像的定制版本安全地推送到这个私有仓库中。后续的持续集成CI流水线、测试环境、生产环境都从这个私有仓库拉取镜像整个过程高效、安全、可控。这不仅仅是技术上的隔离更是研发流程规范化、资产私有化的重要一步。无论是三五人的小团队还是上百人的研发部门一个稳定可靠的私有Registry都是容器化架构中不可或缺的基础设施。2. 核心需求与方案选型在动手搭建之前我们需要明确自己的核心需求这直接决定了技术方案的选择。一个私有Registry并非只有一种形态从最简单的单机版到功能完备的企业级方案差异巨大。2.1 需求拆解你需要什么样的Registry基础存储与分发这是最核心的功能能够通过标准的Docker APIv2接收push和提供pull镜像。身份认证Authentication谁可以推送谁可以拉取简单的场景可能只需要HTTP基本认证复杂的则需要集成LDAP、OAuth2等。访问控制Authorization认证之后用户/系统能对哪些镜像仓库项目进行操作是只读、读写还是管理员权限用户界面WebUI提供一个图形化界面来浏览镜像、查看标签、管理仓库对于非命令行用户或管理者非常友好。漏洞扫描Vulnerability Scanning自动扫描镜像中的操作系统和应用程序依赖识别已知的安全漏洞CVE。镜像复制Replication在多数据中心或混合云场景下将镜像从一个Registry同步到另一个保证环境一致性。高可用与持久化Registry服务本身无状态但存储的镜像数据Blobs和元数据Manifests必须持久化。生产环境需要保证服务的高可用性。2.2 方案对比从Registry到Harbor面对这些需求社区和业界提供了不同层次的解决方案Docker Distribution (Registry:2)这是Docker官方提供的、最基础的镜像仓库实现。它非常轻量只解决了最核心的“存储与分发”问题。认证、UI、扫描等高级功能都需要你自己通过组合其他工具如Nginx做反向代理和认证来实现适合极简场景或作为学习入门。Harbor由VMware现为Broadcom开源是目前最流行、功能最全面的企业级私有Registry解决方案。它在Docker Distribution的基础上原生集成了基于角色的访问控制RBAC、精美的WebUI、漏洞扫描、镜像复制、日志审计、Helm Chart仓库等一系列企业级功能。它像是一个“开箱即用”的完整产品极大地降低了运维复杂度。选型结论对于绝大多数寻求搭建私有Registry的团队尤其是希望获得完整管理能力、安全特性和良好用户体验的Harbor是毫无疑问的首选。它通过容器化部署本身也极其方便。因此本记录将重点围绕Harbor的搭建展开这涵盖了私有Registry搭建的绝大多数核心实践。3. 环境准备与前置条件在启动Harbor容器之前我们需要确保宿主机环境满足要求。这里以一台干净的Linux服务器如Ubuntu 22.04 LTS为例。3.1 系统与依赖检查首先更新系统并安装必要的工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git vim关键依赖Docker与Docker ComposeHarbor本身以容器形式运行因此Docker引擎是必须的。同时Harbor使用docker-compose来编排和管理多个服务容器如核心Registry、数据库、UI、JobService等。安装Docker Engine# 卸载旧版本 sudo apt remove docker docker-engine docker.io containerd runc # 设置仓库 sudo apt install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod ar /etc/apt/keyrings/docker.asc echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 启动并设置开机自启 sudo systemctl enable docker sudo systemctl start docker # 将当前用户加入docker组避免每次使用sudo sudo usermod -aG docker $USER # 注意需要重新登录或执行 newgrp docker 使组生效安装Docker Compose独立版本 虽然Docker Desktop包含了Compose但在Linux服务器上我们通常安装独立的docker-compose二进制文件。Harbor的安装脚本需要调用docker-compose命令。# 下载特定版本这里以v2.24.5为例 sudo curl -L https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 赋予执行权限 sudo chmod x /usr/local/bin/docker-compose # 验证安装 docker-compose --version3.2 规划存储与网络存储路径Harbor的数据镜像文件、数据库、配置文件默认会存储在/data目录下。你需要确保该路径有足够的磁盘空间建议至少100GB视镜像数量而定。你也可以在配置中修改这个路径。网络与防火墙Harbor默认监听80HTTP和443HTTPS端口。确保服务器的防火墙如ufw或firewalld开放了这些端口并且外部网络能够访问到服务器的IP或域名。# 如果使用ufw sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw reload域名与SSL证书强烈推荐在生产环境务必使用HTTPS。你需要一个域名例如harbor.yourcompany.com和对应的SSL证书可以是来自Let‘s Encrypt的免费证书或企业购买的证书。Harbor支持自动生成自签名证书但仅适用于测试环境客户端需要额外配置信任该证书较为麻烦。4. Harbor安装与配置详解一切准备就绪现在开始安装Harbor。我们将采用离线安装包的方式这样更稳定不依赖外网。4.1 下载与解压Harbor访问Harbor的GitHub Releases页面例如https://github.com/goharbor/harbor/releases找到最新的稳定版本。本文以v2.10.0为例。下载离线安装包和对应的校验文件。cd /tmp wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz.sha256sum # 校验文件完整性 sha256sum -c harbor-offline-installer-v2.10.0.tgz.sha256sum解压到安装目录例如/opt。sudo tar xzf harbor-offline-installer-v2.10.0.tgz -C /opt cd /opt/harbor4.2 关键配置文件harbor.ymlHarbor的所有配置都集中在harbor.yml文件中。首次安装时需要复制模板并修改。sudo cp harbor.yml.tmpl harbor.yml sudo vim harbor.yml下面是最关键的一些配置项你需要根据实际情况修改# 主机名必须设置为访问Harbor的域名或IP。这是最重要的配置 hostname: harbor.yourcompany.com # 或你的服务器IP如 192.168.1.100 # HTTP相关配置生产环境建议关闭HTTP只使用HTTPS http: port: 80 # HTTPS相关配置生产环境必须启用 https: port: 443 # 你的证书和私钥的路径 certificate: /your/certificate/path/harbor.yourcompany.com.crt private_key: /your/private/key/path/harbor.yourcompany.com.key # Harbor管理员初始密码。首次登录后请立即修改 harbor_admin_password: Harbor12345 # 数据持久化目录 data_volume: /data # 数据库配置通常使用内部PostgreSQL无需修改除非你有外部数据库 database: password: root123 max_idle_conns: 50 max_open_conns: 100 # 数据表清理作业的周期默认每天凌晨2点 jobservice: max_job_workers: 10 # 通知可选可集成邮件、Webhook等 notification: webhook_job_max_retry: 10 # 日志级别 log: level: info local: rotate_count: 50 rotate_size: 200M location: /var/log/harbor # 版本控制默认false如果从旧版升级需设置为true _version: 2.10.0重要提示hostname配置至关重要。客户端Docker Daemon在登录和推送/拉取镜像时会使用这个主机名来访问Harbor。如果这里填IP客户端就必须用IP如果填域名客户端必须能解析这个域名。配置错误会导致客户端无法认证或操作镜像。4.3 执行安装脚本配置好harbor.yml后运行安装脚本。脚本会解析配置文件拉取必要的Docker镜像并启动所有服务。sudo ./install.sh如果一切顺利你将看到类似✔ ----Harbor has been installed and started successfully.----的输出。安装完成后Harbor的所有服务nginx, portal, core, jobservice, registry, redis, database等都会以容器的形式运行。你可以通过sudo docker-compose ps命令查看所有容器的状态。5. 初始化访问与基础管理安装成功后打开浏览器访问你配置的地址如https://harbor.yourcompany.com。由于是自签名证书或首次访问浏览器可能会提示安全风险选择继续访问即可。5.1 首次登录与修改密码使用默认用户名admin和你在harbor.yml中配置的harbor_admin_password例如Harbor12345登录。登录后第一件事立即在右上角用户菜单中修改管理员密码这是最基本的安全要求。5.2 创建项目与用户Harbor的核心组织单元是“项目”Project。镜像仓库Repository隶属于项目。通常我们会为不同的团队或产品线创建不同的项目。创建项目点击“项目” - “新建项目”。输入项目名称例如backend-team。“访问级别”选择“公开”或“私有”。公开项目所有用户包括未登录的都可以拉取镜像私有项目只有项目成员才能拉取。勾选“启用内容信任”和“自动扫描镜像”可以根据安全需求选择。创建用户与分配权限点击“系统管理” - “用户管理” - “新建用户”。填写用户名、邮箱、密码等信息。创建用户后进入具体的项目如backend-team点击“成员” - “用户”将用户添加进来并赋予相应的角色如“项目管理员”、“开发人员”、“访客”。“开发人员”可以推送和拉取镜像“访客”只能拉取“项目管理员”拥有项目的全部管理权限。6. 客户端配置与日常使用服务器端搭建好了现在需要让开发机器或CI服务器能够使用这个私有仓库。6.1 配置Docker Daemon信任私有仓库由于我们使用了自签名证书或在测试时用了HTTPDocker Daemon默认不信任这样的仓库需要在客户端进行配置。对于使用HTTPS自签名证书的情况将Harbor服务器上的CA证书或你的自签名证书拷贝到客户端机器的信任目录。# 在Harbor服务器上证书通常在 /data/cert/ 或你配置的路径下 # 假设证书文件是 harbor.yourcompany.com.crt # 将其拷贝到客户端例如 /usr/local/share/ca-certificates/ sudo cp harbor.yourcompany.com.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates告诉Docker Daemon信任这个仓库。编辑/etc/docker/daemon.json文件如果不存在则创建。{ insecure-registries: [], registry-mirrors: [], exec-opts: [native.cgroupdriversystemd], log-driver: json-file, log-opts: { max-size: 100m }, storage-driver: overlay2 }关键点如果你使用的是企业CA签发的证书或Let‘s Encrypt证书Docker默认是信任的无需将仓库添加到insecure-registries。只有使用自签名证书时才需要添加。但更推荐的做法是正确部署受信任的证书避免使用insecure-registries这是一个安全风险。对于测试环境使用HTTP的情况不推荐 必须在daemon.json中明确声明该仓库为不安全。{ insecure-registries: [harbor.yourcompany.com:80, 192.168.1.100:80] }修改后重启Docker服务sudo systemctl restart docker6.2 登录、推送与拉取镜像登录到私有仓库docker login harbor.yourcompany.com # 输入你在Harbor创建的用户名和密码登录成功后凭证会保存在~/.docker/config.json中。给本地镜像打标签 Docker镜像的完整名称格式为仓库地址/项目名/镜像名:标签。# 假设我们有一个本地镜像叫 my-app:v1.0 docker tag my-app:v1.0 harbor.yourcompany.com/backend-team/my-app:v1.0推送镜像到私有仓库docker push harbor.yourcompany.com/backend-team/my-app:v1.0推送时Harbor会自动在backend-team项目下创建名为my-app的仓库。从私有仓库拉取镜像docker pull harbor.yourcompany.com/backend-team/my-app:v1.0在WebUI中查看 刷新Harbor的Web界面进入backend-team项目你就能看到刚刚推送的my-app仓库及其v1.0标签。7. 进阶配置与运维要点基础功能跑通后为了满足生产要求还需要关注以下方面。7.1 启用内容信任Notary内容信任Docker Content Trust, DCT机制允许对镜像标签进行数字签名确保拉取的镜像来自可信的发布者且未被篡改。Harbor集成了Notary服务来提供此功能。在项目设置中启用“内容信任”。推送镜像时客户端需要设置环境变量DOCKER_CONTENT_TRUST1。export DOCKER_CONTENT_TRUST1 export DOCKER_CONTENT_TRUST_SERVERhttps://harbor.yourcompany.com:4443 docker push harbor.yourcompany.com/backend-team/my-app:signed-v1.0首次使用会生成本地密钥。启用后拉取未签名的标签将会失败。7.2 配置漏洞扫描Harbor集成了Trivy、Clair等扫描器。以Trivy为例默认集成在“系统管理” - “漏洞扫描器”中确保Trivy扫描器是“启用”状态。在项目或仓库级别可以配置“自动扫描”每当有新的镜像被推送时自动触发漏洞扫描。扫描完成后在镜像详情页可以看到漏洞列表按照严重级别Critical, High, Medium, Low分类并给出修复建议。7.3 配置镜像复制如果你有多个Harbor实例例如北京和上海机房或者需要将镜像同步到公有云仓库可以使用复制功能。在“系统管理” - “注册表管理”中新建一个目标注册表另一个Harbor实例或Docker Hub等。在“复制管理”中新建复制规则。选择源项目、目标注册表和目标项目并选择触发的资源如所有镜像或带特定标签的镜像和触发方式手动、定时、事件驱动。7.4 备份与恢复Harbor的数据包括镜像文件存储在配置的data_volume目录下的registry目录中。数据库存储在database容器卷中对应data_volume下的database目录。配置文件就是你的harbor.yml。备份步骤停止Harbor服务cd /opt/harbor sudo docker-compose down备份整个数据目录和配置文件sudo tar czf harbor-backup-$(date %Y%m%d).tar.gz /data /opt/harbor/harbor.yml启动Harbor服务sudo docker-compose up -d恢复步骤停止Harbor服务。将备份文件解压到原路径。运行Harbor的准备工作脚本会恢复数据库结构等sudo ./prepare启动Harbor服务。8. 常见问题与故障排查实录在实际搭建和运维过程中你几乎一定会遇到下面这些问题。这里记录了我的踩坑实录和解决方法。8.1 客户端登录失败Error response from daemon: Get “https://harbor.yourcompany.com/v2/“: x509: certificate signed by unknown authority问题Docker客户端不信任Harbor服务器的SSL证书。排查确认你访问的地址harbor.yourcompany.com与harbor.yml中的hostname完全一致。确认证书是否正确部署。可以尝试用curl -v https://harbor.yourcompany.com检查证书链。解决方案一推荐生产环境为你的域名申请一个受信任的CA签发的证书如Let‘s Encrypt免费证书并正确配置到Harbor和Nginx。方案二测试环境将Harbor的CA证书或自签名证书添加到客户端的系统信任链并重启Docker如前文6.1节所述。切勿在生产环境使用insecure-registries绕过证书验证。8.2 推送镜像失败denied: requested access to the resource is denied问题权限不足。排查是否已执行docker login用cat ~/.docker/config.json查看当前登录状态。登录的用户是否有目标项目的推送权限例如用户可能只是“访客”角色。镜像的标签格式是否正确必须是仓库地址/项目名/镜像名:标签。项目名必须存在且用户有权限。解决重新登录docker logout harbor.yourcompany.com docker login harbor.yourcompany.com。在Harbor WebUI中检查该用户是否在目标项目中并且角色是“开发人员”或“项目管理员”。8.3 Harbor服务启动失败docker-compose up报错特别是数据库相关问题可能是之前的安装残留或配置文件错误。排查查看具体容器的日志sudo docker-compose logs -f [服务名如 core, database]。常见错误是数据库连接失败或初始化失败。解决彻底清理旧数据危险操作会删除所有镜像和配置仅用于测试环境重装cd /opt/harbor sudo docker-compose down -v # -v 会删除数据卷 sudo rm -rf /data/database /data/registry /data/redis ...再次检查harbor.yml配置文件特别是hostname和数据库密码。重新运行sudo ./install.sh。8.4 磁盘空间不足问题随着镜像增多/data目录所在磁盘被占满。排查使用df -h和du -sh /data/*查看磁盘使用情况。解决清理无用镜像在Harbor WebUI中可以手动删除不再需要的镜像标签。Harbor的“垃圾回收”功能可以清理未被任何标签引用的镜像层Blobs。设置保留策略在项目配置中可以设置“标签保留规则”自动清理早于一定天数的标签。扩容存储规划初期就应为/data目录挂载大容量存储或使用网络存储如NFS、Ceph。Harbor支持配置外部存储如S3、Azure Blob、Swift、Google Cloud Storage这是生产环境的最佳实践需要在harbor.yml中配置storage_service部分。8.5 WebUI访问缓慢或无法加载问题可能是浏览器缓存、前端资源加载问题或后端服务异常。排查检查所有容器是否正常运行sudo docker-compose ps。查看状态是否为Up。检查core和portal服务的日志。解决清除浏览器缓存或使用无痕模式访问。重启Harbor服务cd /opt/harbor sudo docker-compose restart。如果问题持续检查服务器资源CPU、内存是否充足。Harbor在镜像推送/拉取高峰时对资源有一定消耗。搭建和维护一个高可用的私有Docker Registry特别是像Harbor这样的成熟方案远不止是运行几条安装命令。它涉及到网络、存储、安全、权限和日常运维的方方面面。从最初的单机测试到最终承载整个公司的容器镜像流转这个过程让我深刻体会到基础设施的稳定性和易用性是研发效能的一块基石。把镜像仓库这件“小事”做扎实了后续的CI/CD、自动化部署、环境治理才会顺畅。如果你在搭建过程中遇到了上面没覆盖到的问题我的建议永远是第一时间查看日志docker-compose logs是你最好的朋友它能告诉你服务内部究竟发生了什么。