本文记录 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 日志,不要反复重启或立即强制终止。
在恢复自动化写入前,逐项验收:
- Web 登录正常,原有项目、仓库、用户和权限可见。
- 使用普通账户和机器人账户分别验证权限;检查原有镜像的 digest。
- 拉取已有镜像,再向测试项目推送一个新标签并重新拉取。
- 原来启用了 Trivy 的环境能完成一次扫描,复制和 Webhook 等功能按实际使用情况验证。
- 检查磁盘空间、错误日志与容器健康状态,再恢复 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,也不要把备份删除作为升级脚本的自动收尾动作。