Harbor 镜像仓库：安装、升级、Trivy 扫描与双机复制实战

Harbor 是 CNCF 毕业的企业级 Docker 镜像仓库（VMWare 2016 年开源，2018 年捐赠给 CNCF），支持镜像签名、漏洞扫描、跨节点复制、基于角色的访问控制。自建 Harbor 是企业里"内网统一镜像源"的标配。这篇文章把 Harbor 2.9.1/2.10/2.13 的离线安装、配置、镜像 push/pull、Trivy 扫描、双机双向复制的完整流程一次性说清。

阅读对象：运维 / SRE / DevOps 团队；需要在多机房部署 Harbor 做"异地容灾"；需要 Trivy 漏洞扫描合规。 覆盖范围：Harbor 2.9.1/2.10.0/2.13.1 离线安装；harbor.yml 配置；daemon.json 配 insecure-registries；镜像 push/pull/打 tag 实战；Trivy 漏洞扫描 + 离线 DB 同步；双机双向复制（机器人账户 + 复制规则）。

一、Harbor 在企业里的角色

角色	价值
统一镜像源	内网统一分发，避免每台机器去 docker.io 拉
镜像合规	漏洞扫描、未签名镜像拦截、镜像签名
异地容灾	双机房 Harbor 双向复制
权限管理	RBAC、项目级隔离
CI/CD 集成	与 Jenkins / GitLab CI / ArgoCD 集成

架构：Harbor 本身是一个 docker-compose 项目（10+ 容器：core / jobservice / nginx / registry / trivy / portal / db / redis / exporter / log）。所以跑 Harbor = 跑一个 docker compose。

二、Harbor 2.9.1 离线安装

2.1 下载离线包

1
2
3
4
5
6
7
8
# 2.9.1
https://github.com/goharbor/harbor/releases/download/v2.9.1/harbor-offline-installer-v2.9.1.tgz

# 2.10.0
https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz

# 2.13.1
https://github.com/goharbor/harbor/releases/download/v2.13.1/harbor-offline-installer-v2.13.1.tgz

2.2 解压

1
2
mkdir /home/harbor-install
tar -zxvf harbor-offline-installer-v2.10.0.tgz -C /home/harbor-install

2.3 配置 `harbor.yml`

1
2
3
cd /home/docker/harbor
cp -ar harbor.yml.tmpl harbor.yml
vim harbor.yml

关键配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
hostname: internal.example.com    # 改成你的 IP/域名

http:
  port: 13001                     # 改个非默认端口

# 关闭 HTTPS（演示环境，生产必开）
#https:
#  port: 443
#  certificate: /your/certificate/path
#  private_key: /your/private/key/path

# 管理员密码（必改）
harbor_admin_password: {{REDACTED}}

# 数据目录
data_volume: /home/docker/harbor/data

2.4 启动

1
./install.sh

启动日志：

1
2
3
4
5
6
7
[Step 0]: checking if docker is installed ...
[Step 1]: checking docker-compose is installed ...
[Step 2]: loading Harbor images ...
[Step 3]: preparing environment ...
[Step 4]: preparing harbor configs ...
[Step 5]: starting Harbor ...
✔ ----Harbor has been installed and started successfully.----

访问 http://<host>:13001，默认账号 admin / 你的密码。

三、配置 Docker 客户端

3.1 daemon.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
cat << 'EOF' > /etc/docker/daemon.json
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": { "max-size": "50m", "max-file": "1" },
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com",
    "https://docker.nju.edu.cn",
    "https://docker.mirrors.sjtug.sjtu.edu.cn",
    "https://dockerproxy.com"
  ],
  "insecure-registries": ["internal.example.com:13001"]
}
EOF

systemctl daemon-reload
systemctl restart docker

insecure-registries：HTTP 协议的 Harbor 必须加这一项，否则客户端报 server gave HTTP response to HTTPS client。

3.2 登录 Harbor

1
2
docker login -u admin -p {{REDACTED}} internal.example.com:13001
# Login Succeeded

四、镜像 push / pull 实战

4.1 重新打 tag 推送

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 拉官方镜像
docker pull nginx:latest

# 打 tag 到 Harbor
docker tag nginx:latest internal.example.com:13001/library/nginx:latest

# 推送
docker push internal.example.com:13001/library/nginx:latest

# 删除本地 tag
docker rmi -f internal.example.com:13001/library/nginx:latest

# 从 Harbor 拉
docker pull internal.example.com:13001/library/nginx:latest

4.2 完整业务镜像推送示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# JDK 8
docker tag lwd/jdk:8u381 internal.example.com:13001/base/lwd/jdk:8u381
docker push internal.example.com:13001/base/lwd/jdk:8u381

# Go 应用
docker tag lwd/go:2.0 internal.example.com:13001/base/lwd/go:2.0
docker push internal.example.com:13001/base/lwd/go:2.0

# Tomcat
docker tag tomcat:9.0.79-jdk8-temurin-jammy \
  internal.example.com:13001/base/tomcat:9.0.79-jdk8-temurin-jammy
docker push internal.example.com:13001/base/tomcat:9.0.79-jdk8-temurin-jammy

# MySQL 8
docker tag mysql:8.0.23 internal.example.com:13001/base/mysql:8.0.23
docker push internal.example.com:13001/base/mysql:8.0.23

# EMQX
docker tag emqx/emqx:5.0.24 internal.example.com:13001/base/emqx/emqx:5.0.24
docker push internal.example.com:13001/base/emqx/emqx:5.0.24

路径约定：<harbor>/<project>/<repo>:<tag>。library 是默认项目，公开镜像放这里；私有项目用 base 等命名空间。

4.3 Harbor API 查询镜像

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 查 Harbor 版本
curl http://internal.example.com:13001/api/version -k
# {"version":"v2.0"}

# 查项目下的 tags
curl -u admin:{{REDACTED}} -H "Content-Type: application/json" \
  -X GET "http://internal.example.com:13001/v2/library/lwd/jdk/tags/list" -k

# 查镜像是否存在（200 存在，404 不存在）
curl -sIL -w "%{http_code}\n" -o /dev/null \
  -X GET "http://internal.example.com:13001/api/v2.0/projects/base/repositories/lwd%252Fjdk/artifacts/8u381-3"

五、Trivy 漏洞扫描

Harbor 集成了 Trivy 作为默认扫描器。Trivy 漏洞库更新非常频繁（每天），离线环境需要定期同步 DB。

5.1 启用 Trivy 扫描

1
2
3
4
5
6
7
8
9
# 1. 停 Harbor
cd /home/docker/harbor
docker-compose stop

# 2. 重新 prepare（启用 trivy）
./prepare --with-trivy

# 3. 重新启动
docker-compose -f docker-compose.yml up -d

5.2 离线 DB 同步

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 安装 Oras CLI（用于从 OCI 仓库下载 trivy-db）
curl -LO https://github.com/oras-project/oras/releases/download/v1.1.0/oras_1.1.0_linux_amd64.tar.gz
mkdir -p oras-install/
tar -zxf oras_1.1.0_linux_amd64.tar.gz -C oras-install/
mv oras-install/oras /usr/local/bin/

# 拉 trivy-db（用 ghcr dockerproxy 镜像加速）
oras pull ghcr.dockerproxy.com/aquasecurity/trivy-db:2 -v --insecure

# 解压到 Harbor 的 trivy 目录
tar xf db.tar.gz -C /home/docker/harbor/data/trivy-adapter/trivy/db
chown 10000.10000 -R /home/docker/harbor/data/trivy-adapter/trivy/db

5.3 定时同步脚本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
cat << 'EOF' > /usr/bin/sh/download_trivy_db.sh
#!/bin/bash
# 每天凌晨 0:30 同步
# cron：30 0 * * * /usr/bin/sh /usr/bin/sh/download_trivy_db.sh > /var/log/download_trivy_db.log 2>&1 &

cd /home/data/trivy-db

oras pull ghcr.io/aquasecurity/trivy-db:2 -v --insecure

if [ $? -eq 0 ]; then
    tar xf db.tar.gz -C /home/docker/harbor/data/trivy-adapter/trivy/db
    chown 10000.10000 -R /home/docker/harbor/data/trivy-adapter/trivy/db
    echo 'succ'
else
    echo 'download failed!'
fi
EOF
chmod +x /usr/bin/sh/download_trivy_db.sh

坑：Trivy 漏洞库体积 ~100MB，不能放在 Harbor 容器内，必须挂在外部卷。

六、双机双向复制（异地容灾）

Harbor 支持"两个实例之间同步镜像"，**机器人账户（Robot Account）**是机器间互信的标准做法。

6.1 架构

1
2
3
[机房 1 Harbor]                       [机房 2 Harbor]
 10.8.33.254:13001                    1.2.3.4:13001
  robot$copy (双向)  ◄────────────►   robot$copy

6.2 机房 2 创建机器人

访问 http://机房2:13001/harbor/robot-accounts
创建机器人：
- 名称：robot$copy
- 权限：项目级（具体到要复制的项目）
- 复制：+ 保存
记录 Token（如 FKkxBNnmKD8Z13l6TCGf3sTl9ObfB3Lf），关闭后再无法查看

6.3 机房 1 配置复制规则

登录机房 1 Harbor
系统管理 → 复制管理 → 新建规则
填写：
- 名称：to-机房2
- 模式：Pull-based（推荐，先从机房 1 推到机房 2）
- 源注册表：机房 2 的 URL
- 源机器人：机房 2 创建的 robot$copy + Token
- 目标项目：library / base（按需）
- 触发模式：手动 / 定时 / 事件

6.4 验证复制

1
2
3
4
5
# 机房 1 推送
docker push internal.example.com:13001/library/nginx:latest

# 几分钟后在机房 2 看是否自动同步
# 访问 http://机房2:13001 → library 项目 → 应能看到 nginx

七、Harbor 升级（2.9.1 → 2.13.1）

7.1 备份

1
2
3
4
5
6
7
# 停 Harbor
cd /home/docker/harbor
docker-compose down

# 备份配置和数据
mkdir -p /home/bak/harbor2.9.1
rsync -a --exclude="data" /home/docker/harbor/ /home/bak/harbor2.9.1/

不要备份 data 目录（太大，迁移时会复用）。

7.2 装载新版

1
2
3
4
5
6
# 解压新版到同一目录
tar -zxvf harbor-offline-installer-v2.13.1.tgz \
  -C /home/docker/harbor --strip-components=1

# 加载新镜像
docker image load -i harbor.v2.13.1.tar.gz

7.3 迁移旧配置 + 安装

1
2
3
4
5
6
7
8
9
# 把旧 harbor.yml 复制回来
cp /home/bak/harbor2.9.1/harbor.yml /home/docker/harbor/

# 用 prepare 迁移（v2.13.1 自动检测旧配置）
docker run -it --rm -v /:/hostfs \
  goharbor/prepare:v2.13.1 migrate -i /home/docker/harbor/harbor.yml

# 安装
./install.sh

关键：goharbor/prepare:v2.13.1 migrate 会自动转换旧配置到新版本（如 v2.9 的字段升级到 v2.13 的字段）。

八、2024+ 视角补充

本文写于 2024-06，2024-2026 期间 Harbor 持续演进：Harbor 2.11（2024-09）/ 2.12（2025-02）/ 2.13（2025-08）/ 2.14（2026-Q1） 几个大版本。关键变化：

P2P 镜像分发（2.11+）：基于 Kraken / Dragonfly，大镜像（GB 级）拉取速度提升 10x+——AI 训练镜像 / 视频处理镜像场景强相关
SBOM + SLSA Level 3 合规：2.12+ 自动生成 CycloneDX / SPDX 格式 SBOM；满足供应链安全要求（金融 / 政企刚需）
Proxy Cache 项目（2.10+ 引入、2.12 GA）：Harbor 可作为远程 Registry 的"代理缓存层"，减少 90% 出口带宽——多机房 K8s 拉取 docker.io 镜像必备
Trivy 0.50+：漏洞库大小 200MB+，离线 DB 同步脚本对网络要求更高
机器人账户（Robot Account）权限粒度细化：从项目级到仓库级（repository-level）
OCI 1.1+ 兼容：Helm Chart、OPA Bundle 等 OCI artifact 完美支持

实战建议（2026 视角）：Harbor 2.13.1+ 是当前生产推荐版本；Proxy Cache + P2P 是新装机必选能力；金融政企场景强推 SBOM + SLSA 模式。

九、扩展阅读

Harbor 官方仓库：github.com/goharbor/harbor
Harbor 官方文档：goharbor.io/docs
Trivy 漏洞库：github.com/aquasecurity/trivy-db
Trivy 官方仓库：github.com/aquasecurity/trivy
镜像复制最佳实践：goharbor.io/blog/harbor-1.10-release