Nexus 3.24.0-02 内网仓库搭建与 Maven/NPM 代理配置实战

简介Nexus Repository Manager 3.24.0-02 的 Unix/Linux 官方安装包面向 Java 与前端开发团队中负责制品仓库搭建、依赖治理的运维及中高级开发者。它解决 Maven、NPM 等组件分散存储、重复下载与私有包托管难题可作为内网统一仓库代理与分发平台。压缩包整体约 149.69MB解压后主要包含 nexus-3.24.0-02 与 sonatype-work 两部分前者承载可执行文件、配置文件与依赖库后者作为运行时工作目录存放制品、索引、日志及数据库内容部署时需保持独立以保障数据持久化与升级安全。目前已有 212 人学习下载。通过 conf/nexus.properties 与 Web 控制台可配置端口、代理仓库、存储库组与权限并将 Nexus 设为 NPM 默认注册表实现 Maven 依赖加速检索、NPM 包缓存与私有托管帮助团队提升构建效率与组件安全性。1. 从一台内网构建机说起nexus-3.24.0-02-unix.tar.gz 到底解决什么问题如果你所在团队还在用「每个人本地攒一堆 jar 包、靠 U 盘和聊天工具传依赖」的方式协作那迟早会遇到同一个场景某台构建机突然拉不到某个版本的依赖或者同一个包在三台机器上校验值不一样排查半天发现是有人手动替换过本地仓库里的文件。这类问题的根子不在代码而在缺少一个统一的制品仓库。nexus-3.24.0-02-unix.tar.gz 就是一套开箱即用的仓库管理服务端发行包解压后自带运行环境不需要额外装 Web 容器主要用来代理和缓存 Maven、NPM 等生态的依赖同时也能托管团队自己构建出来的制品。它适合中小团队做内网依赖统一入口也适合个人在本地或测试环境搭一套私有仓库把外网依赖的不可控因素挡在构建流程之外。下面按「先跑起来、再配仓库、再排坑」的顺序拆一遍。2. 解压即用的启动链路从 tar.gz 到能登录的 8081拿到 tar.gz 之后很多人第一反应是找安装脚本其实这个包的设计就是解压即用。它内部包含两个顶层目录一个是服务本体一个是数据目录首次启动后生成。理解这两个目录的分工后面迁移和备份才不会翻车。2.1 目录结构与运行用户解压后典型结构如下不同小版本目录名略有差异以实际解压结果为准tar -xzf nexus-3.24.0-02-unix.tar.gz ls -l # nexus-3.24.0-02/ 服务本体bin、etc、lib、system # sonatype-work/ 数据目录仓库文件、索引、配置、日志服务本体里的bin/nexus是启动脚本etc/nexus-default.properties控制端口和上下文路径etc/nexus.vmoptions控制 JVM 堆大小。数据目录sonatype-work/nexus3/才是真正存 blob、配置和日志的地方。这里有个血泪经验升级或迁移时只要把sonatype-work整个搬走仓库数据就跟着走只搬服务本体等于换了个空壳。启动前先确认运行用户。默认脚本不允许用 root 直接跑会提示切换用户。常见做法是建一个专用账号# 创建专用运行用户示例名按团队规范替换 useradd -r -m -d /opt/nexus nexusrun chown -R nexusrun:nexusrun /opt/nexus su - nexusrun -c /opt/nexus/nexus-3.24.0-02/bin/nexus start参数说明-r建系统账号-m建家目录-d指定家目录。启动脚本的start是后台启动run是前台启动调试时用run能看到完整日志。如果启动后立刻退出先看sonatype-work/nexus3/log/nexus.log九成是端口被占或 JVM 内存不够。2.2 端口、上下文与首次登录默认监听 8081上下文路径是/。如果 8081 被占改etc/nexus-default.properties# 应用端口与上下文路径 application-port8081 application-host0.0.0.0 nexus-context-path/改完必须重启才生效。首次启动会初始化数据库和默认仓库耗时可能一两分钟期间访问 8081 会看到初始化提示别急着以为挂了。初始化完成后管理员初始密码在cat sonatype-work/nexus3/admin.password登录后系统会强制改密码。这里有个容易忽略的点admin.password文件在改密后会被删除如果没记下来又忘了新密码只能走重置流程比较麻烦。我一般会在改密后立刻把新密码存进团队的密钥管理工具而不是留在聊天记录里。2.3 用 systemd 托管避免掉线即停用su -c启动的方式会话断开后进程虽然还在但不受服务管理器监管机器重启就没了。生产环境常见做法是写一个 systemd 单元# /etc/systemd/system/nexus.service [Unit] DescriptionNexus Repository Manager Afternetwork.target [Service] Typeforking Usernexusrun ExecStart/opt/nexus/nexus-3.24.0-02/bin/nexus start ExecStop/opt/nexus/nexus-3.24.0-02/bin/nexus stop Restarton-failure [Install] WantedBymulti-user.target逻辑说明Typeforking是因为启动脚本会派生后台进程Restarton-failure让异常退出后自动拉起。改完执行systemctl daemon-reload systemctl enable --now nexus。注意User必须和目录属主一致否则数据目录写不进去日志里会报权限拒绝。3. 把 Maven 和 NPM 接进来代理、宿主与仓库组的配置顺序服务跑起来只是第一步真正让团队受益的是把 Maven 和 NPM 的依赖入口统一到 Nexus 上。这一章按「先建代理仓库、再建宿主仓库、最后建仓库组」的顺序走顺序错了会导致客户端配置反复改。3.1 Maven 代理仓库与中央仓库缓存登录后进入仓库管理新建一个 Maven2 (proxy) 类型的仓库。关键参数参数建议值说明Namemaven-central-proxy仓库标识客户端会引用Remote storage中央仓库地址上游地址按团队网络情况填Version policyRelease只缓存正式版避免快照污染Layout policyStrict严格校验路径减少脏缓存Storagedefault用默认 blob 存储即可建好后第一次拉取某个依赖时 Nexus 会回源下载并缓存之后同一版本直接命中本地。这里有个选型理由代理仓库的Version policy如果选 Mixed快照和正式版混在一起排查依赖冲突时很难区分来源所以正式仓库我一般只留 Release。客户端侧在settings.xml里加镜像mirror idnexus-maven/id mirrorOfcentral/mirrorOf nameinternal maven proxy/name urlhttp://内网地址:8081/repository/maven-central-proxy//url /mirror参数说明mirrorOf写central表示只接管中央仓库请求如果写*会把所有仓库请求都劫持过来团队里如果有自定义仓库地址就会失效这点要按实际情况选。3.2 NPM 代理与私有包宿主NPM 的接入逻辑和 Maven 类似但多一步npm config的指向。先建一个 npm (proxy) 仓库指向公共 registry再建一个 npm (hosted) 仓库用来放团队内部包。# 指向 Nexus 的 npm 代理仓库 npm config set registry http://内网地址:8081/repository/npm-proxy/ # 发布私有包时指向 hosted 仓库 npm config set 团队scope:registry http://内网地址:8081/repository/npm-hosted/逻辑说明第一行让所有公共包走代理缓存第二行用 scope 把团队私有包路由到宿主仓库避免误发到公共源。发布前需要在 Nexus 里给对应账号开nx-repository-view-npm-*-add权限否则会报 403。常见坑是只配了 registry 没配 scope结果私有包发布时被推到代理仓库代理仓库是只读的直接失败。3.3 仓库组一个地址收口所有依赖代理仓库和宿主仓库建完后客户端要配多个地址很麻烦。Nexus 的仓库组group可以把多个仓库聚合成一个入口客户端只认这一个地址。配置顺序有讲究组内成员按从上到下匹配命中即返回。所以一般把 hosted 放最上面私有包优先proxy 放下面公共包兜底。如果顺序反了私有包名和公共包重名时会被代理仓库先截胡出现「明明发布了却拉到旧版本」的玄学问题。!-- Maven 侧指向仓库组 -- mirror idnexus-group/id mirrorOf*/mirrorOf urlhttp://内网地址:8081/repository/maven-group//url /mirror到这里Maven 和 NPM 的依赖入口就统一了。验证方法是清掉本地缓存后重新构建一次观察 Nexus 的访问日志里是否出现对应的下载记录。4. 避坑与排查那些让构建机半夜报警的细节这一章集中写几类高频问题每条按「现象 → 原因 → 解决」展开。这些问题在刚搭好的环境里出现频率很高提前知道能省不少排查时间。4.1 磁盘涨得比预期快现象运行一两周后磁盘告警sonatype-work目录体积远超预期。原因代理仓库会缓存所有拉取过的依赖包括大量历史版本和快照清理任务默认没有及时执行。解决在系统任务里配置「清理未使用缓存」和「压缩 blob 存储」的定时任务同时给代理仓库设置合理的缓存过期时间。我一般把清理任务设成每天凌晨跑一次压缩任务每周一次。4.2 客户端报 401 但账号密码没错现象settings.xml里账号密码确认无误构建时仍报 401。原因密码里包含特殊字符在 XML 里没有转义或者账号只有读权限没有对应仓库的浏览权限。解决先确认密码在 XML 中做了转义如写成amp;再检查账号角色是否包含目标仓库的read权限。权限是分仓库授予的新建仓库后旧账号不会自动获得权限。4.3 上传的包在仓库组里搜不到现象制品明明上传成功客户端却拉不到。原因上传到了 hosted 仓库但仓库组里没有把这个 hosted 加进成员列表或者加进去了但排在代理仓库后面被同名包遮蔽。解决检查仓库组的成员顺序把 hosted 上移同时确认上传时用的仓库地址就是 hosted 本身而不是组地址组地址通常不允许写入。4.4 启动卡在初始化不动现象首次启动后访问 8081 长时间显示初始化中。原因JVM 堆内存不足或数据目录所在磁盘 IO 慢。解决编辑etc/nexus.vmoptions把-Xms和-Xmx调到合适值小团队 2G 起步并确认数据目录不在网络挂载盘上。网络盘做 blob 存储初始化会慢到让人怀疑人生。4.5 升级后配置丢失现象换了新版本的服务本体启动后发现仓库配置全没了。原因只替换了服务本体目录没有保留原来的sonatype-work或者新版本用了不同的数据目录路径。解决升级前先备份sonatype-work升级时保持数据目录路径不变。如果新版本默认路径变了在nexus-default.properties里显式指回旧路径。5. 进阶技巧用脚本做仓库健康检查与依赖预热环境稳定运行一段时间后真正影响体验的往往不是服务本身而是「某个依赖第一次拉取特别慢」和「仓库悄悄满了没人知道」。这一章给两个我常用的脚本思路一个是健康检查一个是依赖预热。5.1 用 REST 接口做仓库状态巡检Nexus 提供了 REST 接口可以定时拉取仓库状态和存储用量。下面是一个用 curl 做基础巡检的示例#!/usr/bin/env bash # 仓库健康巡检检查服务存活与存储用量 NEXUS_URLhttp://内网地址:8081 AUTHadmin:你的密码 # 检查服务状态返回 200 视为正常 status$(curl -s -o /dev/null -w %{http_code} -u $AUTH $NEXUS_URL/service/rest/v1/status) echo service status: $status # 拉取 blob 存储用量超过阈值告警 curl -s -u $AUTH $NEXUS_URL/service/rest/v1/blobstores | head -c 500逻辑说明/service/rest/v1/status返回 200 表示服务可用/service/rest/v1/blobstores能拿到各存储的用量信息。参数上-u后面跟账号密码生产环境建议用只读账号而不是 admin。这个脚本可以挂到定时任务里配合告警通道比等磁盘满了再处理主动得多。5.2 依赖预热把首次构建的等待挪到空闲时段新环境上线后第一次全量构建往往最慢因为所有依赖都要回源。常见做法是提前跑一次预热把常用依赖先拉进缓存# 依赖预热对核心项目执行一次依赖解析触发缓存 mvn -q dependency:go-offline -Dmaven.repo.local/tmp/warmup-repo参数说明dependency:go-offline会解析项目声明的所有依赖并下载-Dmaven.repo.local指向临时目录避免污染本机仓库。跑完后这些依赖已经进了 Nexus 缓存后续团队构建直接命中。注意这个命令对多模块项目的插件依赖解析不一定完整预热后最好再跑一次真实构建确认。5.3 一个我坚持了很久的习惯从那以后我每次搭完 Nexus都会强制走一遍「清空本地缓存 → 用仓库组地址构建 → 检查访问日志」的流程确认依赖确实走了内网入口而不是悄悄回了外网。这个习惯帮我提前发现过好几次镜像配置写错、仓库组顺序不对的问题。环境这东西配好只是开始验证过才算数。希望帮到你。本文还有配套的精品资源点击获取