Harbor：CNCF 云原生容器注册表的技术指南

Harbor 真正解决的不是「存镜像」—— Docker Hub 和云厂商的 ECR / ACR 都能存镜像。Harbor 解决的是：当你的组织需要自建一套镜像仓库，同时还要合规、要权限隔离、要跨数据中心同步、要镜像签名和漏洞扫描这条完整链路时，怎么把这些需求组装成一套可运维的系统。

本文从三个角度展开：

1. 结构层面：Harbor 的组件拆了什么、每层存储怎么配合，让你知道出问题时该看哪个容器日志。
2. 流转层面：一次镜像推送在 Harbor 里经历了什么——认证、存储、扫描、签名、复制，每一步的触发条件和失败后果。
3. 决策层面：什么场景下该用 Harbor 而不是云厂商的托管注册表，部署时副本数、存储选型、灾备策略怎么定。

默认读者已经用过 docker push / docker pull，但对自建注册表的技术选型还不确定。

学习目标

读完本文后，你应能：

• 说清 Harbor 解决的五个问题（分发效率、安全合规、权限控制、多格式支持、审计追溯）以及它和 Docker Hub / ECR / ACR 的边界划在哪里。
• 跟着一次镜像推送走完认证、存储、扫描、签名、复制五条独立链路，定位每条链路失败时该看哪个组件日志。
• 在 Harbor 和云厂商托管注册表之间做选型时，能列出"自建 vs 托管"在合规、多数据中心、RBAC、运维成本四个维度上的真实差异。
• 判断自己的场景该用代理缓存还是复制策略，以及推送模式和拉取模式分别对应什么网络拓扑。

目录

• 2. 项目背景与生态定位
• 3. 核心功能详解
• 4. 系统架构深度解析
• 5. 一次镜像推送的完整流转
• 6. 安装与配置
• 7. 运维管理
• 8. 安全加固
• 9. 最佳实践
• 10. 怎么选、怎么上线
• 11. 常见问题

2. 项目背景与生态定位

2.1 云原生场景下注册表要解决什么

在云原生环境中，容器镜像的存储与管理需要同时面对五个问题：

2.2 Harbor 的定位

Harbor 是什么？

Harbor is an open source trusted cloud native registry project that stores, signs, and scans content.

官方定义：Harbor 是一个开源的可信云原生注册表项目，用于存储、签名和扫描容器镜像及 Helm Chart。

托管方：CNCF（Cloud Native Computing Foundation，云原生计算基金会）

Harbor 的四个关键能力：

┌─────────────────────────────────────────────────────────────┐
│                      Harbor 关键能力                        │
├─────────────────────────────────────────────────────────────┤
│  OCI 兼容：Docker Image + Helm Chart + OCI Artifact         │
│  安全可信：内容签名 + 漏洞扫描 + 权限控制                   │
│  高可用：多主复制 + 故障转移 + 水平扩展                     │
│  易集成：RESTful API + Webhook + Kubernetes Operator        │
└─────────────────────────────────────────────────────────────┘

2.3 竞品对比

3. 核心功能

3.1 功能全景图

┌─────────────────────────────────────────────────────────────────┐
│                         Harbor 功能矩阵                          │
├────────────────┬────────────────┬────────────────┬───────────────┤
│   存储分发      │     安全      │     管理      │    集成     │
├────────────────┼────────────────┼────────────────┼───────────────┤
│ 容器镜像存储    │ 漏洞扫描      │ 多项目管理    │ Kubernetes   │
│ Helm Chart     │ 内容签名      │ RBAC 权限     │ Helm/OCI     │
│ OCI Artifact   │ Notary 信任   │ LDAP/AD 集成  │ RESTful API  │
│ 代理缓存       │ 镜像删除 GC   │ 审计日志      │ Webhook      │
│ 多注册表复制   │ OIDC 单点登录 │ 用户组管理    │ Harbor API   │
└────────────────┴────────────────┴────────────────┴───────────────┘

3.2 云原生注册表

Harbor 作为云原生注册表，支持以下产物类型：

支持的 Helm 版本：Helm 2 / Helm 3，兼容 Chartmuseum。

3.3 基于角色的访问控制（RBAC）

Harbor 采用项目级权限模型：

┌─────────────────────────────────────────────────────────────┐
│                    Harbor 权限模型                          │
├─────────────────────────────────────────────────────────────┤
│  系统级：                                                  │
│  ├── sysAdmin（系统管理员）：管理所有项目、用户、系统配置   │
│  └── anonymous（匿名用户）：只读公共项目                   │
│                                                             │
│  项目级：                                                   │
│  ├── projectAdmin（项目管理员）：管理项目成员、策略         │
│  ├── developer（开发者）：推送/拉取镜像                    │
│  ├── guest（访客）：仅拉取公共/授权镜像                    │
│  └── maintainer（维护者）：高级开发者权限                   │
└─────────────────────────────────────────────────────────────┘

权限继承关系：

3.4 基于策略的复制

Harbor 的复制功能支持多种同步场景：

3.4.1 复制模式

3.4.2 复制过滤器

复制策略配置：
├── 仓库过滤器
│   ├── 仓库名称模式：匹配哪些仓库（如：project/*）
│   └── 排除模式：排除哪些仓库（如：project/internal）
├── 标签过滤器
│   ├── 标签模式：匹配哪些标签（如：release-*）
│   └── 排除模式：排除哪些标签（如：latest）

3.4.3 复制触发器

3.5 漏洞扫描

Harbor 集成 Trivy 作为漏洞扫描器：

3.5.1 扫描流程

镜像推送 → 触发扫描 → 提取 Layer → 对比 CVE 数据库 → 生成报告
                              ↓
                      严重程度分级
                              ↓
                    高危 → 阻止部署策略
                    中危 → 警告
                    低危 → 允许

3.5.2 CVE 严重级别

3.5.3 阻止策略配置

�PROTECTED_5�

3.6 内容签名与 Notary

Harbor 通过 Docker Notary 实现镜像签名：

3.6.1 信任模型

�PROTECTED_6�

3.6.2 签名验证流程

1. 签名阶段：

   • 开发者使用私钥对镜像 tag 进行签名
   • 签名信息随镜像一起存储在 Harbor 中

2. 验证阶段：

   • Docker Client 请求 Harbor 时携带公钥
   • Harbor 返回签名信息
   • Docker Client 验证签名完整性

3. 部署策略：

   • 可配置为「仅允许已签名镜像」
   • K8s Admission Controller 可集成验证

4. 系统架构

4.1 整体架构

Harbor 采用微服务架构，核心组件如下：

�PROTECTED_7�

4.2 核心组件职责

5. 一次镜像推送的完整流转

以「开发者推送一个带签名的镜像到 Harbor，并要求漏洞扫描」为例，把前面讲的组件串起来。

5.1 初始化状态

• Harbor 已部署，hostname 为 �PROTECTED_35�
• 项目 �PROTECTED_36� 已创建，配置了漏洞扫描策略：Critical 级别阻止部署
• 开发者本地已配置 Docker Content Trust

5.2 推送流程

Step 1：认证

�PROTECTED_8�

Docker Client 向 Harbor API 发送认证请求。API 检查凭据（本地数据库或 LDAP/OIDC），生成 JWT Token 返回。后续所有操作都携带此 Token。

Step 2：推送镜像

�PROTECTED_9�

Registry 组件接收推送请求。镜像 Layer 按块写入存储后端（S3 / GCS / 本地文件系统）。每层写入完成后，Registry 向 PostgreSQL 写入一条 blob 记录。

Step 3：触发扫描

镜像 Manifest 写入成功后，Registry 通过内部事件通知 Job Service。Job Service 创建一个扫描任务，交给 Trivy 适配器。Trivy 逐层解压镜像、对比 CVE 数据库，生成漏洞报告写回 PostgreSQL。

如果扫描结果中有 Critical 级别漏洞，Harbor 会在该镜像上标记「不可部署」，并拒绝后续拉取请求（前提是项目已开启阻止策略）。

Step 4：签名

如果开发者启用了 Docker Content Trust：

�PROTECTED_10�

SC Service（签名服务）接收 Notary 请求，将签名元数据存入 Notary 数据库。此后，任何拉取该镜像的客户端如果也开启了 Content Trust，Docker 会自动验证签名链。

Step 5：复制（可选）

如果项目配置了复制策略（例如推送到灾备站点），Job Service 在镜像推送成功后触发复制任务，将镜像同步到目标注册表。复制任务的状态和进度记录在 PostgreSQL 中，可通过 API 或 Portal 查看。

5.3 拉取流程

�PROTECTED_11�

1. Docker Client 携带 Token 向 Harbor API 发起拉取请求。
2. API 验证 Token，检查用户对 �PROTECTED_37� 的权限（至少需要 guest）。
3. API 检查该镜像是否被阻止部署（扫描策略结果）。
4. 通过后，返回 Registry 的 blob 下载地址。
5. Docker Client 从 Registry 拉取各 Layer。

5.4 五条独立链路，一个共享状态

上面这次推送把 Harbor 的五条链路都走了一遍。每条链路都由不同组件执行，但共享 PostgreSQL 和 Redis 里的状态：

• 认证失败 → API 返回 401，后续全部中断。
• 存储完成但扫描失败 → 镜像仍可拉取（除非项目开了阻止策略），漏洞报告缺失。
• 签名失败 → 镜像可用，但 Content Trust 客户端会拒绝拉取。
• 复制失败 → 不影响本地，灾备站点缺这个镜像，Job Service 日志里能看到 pending 任务堆积。

排查时直接对号入座：认证看 API 日志，存储看 Registry 日志，扫描看 Trivy 日志，复制和 GC 看 Job Service 日志。

6. 安装与配置

6.1 系统要求

6.2 Docker Compose 部署

6.2.1 下载安装包

�PROTECTED_12�

6.2.2 配置 harbor.yml

�PROTECTED_13�

6.2.3 启动 Harbor

�PROTECTED_14�

6.3 Kubernetes Helm 部署

6.3.1 添加 Harbor Helm 仓库

�PROTECTED_15�

6.3.2 Helm 配置 values.yaml

�PROTECTED_16�

6.3.3 部署命令

�PROTECTED_17�

6.4 高可用部署

6.4.1 多副本架构

�PROTECTED_18�

6.4.2 推荐配置

7. 运维管理

7.1 用户管理

7.1.1 创建用户

�PROTECTED_19�

7.1.2 LDAP 集成

�PROTECTED_20�

7.2 垃圾回收

7.2.1 GC 策略配置

�PROTECTED_21�

7.2.2 GC 执行策略

7.3 审计日志

7.3.1 可审计事件

7.3.2 日志保留

�PROTECTED_22�

7.4 故障排查

7.4.1 常见问题

7.4.2 日志查看

�PROTECTED_23�

8. 安全加固

8.1 网络安全

�PROTECTED_24�

8.2 证书管理

8.2.1 自签名证书

�PROTECTED_25�

8.2.2 Let’s Encrypt 自动证书

�PROTECTED_26�

8.3 CVE 防护

8.3.1 自动阻断策略

�PROTECTED_27�

8.3.2 安全加固清单

9. 最佳实践

9.1 镜像管理

�PROTECTED_28�

9.2 权限管理

�PROTECTED_29�

9.3 灾备方案

�PROTECTED_30�

10. 怎么选、怎么上线

10.1 什么时候选 Harbor

Harbor 不是「比云厂商注册表更好」的选项，而是适合以下场景：

• 镜像需要留在自有基础设施内（合规要求、数据主权）。
• 多集群、多数据中心之间需要策略驱动的镜像同步。
• 需要免费的漏洞扫描和内容签名，而云厂商这些功能在付费 tier。
• 团队需要项目级 RBAC 隔离，而不是单一 Namespace 的权限模型。

不推荐 Harbor 的场景：

• 你只有 1-2 个集群，团队规模小，镜像量不大——云厂商的托管注册表（ECR、ACR、GCR）运维成本更低。
• 你的组织还没有专人维护基础设施——Harbor 的高可用部署需要维护 PostgreSQL、Redis、存储三层，不是装完就能忘的。

10.2 上线顺序建议

�PROTECTED_31�

10.3 上线后关注什么

• 磁盘：镜像 Layer 只增不减，GC 不是自动执行的。每周检查一次存储使用量，定期触发 GC。
• CVE 数据库：Trivy 的 CVE 库需要定期更新，否则新漏洞扫不出来。Harbor 默认每天更新一次。
• 复制任务积压：如果灾备站点网络不稳定，复制任务会堆积。Job Service 的队列长度是需要监控的关键指标。
• 证书过期：自签名证书和 Let’s Encrypt 证书都有有效期。证书过期会导致所有 �PROTECTED_38� / �PROTECTED_39� 失败，且报错信息不直观。

10.4 官方资源

• 官网：�PROTECTED_70�
• GitHub：�PROTECTED_71�
• 文档：�PROTECTED_72�
• 在线 Demo：�PROTECTED_73�
• Slack：#harbor、#harbor-dev

11. 常见问题

Q1：Trivy 扫不出刚公开的 CVE，是 Harbor 的问题吗？

不是。Trivy 的 CVE 数据库默认每天从 GitHub 拉取一次。今天公开的高危漏洞，Harbor 要到下一次数据库更新才会扫到。如果遇到紧急 CVE，可以手动触发更新：

�PROTECTED_32�

也可以在 �PROTECTED_40� 里调整 �PROTECTED_41� 的 Cron 表达式把频率提到每小时。

Q2：docker push 成功但 docker pull 报 403 forbidden，从哪开始查？

按这个顺序排查三层权限：

1. 用户角色：打开 Portal → 项目 → 成员列表，确认用户至少有 guest 角色。新建用户默认不属于任何项目，需要手动添加。
2. 阻止策略：Portal → 项目 → 策略，看镜像是否被扫描阻止策略标记。如果有 Critical CVE 且项目开了自动阻止，拉取会直接返回 403。
3. Content Trust：如果 �PROTECTED_42�，未签名或签名不匹配的镜像也会被拒绝，但报错信息通常不是 403。用 �PROTECTED_43� 确认签名状态。

Q3：GC 跑完磁盘空间没释放，为什么？

Harbor 的 GC 分两步：先在 PostgreSQL 里把 blob 标记为 deleted，再由 Registry 异步执行实际文件删除。这两个步骤不是原子操作。如果刚跑完 GC 就看磁盘，可能 Registry 还没删完。另外 S3 存储的删除本身有最终一致性延迟。排查方法：去 Job Service 日志 grep �PROTECTED_44�，看 �PROTECTED_45� 是否已经是 �PROTECTED_46�。

Q4：复制任务一直 pending，通常是什么原因？

两种最常见的情况：

1. 目标注册表不可达：先用 �PROTECTED_47� 从 Harbor 所在节点测试连通性和证书。证书过期或自签名证书未加入信任链是最常见的根因。
2. Job Service worker 池被占满：�PROTECTED_48� 看是否有大量 running 状态的任务堆积。可以考虑增加 Job Service 的 �PROTECTED_49�（默认 10）。

Q5：代理缓存和复制有什么区别？什么时候该用哪个？

代理缓存的逻辑是「有人第一次拉，Harbor 从上游缓存一份到本地」，适合加速 Docker Hub 等公共镜像的拉取速度。配置简单，不需要预先指定要缓存哪些镜像。

复制是「按策略主动同步指定镜像到目标站」，适合多数据中心灾备和镜像分发。需要明确指定仓库和 tag 匹配规则。

快速判断：只是想加速 �PROTECTED_50� → 代理缓存。需要跨机房灾备或合规同步 → 复制。

12. 自测：你对 Harbor 理解了多少

以下 4 道题覆盖了 Harbor 的链路协作、权限模型、依赖关系和灾备决策。建议读完文章后独立回答，再对照文中对应章节验证。

1. 链路判断

Harbor 一次镜像推送会经过认证、存储、扫描、签名、复制五条链路。如果扫描链路因为 Trivy 容器 OOM 导致失败，其他四条链路会受影响吗？已经推送成功的镜像还能不能拉取？

2. 权限设计

你的团队有 3 个业务线（订单组、支付组、用户组），每个组需要自己的镜像仓库且组员只能推送自己的镜像，但所有组都能拉取公共基础镜像（如 base/nginx）。你会怎么设计 Harbor 的项目结构和角色分配？

3. 依赖关系

Harbor 依赖 PostgreSQL 存元数据、Redis 存会话和缓存、S3 存镜像文件。如果 PostgreSQL 挂了，哪些操作会直接失败？docker pull 之前已经缓存过的镜像还能成功吗？

4. 灾备决策

你的 Harbor 部署在自建机房，需要在云上部署一个灾备实例。你会选择推送模式还是拉取模式？给出两个关键理由。

练习

练习 1：在本地虚拟机部署一套单节点 Harbor

1. 准备一台 4 核 8GB 的虚拟机（Ubuntu 20.04+）
2. 按照第 6 章步骤，用 Docker Compose 完成 Harbor 安装
3. 创建一个项目 myproject，配置一个开发者用户
4. 从本地 docker push 一个测试镜像到 Harbor，再 docker pull 验证

练习 2：配置跨数据中心的镜像复制

假设你在上海和北京两个机房各有一套 Harbor，完成：

1. 在上海 Harbor 上配置复制策略：推送模式，目标为北京 Harbor
2. 推送一个镜像到上海，观察复制任务状态
3. 模拟北京机房网络中断，观察 Job Service 队列变化
4. 恢复网络后，验证镜像是否自动同步

练习 3：用 Harbor API 自动化镜像清理

写一个简单的 Python 脚本，完成：

1. 调用 Harbor API 列出所有项目下超过 30 天未拉取的镜像
2. 生成清理计划（保留最近 3 个 tag）
3. 输出为 CSV 报告，包含：项目名、仓库名、tag、上次拉取时间

进阶路径

入门（第一次接触容器注册表）

• 理解 Docker 镜像的基本结构（Layer、Manifest、Tag）
• 完成练习 1，在本地跑通一套单节点 Harbor
• 阅读 Harbor 官方文档的 Quick Install 部分

进阶（在生产环境运维 Harbor）

• 掌握 Harbor 高可用架构（第 6.4 节）：多副本 + 外部 PostgreSQL/Redis
• 深入理解镜像安全链路：漏洞扫描（Trivy）+ 内容签名（Notary）+ 阻止策略
• 参与一次 Harbor 版本升级，理解数据迁移和回滚步骤

专业（为组织设计镜像管理战略）

• 对比 Harbor 与云厂商托管注册表（ECR、ACR、GCR）的总拥有成本（TCO）
• 设计多区域镜像分发架构：就近推送 + 中心同步 + 边缘缓存
• 深入理解 OCI 标准：不止 Docker 镜像，还能分发 Helm Chart、SBOM、扫描报告

文档版本：v1.1 | 写作日期：2026-04-09 | 更新日期：2026-06-02