harbor | 人民万岁

type

Post

status

Published

date

Jun 14, 2025

slug

harbor

summary

Harbor简介

Harbor 是一个 CNCF 基金会托管的开源的可信的云原生 docker registry 项目，可以用于存储、签名、扫描镜像内容，Harbor 通过添加一些常用的功能如安全性、身份权限管理等来扩展 docker registry 项目，此外还支持在 registry 之间复制镜像，还提供更加高级的安全功能，如用户管理、访问控制和活动审计等，在新版本中还添加了 Helm 仓库托管的支持。官方地址：https://goharbor.io

Harbor 最核心的功能就是给 docker registry 添加上一层权限保护的功能，要实现这个功能，就需要我们在使用 docker login、pull、push 等命令的时候进行拦截，先进行一些权限相关的校验，再进行操作，其实这一系列的操作 docker registry v2 就已经为我们提供了支持，v2 集成了一个安全认证的功能，将安全认证暴露给外部服务，让外部服务去实现

核心特性

基于角色的访问控制 (RBAC): Harbor 允许管理员精细地控制用户对镜像仓库的访问权限。用户和仓库按项目组织，每个用户在项目内可以被赋予不同的角色，如管理员、开发者或访客，确保只有授权用户能访问特定资源。 镜像复制策略: Harbor 支持在多个实例间复制镜像，这使得跨数据中心或地理区域的镜像分发变得简单高效，有助于实现负载均衡和容灾备份。 安全特性: 包括镜像漏洞扫描，通过集成第三方工具自动检测镜像中的已知安全漏洞；镜像签名功能，确保镜像的完整性和来源可信。 LDAP/AD集成: 无缝对接企业现有的轻量目录访问协议(LDAP)或活动目录(AD)，简化用户认证与权限管理流程，便于在大型企业环境中实施统一的身份认证。 LDAP（轻量级目录访问协议）和AD（Active Directory）集成是企业IT环境中常见的身份验证和授权策略，用于集中管理用户访问各种服务和系统的权限。当涉及到像Harbor这样的容器镜像仓库时，集成LDAP或AD能够让组织利用现有的用户目录服务，实现统一的身份认证和权限控制 审计日志: 记录详细的用户操作日志，包括镜像上传、下载、删除等，有助于合规性和问题排查。 可扩展性与自定义: Harbor 设计上支持模块化，可以根据需要扩展存储、认证和日志等组件，以适应不同规模和复杂度的部署场景。 用户友好的界面: 提供直观的Web UI，使用户无需深入了解底层技术就能执行日常的镜像管理任务，同时也支持命令行工具，满足自动化和脚本化需求。 镜像策略管理: 用户可以根据标签、命名规则等条件设定镜像的保留策略，自动清理过时或不再需要的镜像，节省存储空间。

Harbor组成部分

Proxy (Nginx)：Harbor 使用 Nginx 作为前端代理服务器，负责接收所有客户端请求（包括浏览器和Docker客户端的请求），并将它们路由到后端的不同服务，比如UI、Registry等。它还处理SSL/TLS加密，确保通信安全。

Registry：这是存储Docker镜像的核心服务。Registry 负责处理镜像的上传（push）和下载（pull）请求。为了实施访问控制，Registry与token服务协同工作，要求每次镜像操作都必须携带有效的token进行权限验证。认证方式有以下三种：令牌认证: 这是最主要的方式，用户在与Registry交互前需获取一个临时的Token，这个Token包含访问权限信息，并在请求中携带以完成认证。基本认证: 这种方式通常涉及用户名和密码，用户凭据会被Base64编码后随HTTP请求头部发送。虽然直接使用用户名密码不太安全，但在某些场景或旧版本的Registry中，可能会用到这种方式。不过，现代做法更倾向于使用Token机制来增加安全性。 SSL/TLS客户端证书认证: SSL/TLS不仅用于加密通信，还可以与客户端证书一起实现用户认证。客户端证书是一种数字证书，证明了客户端（如Docker引擎）的身份。这种方式下，Registry会要求客户端在建立连接时出示证书，从而验证客户端的身份。

Core services：Harbor的核心功能，主要提供以下3个服务: UI (用户界面): 提供了一个图形化的管理界面，允许用户轻松地浏览、上传、下载和管理存储在Registry中的Docker镜像。同时，UI还支持用户权限管理、项目管理和镜像复制任务的配置 WebHook：为了及时获取Registry上image 状态变化的情况，在Registry 上配置 Webhook，把状态变化传递给 UI 模块。 Token 服务：负责根据用户权限给每个 Docker push/pull 命令签发 Token。Docker 客户端向 Registry 服务发起的请求，如果不包含 Token，会被重定向到 Token 服务，获得 Token 后再重新向 Registry 进行请求

Database：存储用户权限信息、审计日志、Docker镜像分组信息等元数据。Harbor使用MySQL或其他兼容数据库来持久化这些信息。

JobService：负责镜像复制工作，支持在多个Registry节点间复制镜像。它从一个Registry拉取镜像，然后推送到另一个Registry，并记录操作日志，支持镜像的分发和备份策略。

Log Collector：负责收集Harbor各组件的日志信息，通常通过Docker的log-driver机制，将日志汇聚并记录到syslog或其他日志存储系统，便于日志管理和分析，提高系统监控与故障排查的效率。

AdminServer：系统的配置管理中心，负责管理Harbor的全局配置，包括存储用量检查、以及为UI和jobService提供配置信息。它是Harbor运行时的配置和管理后台。

这些组件共同协作，为用户提供了一个全方位的容器镜像管理解决方案，涵盖了安全、访问控制、镜像复制、日志记录等多个层面，满足企业对于私有容器镜像仓库的高级需求

harbor 部署

Harbor 的每个组件都是以容器的形式构建的，因此，使用 Docker Compose 来对它进行部署。总共分为7个容器运行，通过在docker-compose.yml所在目录中执行 docker-compose ps 命令来查看，名称分别为：nginx、harbor-jobservice、harbor-ui、harbor-db、harbor-adminserver、registry、harbor-log。 nginx：作为反向代理，处理所有进入Harbor的HTTP(S)请求，负责路由到各个服务，并且处理SSL证书。 harbor-jobservice：负责执行一些后台任务，比如镜像的复制、垃圾回收等。 harbor-ui：提供Web界面，用户可以通过UI与Harbor交互，进行镜像的浏览、搜索、上传、下载等操作。 harbor-db：存储Harbor的元数据，如用户、项目、标签信息等。通常使用PostgreSQL或MySQL数据库。 harbor-adminserver：这是一个关键组件，它作为配置管理和API服务，harbor-ui与之交互来获取或更新配置信息。它管理着系统的配置数据，比如用户权限、项目设置等。 registry：实际存储Docker镜像的组件，基于开源的Docker Registry项目，增加了额外的功能如镜像复制、访问控制等。 harbor-log：集中日志收集和管理服务，方便系统管理员查看和分析各个组件的日志

安装 harbor-offline，下载数据包，或者在官方网站下载完毕之后，上传到服务器当中

将下载的tar包解压

创建Harbor的配置文件

修改harbor.yml配置文件，配置参考

执行install.sh脚本安装harbor，过程会从网上拉取镜像，install完成后会自动启动相关服务

查看服务状态

通过修改 rc.local 文件实现开机自启

浏览器访问harbor，用户名为admin，密码为harbor.yml中指定的密码，默认为Harbor12345

配置安全访问证书

要配置 HTTPS，就必须要创建 SSL 证书。可以使用受信任的第三方 CA 签署的证书，也可以使用自签名证书。创建证书目录并进入到证书目录

生成ca的私钥

生成ca的自签名证书

生成harbor主机的私钥

生成harbor主机的证书申请

生成 x509 v3 扩展文件

使用 v3.ext 给 harbor 主机签发证书

查看该目录下生成的证书文件

配置harbor服务器使用证书，修改 harbor.yml 配置文件

运行prepare脚本以启用 HTTPS

执行install.sh脚本安装Habor

查看服务状态，install完成后，会自动启动相关服务

登录Harbor UI界面，登录地址：https://192.168.209.101，账号默认admin，密码是默认Harbor12345

卸载

在卸载之前，首先停止正在运行的 Harbor 服务。进入之前安装的 Harbor 目录

删除配置文件中配置harbor的存储目录

删除 Harbor 镜像和容器

维护管理Harbor

创建项目

在 Harbor 仓库中，任何镜像在被 push 到 regsitry 之前都必须有一个自己所属的项目。点击新建项目，填写项目名称，项目级别若设置为私有，则不勾选。如果设置为公共仓库，则所有人对此项目下的镜像拥有读权限，命令行中不需要执行 docker login 即可下载镜像

点击 +新建项目 按钮，填写自定义项目名称，点击 确定 按钮，创建新项目

上传镜像

上传镜像前需要先登录 Harbor

当使用客户端机器登录 Harbor 时，Harbor 服务器会拒绝连接请求，这是因为 Harbor 未配置HTTPS。Harbor UI 使用的协议是HTTP。如果 Harbor 实际配置中并未启用HTTPS，而Docker客户端默认尝试通过HTTPS访问，就会出现连接拒绝的问题。以下两种方法，均在客户端进行操作方法一：修改/etc/docker/daemon.json文件

insecure-registries可以翻译为不安全的注册表，是Docker守护进程的一个配置项。当需要Docker与那些未使用HTTPS加密协议的私有镜像仓库进行通讯时，就需要把这个仓库地址添加到insecure-registries列表中。这样一来，尽管这些仓库没有采用安全的HTTPS连接，Docker也能绕过默认的安全检查，继续与其进行不安全的数据传输

方法二：在 Docker server 启动的时候，增加启动参数，默认使用 HTTP 访问

加载后重启服务

再次登录 Harbor，发现登录成功

登录成功之后，会在~/.docker/目录下生成config.json文件，这是一个登录凭据，下次登录时可直接使用凭据登录Harbor

下次登录时可直接使用凭据登录Harbor

下载或使用dockerfile生成镜像，而后进行上传测试，我们这里下载一个busybox镜像进行演示

将镜像打标签

上传镜像到 Harbor

在 Harbor 界面 test 项目下可看见此镜像及相关信息

下载镜像

下载刚才推送到harbor服务上的镜像，因为项目是公开的，所以不需要执行 docker login ，直接下载即可

查看下载到本地的镜像

创建用户

在 Web 管理界面中单击：系统管理 -> 用户管理 -> +创建用户

给创建的用户访问新建项目的角色，在 Web 管理界面中单击项目-->选择需要操作的项目-->选择成员-->点击+成员

项目管理员权限：项目管理员拥有对项目内的镜像最为全面的控制权。这包括上传（push）、下载（pull）、删除（delete）镜像以及查看（view）镜像的权限。此外，项目管理员还可以管理项目内的成员，包括添加或删除用户以及分配用户角色，以及修改项目的设置。 开发人员权限：开发人员可以查看项目内的镜像列表，上传新的镜像版本，以及从项目中下载镜像到本地。这意味着他们有读（read）、写（write，即上传）和查看（pull，即下载）的权限，但通常不具备删除镜像的能力，除非该权限被特别授予。 访客权限：访客的权限较为有限，主要被限制在只读权限上。他们可以查看（view）项目中的镜像列表和标签，以及拉取（pull）镜像，但不允许上传（push）新的镜像到项目中或删除已有镜像。这意味着访客角色适合那些只需要访问和使用镜像，而不参与镜像管理和上传的用户。

登录用户操作

修改Harbor.cfg配置文件

要更改 Harbor的配置文件中的可选参数时，请先停止现有的 Harbor实例并更新 Harbor.cfg；然后运行 prepare 脚本来填充配置；最后重新创建并启动 Harbor 的实例。使用 docker-compose 管理 Harbor 时，必须在与 docker-compose.yml 相同的目录中运行

停止harbor服务

修改可选参数

执行prepare脚本生成harbor各容器服务的配置

启动harbor

镜像仓库空间的清理

项目中每次构建时，会推送容器镜像到 Harbor 镜像仓库。由于是开发环境，构建次数非常多，导致 Harbor 占用的存储空间越来越大。存储空间使用率达到一定阈值后，就会触发磁盘空间使用率的告警。现在希望定期清理掉一些没有 tag 的容器镜像，释放掉一部分磁盘空间占用。当然，这部分容器镜像后续也不会被用到了，可以被删除掉了。

方法一：登录harbor镜像仓库，找到项目 → 选择某个项目（比如library）→ 策略。具体如下图所示：

策略支持多个规则，我这里选择的是第一个默认规则，保留最近推送的5个。然后执行的频率是每周，这个频率看每个人的使用场景。

方法二：登录harbor镜像仓库，点击清理服务 → 垃圾清理

方法三：通过harbor gc执行清理操作执行如下的前提是必须保证harbor是处于stop状态,而不能是down状态

执行如下命令，--dry-run是打印进度而不删除任何数据。如果是down状态，则会报错docker: Error responsefrom daemon: No such container: registry.

当执行这步操作后,如果发现磁盘空间并未减少多少,则只能证明垃圾回收针对删除的image是起作用的,而harbor的blobs依然会占用很大空间并未释放。

Harbor删除镜像后且GC清理后，磁盘空间没有释放。因为我们push大量相同标签的镜像，Docker 镜像由标签引用，并由唯一的摘要标识。这意味着如果myImage使用标记推送两个图像，在DR内部他们显示的不同，它们将由两个不同的digests标识。最后推送的Images是当前的。Docker 镜像由layers组成，每个layers都关联一个blob。该blob是最占用存储的文件; 这些文件将由GC清理。正由上面的描述每个镜像都会存储一个引用，因为，我们重复提交10次，那一个标签在DR中会有10个引用，标签只能获取tag。而其他9个只能用digest获取了。简单的来说就是因为相同的标签的镜像重复提交次数过多导致。

解决方法编辑common/config/registry/config.yml文件，此文件在harbor安装目录下，关闭的目的是为了禁止身份验证

修改 docker-compose.yml 文件，修改此文件的目的是把 registry port 端口暴露出来

重新配置harbor，使其配置生效

清理已删除未使用的清单

清理以删除现在不再与清单关联的blob

把步骤1和步骤2的配置修改回初始状态，并重启harbor。

迁移

首先，安全地停止Harbor服务，避免在迁移过程中产生数据不一致。进入之前安装的 Harbor 目录

备份迁移，所有的项目文件，默认存储在此目录下

进行打包压缩，而后移动到其它服务器上

Harbor高可用

随着harbor越来越多的部署在生产环境，harbor的高可用越来越收到人们的关注。对于大中型企业用，如果只有单示例的Harbor，则一旦发生故障，其从开发到交付的流水线就可能被迫停止，无法满足生产高可用的需求。 harbor的高可用目标是消除单点故障。提高系统的高可用性。

Harbor的高可用方案大致可以分为下面两种：依赖共享存储来保存镜像数据 和 基于不同Harbor服务器间的镜像复制实现。

两个方案的共同点是计算高可用，都是通过lb实现的多主热运行，保证无单点；存储高可用则各有各的方案。一个使用了分布式共享存储，数据可靠性由共享存储provider提供；另外一个则需要harbor自身逻辑参与，通过镜像相互复制的方式保持数据的多副本。

两种方案各有优缺点，就看哪种更适合你的组织以及你手里的资源是否能满足方案的搭建要求。方案1是Harbor开发团队推荐的标准方案，由于基于分布式共享存储，因此其scaling非常好；同样，由于多Harbor实例共享存储，因此可以保持数据是实时一致的。方案1的不足也是很明显的，第一：门槛高，需要具备共享存储provider；第二搭建难度要高于第二个基于镜像复制的方案。方案2的优点就是首次搭建简单。不足也很多：scaling差，甚至是不能，一旦有三个或三个以上节点，可能就会出现“环形复制”；镜像复制需要时间，因此存在多节点上数据周期性不一致的情况；Harbor的镜像复制规则以Project为单位配置，因此一旦新增Project，需要在每个节点上手工维护复制规则，非常繁琐。

Helm部署Harbor

使用 Helm 来安装一个高可用版本的 Harbor。Harbor 的大部分组件都是无状态的，所以我们可以简单增加 Pod 的副本，保证组件尽量分布到多个节点上即可，在存储层，需要我们自行提供高可用的 PostgreSQL、Redis 集群来存储应用数据，以及存储镜像和 Helm Chart 的 PVC 或对象存储。

添加 Chart 仓库地址

更新仓库

拉取1.15.0版本并解压

在安装 Harbor 的时候有很多可以配置的参数，可以在 harbor-helm 项目上进行查看，在安装的时候我们可以通过 --set 指定参数或者 values.yaml 直接编辑 Values 文件即可。比如这里我们使用的是nodeport，通过一个 nfs-client 的 StorageClass 来提供存储，又因为前面我们在安装 GitLab 的时候就已经单独安装了 postgresql 和 reids 两个数据库，所以我们也可以配置 Harbor 使用这两个外置的数据库，这样可以降低资源的使用（我们可以认为这两个数据库都是 HA 模式）。但是使用外置的数据库我们需要提前手动创建数据库，比如我们这里使用的 GitLab 提供的数据库，则进入该 Pod 创建 harbor、notary_server、notary_signer 这 3 个数据库：

部署harbor

查看部署的服务

打开浏览器，访问集群任意ip:30002，账号admin，密码Harbor12345