从1.x到2.x的无缝迁移：Harbor容器仓库升级实战指南-优快云博客

从1.x到2.x的无缝迁移：Harbor容器仓库升级实战指南

【免费下载链接】harbor Harbor 是一个开源的容器镜像仓库，用于存储和管理 Docker 镜像和其他容器镜像。 * 容器镜像仓库、存储和管理 Docker 镜像和其他容器镜像 * 有什么特点：支持多种镜像格式、易于使用、安全性和访问控制项目地址: https://gitcode.com/GitHub_Trending/ha/harbor

还在为Harbor升级时的数据迁移焦虑？还在担心配置文件不兼容导致服务中断？本文将带你一步步完成从Harbor 1.x到2.x版本的迁移，避开所有已知陷阱，确保镜像仓库平稳过渡到新版本。读完本文后，你将掌握版本检查、数据备份、配置迁移、增量升级和回滚预案的完整流程，让升级工作变得简单可控。

升级前准备：版本兼容性与环境检查

在开始升级前，首先需要确认你的当前Harbor版本是否符合升级路径要求。根据官方升级政策，Harbor仅支持从最近的两个次要版本升级到当前版本。例如，要升级到2.3.0，你必须先升级到2.1.0或2.2.0版本。如果你使用的是1.x版本，需要先升级到1.10.x，再逐步迁移到2.x系列。

版本检查命令：

docker-compose version
grep VERSION ./VERSION

环境要求变化

Harbor 2.x对运行环境有以下重要变更：

Docker引擎最低版本要求提升至19.03+
Docker Compose需要1.23.0以上版本
数据库从MySQL迁移到PostgreSQL
配置文件格式从harbor.cfg改为harbor.yml

环境检查清单：

操作系统内核版本≥3.10
磁盘空间至少为当前数据量的2倍
内存建议≥8GB（生产环境）
网络通畅，能够拉取升级所需镜像

数据备份策略：保护你的容器镜像资产

升级前的备份工作至关重要，任何数据丢失都可能导致严重后果。Harbor的数据主要存储在以下几个位置：

配置文件：位于./harbor.yml（2.x）或./harbor.cfg（1.x）
数据卷：包括数据库、镜像文件和日志
证书文件：SSL证书和密钥

完整备份方案

# 停止Harbor服务
docker-compose down

# 创建备份目录
mkdir -p /backup/harbor-$(date +%Y%m%d)

# 备份配置文件
cp harbor.cfg /backup/harbor-$(date +%Y%m%d)/
cp docker-compose.yml /backup/harbor-$(date +%Y%m%d)/

# 备份数据卷
rsync -avz /data/harbor /backup/harbor-$(date +%Y%m%d)/data/

# 启动Harbor服务
docker-compose up -d

注意：备份过程中Harbor服务会短暂不可用，请选择业务低峰期执行。对于生产环境，建议使用tests/e2e_setup/目录中的自动化备份脚本。

配置文件迁移：从harbor.cfg到harbor.yml的转变

Harbor 2.x引入了新的配置文件格式，将原来的harbor.cfg替换为harbor.yml。这个变更不仅是文件名的改变，更是配置结构的重构。主要变化包括：

配置项分组更加清晰
支持更多环境变量注入
新增了多项安全配置

配置迁移步骤

生成新配置文件：

# 从1.x安装目录复制模板文件
cp ./make/harbor.yml.tmpl ./harbor.yml

关键配置项映射：

1.x配置项	2.x配置项	说明
hostname	hostname	保持不变
ui_url_protocol	protocol	移至server部分
db_password	database.password	数据库密码
max_job_workers	jobservice.max_job_workers	任务并发数
custom_crt	certificate.custom_crt	自定义证书

使用官方迁移工具：

# 运行配置迁移脚本
./prepare --migrate

详细的配置项映射关系可参考src/core/config/目录下的配置定义文件。

增量升级流程：分阶段迁移确保平稳过渡

根据Harbor的升级政策，从1.x直接升级到最新2.x版本是不支持的，需要采用增量升级策略。推荐的升级路径为：

1.x → 1.10.x → 2.0.x → 2.1.x → 最新2.x

升级到1.10.x

首先将你的Harbor 1.x升级到1.10.x版本，这是1.x系列的最后一个版本，也是支持向2.x迁移的基础版本。

# 下载1.10.x版本安装包
wget https://github.com/goharbor/harbor/releases/download/v1.10.15/harbor-offline-installer-v1.10.15.tgz
tar xvf harbor-offline-installer-v1.10.15.tgz

# 执行升级
cd harbor
./install.sh --with-chartmuseum

迁移到2.x版本

完成1.10.x版本升级后，可以开始向2.x版本迁移。Harbor提供了专门的迁移工具来处理数据库转换：

# 下载2.x版本安装包
wget https://github.com/goharbor/harbor/releases/download/v2.5.3/harbor-offline-installer-v2.5.3.tgz
tar xvf harbor-offline-installer-v2.5.3.tgz

# 执行数据库迁移
cd harbor
./prepare --migrate-db
./install.sh --with-trivy --with-chartmuseum

迁移过程中，数据库会从MySQL转换为PostgreSQL，所有数据会自动迁移。详细迁移逻辑可查看migration/migration.go文件。

验证与回滚：确保升级成功的最后一道防线

升级完成后，需要进行全面验证，确保所有功能正常工作。同时，也要准备好回滚方案，以防升级过程中出现意外情况。

升级验证清单

基本功能验证：
- 登录Web UI，检查项目和镜像是否完整
- 推送和拉取镜像测试
- 执行简单的复制策略
- 检查日志是否有错误信息
高级功能验证：
- 漏洞扫描功能（Trivy集成）
- 镜像签名和验证
- Helm Chart仓库功能
- 用户权限和RBAC配置

验证命令示例：

# 拉取测试镜像
docker pull busybox:latest
docker tag busybox:latest localhost:8080/library/busybox:latest
docker push localhost:8080/library/busybox:latest

# 检查镜像是否存在
curl -u admin:password http://localhost:8080/api/v2.0/projects/library/repositories/busybox/tags

回滚预案

如果升级过程中出现严重问题，需要能够快速回滚到之前的稳定版本。回滚步骤如下：

# 停止当前版本
cd /path/to/new/harbor
docker-compose down

# 恢复备份数据
rm -rf /data/harbor
rsync -avz /backup/harbor-20230101/data/ /data/harbor/

# 启动旧版本
cd /path/to/old/harbor
docker-compose up -d

建议在升级前使用tests/testcases/目录中的测试用例进行预验证，确保升级不会影响关键业务流程。

常见问题与解决方案

数据库迁移失败

问题：执行prepare --migrate-db时提示数据表不存在。

解决方案：

检查源数据库连接是否正常
确认1.x版本已升级到1.10.x
手动执行SQL脚本修复数据库结构：

psql -U postgres -d harbor -f ./make/migrations/postgresql/upgrade-1.10.0-2.0.0.sql

镜像拉取权限问题

问题：升级后普通用户无法拉取镜像。

解决方案： Harbor 2.x引入了更严格的权限控制，需要重新配置项目成员权限：

登录管理员账户
进入项目设置
检查并更新成员角色分配

相关代码实现可参考src/controller/member/目录下的权限控制文件。

配置文件解析错误

问题：启动时提示harbor.yml配置错误。

解决方案：

使用yamllint检查配置文件格式：

yamllint harbor.yml

确保所有必填项都已设置，特别是 hostname 和证书相关配置
检查缩进是否正确，YAML对缩进非常敏感

结语：拥抱Harbor 2.x的新特性

完成Harbor升级后，你将获得诸多强大新功能，包括：

基于角色的细粒度访问控制
集成Trivy进行漏洞扫描
支持OCI制品和Helm Chart管理
增强的复制和同步功能
改进的UI和用户体验

建议升级后参考ROADMAP.md了解未来功能规划，以及CONTRIBUTING.md参与社区贡献。如有任何升级相关问题，可通过Harbor的GitHub Issues或社区论坛寻求帮助。

祝你的Harbor升级顺利，享受新版本带来的强大功能！如果觉得本文对你有帮助，请点赞收藏，并关注我们获取更多容器技术实践指南。下期我们将带来"Harbor高可用部署最佳实践"，敬请期待！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考