1. 为什么Nexus 2.11.4的迁移升级值得认真对待私库这东西平时没人关注一出问题全公司研发都得停下来。我们团队用Nexus 2.11.4搭的Maven私库跑了快四年上面托管了自研的二方库、代理了中央仓库和阿里云仓库还有一堆历史版本的快照。机器是老虚拟机版本是2016年的Nexus 2.11.4界面老、性能差、搜索慢最关键的是Sonatype官方对2.x早就停止维护了安全补丁不再更新。真正下决心迁移是因为一次批量拉取依赖超时导致整个构建流水线卡了四十分钟那之后我就开始研究怎么把nexus 2.11.4平滑迁到nexus 3.12.0。这篇文章面向的是手里管着Maven私库、正在纠结要不要升级或者已经决定升级但不知道从哪下手的运维和开发同学。我会把整个迁移链路拆开讲为什么不能一步到位、升级代理怎么用、Maven客户端配置怎么同步改、迁移后哪些坑必踩。读完你能拿到一套可直接参照执行的方案包括我实际用过的参数、校验脚本和排查思路。整个过程我做了两轮第一轮在测试环境跑通第二轮才上生产中间踩的坑都会写出来。2. 迁移之前必须想清楚的几件事2.1 Nexus 2.x 和 3.x 到底差在哪里很多人以为Nexus 3只是Nexus 2的界面美化版其实底层差别很大。Nexus 2用的是OrientDB作为存储引擎仓库数据、元数据、配置全部塞在同一个数据库里Nexus 3早期版本3.12.0属于这一批同样基于OrientDB但数据模型完全重构而且引入了Blob Store的概念把二进制文件和元数据分开管理。这意味着你不能简单地把Nexus 2的sonatype-work目录拷到Nexus 3下面让它直接读两边数据结构根本不兼容。仓库模型的差异更直接。Nexus 2里一个仓库可以是hosted、proxy、group、virtual四种类型Nexus 3里virtual被取消了group的聚合逻辑也重写了。Nexus 3还额外支持了Docker、npm、PyPI、RubyGems、Yum等格式的仓库这是2.x时代想要但没做好的东西。权限模型方面Nexus 2的privilege和role体系在3.x里做了精简和重组部分内置角色名称变了迁移之后需要重新核对一遍。对Maven用户来说最直观的差异是URL路径。Nexus 2的仓库地址形如http://host:8081/nexus/content/groups/public/而Nexus 3改成了http://host:8081/repository/maven-public/。这个变化意味着所有项目的settings.xml、pom.xml以及CI流水线里的仓库地址都要跟着改漏一个地方就会出现依赖拉不到的情况。我第一轮迁移时就是因为漏改了一个老旧项目的POM构建时一直报Could not find artifact排查了半小时才定位到。2.2 版本选型的逻辑为什么是3.12.0而不是更高选3.12.0不是因为它最新而是因为它是当时3.x系列里相对稳定、社区资料最全的版本。Nexus 3.x在3.14之前对OrientDB的依赖还比较重3.12.0正好处于功能完备性和稳定性都比较均衡的阶段。再往上到3.15存储引擎开始向Elasticsearch过渡迁移路径和配置方式又有变化对于刚从2.x过来的团队来说学习成本更高。3.12.0的升级代理Upgrade Agent功能已经成熟能识别Nexus 2.14.x的数据格式这是能迁移成功的先决条件。这里有个关键限制必须说清楚升级代理只支持从Nexus 2.14.x迁移到Nexus 3.x2.11.4版本太老代理根本认不出来。所以整个迁移路径实际上是两段先把2.11.4升到2.14.202.x系列的最终版本再从2.14.20通过升级代理迁到3.12.0。第一段升级是原地升级替换安装包、指向同一个数据目录就行第二段才是真正的跨版本迁移。这个两段式路径是绕不开的我试过跳过中间版本直接用2.11.4连升级代理代理直接报Unsupported source version。2.3 迁移前的资产盘点和备份策略动手之前先做一次彻底的资产盘点把Nexus 2上所有仓库列出来标注类型、用途、数据量、最近更新时间。我当时的清单是这样的hosted类型的releases和snapshots各一个proxy类型的central、aliyun、spring各一个group类型的public一个另外还有几个废弃的历史仓库。盘点之后明确哪些必须迁、哪些可以合并、哪些直接丢弃能大幅减少迁移时间和后续维护成本。备份是整个迁移里最不能省的一步。Nexus 2.11.4的数据全在sonatype-work/nexus目录下直接打包整个目录是最稳妥的做法命令很简单# 停掉Nexus 2服务 service nexus stop # 打包整个数据目录 tar -czvf nexus2-backup-$(date %Y%m%d).tar.gz /opt/sonatype-work/nexus # 确认包完整 tar -tzvf nexus2-backup-20240101.tar.gz | head -20注意备份时一定要停服务Nexus 2运行中直接打包OrientDB可能有锁文件残留恢复时容易出问题。备份文件至少保留两份放在不同的物理位置。除了数据目录还要导出Nexus 2的仓库配置和权限配置。Nexus 2的conf/nexus.properties里记录了端口、上下文路径等关键信息conf/security.xml里有用户和角色。这些在迁移后做对照校验时非常有用。我当时把这两个文件也一并归档后面核对权限映射时省了不少事。3. 第一段从2.11.4原地升级到2.14.203.1 升级包获取和服务替换Nexus 2.14.20是2.x系列的最后一个版本下载地址在Sonatype的归档页面能找到。拿到nexus-2.14.20-02-bundle.tar.gz之后解压到一个新目录把旧版本的conf目录下几个关键配置文件拷过来包括nexus.properties、jetty.xml、security.xml和logback.xml。数据目录不用动新版本启动时会自动识别并升级OrientDB的结构。替换过程我记录得很细先在测试环境操作确认没问题再上生产。测试环境用的是同一份数据备份这样能真实反映升级过程。命令大致如下# 解压新版本 tar -xzvf nexus-2.14.20-02-bundle.tar.gz -C /opt/ # 备份旧配置 cp -r /opt/nexus-2.11.4/conf /opt/nexus-2.11.4/conf-bak # 拷贝关键配置到新版本 cp /opt/nexus-2.11.4/conf/nexus.properties /opt/nexus-2.14.20-02/conf/ cp /opt/nexus-2.11.4/conf/security.xml /opt/nexus-2.14.20-02/conf/ # 指向原数据目录 # 编辑 nexus.properties确认 nexus-work 指向原 sonatype-work启动新版本之前先确认nexus.properties里的nexus-work属性指向的还是老的sonatype-work目录。启动后观察日志OrientDB会有一段时间的schema升级过程几分钟到十几分钟不等取决于数据量。升级完成后用浏览器访问能看到Nexus 2.14.20的界面所有仓库、用户、权限都在说明原地升级成功。3.2 升级到2.14.x之后需要检查什么原地升级完成后不能急着往3.x迁先做几项检查。第一是登录验证用原来的管理员账号登录确认用户和角色都在第二是仓库验证逐个仓库查看内容是否正常重点看proxy仓库的缓存文件有没有丢失第三是功能验证用一个测试项目往hosted仓库部署一个快照再从group仓库拉取一次确认读写链路通畅。我遇到过一个情况升级后有个proxy仓库的远程状态显示异常原因是该仓库配置的远程地址已经失效升级过程中校验不通过。处理方式是在仓库配置页面重新点一次Update或者Invalidate Cache让它重新连接。这种问题不影响迁移但放在那里会让后续的升级代理导入时多一条警告。另外记得检查conf/security.xml里的anonymous用户是否还在启用状态有些团队为了安全禁用了匿名访问迁移到Nexus 3之后需要在新平台上重新配置对应的权限。3.3 升级代理的安装位置和启动方式升级代理不是一个独立的服务它是Nexus 3自带的一个功能模块。要使用它需要先在Nexus 3.12.0上启用Upgrade Agent这个能力然后在Nexus 2.14.20上安装一个配套的代理插件。具体的做法是登录Nexus 3的管理界面找到Upgrade相关的配置入口系统会提示你下载一个针对Nexus 2的代理包。把下载下来的代理包放到Nexus 2.14.20的nexus/WEB-INF/plugin-repository目录下重启Nexus 2服务。重启后在Nexus 2的界面里会多出一个升级相关的入口同时Nexus 2会通过一个内部通道与Nexus 3建立连接。这一步的关键是网络要通Nexus 2和Nexus 3之间能互相访问端口。我测试环境用的是同一台机器不同端口生产环境是两台独立机器配置时把Nexus 3的地址和端口填进Nexus 2的升级代理配置里就行。注意升级代理在两边的版本兼容性上有要求Nexus 2侧必须是2.14.xNexus 3侧建议3.12.0及以上。如果你的Nexus 3低于这个版本先升级Nexus 3再操作。4. 第二段通过升级代理迁到Nexus 3.12.04.1 需要先想清楚哪些仓库要迁移Nexus 2上的仓库不一定全部需要迁移尤其是那些废弃的、数据量巨大的历史快照仓库。迁移前我建议做一次筛选把仓库分成三类必须迁移的正在被项目依赖的releases、snapshots、proxy缓存、可以合并的多个功能重复的proxy仓库、可以丢弃的历史遗留、无人使用的仓库。筛选逻辑是看仓库的最近一次访问时间和被依赖的次数。我当时把三个proxy仓库合并成了一个因为它们的远程地址指向的都是中央仓库只是配置时间不同。合并之后Nexus 3上的仓库数量从十多个减到六个迁移时间缩短了近一半后续维护也简单很多。筛选这一步看起来是额外工作但它直接决定了迁移后的私库是否清爽。私库这东西最怕的就是仓库越堆越多谁都不敢删最后变成一个巨大的垃圾场。4.2 执行迁移和观察迁移日志迁移是在Nexus 3的界面上触发的。进入升级代理的配置页选择要迁移的仓库点击开始迁移。迁移过程是逐仓库进行的每个仓库分为两个阶段先同步元数据再复制二进制文件。元数据同步很快几分钟就完成二进制文件复制取决于数据量和网络带宽几十GB的proxy缓存可能要跑几个小时。迁移过程中一定要盯着日志。Nexus 3侧看nexus.log和upgrade-agent相关的日志文件Nexus 2侧看代理插件的日志。日志里能看到每个仓库的迁移进度、跳过数量、失败数量。我遇到过一个proxy仓库迁移时大量文件报checksum mismatch原因是远端仓库的文件在Nexus 2缓存之后发生了变化校验对不上。这种情况不用慌迁移完成后重新触发一次该仓库的缓存更新即可或者直接忽略这些缓存文件反正proxy仓库的缓存本身可以重建。迁移的顺序也有讲究。我建议先迁group仓库再迁hosted最后迁proxy。原因是hosted仓库里是自研的二方库体量小但重要性最高先确认这部分数据完整proxy仓库体量大但可以重建放最后即使出问题也不影响核心业务。4.3 迁移完成后的四步校验迁移跑完之后绝对不能直接宣布成功必须做校验。我的校验分四步数量校验对比Nexus 2和Nexus 3上各仓库的artifact数量允许有少量差异但不能差太多内容校验随机抽取几个artifact比对文件大小和校验和功能校验用真实项目从Nexus 3拉取依赖确认能正常构建部署校验往hosted仓库部署一个新版本确认写入正常。数量校验我用了一个简单的API脚本来做Nexus 2和Nexus 3都提供了REST API可以查询仓库内容。下面的脚本思路是用curl拉取两边的artifact列表然后做diff# 查询Nexus 2仓库组件列表 curl -u admin:password http://nexus2-host:8081/nexus/service/local/repositories/releases/content/ -o nexus2-list.txt # 查询Nexus 3仓库组件列表 curl -u admin:password http://nexus3-host:8081/service/rest/v1/components?repositorymaven-releases -o nexus3-list.json # 对列表做数量比对具体解析根据返回格式调整实际的数量对比脚本要根据两边的API返回格式做适配不要直接套用。核心思路是拿到两边的artifact坐标列表做集合比对找出只在一边存在的项然后人工确认这些差异是正常的还是迁移遗漏。5. Maven客户端配置的同步修改5.1 settings.xml里必须改的那几处服务端迁完了客户端配置不改等于白迁。Maven客户端的配置集中在settings.xml文件里主要涉及两个地方mirrors和servers。mirrors里配置的是镜像地址原来指向Nexus 2的/nexus/content/groups/public/现在要改成Nexus 3的/repository/maven-public/。servers里配置的是部署仓库的用户名密码地址不需要改但密码要确认在新平台上有效。一个典型的settings.xml片段是这样的mirrors mirror idnexus/id nameNexus 3 Private Repository/name urlhttp://nexus3-host:8081/repository/maven-public//url mirrorOfcentral/mirrorOf /mirror /mirrors servers server idnexus-releases/id usernamedeploy/username passwordyour-password/password /server server idnexus-snapshots/id usernamedeploy/username passwordyour-password/password /server /serversmirrorOf的配置有讲究。如果配成central只镜像中央仓库如果配成*所有仓库请求都走私库。我一般建议配成central加上额外需要的仓库避免把所有请求都压到私库上导致私库压力过大。但如果公司要求所有依赖必须经过私库审计那就配置成*同时确保私库上的proxy仓库配置了所有需要的外部源。5.2 项目POM里的仓库地址和发行版管理settings.xml改了之后大部分场景就够了。但如果项目POM里显式声明了仓库地址那些地方也要改。检查项目里的pom.xml搜索repositories和distributionManagement标签。repositories里如果是写死的Nexus 2地址改成Nexus 3的distributionManagement里的部署地址同样要改。我建议趁这次迁移把POM里的仓库地址统一管理起来。可以在父POM里定义好distributionManagement子模块继承避免每个模块都写一遍。版本号也可以统一管理用properties定义Nexus的地址前缀切换环境时只改一处。这次迁移就是一个很好的重构机会把散落在各个项目里的私库地址收拢到统一的父POM里。提示迁移后如果发现某个老项目构建失败第一件事是搜它的POM里有没有写死的/nexus/content/路径。这是最常见的遗漏点尤其是那些很久没人维护但偶尔还要编一次的老项目。5.3 CI/CD流水线里的配置同步除了开发本地环境CI/CD流水线里的Maven配置也要同步改。Jenkins、GitLab CI、GitHub Actions这些工具里通常有自己的settings.xml或者环境变量来指定私库地址。我踩过的坑是本地改完了CI上没改结果流水线构建时拉依赖还是走老地址报Connection refused或者404。流水线里的私库配置一般有两种形式一种是挂在CI服务器上的全局settings.xml改一处就行另一种是每个项目里自带settings.xml文件需要逐个改。我建议统一成全局配置配合环境变量注入地址这样以后换私库地址只需要改环境变量。迁移期间可以新旧地址并存一段时间老配置指向Nexus 2保持只读新配置指向Nexus 3等所有项目都验证通过后再关掉Nexus 2。6. 迁移后绕不开的权限和认证问题6.1 用户权限在Nexus 3里的对应关系Nexus 2的权限模型在Nexus 3里重新设计了。Nexus 2的repository-any-read、repository-any-write这类粗粒度权限在Nexus 3里变成了更细粒度的nx-repository-view-*-*-read、nx-repository-view-*-*-add等形式。迁移代理能自动搬运用户和角色但角色里的权限映射不一定完全准确需要人工核对。我迁移之后发现一个部署账号失去了hosted仓库的写权限原因是它在Nexus 2里依赖的是repository-any-write这个全局权限迁移到Nexus 3后没有自动转换成对应的细粒度权限。解决方法是在Nexus 3里找到该账号的角色手动补上nx-repository-view-maven2-*-add和nx-repository-view-maven2-*-edit权限。核对权限时我列了一张表把Nexus 2的常用权限和Nexus 3的对应权限列出来逐项对照检查Nexus 2 权限Nexus 3 对应权限说明repository-any-readnx-repository-view---read所有仓库读权限repository-any-writenx-repository-view---add/edit写权限需分add和editrepository-{name}-readnx-repository-view-maven2-{name}-read按仓库名细粒度控制nexus:metrics无直接对应3.x用内置监控替代6.2 匿名访问和部署账号的处理匿名访问是个容易忽略的点。Nexus 2默认允许匿名读取Nexus 3同样默认开启匿名访问但迁移后可能因为权限配置不一致导致匿名用户看不到仓库内容。我的做法是先在Nexus 3的Security Anonymous里确认匿名用户有nx-repository-view-*-*-read权限再测试用未登录状态访问仓库URL确认返回正常。部署账号建议单独建不要用admin。迁移后检查部署账号的密码是否同步过来了Nexus 2的密码哈希算法和Nexus 3不完全一样有些账号迁移后可能需要重置密码。我遇到过一次部署失败报401排查发现是部署账号的密码在迁移后变成了无效状态重置密码后恢复正常。所以迁移完成后第一件事是用部署账号在Nexus 3上手动部署一个测试artifact确认写入链路通畅。6.3 密码找回和初始密码问题Nexus 3的admin初始密码在3.17之前是admin123这类默认值3.17之后改成了首次启动时生成随机密码存在admin.password文件里。3.12.0属于前者默认密码是admin123但迁移过来的admin账号密码会以Nexus 2里的为准。如果忘了密码可以停掉Nexus 3删除db/security目录下的相关文件重置到初始状态但这样会丢失所有用户配置。更稳妥的密码找回方式是通过Nexus 3的API或者直接操作OrientDB。我一般不建议在生产环境直接操作数据库风险太高。如果真的忘了admin密码可以先停服务用一个临时的Nexus 3实例连同一个数据目录初始密码恢复后再启动正式服务。另一种方式是用Nexus 3自带的reset-admin-password脚本指定数据目录执行能把admin密码重置为默认值。7. 迁移过程中常见的报错和排查思路7.1 迁移任务卡住或者静默失败迁移任务卡住是常见问题表现为进度条长时间不动或者日志不再输出。原因通常有三种网络不通、Nexus 2侧代理插件异常、数据量过大导致超时。排查顺序是先确认两个服务之间的网络连通性用telnet或者curl测试端口再检查Nexus 2侧代理插件的日志有没有异常最后看是不是单个仓库的数据量太大可以拆分成多个小任务分批迁移。我遇到过一次迁移任务跑到一半停了日志显示Connection reset。排查发现是Nexus 2所在的虚拟机内存不足迁移过程中OrientDB的查询把内存撑爆了导致代理进程被系统杀掉。处理方式是给Nexus 2临时加内存重启服务后重新执行迁移。这次之后我养成了一个习惯迁移前先检查两边的资源使用情况内存、CPU、磁盘空间都要留够余量。7.2 依赖拉取报404或者找不到artifact迁移后最常见的问题是依赖拉不到。排查路径是这样的先确认Nexus 3上该artifact确实存在通过浏览器访问仓库URL或者用REST API查询如果存在检查客户端的仓库地址是否改对了如果地址也对但还拉不到检查settings.xml里的mirrorOf配置是否把请求错误地路由到了别的仓库。我整理了一个排查速查表遇到问题按顺序对照现象可能原因排查方法404 Not Found仓库地址没改仍指向Nexus 2检查settings.xml和POM里的URL401 Unauthorized部署账号权限或密码问题用部署账号测试写入依赖能找到但下载失败proxy仓库缓存不完整触发缓存更新或检查远端连通性部分老版本拉不到迁移时跳过或数据缺失对比两边artifact数量构建慢mirrorOf配置导致请求绕路检查镜像路由配置7.3 仓库合并和路径变化的连带影响如果迁移时做了仓库合并比如把多个proxy仓库合并成一个那么原来指向被合并仓库的客户端配置就会失效。这种问题不会报错而是表现为某些依赖突然拉不到。处理方式是在Nexus 3上保留一个group仓库把合并后的仓库都加进去客户端统一指向这个group仓库。这样既完成了合并又不会破坏原有的访问路径。路径变化还影响一类特殊场景有些项目在POM里引用了私库上的其他项目作为依赖坐标没变但仓库地址变了。这类项目需要逐个检查确保它们的父POM或者settings.xml用的是新地址。我当时的做法是全局搜索代码仓库里的/nexus/content/字符串把所有出现的文件都列出来逐个确认是否已经更新。8. 迁移期间的灰度切换和回滚预案8.1 双写还是单切迁移窗口期的策略选择迁移不可能瞬间完成中间必然有一个过渡期。过渡期的策略有两种双写和单切。双写是指Nexus 2和Nexus 3同时提供服务新部署的artifact两边都写读取走Nexus 3单切是在一个时间窗口内停掉Nexus 2全部切到Nexus 3。我推荐单切因为双写会带来一致性问题尤其是快照版本很容易出现两边版本不一致的混乱。单切的关键是选好时间窗口。我选的是周五晚上到周六凌晨这个时间段研发活动最少即使出问题也有周末缓冲。切换前把Nexus 2设为只读防止切换期间还有新的部署写入导致数据不一致。Nexus 2的只读设置可以在仓库配置里把部署策略关掉或者直接在网络层面限制写请求。8.2 回滚预案和触发条件回滚预案必须在切换前就准备好。我的回滚方案是保留Nexus 2的完整数据和配置切换后如果Nexus 3出现无法快速解决的问题把客户端配置改回Nexus 2的地址重启Nexus 2服务即可恢复。整个过程要求客户端配置的修改是可逆的所以我在改settings.xml时没有直接覆盖而是保留了老配置作为注释回滚时取消注释就行。触发回滚的条件我定了几条核心仓库无法读取超过15分钟部署功能完全不可用数据校验发现大面积丢失。只要满足其中一条立即执行回滚不在故障状态下尝试修复。这条经验是从一次生产事故里学来的当时试图在故障状态下一边排查一边修结果拖了两个小时最后还是回滚。后来我给自己定了规矩迁移切换要么成功要么快速回滚不在中间状态浪费时间。9. 我踩过的坑和实操心得第一个坑是版本路径没搞清楚就动手。我一开始想直接拿2.11.4连升级代理折腾了半天才发现必须经过2.14.x。这个信息在官方文档里写得不算显眼但确实是硬性约束。后来我先在测试环境把2.11.4升到2.14.20再走升级代理一次就通了。所以如果你手上的Nexus低于2.14先做原地升级别想着抄近路。第二个坑是忽略了客户端配置的同步修改。服务端迁移只完成了工作的一半客户端的settings.xml、项目POM、CI配置三处都要改。我第一轮迁移时只改了本地settings.xmlCI流水线没改结果第二天早上自动构建全部失败排查了半小时才发现是流水线还指向老地址。建议把客户端配置的修改列成清单逐项打勾确认比靠记忆靠谱。第三个坑是权限映射没有逐项核对。Nexus 2的全局权限在Nexus 3里没有完全对应的转换尤其是repository-any-write这类粗粒度权限。迁移后如果不核对部署账号看起来存在但实际没有写权限部署时会报401。我的解决办法是迁移后先用部署账号做一次写入测试能写成功再宣布迁移完成这比看权限配置页面更直接。第四个坑是迁移后的仓库校验偷懒了。有一批旧版本的快照没有迁移过来原因是那些快照在Nexus 2上已经被标记为过期清理迁移代理跳过了它们。这些快照虽然旧但有几个老项目还在用结果构建时报找不到依赖。后来我手动从Nexus 2的备份里把这些快照恢复到Nexus 3上。这件事让我明白迁移后的数量校验不能只看总数要按仓库、按时间范围细看把差异项逐个确认。最后一个心得是关于迁移节奏的。整个过程分成了测试环境验证、生产环境灰度、生产环境全量三步中间留了足够的时间做校验和观察。切忌一步到位直接在生产环境上操作也不要在周五下午这种敏感时间做切换。给迁移留出至少两个工作日的缓冲期遇到问题可以从容处理。私库迁移不像普通的服务升级它影响的是所有研发的构建链路稳比快重要得多。