Harbor 是一个开源的企业级容器镜像仓库（Container Registry），最初由 VMware 开发，后捐赠给 CNCF，现为 CNCF 毕业项目。它并不是从零实现镜像存储协议，而是基于 Docker Distribution（Registry V2）构建，在原生镜像存储与分发能力之上，增加了企业所需的权限管理、项目管理、镜像复制、漏洞扫描、审计日志、配额与保留策略、内容信任和图形化界面等功能。因此，可以把 Harbor 理解为：Docker Registry 的存储底座 + 企业级控制平面 + 安全与异步任务体系。

一、Harbor 是什么

Harbor 的核心仍然是 OCI/Docker Registry 的存储分发协议，支持 Docker 镜像和 OCI Artifact。它在原生 Registry 外面包了一层企业级管理平面，使用户可以：

  • 通过 Web UI 管理项目、用户、镜像和策略；
  • 使用 RBAC 做细粒度权限控制；
  • 集成 LDAP/AD/OIDC 做统一身份认证；
  • 配置镜像复制，实现多机房、多集群、跨云同步；
  • 使用 Trivy 或 Clair 做 CVE 漏洞扫描；
  • 通过 Notary/Cosign 做镜像签名与内容信任；
  • 设置存储配额和 Tag 保留策略，防止磁盘无限增长；
  • 查看审计日志，满足安全合规要求。

一句话概括：Harbor = Registry（存储） + Core（管控） + Scanner（安全） + JobService（异步任务） + 数据库/缓存/前端，通过 Token 鉴权实现控制面与数据面分离。

二、核心原理与架构

1. 设计哲学：控制面与数据面分离

Harbor 的关键设计思想是：元数据、鉴权、策略属于控制面；镜像 Blob 和 Manifest 的实际传输属于数据面。

  • 控制面：Portal、Core、PostgreSQL、Redis、JobService 等，负责用户、项目、权限、策略、扫描结果、复制规则。
  • 数据面：Docker Registry V2，负责镜像层的读写和按层拉取。
  • 统一入口：Nginx / Ingress 反向代理，接收浏览器、Docker 客户端、CI/CD 脚本的请求，并根据路径分发到后端服务，同时处理 TLS 终止。

这种分离让 Harbor 可以在不重造镜像存储协议的前提下，叠加企业能力。

2. 整体架构图

用户 / Docker CLI / Podman / Kubernetes / CI-CD
                │
                ▼
        Nginx / Ingress（反向代理、TLS、路由）
                │
    ┌───────────┼────────────┬─────────────┐
    ▼           ▼            ▼             ▼
 Portal       Core       Registry       JobService
 Web UI     业务逻辑     镜像存储       异步任务
                │            │             │
                └──────┬─────┴──────┬──────┘
                       ▼            ▼
                 PostgreSQL       Redis
                 元数据库       缓存/队列
                       │
                       ▼
              存储后端：本地文件系统 / S3 / OSS / GCS / Swift / NFS

3. 主要组件详解

组件作用原理说明
Nginx / Ingress反向代理所有外部请求的统一入口，按 URI 分发到 Core、Registry、Portal，处理 TLS。
PortalWeb 管理界面基于 Angular 的前端，用于管理项目、用户、镜像、复制、扫描、配置。
Core核心业务组件处理认证、权限校验、项目管理、配额、Tag 保留策略等元数据操作，不直接存储镜像层。
Registry (Docker Distribution)镜像存储与分发原生 Docker Registry V2 实现，负责 Blob 和 Manifest 的实际读写。Harbor 对其封装以集成鉴权。
JobService异步任务调度执行镜像复制、垃圾回收、扫描触发、日志导出等耗时任务，从 Redis 队列获取任务。
PostgreSQL元数据存储存储用户、项目、角色、镜像标签、扫描结果、复制策略、配置等结构化数据。
Redis缓存与队列缓存会话、Token、Registry 元数据，并作为 JobService 的任务队列。
Trivy / Clair安全扫描异步扫描镜像中的 CVE 漏洞，结果写入数据库，支持手动和自动扫描。
Notary / Cosign内容信任提供镜像签名验证，确保镜像未被篡改且来源可信。
ChartMuseum / Helm旧版 Helm Chart 托管历史版本用于管理非 OCI 的 Helm Chart，现已逐步被 OCI Artifact 支持取代。

4. 关键工作流程

（1）Push/Pull 鉴权流程

当客户端执行 docker push 或 docker pull 时：

  1. 请求先到达 Nginx / Ingress；
  2. 请求被转发到 Core Service 进行 Token 验证和权限检查；
  3. 通过后，Core 生成临时 Bearer Token；
  4. 客户端携带 Token 访问 Registry 服务；
  5. Registry 完成实际的镜像层与 Manifest 传输。

这样，控制平面负责“能不能传”，数据平面负责“怎么传”，既复用了 Docker Distribution 的能力，又实现了企业级鉴权。

（2）垃圾回收（GC）

Harbor 采用 Mark-and-Sweep 机制。Registry 只负责存文件，并不知道哪些镜像在业务上已被逻辑删除。因此需要 JobService 比对数据库中的元数据和 Registry 中的物理文件，标记并清理孤儿 Blob。

注意：GC 期间默认会阻止新的 Push 操作，进入只读模式。生产环境建议在低峰期执行，或使用非阻塞 GC 版本。

（3）镜像复制

复制支持基于 Tag、Label 或正则表达式的过滤规则，也支持手动、定时、事件驱动触发。JobService 拉取源端 Manifest 和 Blob，推送到目标端，并同步元数据。支持断点续传和并发传输，适用于多数据中心、灾备、跨区域分发。

（4）漏洞扫描

Harbor 从 2.0 版本起默认集成 Trivy。扫描器适配器将 Harbor 的扫描 API 翻译为 Trivy 命令，对镜像进行静态分析，生成 CVE 报告。可在项目配置中勾选“自动扫描镜像”，推送后自动扫描；也可在镜像详情页手动触发。

三、关键设计概念

1. 项目（Project）

Harbor 用“项目”代替扁平的仓库命名空间。每个项目是权限隔离单元，分为：

  • 公开项目（Public）：任何人可拉取，仅成员可推送。
  • 私有项目（Private）：仅授权成员可访问。

推送镜像前必须先在 Harbor 创建项目，Harbor 不会自动创建。

2. 基于角色的权限（RBAC）

项目内常见角色包括：访客（Guest）、开发者（Developer）、维护者（Maintainer）、项目管理员（Project Admin）。建议遵循最小权限原则，CI/CD 机器人账号仅授予 Developer 权限。

3. 机器人账号

项目可创建机器人账号，生成 robot$项目+名称 的专用拉取/推送凭证。CI/CD 推荐使用机器人账号，而不是个人密码。

4. 镜像复制

支持两个 Harbor 实例之间，或对接 Docker Hub、阿里云 ACR、GCR 等远程仓库。可配置源仓库、目标仓库、触发模式、过滤条件。支持“基于推送”和“基于拉取”两种方向。

5. 安全扫描与门禁

可配置“阻止严重漏洞镜像拉取”。当 Trivy 扫描出 High/Critical 漏洞时，禁止部署或拉取，满足安全合规。

6. 内容信任

通过 Notary 或 Cosign 支持镜像签名。客户端可配置只运行已签名镜像，确保供应链安全。

7. 配额与保留策略

  • 存储配额：按项目限制容量，防止个别项目撑爆磁盘。
  • Tag 保留策略：如“每个仓库最多保留最近 10 个 Tag”或“保留最近 N 天”，自动清理旧镜像。
  • GC 清理：删除镜像后 Blob 不会立即释放，需要运行垃圾回收。

四、部署与安装

1. 前置条件

  • Docker 与 Docker Compose；
  • 开放端口：80/443（UI/API）、4443（Notary，可选）；
  • 生产环境建议使用 HTTPS 和受信任证书。

2. 快速部署（Docker Compose 离线安装包）

# 下载离线安装包（示例 v2.11）
wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar xvf harbor-offline-installer-v2.11.0.tgz
cd harbor

# 生成并编辑配置
cp harbor.yml.tmpl harbor.yml
vim harbor.yml

harbor.yml 关键配置：

hostname: harbor.example.com          # 必须填客户端可访问的地址
https:                                # 生产建议开启 HTTPS
  port: 443
  certificate: /your/cert.crt
  private_key: /your/cert.key
harbor_admin_password: Harbor12345    # 默认管理员密码，务必修改
database:
  password: root123
data_volume: /data                    # 镜像和元数据存储位置

# 启动（含 Trivy 扫描器）
./install.sh --with-trivy

# 管理命令
docker compose stop / start / restart

首次登录 Web 界面：https://<hostname>，账号 admin。

3. 生产与 Kubernetes 部署

生产环境推荐使用 Helm Chart 部署到 Kubernetes，支持：

  • 高可用：多副本 Core / Registry / Portal / JobService；
  • 对象存储后端：S3、OSS、GCS 等；
  • 外部 PostgreSQL 和 Redis；
  • TLS 证书管理；
  • 负载均衡与 Ingress。

Harbor 的大多数组件是无状态的，因此高可用核心思路是：状态外置 + 多实例部署 + 负载均衡。将 PostgreSQL、Redis 和对象存储做成高可用服务，前端通过负载均衡器分发流量，即可实现弹性扩展和故障容错。

五、日常使用

1. 登录、打标签、推送、拉取

# 登录
docker login harbor.example.com

# 打标签（必须包含项目名）
docker tag nginx:1.25 harbor.example.com/myproject/nginx:1.25

# 推送
docker push harbor.example.com/myproject/nginx:1.25

# 拉取
docker pull harbor.example.com/myproject/nginx:1.25

若使用自签证书，需要让客户端信任 CA：

  • 方式 A：拷贝 ca.crt 到 /etc/docker/certs.d/harbor.example.com/ca.crt；
  • 方式 B：配置 insecure-registries，仅测试环境使用。

2. Kubernetes 集成

创建 imagePullSecret：

kubectl create secret docker-registry harbor-secret \
  --docker-server=harbor.example.com \
  --docker-username=robot$myproject+deployer \
  --docker-password=<token> \
  -n myns

在 Deployment 中引用：

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      imagePullSecrets:
        - name: harbor-secret
      containers:
        - name: app
          image: harbor.example.com/myproject/nginx:1.25

如果 Harbor 使用自签名 HTTPS 证书，还需要将 CA 证书加入所有 K8s 节点的信任库，或配置 containerd 跳过 TLS 验证（不推荐生产使用）。

3. 常用高级功能

功能使用方式
机器人账号项目 → 机器人账号，生成专用拉取/推送凭证，CI/CD 推荐
镜像复制系统管理 → 仓库管理 → 复制管理，建规则实现跨机房同步
漏洞扫描项目 → 配置管理 → 勾选“自动扫描镜像”，推送后自动 Trivy 扫描
镜像保留策略项目 → 策略 → 保留规则，如“每个仓库最多保留 10 个最近 Tag”
存储配额项目 → 配置容量上限，防止个别项目撑爆磁盘
GC 清理删除镜像后运行垃圾回收，释放 Blob
P2P 分发集成 Dragonfly/Kraken，解决大规模节点同时拉取镜像的带宽瓶颈
审计日志查看完整操作记录，满足合规要求

六、与裸 Docker Registry 的对比

维度Docker RegistryHarbor
权限管理基本 Token 认证RBAC、项目隔离、LDAP/AD/OIDC 集成
Web UI无有
漏洞扫描无内置 Trivy
镜像复制无跨实例/跨云同步
存储配额/清理无有
审计日志无完整操作日志
内容信任需自行集成Notary/Cosign 支持
高可用与扩展需自行设计Helm + 对象存储 + 多实例

相比 Docker Hub、GitLab Container Registry、Quay 等方案，Harbor 在中国区网络友好度、中文文档完善度、多云复制能力方面具有显著优势，是国内企业私有化镜像仓库的首选方案之一。

七、常见问题与排查

  1. http: server gave HTTP response to HTTPS client
    Docker 客户端默认使用 HTTPS。需在 daemon 配置 insecure-registries，或配置受信任证书。

  2. 项目不存在
    推送前必须先在 Harbor 创建项目，Harbor 不会自动创建。

  3. 磁盘没被释放
    删除 Tag 后需执行垃圾回收（GC），且 GC 期间需停止推送或进入只读模式。

  4. 复制不同步
    检查两端证书信任、网络连通性，查看 JobService 日志排查。

  5. Push 失败 413
    Nginx 或 Ingress 的 client_max_body_size 限制，需调大至 0 或足够值。

  6. GC 卡住
    检查 Redis 连接及 JobService 日志，确认是否有未完成的删除任务阻塞队列。

  7. 存储增长过快
    确认是否开启在线 GC 或定期离线 GC；检查是否误将构建缓存当作镜像存储。

  8. HTTPS 证书问题
    自签证书需将 CA 加入系统信任链，或在 Docker daemon 配置 insecure-registries。

八、企业级最佳实践

场景推荐配置说明
安全合规开启“阻止严重漏洞镜像拉取”Trivy 扫描出 High/Critical 漏洞时禁止部署
身份认证集成 OIDC/LDAP/AD避免共享 admin 密码，统一身份管理
权限控制最小权限原则CI/CD 机器人账号仅授予 Developer 权限
镜像瘦身配置 Tag Retention Policy自动保留最近 N 个版本或 N 天内的镜像
多集群分发P2P 分发 Dragonfly/Kraken解决大规模节点同时拉取镜像的带宽瓶颈
备份恢复元数据 + 对象存储分离备份DB 用 pg_dump 定时备份；镜像数据依赖 S3 版本控制或跨区域复制
高可用共享存储 + 多实例Core/Registry 无状态化，DB/Redis 使用托管服务或 Operator，存储使用 S3/GCS
生产部署必须 HTTPS使用受信任证书，避免中间人攻击和客户端信任问题
垃圾回收低峰期执行GC 默认阻塞 Push，建议在业务低峰或使用非阻塞 GC

九、总结

Harbor 的原理可以概括为：

以 Docker Distribution 为镜像存储底座，通过 Core 服务叠加企业级管理与安全能力，用 JobService 处理异步任务，用 PostgreSQL/Redis 管理元数据与队列，最终由 Nginx/Ingress 统一对外暴露服务。

其核心优势在于控制面与数据面分离、项目与 RBAC 权限模型、镜像复制、漏洞扫描、内容信任、配额与保留策略、审计日志和高可用扩展能力。

使用时，核心操作围绕项目、用户、机器人账号、镜像标签、复制规则、扫描策略和保留策略展开；与 Kubernetes 集成则通过 ImagePullSecret 打通拉取链路。生产环境务必配置 HTTPS、启用漏洞扫描门禁、设置 Tag 保留策略、将存储后端对接对象存储，并采用外部数据库 + 共享对象存储的多实例高可用部署模式。

对于需要私有化、安全合规、多集群分发和统一镜像治理的企业来说，Harbor 是目前最成熟、生态最完善的开源企业级容器镜像仓库方案之一。

# docker
Logo
DAMO开发者矩阵

DAMO开发者矩阵，由阿里巴巴达摩院和中国互联网协会联合发起，致力于探讨最前沿的技术趋势与应用成果，搭建高质量的交流与分享平台，推动技术创新与产业应用链接，围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐

cover

谈谈多Agent架构核心特性与应用

avatar DAMO开发者矩阵
cover

人形机器人整机与系统标准

avatar DAMO开发者矩阵
cover

人形机器人应用标准

avatar DAMO开发者矩阵