Harbor 升级

  • ~9.57K 字
  1. 1. 一、确认适用范围和升级路径
  2. 2. 二、检测实际运行版本
    1. 2.1. 版本检测脚本
  3. 3. 三、准备安装包和维护窗口
    1. 3.1. 下载与验证
  4. 4. 四、停止服务并备份
  5. 5. 五、迁移配置并启动
  6. 6. 六、升级后验证
    1. 6.1. 2.15.2 的索引维护
  7. 7. 七、失败后的恢复
  8. 8. 八、确认成功后清理
  9. 9. 参考资料

本文记录 Linux 单机、Docker Compose、官方安装包部署的 Harbor 升级流程,保留 /data/harbor/harbor-v版本号 的安装目录约定。示例为 2.15.1 → 2.15.2,仅用于说明操作,不代表最新版本或当前推荐目标。

升级顺序为:确认实际版本和升级路径 → 下载并验证安装包 → 停止写入 → 停机备份 → 迁移配置 → 启动新版本 → 验证业务。数据库可能在启动时自动迁移,回滚必须恢复升级前的数据,不能只切换旧镜像。

一、确认适用范围和升级路径

本文的备份、恢复命令适用于以下环境:

  • Harbor 使用内置 PostgreSQL、Redis,以及本地文件系统存储镜像。
  • harbor.yml 中的 data_volume 是 Harbor 专用数据目录。
  • 使用 Docker Compose v2,操作在 root 的 Bash 会话中执行。
  • 示例启用了 Trivy;如果原部署未启用,后续 ./prepare 不添加 --with-trivy。

Helm 部署请使用官方 Helm 升级流程。外部数据库、Redis、S3 / MinIO 等存储需要独立备份和恢复,不能仅靠复制本机目录完成。

升级前阅读目标版本的升级文档和发布说明。2.15 官方迁移指南覆盖从 2.12.0 及以后版本升级到 2.15.0;更老版本应按相应版本的指南分阶段迁移,不要直接把“最新版本”作为升级目标。官方升级指南

特别注意:2.15.2 发布说明指出,内置数据库会在启动时由 PostgreSQL 15 自动升级至 18,可能延长启动时间;包含非 ASCII 数据的环境还需安排索引重建。即使只是补丁版本升级,也必须检查发布说明。

二、检测实际运行版本

目录名只能表示磁盘上存在某套安装文件,不能证明该版本正在运行。优先从运行中的 Harbor API 和容器镜像交叉确认:

# 替换为实际地址;私有 CA 使用 --cacert 指定证书,不要直接跳过 TLS 校验
curl --fail --silent --show-error \
    https://harbor.example.com/api/v2.0/systeminfo | jq -r '.harbor_version'

cd /data/harbor/harbor-v2.15.1
docker compose ps
docker compose images

同时检查实际容器挂载,确认数据库、镜像数据和密钥的路径:

docker inspect harbor-db registry harbor-core \
    --format '{{.Name}} {{json .Mounts}}'

版本检测脚本

保存为 check-harbor-version.sh。需要 bash、curl、jq 和 GNU sort;它只比较版本,不自动执行升级。

#!/usr/bin/env bash
set -euo pipefail

if [[ $# -ne 1 ]]; then
    echo "用法:$0 https://harbor.example.com"
    exit 1
fi

harbor_url="${1%/}"
current_version="$(curl -fsS --connect-timeout 10 --max-time 30 \
    "${harbor_url}/api/v2.0/systeminfo" | jq -er '.harbor_version')"
current_version="${current_version#v}"

curl_args=(-fsS --connect-timeout 10 --max-time 30 --retry 3
    -H 'Accept: application/vnd.github+json')
if [[ -n "${GITHUB_TOKEN:-}" ]]; then
    curl_args+=(-H "Authorization: Bearer ${GITHUB_TOKEN}")
fi
latest_tag="$(curl "${curl_args[@]}" \
    https://api.github.com/repos/goharbor/harbor/releases/latest \
    | jq -er '.tag_name')"
latest_version="${latest_tag#v}"

# 此脚本只比较正式版 x.y.z,遇到 RC 或定制版本时人工检查。
if [[ ! "$current_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ||
      ! "$latest_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
    printf '无法自动比较:当前=%s,GitHub=%s,请人工确认。\n' \
        "$current_version" "$latest_version"
    exit 1
fi

printf '当前版本:%s\nGitHub 最新正式发布:%s\n' "$current_version" "$latest_version"
if [[ "$current_version" == "$latest_version" ]]; then
    echo '两者版本相同。'
elif [[ "$(printf '%s\n' "$current_version" "$latest_version" | sort -V | head -n 1)" == "$current_version" ]]; then
    echo "发现较新版本,请先阅读 https://github.com/goharbor/harbor/releases/tag/${latest_tag}"
    echo '确认升级路径、备份和维护窗口后,再手动升级。'
else
    echo '当前版本高于该接口返回的版本,不进行降级。'
fi

使用方式:

chmod +x check-harbor-version.sh
./check-harbor-version.sh https://harbor.example.com

访问公开 GitHub Release 通常不需要 Token。若遇到 GitHub API 限流,可临时读取 Token,避免将明文写入脚本或命令历史:

read -rsp 'GitHub Token: ' GITHUB_TOKEN
printf '\n'
export GITHUB_TOKEN
./check-harbor-version.sh https://harbor.example.com
unset GITHUB_TOKEN

不要启用 set -x。Harbor 使用私有 CA 时,应先让系统信任该 CA,或在脚本中为 Harbor 的 curl 请求添加 --cacert。

三、准备安装包和维护窗口

以下各步骤在同一个 root Bash 会话中按顺序执行,命令失败时停止并检查,不要继续下一步。先按实际环境修改变量:

sudo -i
bash

old_version='2.15.1'
new_version='2.15.2'
base_dir='/data/harbor'
old_dir="${base_dir}/harbor-v${old_version}"
new_dir="${base_dir}/harbor-v${new_version}"

# 必须与现有 harbor.yml 的 data_volume 完全一致,不要为了升级修改它。
data_dir='/data'
# 备份必须位于 data_dir 和安装目录之外,最好使用独立备份磁盘。
backup_dir="/backup/harbor/${old_version}-$(date +%Y%m%d%H%M%S)"

pkg="harbor-online-installer-v${new_version}.tgz"
release_url="https://github.com/goharbor/harbor/releases/download/v${new_version}"

# 必须确认这些检查均通过
test -f "$old_dir/harbor.yml"
test -f "$old_dir/docker-compose.yml"
test -d "$data_dir/database"
test ! -e "$new_dir"
docker compose version
docker info
df -h "$data_dir" /backup

这里的 /data 是 Harbor 的常见默认值,不是从配置自动读取的值。核对 harbor.yml 中的 data_volume、证书路径、外部服务配置,以及实际容器挂载。如果 /data 同时存放其他应用,必须先确定专用备份和恢复范围;不要使用后文“完整恢复目录”的命令覆盖共享数据。

提前准备足够空间:数据库迁移、镜像下载、完整数据备份和失败现场保留都会占用磁盘。记录现有项目、镜像标签与 digest、机器人账户、复制规则和扫描器配置;暂停 CI 推送、复制、垃圾回收及其他写入任务,安排停机窗口。

下载与验证

先完成下载和验签,再停止旧服务。安装 Cosign 后执行:

mkdir -p "$base_dir"
download_dir="$(mktemp -d "${base_dir}/download.XXXXXX")"
cd "$download_dir"

curl -fL --retry 3 -o "$pkg" "${release_url}/${pkg}"
curl -fL --retry 3 -o "${pkg}.sigstore.json" \
    "${release_url}/${pkg}.sigstore.json"

cosign verify-blob \
    --bundle "${pkg}.sigstore.json" \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-identity "https://github.com/goharbor/harbor/.github/workflows/publish_release.yml@refs/tags/v${new_version}" \
    "$pkg"

# 仅在验签成功后解压;新目录必须不存在,不删除已有目录。
tar -xzf "$pkg"
mv harbor "$new_dir"
docker pull "goharbor/prepare:v${new_version}"

签名机制从 2.15.0 开始提供,文件名和验证要求以目标 Release 附件及其签名验证说明为准。若验签失败,先核对文件和工具版本,不要直接跳过验证。

在线安装包不包含全部运行镜像,后续仍需要拉取镜像。离线环境应下载对应离线包,验签后解压,并在迁移前用 docker load -i 导入包中的 harbor.*.tar.gz,同时保留旧版本镜像供恢复使用。

四、停止服务并备份

确认上游写入和后台任务已停止后执行:

cd "$old_dir"
docker compose down

# 备份包含配置密码、证书和密钥,仅允许 root 访问。
umask 077
mkdir -p "$backup_dir"
cp -a "$old_dir" "$backup_dir/installer"

# 在数据库及其他 Harbor 容器停止后,备份整个本地数据目录。
# /backup 不能位于 data_dir 内,否则可能递归复制。
rsync -aHAX --numeric-ids "$data_dir/" "$backup_dir/data/"

# 无输出表示内容和元数据一致;发现差异时先检查,不能开始迁移。
rsync -aHAXnc --numeric-ids --delete "$data_dir/" "$backup_dir/data/"

本示例需要安装 rsync。data_dir 为默认 /data 时,备份也会包含位于其中的安装目录和预下载文件,因此要预留相应容量。数据量大时可改用经验证的存储快照方案,仍需保证数据库备份的一致性。

备份安装目录不能替代备份数据目录。 数据库通常在 data_volume/database,镜像数据、密钥等也在 data_volume 下。还应单独备份配置引用的外部证书、自定义 CA、内部 TLS 证书和其他外部文件,保留权限、属主及原路径;它们不一定包含在上述复制范围内。

备份必须可恢复:检查数据库、镜像存储和密钥是否齐全,最好先在隔离环境演练。若备份失败而尚未执行迁移,可回到旧目录运行 docker compose up -d 恢复服务,重新安排升级。

五、迁移配置并启动

只复制原始配置,由目标版本重新生成 common/config 和 Compose 文件,避免混用新旧模板:

cp -a "$old_dir/harbor.yml" "$new_dir/harbor.yml"

docker run --rm -v /:/hostfs \
    "goharbor/prepare:v${new_version}" \
    migrate -i "$new_dir/harbor.yml"

# 人工检查迁移后的配置,注意不要将密码输出到共享日志。
# hostname / external_url、证书路径、data_volume、数据库、存储等应保持原有含义。
cd "$new_dir"
./prepare --with-trivy

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps

这里 migrate -i 按官方命令传入宿主机绝对路径;容器通过 /hostfs 访问宿主机。该工具只应使用官方、与目标版本一致的 prepare 镜像。

migrate 迁移的是配置;数据库 schema 和数据迁移由新组件在启动时执行。本文显式拆开 prepare、拉取镜像和启动步骤,便于定位失败;不要手工复制旧版生成的 common/config,也不要在安装目录间搬动运行数据。

六、升级后验证

容器启动并不代表业务已恢复,先检查:

cd "$new_dir"
docker compose ps
docker compose logs --tail=100 core postgresql registry jobservice

curl --fail --silent --show-error \
    https://harbor.example.com/api/v2.0/health | jq .
curl --fail --silent --show-error \
    https://harbor.example.com/api/v2.0/systeminfo | jq -r '.harbor_version'

健康接口预期整体状态为 healthy,版本接口应返回目标版本。若启动耗时较长,先观察数据库迁移和 core 日志,不要反复重启或立即强制终止。

在恢复自动化写入前,逐项验收:

  1. Web 登录正常,原有项目、仓库、用户和权限可见。
  2. 使用普通账户和机器人账户分别验证权限;检查原有镜像的 digest。
  3. 拉取已有镜像,再向测试项目推送一个新标签并重新拉取。
  4. 原来启用了 Trivy 的环境能完成一次扫描,复制和 Webhook 等功能按实际使用情况验证。
  5. 检查磁盘空间、错误日志与容器健康状态,再恢复 CI 和后台任务。

2.15.2 的索引维护

针对非 ASCII 数据或出现机器人账户权限异常、页面列表持续加载、索引查询异常的情况,发布说明要求在维护窗口执行索引重建。内置 PostgreSQL 的 Compose 服务名为 postgresql,示例:

cd "$new_dir"
docker compose exec -T --user postgres postgresql \
    reindexdb --all-databases -U postgres

重建可能耗时并持有锁,完成后重新验证权限与业务。外部数据库应由数据库管理员按其连接方式操作。2.15.2 数据库升级说明

七、失败后的恢复

Harbor 支持恢复到升级前的备份状态,不支持让旧版本直接使用已迁移的新数据库完成降级。恢复意味着丢弃备份时间点之后的更改,因此升级验收期间应持续限制业务写入。官方回滚说明

以下命令仅用于前述本地、Harbor 专用数据目录方案。先核对变量、备份内容和磁盘容量,所有 Harbor 容器必须停止;外部存储需同步恢复至同一时间点。

# 若已换会话,先重新设置旧/新安装目录、data_dir 和实际 backup_dir。
cd "$new_dir"
docker compose down
cd /root

test -d "$backup_dir/data/database"
test -f "$backup_dir/installer/harbor.yml"

# 保留失败现场;目标必须不在 data_dir 中。
failed_dir="${backup_dir}-failed-$(date +%Y%m%d%H%M%S)"
mkdir -m 0700 "$failed_dir"
cp -a "$new_dir" "$failed_dir/installer"
rsync -aHAX --numeric-ids "$data_dir/" "$failed_dir/data/"

# 先预览恢复范围。--delete 会删除目标中备份没有的文件,必须人工检查输出。
rsync -aHAXn --numeric-ids --delete "$backup_dir/data/" "$data_dir/"

确认预览的删除和覆盖范围正确、备份完整后,才执行恢复:

rsync -aHAX --numeric-ids --delete "$backup_dir/data/" "$data_dir/"

# 使用升级前备份中的原始安装文件;旧安装目录此时应已存在。
rsync -aHAX --numeric-ids --delete "$backup_dir/installer/" "$old_dir/"
cd "$old_dir"
docker compose up -d
docker compose ps

配置引用的外部证书等文件如有变更,也应恢复对应备份。最后重新执行健康、版本和镜像读写验证。若失败发生在数据库迁移之后,不要省略数据恢复而直接启动旧版服务。

八、确认成功后清理

保留升级前备份、旧安装目录和旧镜像至观察期结束,并确认备份已转存至独立存储。再按明确的路径逐项清理下载文件、旧安装文件和不再需要的镜像,不要直接运行 docker system prune --volumes,也不要把备份删除作为升级脚本的自动收尾动作。

参考资料