搭建 Harbor 企业镜像仓库

适用场景

需要私有镜像仓库、镜像扫描、签名、复制和基于项目的权限控制。Harbor 适合替代简单的 registry，尤其是多团队、多集群和需要审计的生产环境。

前置条件

• 域名和 TLS 证书。
• 外部 PostgreSQL、Redis 和对象存储（S3/MinIO/OSS/COS）；生产不建议用内置存储。
• Kubernetes 集群或独立主机，磁盘容量按镜像增长预估。
• 明确项目划分、机器人账号和保留策略。

步骤

1. 添加 Helm 仓库并准备 values：

helm repo add harbor https://helm.goharbor.io
helm repo update
helm show values harbor/harbor > harbor-values.yaml

2. 配置外部数据库、Redis、对象存储和 TLS：

helm install harbor harbor/harbor \
  --namespace harbor --create-namespace \
  -f harbor-values.yaml

关键配置包括 expose.type=ingress、expose.tls.enabled=true、database.type=external、redis.type=external、persistence.imageChartStorage.type=s3。

3. 等待组件就绪：

kubectl -n harbor get pods
kubectl -n harbor get ingress
curl -I https://harbor.example.com

4. 创建项目并分配角色：

# 在 UI 或 API 中创建项目 prod
curl -u admin:"$HARBOR_PASSWORD" -X POST \
  -H 'Content-Type: application/json' \
  https://harbor.example.com/api/v2.0/projects \
  -d '{"project_name":"prod","public":false}'

5. 创建机器人账号用于 CI 推送，只授予目标项目的 push/pull 权限。

6. 配置镜像扫描和保留策略：

• 扫描器选择 Trivy，开启推送后自动扫描。
• 保留策略按最近 N 个标签或按天数清理，避免磁盘无限增长。
• 需要签名时启用 Cosign/Notation，并在准入控制里校验。

7. 多集群复制：

# 在 UI 中创建目标 registry 端点和复制规则
# 也可以用 API 创建 replication policy

8. 配置日志和监控，接入 Prometheus 与外部日志系统。

验证

• docker login harbor.example.com 成功。
• docker push 和 docker pull 正常，镜像在 UI 可见。
• 未授权用户无法拉取私有项目镜像。
• 推送后自动扫描，漏洞结果可见。
• 复制规则触发后，目标仓库出现对应镜像。
• 证书链完整，curl 不报证书错误。

回滚

• 升级前备份 Harbor 数据库和对象存储配置。
• Helm 回滚：helm rollback harbor <revision> -n harbor。
• 保留旧版本镜像和 values 文件，确认新版本稳定后再清理。
• 数据库迁移通常不可逆，跨大版本升级前先在测试环境演练。

常见坑

• 使用内置数据库和存储，Pod 重建后数据丢失。
• externalURL 配错，UI 重定向、webhook 和复制地址都会异常。
• 对象存储的 bucket、region、endpoint 或 path-style 配置错误，推送失败。
• 证书只配了服务端，没有把 CA 放进节点或 Docker 的信任链。
• 机器人账号权限过大，泄露后可删除整个项目。
• 没有保留策略和垃圾回收，磁盘很快被旧镜像占满。
• 跨版本升级跳过必需版本，数据库迁移失败。

相关命令

• docker / podman — 登录、推送和拉取镜像
• helm — 安装、升级和回滚 Harbor
• kubectl — 查看组件和 Ingress
• curl — 调用 Harbor API 和检查健康状态
• trivy — 本地镜像扫描