搬瓦工 VPS 搭建 Harbor 企业级镜像仓库教程

Harbor 是由 VMware 开发并捐赠给 CNCF 的企业级容器镜像仓库，在 Docker Registry 的基础上增加了安全扫描、访问控制、镜像复制、审计日志等企业级功能。对于使用 Docker 部署应用的团队，自建 Harbor 镜像仓库可以加速镜像拉取、保障供应链安全并实现精细的权限管理。本教程将介绍如何在搬瓦工 VPS 上安装和配置 Harbor。部署前请确保已安装好 Docker 和 Docker Compose。

一、Harbor 核心功能

多租户项目：支持创建多个项目隔离不同团队的镜像，每个项目独立管理访问权限。
漏洞扫描：集成 Trivy 扫描引擎，自动检测镜像中的安全漏洞。
镜像复制：支持跨 Harbor 实例或与 Docker Hub 之间的镜像同步复制。
RBAC 权限：基于角色的访问控制，支持项目管理员、开发者、访客等角色。
内容签名：支持 Cosign/Notation 镜像签名，确保镜像来源可信。
垃圾回收：清理不再引用的镜像层，释放存储空间。

二、系统要求

内存：至少 4GB，推荐 8GB
磁盘：至少 40GB 可用空间
Docker：20.10+ 和 Docker Compose

三、安装 Harbor

# 下载 Harbor 离线安装包
cd /opt
wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar xzf harbor-offline-installer-v2.11.0.tgz
cd harbor

3.1 配置 harbor.yml

cp harbor.yml.tmpl harbor.yml

# 编辑关键配置
# hostname: registry.example.com
# https:
#   port: 443
#   certificate: /etc/letsencrypt/live/registry.example.com/fullchain.pem
#   private_key: /etc/letsencrypt/live/registry.example.com/privkey.pem
# harbor_admin_password: Harbor_Admin_2026
# database:
#   password: harbor_db_2026
# data_volume: /data/harbor

3.2 执行安装

# 安装（包含 Trivy 漏洞扫描）
./install.sh --with-trivy

# 检查运行状态
docker compose ps

四、基本使用

# 登录 Harbor
docker login registry.example.com -u admin -p Harbor_Admin_2026

# 给镜像打标签
docker tag myapp:latest registry.example.com/myproject/myapp:v1.0

# 推送镜像
docker push registry.example.com/myproject/myapp:v1.0

# 拉取镜像
docker pull registry.example.com/myproject/myapp:v1.0

五、项目与用户管理

创建项目：点击"新建项目"，设置名称和访问级别（公开/私有）。
添加成员：在项目中添加用户并分配角色（管理员/开发者/访客）。
配置机器人账户：为 CI/CD 系统创建专用的机器人账户，限制权限范围。

# 创建机器人账户（通过 API）
curl -X POST "https://registry.example.com/api/v2.0/robots" \
  -H "Content-Type: application/json" \
  -u "admin:Harbor_Admin_2026" \
  -d '{
    "name": "ci-bot",
    "duration": -1,
    "level": "project",
    "permissions": [
      {
        "namespace": "myproject",
        "kind": "project",
        "access": [
          {"resource": "repository", "action": "push"},
          {"resource": "repository", "action": "pull"}
        ]
      }
    ]
  }'

六、镜像复制

在 Web 界面的"仓库管理 > 复制管理"中配置复制规则，支持：

Harbor 到 Harbor（跨数据中心同步）
Docker Hub 到 Harbor（缓存公共镜像）
Harbor 到 AWS ECR / GCR（混合云场景）

七、漏洞扫描

# 手动触发扫描（通过 API）
curl -X POST "https://registry.example.com/api/v2.0/projects/myproject/repositories/myapp/artifacts/v1.0/scan" \
  -u "admin:Harbor_Admin_2026"

# 查看扫描结果
curl -s "https://registry.example.com/api/v2.0/projects/myproject/repositories/myapp/artifacts/v1.0/additions/vulnerabilities" \
  -u "admin:Harbor_Admin_2026" | python3 -m json.tool

八、垃圾回收

# 在 Web 界面: 系统管理 > 垃圾回收 > 立即回收
# 或配置定时回收计划

# 手动执行（需要先停止 Harbor）
docker compose stop
docker run -it --name gc --rm \
  -v /data/harbor/registry:/storage \
  goharbor/registry-photon:v2.11.0 \
  garbage-collect /etc/registry/config.yml
docker compose start

九、常见问题

推送镜像失败 (413)

如果使用 Nginx 反向代理，需要增加请求体大小限制：

client_max_body_size 2G;

HTTPS 证书更新

# Let's Encrypt 证书更新后重启 Harbor
cd /opt/harbor
docker compose down
docker compose up -d

总结

Harbor 是自建容器镜像仓库的首选方案，安全扫描和权限管理功能使其满足企业级需求。构建镜像可以通过 Woodpecker CI 自动化，制品管理还可以参考 Nexus 仓库教程。选购搬瓦工 VPS 请参考全部方案，部署 Harbor 建议选择内存 4GB 以上的方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，购买链接：bwh81.net。