Docker发布于 2026/4/18更新于 2026/4/18约 15 分钟顶有教育科技

Harbor 私有镜像仓库搭建：HTTPS 配置、RBAC 权限、镜像扫描与复制策略

从零搭建企业级 Docker 私有镜像仓库 Harbor：docker-compose 安装流程、自签名与 Let's Encrypt HTTPS 证书配置、RBAC 项目/用户/角色权限管理、集成 Trivy 镜像安全扫描（CVE 扫描自动阻断推送）、跨数据中心镜像复制策略，以及 Harbor 高可用部署方案与日常运维操作。

企业生产环境不能依赖 Docker Hub（国内访问慢、有拉取限制），必须自建私有镜像仓库。Harbor 是 CNCF 毕业项目，提供 RBAC 权限控制、镜像安全扫描、跨机房同步等企业功能，是目前最主流的开源私有仓库方案。

准备工作

最低硬件要求：
  CPU：4 核
  内存：8GB
  磁盘：100GB+（存放镜像）

软件要求：
  Docker 20.10+
  docker-compose 2.x
  域名（推荐，用于 HTTPS）或 IP+自签名证书

端口：
  80  → HTTP（重定向到 HTTPS）
  443 → HTTPS（主服务）

一、Harbor 安装

下载安装包

# 获取最新版本
HARBOR_VERSION="v2.11.0"
wget https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz

# 国内访问 GitHub 慢，可用国内镜像
# wget https://ghproxy.com/https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz

tar xzf harbor-online-installer-${HARBOR_VERSION}.tgz
cd harbor

准备 HTTPS 证书

方案1：自签名证书（内网环境）

mkdir -p /data/harbor/ssl
cd /data/harbor/ssl

# 生成 CA 私钥和证书
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
    -key ca.key \
    -out ca.crt \
    -subj "/C=CN/ST=Hubei/L=Wuhan/O=Company/CN=Harbor CA"

# 生成 Harbor 服务器证书
openssl genrsa -out harbor.key 4096

openssl req -sha512 -new \
    -key harbor.key \
    -out harbor.csr \
    -subj "/C=CN/ST=Hubei/L=Wuhan/O=Company/CN=harbor.company.com"

# 配置 SAN（Subject Alternative Name，必须包含）
cat > v3.ext << 'EOF'
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1=harbor.company.com
DNS.2=harbor
IP.1=192.168.1.200
EOF

openssl x509 -req -sha512 -days 3650 \
    -extfile v3.ext \
    -CA ca.crt -CAkey ca.key -CAcreateserial \
    -in harbor.csr \
    -out harbor.crt

ls -la
# ca.crt  ca.key  harbor.crt  harbor.csr  harbor.key

方案2：Let’s Encrypt（公网域名）

# 安装 certbot
apt-get install -y certbot

# 申请证书（需要 80 端口可访问）
certbot certonly --standalone -d harbor.company.com

# 证书位置
# /etc/letsencrypt/live/harbor.company.com/fullchain.pem
# /etc/letsencrypt/live/harbor.company.com/privkey.pem

配置 harbor.yml

cp harbor.yml.tmpl harbor.yml
vi harbor.yml

# harbor.yml（关键配置项）

# 访问域名
hostname: harbor.company.com

# HTTP（只用于重定向，不存数据）
http:
  port: 80

# HTTPS
https:
  port: 443
  certificate: /data/harbor/ssl/harbor.crt
  private_key: /data/harbor/ssl/harbor.key

# 管理员密码（首次启动后可改）
harbor_admin_password: Harbor12345

# 数据库
database:
  password: root123

# 数据存储路径（镜像存在这里）
data_volume: /data/harbor/data

# 镜像扫描（Trivy，推荐）
trivy:
  ignore_unfixed: false           # 是否忽略未修复的漏洞
  skip_update: false              # 是否跳过更新漏洞数据库
  offline_scan: false             # 离线模式（内网环境设 true）

# 日志
log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 200m
    location: /var/log/harbor

安装与启动

# 预安装（生成 docker-compose.yml 和配置）
./prepare --with-trivy

# 安装 Harbor
./install.sh --with-trivy

# 查看运行状态
docker compose ps
# NAME                    STATUS     PORTS
# harbor-core             running    
# harbor-db               running    
# harbor-jobservice       running    
# harbor-log              running    
# harbor-portal           running    
# harbor-redis            running    
# harbor-registryctl      running    
# nginx                   running    0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp
# registry                running    
# trivy-adapter           running    

# 访问
# https://harbor.company.com
# 用户名：admin   密码：Harbor12345（harbor.yml 中设置的）

二、客户端配置

信任自签名证书

# 在所有需要使用 Harbor 的机器上配置

# 复制 CA 证书到系统信任目录
mkdir -p /etc/docker/certs.d/harbor.company.com
cp /data/harbor/ssl/ca.crt /etc/docker/certs.d/harbor.company.com/ca.crt

# 登录测试
docker login harbor.company.com
# Username: admin
# Password: Harbor12345
# Login Succeeded

# 拉取测试
docker pull harbor.company.com/library/nginx:1.25

三、RBAC 权限管理

Harbor 的权限模型：系统角色 + 项目角色 双层控制。

系统角色（全局）：
  系统管理员（System Admin）  → 管理 Harbor 全部功能
  普通用户（Registered User） → 只能访问被授权的项目

项目角色（项目内）：
  项目管理员（Project Admin）→ 管理项目内所有资源
  维护者（Maintainer）      → 推送/拉取/删除镜像，管理机器人账户
  开发者（Developer）       → 推送/拉取镜像
  访客（Guest）             → 只能拉取镜像
  限制访客（Limited Guest） → 只能看到部分内容

# 用 Harbor API 管理（也可通过 Web UI）

# 创建项目
curl -X POST https://harbor.company.com/api/v2.0/projects \
    -H "Content-Type: application/json" \
    -u admin:Harbor12345 \
    -d '{
        "project_name": "backend",
        "public": false,
        "metadata": {"public": "false"}
    }'

# 创建用户
curl -X POST https://harbor.company.com/api/v2.0/users \
    -H "Content-Type: application/json" \
    -u admin:Harbor12345 \
    -d '{
        "username": "dev-team",
        "password": "Dev@123456",
        "email": "dev@company.com",
        "realname": "开发团队"
    }'

# 将用户添加到项目（角色：开发者=2，访客=3，维护者=4，管理员=1）
curl -X POST https://harbor.company.com/api/v2.0/projects/2/members \
    -H "Content-Type: application/json" \
    -u admin:Harbor12345 \
    -d '{
        "role_id": 2,
        "member_user": {"username": "dev-team"}
    }'

机器人账户（Robot Account，用于 CI/CD）

# 在 Web UI 中：项目 → 机器人账户 → 添加机器人
# 或通过 API

curl -X POST https://harbor.company.com/api/v2.0/projects/2/robots \
    -H "Content-Type: application/json" \
    -u admin:Harbor12345 \
    -d '{
        "name": "ci-bot",
        "description": "GitLab CI 推送机器人",
        "duration": 365,
        "permissions": [
            {
                "kind": "project",
                "namespace": "backend",
                "access": [
                    {"resource": "repository", "action": "push"},
                    {"resource": "repository", "action": "pull"}
                ]
            }
        ]
    }'

# 返回的 secret 只显示一次，立即保存！
# 用机器人账户登录：
docker login harbor.company.com \
    -u "robot$backend+ci-bot" \
    -p <secret>

四、镜像安全扫描（Trivy）

# Web UI 操作：
# 仓库 → 选择镜像 → 扫描 → 查看漏洞报告

# API 触发扫描
curl -X POST https://harbor.company.com/api/v2.0/projects/backend/repositories/myapp/artifacts/v1.2.3/scan \
    -u admin:Harbor12345

# 查看扫描结果
curl https://harbor.company.com/api/v2.0/projects/backend/repositories/myapp/artifacts/v1.2.3/additions/vulnerabilities \
    -u admin:Harbor12345 | jq '.["application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0"].vulnerabilities[] | select(.severity == "Critical") | {id: .id, package: .package, version: .version}'

配置扫描策略（自动阻断）

Web UI 操作路径：
项目设置 → 安全 → 自动扫描推送的镜像 → 开启
项目设置 → 安全 → 阻止有漏洞的镜像拉取 → 设置阻止策略

阻止策略选项：
  低危（Low）以上    → 阻止拉取含任何漏洞的镜像（最严格）
  中危（Medium）以上 → 阻止中危及以上
  高危（High）以上   → 阻止高危及以上（推荐）
  严重（Critical）以上 → 只阻止严重漏洞（最宽松）

五、镜像复制策略（跨数据中心同步）

# 场景：北京机房是主 Harbor，上海机房是从 Harbor
# 需要将北京的镜像自动同步到上海

# 1. 在北京 Harbor 中配置目标仓库（上海）
# Web UI：系统管理 → 仓库管理 → 新建目标
# 目标名：harbor-shanghai
# 目标 URL：https://harbor-sh.company.com
# 凭证：admin / Harbor12345

# 2. 创建复制规则
# Web UI：系统管理 → 复制管理 → 新建规则

// 复制规则配置（API 创建）
{
  "name": "sync-to-shanghai",
  "description": "同步 backend 项目到上海",
  "src_registry": null,                 // null = 当前 Harbor
  "dest_registry": {"id": 1},           // 上海 Harbor 的 ID
  "dest_namespace": "backend",
  "trigger": {
    "type": "event_based",             // 触发方式：event_based=推送后立即同步
    "trigger_settings": {}
  },
  "filters": [
    {
      "type": "name",
      "value": "backend/**"            // 只同步 backend 项目
    },
    {
      "type": "tag",
      "value": "v*"                    // 只同步 v 开头的 tag（过滤 dev/latest）
    }
  ],
  "deletion": false,                   // 源删除时是否同步删除目标
  "override": true,                    // 同名镜像是否覆盖
  "enabled": true,
  "speed": -1                          // 不限速（-1）
}

六、Harbor 日常运维

# 启动/停止 Harbor
cd /opt/harbor
docker compose start
docker compose stop

# 升级 Harbor
# 1. 备份数据库
docker compose exec harbor-db pg_dump -U postgres registry > harbor_db_backup.sql

# 2. 停止服务
docker compose down

# 3. 下载新版本安装包，解压
# 4. 复制旧的 harbor.yml（注意版本间的配置变化）
# 5. 执行 ./prepare 和 ./install.sh

# 清理旧镜像（GC）
# Web UI：系统管理 → 垃圾清理 → 立即清理
# 或 API：
curl -X POST https://harbor.company.com/api/v2.0/system/gc \
    -u admin:Harbor12345

# 配置定时 GC（每天凌晨 2 点）
# Web UI：系统管理 → 垃圾清理 → 计划

# 检查 Harbor 磁盘使用
du -sh /data/harbor/data/
du -sh /data/harbor/data/registry/docker/registry/v2/repositories/

# 查看 Harbor 日志
docker compose logs -f harbor-core
docker compose logs -f registry

# 镜像配额管理（限制项目使用的存储空间）
# Web UI：项目 → 配额
# 推荐：每个项目限制 50GB，超出无法推送

Webhook 配置（推送事件通知）

# Web UI：项目 → Webhooks → 新建
# 支持：镜像推送、扫描完成、复制完成等事件

# Webhook Payload 示例（推送镜像时）
{
  "type": "PUSH_ARTIFACT",
  "operator": "ci-bot",
  "event_data": {
    "repository": {
      "name": "myapp",
      "full_name": "backend/myapp"
    },
    "resources": [
      {
        "tag": "v1.2.3",
        "digest": "sha256:abc123..."
      }
    ]
  }
}
# 可以用来触发 CD 流水线（镜像推送后自动部署）

小结

Harbor 生产搭建的关键步骤：HTTPS 证书（自签名或 Let’s Encrypt）→ harbor.yml 配置 → ./install.sh --with-trivy 安装 → 创建项目和用户 → 为 CI/CD 创建机器人账户 → 配置自动扫描策略。

三个必须配置的运维项：磁盘配额（防止镜像无限增长）、定时 GC（清理未引用的镜像层）、复制策略（多机房容灾）。

不要用 admin 账户做日常推送，为每个 CI/CD 流水线创建独立的机器人账户，出问题时可以精确定位并单独吊销。