1. 迁移前的准备工作先摸清家底再动手接手过harbor迁移的活儿之后我发现一个规律凡是迁移过程翻车的十有八九是卡在前期准备不足上而不是迁移本身有多难。harbor低版本迁高版本这件事首先要搞清楚你手里到底是什么版本、要往哪个版本迁、中间隔着几个大版本这三个问题直接决定了迁移路径怎么设计。先说说harbor的版本演进逻辑。harbor的版本号大致按主版本.次版本.补丁版本排列比如1.10.2、2.3.5这种。主版本升级通常意味着架构层面的调整比如从1.x升级到2.0核心变化是底层组件大换血——从docker compose管理方式转向了对kubernetes更友好的部署方式同时引入了OCI兼容支持镜像存储的格式也做了调整。次版本升级则偏向功能增强和组件版本更新比如2.0到2.1、2.2这样的递进。补丁版本就是修bug、补漏洞基本不影响迁移方案。迁移路径大致可以分成三类同主版本内的补丁升级比如2.3.1迁到2.3.5这种最简单直接替换镜像重启就行跨次版本升级比如2.2.x迁到2.4.x通常需要按顺序逐级升不能跳级跨主版本升级比如1.10迁到2.8这种最复杂往往需要先升到一个中间版本再做数据层面的转换和迁移。迁移前最重要的一个动作是盘点数据构成。harbor的数据分三大块一是数据库数据存放项目、用户、镜像仓库元数据、权限配置、复制规则、审计日志这些信息二是存储数据即实际的镜像层文件可能在本地磁盘、NFS、对象存储或者S3兼容存储上三是配置文件包括harbor.yml、nginx配置、证书文件等。这三块数据的备份和迁移策略完全不同缺一块都可能导致新环境起不来或者数据对不上。我的建议是先把这个清单列出来逐项确认当前环境的情况再做迁移方案设计。我见过有人直接拷贝harbor的数据库文件到新版本用的结果版本跨度太大数据库结构对不上项目信息全错乱最后只能回滚从头再来。所以说低版本迁高版本本质上是个数据转换与兼容性处理的问题不是简单地把东西搬过去就行。另一个容易忽略的点是版本兼容性预检。harbor官方文档里通常会对迁移路径有明确说明比如从某个版本升级到另一个版本可能需要先升级到某个中间版本。比如1.x要迁到2.x官方一般建议先升级到1.10.x最新补丁再升到2.0然后再逐级往上。这个路径一定要提前确认别想着一次跨好几个大版本底层数据库结构和API的变化可以通过中间版本来承接直接跳级往往导致数据库迁移脚本跑不过去。2. 数据备份的完整方案数据库、存储和配置一样都不能少备份这块是整个迁移里最不能省的环节。一个完整的harbor备份应该覆盖三块数据库备份、存储数据备份、配置文件备份。我先逐个讲清楚怎么操作再说说常见的坑。2.1 数据库备份的具体操作harbor的数据库跑在postgresql里容器名一般叫harbor-db数据持久化在宿主机的/data/database目录下。备份数据库有两种方式一种是直接拷贝数据目录另一种是用pg_dump导出逻辑备份。直接拷贝数据目录的方式适合停机时间窗口长、数据量不算特别大的场景。操作上就是先把harbor停掉确保数据库没有写入然后tar打包整个/data/database目录。这种方式的好处是恢复速度快直接把目录放回去就行但前提是主版本和数据库大版本要对得上如果跨大版本迁移数据库本身的二进制升级可能都搞不定这时候就得用pg_dump。pg_dump的方式适合跨版本场景因为它是逻辑导出与数据库的物理文件格式无关。在harbor容器里执行docker exec harbor-db pg_dump -U postgres -Fc postgres postgres.dump需要注意harbor的数据库不止一个项目数据在postgres库里但clair组件有自己的数据库有的版本还有notary的库。保险的做法是用pg_dumpall把整个实例的所有库都导出来docker exec harbor-db pg_dumpall -U postgres all.dump这个命令会把所有数据库、角色、权限都导出来恢复的时候能保持完整。我见过有人只备份了postgres库结果迁移后发现复制规则全丢了查了半天才想起来复制规则的数据有一部分存在别的库里。所以如果可以一律用pg_dumpall。2.2 存储数据备份的策略镜像层数据是harbor里最占空间的部分备份策略跟存储后端类型强相关。如果是本地存储即默认的/data/registry目录备份方式就是停服后打包目录。但镜像文件数量动辄几十万直接tar会很慢而且一旦镜像文件在打包过程中被写入整个备份就不一致了。最稳妥的做法是先停harbor服务再打包。停服的时间窗口如果只有几分钟那就要考虑增量备份或者用文件系统快照比如LVM快照或者云盘快照几秒钟就能完成不用停服太久。如果是对象存储比如S3或者阿里云OSS、腾讯云COS这类备份就简单多了直接利用云平台提供的快照或者跨区域复制功能甚至可以不用对harbor做任何操作在存储层面做只读快照即可。然后在迁移时新环境的harbor直接配置对接同一个bucket镜像数据就天然可用了。但这里有个容易踩的坑harbor迁移时如果存储数据不搬走新环境直接复用旧bucket那么数据库里的镜像元数据和存储里的层文件必须一一对应。层文件的路径规则在harbor里跟项目名、仓库名相关如果迁移过程中改了项目名或者仓库名存储路径就对不上了镜像pull的时候会报manifest unknown。所以迁移时要么保持项目名和仓库名完全不变要么在数据导入时做一次路径映射。2.3 配置文件与证书的备份细节配置文件这部分虽然小但重要性不亚于数据库。需要备份的主要包括harbor.yml有的版本是harbor.yml.in需要先复制一份harbor.yml再改、harbor的证书文件和私钥/data/cert目录、以及自定义的nginx配置如果改过。证书这块要特别提醒harbor默认安装时会自签证书但如果之前用的是企业内部证书或者机构签名证书这些证书在迁移时必须保留否则所有docker客户端pull/push的时候都会因为证书不匹配而报错。迁移后docker daemon端需要配置的insecure-registries或者CA证书也要同步更新。还有一点harbor.yml里配置的数据库密码、harbor_admin_password、secretkey这些敏感信息在备份时要单独记录下来。harbor在安装时会生成一个/data/secret目录存着一些加密密钥这个目录如果丢了即使数据库正确恢复了原来加密存储的密码字段可能也解不开导致登录失败。所以说/data目录整个备份是最省心的但要注意备份文件的权限保护毕竟里面都是明文或弱加密的凭据。3. 安装新版本与数据恢复核心环节逐步拆解3.1 新版本规划与安装包准备备份做完接下来就是在目标机器上装新版本的harbor。这里牵涉到一个关键问题是原地升级还是新机部署。原地升级是指在同一台服务器上替换版本新机部署则是在一台干净机器上装新harbor然后把旧数据导过来。我的经验是跨大版本迁移优先选择新机部署原因很简单——一旦迁移过程中出现问题旧环境的服务还能继续对外提供回滚也方便。原地升级的话等你想回滚时旧版本可能已经被拆掉了。安装包准备要说一下离线包的事情。harbor提供了在线安装包和离线安装包离线安装包会把所有镜像打成一个tar包体积比较大但内网环境部署时特别省心。下载安装包之前务必核对目标版本的sha256校验值下载后做一次完整性校验避免安装包损坏导致后面各种莫名其妙的问题。sha256sum harbor-offline-installer-v2.8.6.tgz解压后目录里会有一个harbor.yml.in模板文件需要复制为harbor.yml并修改。这里有个细节harbor.yml里的配置项在不同版本之间是有差异的比如低版本里没有的配置项在高版本中可能是必填项或者某个配置项的默认值发生了变化。比如从1.x升级到2.x新增了metrics、cache layer等配置项而有的旧配置项被移除了。所以安装新版本时不建议直接拿旧的harbor.yml塞进去最稳妥的做法是拿新模板生成一份全新的harbor.yml然后把旧环境里的关键配置项hostname、端口、证书路径、存储配置、数据库密码等逐一对应填进去。3.2 镜像数据导入的几种路径选择镜像数据怎么迁过去是整个迁移方案分歧最大的地方。根据数据量和停机窗口的要求有三条路可以走。第一条路存储层复用。如果新旧harbor用的是同一套对象存储比如同一个S3 bucket或者新机器NFS挂载的是同一个存储池那镜像数据就压根不用搬。新harbor在配置存储时指定同一个bucket镜像层文件直接就能访问到。但这里条件苛刻项目名和仓库名必须跟旧环境完全一致并且镜像在存储中的路径规则在目标版本中不能变化。harbor从1.x到2.x镜像存储路径规则有没有变坦白说不同的版本组合结果不一样如果目标是2.0以上层文件路径格式相对稳定但1.x和2.x之间的兼容性需要实测验证。这条路建议先在测试环境跑通再上生产。第二条路docker client方式批量推送。思路很朴素用docker login登录旧harbor把每个仓库的镜像pull下来tag成新harbor的地址再push上去。这种方式的好处是跟harbor的数据结构没关系纯粹走标准镜像分发协议兼容性最好几乎不会出数据层面的幺蛾子。坏处是效率低镜像多的时候非常费时间而且占用的带宽和磁盘空间都很大。如果镜像总量在几百GB以内停机窗口又允许这条路径是最省脑子的。我一般会写一个脚本自动遍历harbor的API拿到所有项目下的仓库列表然后逐仓库搬运。脚本要点是这样的# 获取所有项目 curl -u admin:password https://old-harbor/api/v2.0/projects # 获取项目下所有仓库 curl -u admin:password https://old-harbor/api/v2.0/projects/{project_name}/repositories # 获取仓库下所有tag curl -u admin:password https://old-harbor/api/v2.0/projects/{project_name}/repositories/{repo_name}/artifacts拿到镜像清单后逐条执行docker pull old-harbor/project/repo:tag docker tag old-harbor/project/repo:tag new-harbor/project/repo:tag docker push new-harbor/project/repo:tag需要提醒的是v2.0的API和v1.x版本的API路径差异很大脚本要跟旧环境的API版本匹配。如果旧环境是1.x用的是/api/repositories这类的旧接口如果旧环境本来就是2.x才能直接用/api/v2.0路径。第三条路底层数据文件直接拷贝加数据库恢复。这个方法的核心是用新版本提供的迁移工具或者手动将旧数据库dump文件导入新环境同时把镜像存储数据原样拷贝到新环境的存储目录。这条路的前提是数据库结构兼容或者能被迁移工具自动升级。harbor官方对新版本迁移提供了upgradehelper工具它的原理是启动一个迁移辅助容器用旧的镜像启动旧版本然后对新版本数据库做schema升级再辅助把数据搬迁过去。这个工具我在低版本升1.x到2.x的场景里用过整体流程还算顺但必须严格按官方文档的操作顺序来而且官方文档对不同的跨大版本路径有明确要求比如必须先升级到特定的中间版本再升级。我在实操中发现很多人在这个环节容易犯一个错误直接把旧的postgres.dump文件恢复到新版本数据库里认为万事大吉但新版本的harbor在启动时可能自己会跑数据库初始化如果检测到已有数据可能不会执行升级脚本或者执行到一半发现字段不匹配而报错。这个问题的根源是版本跨度大数据库schema差异太大了。更稳的路径是先启动一次空的新harbor让初始化脚本跑完然后再停掉把旧数据导入把存储目录覆盖回去再重新启动。这样新版本自己生成的schema基础加上旧数据匹配度会高很多。3.3 数据库恢复与配置修正的实操细节如果采用底层数据导入的方案数据库恢复这一步要格外小心。假设你dump的是旧环境的pg_dumpall输出恢复的时候在目标机器上先启动一次全新的harbor让它把数据库初始化好然后停止harbor把备份的dump导入docker exec -i harbor-db psql -U postgres -f - all.dump然后重新启动harbor应用容器docker-compose up -d如果数据库本身没有报错再用harbor的迁移或健康检查脚本验证。有的版本提供了harbor migrate的脚本在prepare阶段可以对数据库进行预检和修复./prepare --with-notary --with-clair这一步如果提示数据库结构有问题通常意味着你的导入方式不对或者版本的schema差异太大需要重新审视迁移路径。3.4 新harbor的完整安装初始化流程不管选哪条镜像导入路径新harbor的安装初始化本身是个标准流程。参考步骤是修改配置后执行install脚本指定数据目录和存储类型。如果复用旧数据目录确保config目录里旧配置已经清理避免新旧配置冲突。sudo ./install.sh --with-trivy --with-notary注意带上需要的组件参数。trivy是漏洞扫描组件2.x之后取代了clair如果以前用了clair现在得换成trivy。notary是镜像签名用的用不到的话可以不启用减少资源占用。安装完成后的预检动作要重视先检查harbor的核心服务是否都在running状态然后挑一个测试项目跑通login、push、pull全流程确认镜像能正常访问后再把对外流量切过来。这个预检环节能把绝大多数问题在业务影响范围扩大前暴露出来。4. 迁移后的验证与常见问题排查不要急着删旧库迁移不是把数据搬完就算完事新环境必须经过一系列验证确认服务稳定、数据完整、功能正常才算真的迁移成功。我一般把验证分成四层每一层都有具体的检查项。第一层是基础设施检查服务状态、端口监听、数据卷挂载情况。用docker-compose ps或者docker ps看所有容器状态重点看harbor-core、harbor-registry、harbor-db、harbor-portal和proxy这几个关键容器是否正常。第二层是API与UI验证登录harbor的Web界面确认项目、用户、仓库列表都在确认镜像的tag信息、manifest信息能正常展示。再用API方式抽查数据一致性比如通过harbor的catalog接口拉一遍已有的仓库清单跟旧环境的清单比对确认数量一致。第三层是功能抽验随机挑几个重点项目从新harbor拉取镜像跑一个docker pull确认tag能正确解析manifest能正常下载镜像层能按需拉取。有复制规则的触发一次复制任务确认能正常执行。涉及用户权限的创建或修改一个用户确认权限能生效。第四层是数据一致性核对把旧环境导出的镜像清单和tag清单跟新环境实际拉取的清单做一次全量对比。这里可以用脚本从API导出两边的repo和tag列表然后diff一下。镜像数量多的时候这一步绝对必要因为某些镜像可能在搬运过程中因为网络中断或者脚本中断被跳过了。我当时迁移时就是因为脚本中途超时退出结果有几十个镜像没搬过去还好做了这层核对才及时发现。发现的常见问题我整理了几个典型的基本覆盖了大部分迁移翻车场景。4.1 镜像标签消失或manifest不正确这个问题的表现是新harbor里仓库存在但镜像tag列表是空的或者pull镜像时报manifest unknown。原因一般有三种一是存储层复用后镜像数据的路径跟数据库记录不一致二是推送过程中部分镜像push失败被忽略了三是数据库的镜像元数据导入不完整。处理思路是先确认存储目录里对应的仓库路径是否存在镜像层文件如果存在且路径对得上那大概率是数据库里的repository和tag记录缺失。解决方法可能是用harbor的GC或者镜像清理任务强制harbor重新扫描存储重建tag索引。harbor有garbage collection功能在管理页面可以触发一次也可以命令行执行docker exec harbor-registry /etc/docker/registry/gc.sh如果GC之后还不行就得考虑是不是存储路径规则在版本间发生了变化这时候只能通过动态推送方式重新同步这部分镜像。4.2 数据库认证失败或密码不一致新harbor报数据库连接失败的错误最常见的原因是harbor.yml里配置的数据库密码跟实际数据库里的密码不一致。这个问题的根源往往不是迁移本身而是配置步骤里漏了密码对齐。旧环境安装时会在数据库中创建一个专门的数据库用户密码存放在harbor.yml或者之前的配置里新环境搭建时用的密码如果跟数据库中的不一致docker-compose启动的harbor组件就会认证失败。解决方法是在执行install.sh之前先确认harbor.yml中数据库密码字段的值并同步到数据库里。可以通过docker exec进入harbor-db容器用psql重置用户密码然后再启动harbor。另一种情况是跨版本后数据库里默认用户被重新初始化了原来在旧环境里创建的额外数据库账号比如某些应用设置的只读账号在新环境不存在这个在验证阶段容易被忽略。4.3 组件连接超时或证书不匹配组件之间通信出问题典型的报错是nginx返回502 Bad Gateway或者harbor-core无法访问registry服务。这通常跟网络配置或者TLS证书有关。迁移后如果在harbor.yml里改了hostname但旧证书仍然是用旧hostname签发的HTTPS握手就会失败。这种情况必须在启动前把新hostname的证书生成好并放到指定目录同时更新docker daemon对harbor域名的信任配置。另一个容易出问题的地方是NTP时钟同步。harbor内部组件和外部客户端之间有时会做token签名和过期时间校验如果服务器时间偏差大会出现莫名其妙的token invalid报错。这个在迁移后必须检查尤其当新环境是从模板克隆出来的虚拟机时间往往不准。4.4 机器资源占用过高或数据库初始化缓慢高版本harbor对硬件资源的要求普遍比低版本高特别是内存。2.x版本的harbor默认会启用trivy组件扫描器启动时内存占用可能达到1GB以上。如果新机器内存不够充足服务看起来起来了但过一会儿容器被OOM杀掉导致整个平台不可用。这个问题的排查思路是看docker events或者system log确认是否有OOM相关记录然后适当调整trivy的并发数和内存限制配置。数据库初始化缓慢的问题通常出现在数据量非常大的场景里。新版本首次启动时要跑数据库迁移脚本对已有数据做schema升级数据量大时这个阶段可能持续几十分钟。很多人以为机器卡死了直接重启结果把初始化流程打断导致数据库处于半迁移状态。我的经验是首次启动新环境时如果dump文件导入过启动后至少要等15~20分钟再做健康检查期间不要频繁重启可以通过数据库日志观察迁移进度。5. 避坑经验与效率技巧实测出来的心得迁harbor这种事做得多了就会发现很多文档里查不到的细节记录在这里供大家参考。第一个建议是如果旧环境和新环境的镜像数据处理能力允许优先用动态推送的方式迁移镜像尤其是跨大版本时。原因很简单底层数据文件拷贝和数据库导入的方式跟版本耦合度高一旦版本间数据结构变化大问题排查的复杂度会显著上升而动态推送是走标准协议即使harbor版本升级镜像分发协议始终是稳定的问题面小得多。当然动态推送的代价是需要比较长的时间窗口如果停机时间不允许那就只能走底层数据方案但建议先在测试环境完整演练一遍。第二个建议是迁移前把旧环境的镜像清单导出一份完整的记录包括项目、仓库、tag、digest、大小这些信息。这个清单不仅用于迁移后的核对还会在迁移期间遇到问题时帮你快速判断哪些数据还没迁移、哪些数据已经对齐。导出方式很简单写一个脚本循环调用API就行我现在每次迁harbor都会做这件事。第三个建议是如果在迁移过程中遇到组件版本不兼容的报错不要慌先去看官方文档的升级路径说明大多数已知问题都有明确的处理方案。很多报错信息看起来复杂其实只是某个中间步骤没走完或者某个环境变量没设置好。把日志打出来逐行读一遍通常能发现工业化生产的坑反而好解。第四个建议是harbor迁移完后的收尾工作别落下了新环境的备份任务要重新配置监控告警要重新接入docker daemon等其他需要对接harbor的系统要重新指向新地址并更新证书配置甚至有些CI/CD流水线里硬编码了harbor服务器地址的需要全部替换。我在一次迁移后遇到一个最无语的问题某个构建脚本里写死了旧harbor的IP管理员说迁移完了两天后发现流水线还在往旧harbor推镜像不知道推到了哪里去。所以迁移清单里一定要有“下游系统对接确认”这一项。迁移harbor这件事本质上是个严谨的数据搬迁工程低版本迁高版本的挑战主要来自版本间数据结构的差异和组件配置的变化。只要前期规划到位备份完整路径选对验证充分风险是可控的。最怕的是跳过一些看着不起眼的步骤比如中间版本跳级、直接拿旧配置文件用在新版本上、没有核对镜像清单这些都会给后续埋雷。从我个人的经验看把备份放在第一优先级、把镜像清单核对贯穿全程哪怕数据量大一点迁移过程再慢一点换来的都是稳定和可回滚的保障。干这一行稳比快重要能回滚比一次成功更让人踏实。