保姆级实战教程:Maven私服Nexus搭建

做Java的同学一定都遇到过这些痛点团队开发时成员本地 Maven 依赖版本五花八门频繁出现我本地能跑你那不行的诡异问题新同事入职拉取项目要等半小时甚至更久下载依赖速度全靠外网中央仓库的网速随缘公司内网环境无法访问外网项目直接断了「粮」根本无法完成构建团队内部封装了公共工具包只能手动拷贝 Jar 包导入项目版本迭代和维护艰难。而解决这些问题的标准答案就是搭建一套团队内部的Maven私服。本文就带大家从0到1完整搭建基于Nexus3的Maven私服从核心原理到全流程实战再到踩坑避坑一篇搞定所有问题。一、Maven私服核心基础认知1. 什么是Maven私服Maven 私服Repository Manager本质上是架设在局域网内的私有仓库服务器核心作用是代理远程公共仓库、管理团队私有构建制品Jar、War、POM 等文件。它就像团队内部的 Maven「中转站 专属仓库」所有依赖拉取、制品发布都通过它统一完成。2. 主流私服产品对比目前业界主流的 Maven 私服产品有 3 款特性和适用场景如下产品出品方核心特点适用场景Nexus RepositorySonatype 公司业界绝对主流功能强大支持 Maven、npm、Docker 等多种制品格式开源免费版完全满足中小企业需求绝大多数团队的首选通用型制品管理JFrog ArtifactoryJFrog 公司企业级制品仓库扩展性极强深度集成 CI/CD 工具生态完善中大型企业、复杂 DevOps 流程场景Apache ArchivaApache 基金会轻量级开源工具仅提供基础的 Maven 仓库管理功能小型项目、极简需求场景本文我们选用最主流、生态最完善的 Nexus Repository 3简称 Nexus3进行搭建。3. 私服依赖拉取的完整链路很多同学只知道用私服却不了解背后的依赖查找逻辑理解这个流程后续出问题才能快速定位。完整的依赖查找链路分为 3 步优先查询本地仓库当项目构建需要某个构件时Maven 会首先检查本地仓库是否存在该构件。如果存在直接使用不发起任何远程请求如果不存在进入下一步。请求局域网 Maven 私服本地仓库无对应构件时请求会直接发送到我们搭建的 Nexus 私服。私服会检查自身仓库如果有直接将构件返回给本地 Maven并存入本地仓库如果没有进入下一步。代理请求外部远程仓库私服中无对应构件时会根据配置的代理规则去外部远程仓库默认 Maven 中央仓库我们会替换为阿里云镜像拉取构件。拉取成功后构件会先缓存到私服中再返回给本地 Maven 并存入本地仓库。如果连外部远程仓库都找不到该构件Maven 才会最终抛出「依赖找不到」的错误。4. 搭建私服的核心优势加速构建过程依赖优先从局域网私服获取大幅降低外网网络波动带来的影响构建速度提升数倍统一依赖管理团队所有成员共用一套私服依赖彻底解决版本不一致问题减少「环境玄学」问题离线构建支持私服缓存了所有已拉取的依赖即使断网也能正常完成项目构建适配内网隔离场景私有制品管控提供统一的私有 Jar 包托管能力告别手动拷贝 Jar 包的原始方式实现版本规范化管理安全权限管控支持细粒度的访问控制仅授权人员可发布 / 拉取制品保障代码和依赖的安全性。二、前置环境准备在开始搭建之前先确认你的环境满足以下要求避免后续踩坑Java 环境Nexus3 对 Java 版本有严格要求3.70.x 及以下版本支持 Java 8/Java 11更高版本建议使用 Java 11必须提前配置好JAVA_HOME环境变量硬件要求建议至少 2 核 4G 配置磁盘空间根据团队依赖量预留至少 20G 以上系统环境本文以 Windows 系统为例Linux 系统的核心配置逻辑完全一致仅启动脚本不同网络要求服务器能访问外网用于代理拉取公共依赖局域网内其他机器能访问该服务器的对应端口默认 8081。三、Nexus3 下载与安装1. 安装包下载Nexus 分为专业版和开源 OSS 版我们使用完全免费的 OSS 版即可提供两种下载渠道官方地址下载Download Archives - Sonatype Nexus Repository 3https://help.sonatype.com/en/download-archives---repository-manager-3.html可根据自己的系统和 Java 版本选择对应的安装包Windows 系统选择 win64.zipLinux/Unix 选择 unixtar.gz。2. 安装与目录说明下载完成后将压缩包解压到非中文、无空格的目录下解压后会得到两个核心文件夹文件夹核心作用nexus-xxxxxx 为版本号Nexus 安装目录包含应用程序、启动脚本、配置文件、依赖库等核心内容sonatype-workNexus 数据目录所有仓库的制品、配置、日志、数据库都存储在这里后续数据备份核心就是备份该文件夹最好解压到你用来开发的目录下便于管理。其中安装目录下的核心子目录说明bin/Nexus 启动脚本和启动相关配置文件所在目录etc/Nexus 核心配置文件目录数据目录下的核心子目录说明blobs/所有构件的二进制文件存储目录db/Nexus 元数据数据库目录log/应用运行日志目录出问题可在这里查看日志定位。四、Nexus 启动与初始登录配置1. 启动 Nexus 服务进入解压后的nexus-xxx/bin目录这是启动脚本所在位置在文件夹地址栏输入cmd回车打开命令提示符窗口会自动定位到当前 bin 目录输入启动命令nexus /run回车执行旧版本。新版本输入install-nexus-service.bat添加nexus服务。注意首次启动会初始化数据库和配置耗时较长请耐心等待不要关闭命令行窗口。Windows 系统可将 Nexus 配置为系统服务实现后台运行Linux 系统可使用nexus start命令后台启动。对应的中文翻译可以看这篇博客nexus3.90.x README文档翻译添加完成后以终端程序方式启动 nexus:nexus.exe run SonatypeNexusRepository2. 首次登录与初始设置打开浏览器访问地址http://localhost:8081/服务器部署则将localhost替换为服务器 IP即可看到 Nexus 管理页面。首次登录会给你一个密码位置点击页面右上角的Sign in进行登录默认用户名为admin初始密码获取老版本默认密码为admin123新版本的初始密码存放在sonatype-work/nexus3/admin.password文件中打开该文件即可获取随机初始密码首次登录成功后会引导你修改 admin 账户的密码按照提示设置新密码即可后续登录均使用该密码。然后next就可以了。五、Nexus 核心仓库类型全解析登录完成后点击左侧菜单栏的设置--Repository就能看到 Nexus 默认创建的仓库旧版是在左侧导航栏有一个Browse。核心分为 3 种类型这是 Nexus 最核心的概念一定要理解清楚仓库类型核心作用典型默认示例proxy代理仓库用于代理远程公共仓库比如 Maven 中央仓库、阿里云镜像。当私服中没有对应依赖时会从配置的远程地址拉取并缓存到私服中后续无需重复请求外网。maven-central默认代理 Maven 中央仓库hosted宿主仓库用于存放团队内部的私有构件也就是我们自己开发的 Jar 包。默认分为两个仓库- maven-releases存放稳定的发布版构件Release 版本- maven-snapshots存放开发中的快照版构件Snapshot 版本maven-releases、maven-snapshotsgroup仓库组本身不存储任何构件核心作用是将多个 proxy 代理仓库、hosted 宿主仓库聚合在一起对外提供统一的访问地址。本地 Maven 只需配置仓库组的地址就能同时从聚合的所有仓库中拉取依赖无需配置多个地址。maven-public默认的 Maven 仓库组仓库组maven-public六、实战配置阿里云镜像加速解决外网下载慢问题默认的 maven-central 仓库代理的是国外 Maven 中央仓库国内下载速度极慢甚至会超时失败。这里推荐企业级最佳实践新增独立的阿里云代理仓库加入仓库组不修改默认配置灵活性更高。步骤 1创建阿里云代理仓库在仓库列表页面点击右上角的Create repository创建新仓库在仓库类型列表中选择maven2 (proxy)Maven 格式的代理仓库进入配置页面填写核心配置Name仓库名称填写aliyun自定义方便识别即可Remote storage远程存储地址填写阿里云镜像地址http://maven.aliyun.com/nexus/content/groups/public/其他配置保持默认无需修改拉到页面最底部点击Create repository完成创建。步骤 2将阿里云仓库加入公共仓库组回到仓库列表点击默认的maven-public仓库组进入配置页面在Group配置的Member repositories区域将左侧可用仓库中的aliyun移动到右侧的成员仓库中并将其调整到最顶部优先级最高点击Save保存配置阿里云镜像加速配置完成。核心原理仓库组会按照成员仓库从上到下的顺序查找依赖把阿里云放在最前面会优先从阿里云镜像拉取依赖速度大幅提升。七、本地 Maven 配置对接私服完成依赖拉取私服配置完成后我们需要修改本地 Maven 的核心配置文件settings.xml让所有 Maven 请求都走我们的私服。1. 找到配置文件配置文件位于你的 Maven 安装目录下的conf/settings.xml例如D:\apache-maven-3.6.3\conf\settings.xml。2. 配置私服镜像在settings.xml的mirrors标签内添加如下配置将所有 Maven 请求都指向我们的私服仓库组!-- 配置Nexus私服镜像拦截所有对central仓库的请求 -- mirror idnexus-maven/id !-- mirrorOf设置为central代表拦截所有中央仓库的请求也可设置为*拦截所有请求 -- mirrorOfcentral/mirrorOf nameNexus Private Repository/name !-- 地址为maven-public仓库组的URL在Nexus仓库列表中点击copy即可获取 -- urlhttp://localhost:8081/repository/maven-public//url /mirror注意id标签的值必须全局唯一后续的账号密码配置会通过这个 id 关联。3. 配置私服访问账号密码私服默认开启了权限控制我们需要在settings.xml的servers标签内添加私服的账号密码配置和上面的镜像 id 关联!-- 配置Nexus私服的访问账号密码 -- server !-- 这里的id必须和上面mirror标签中的id完全一致 -- idnexus-maven/id !-- Nexus的登录用户名 -- usernameadmin/username !-- 你设置的Nexus登录密码 -- password你的Nexus密码/password /server4. 验证配置是否生效保存settings.xml文件后打开任意一个 Maven 项目在项目根目录执行命令mvn clean compile如果控制台能正常拉取依赖且日志中显示从我们的私服地址下载构件就代表配置成功了。此时你拉取的所有依赖都会被缓存到 Nexus 私服中后续团队其他成员拉取同一个依赖直接从私服局域网下载速度会有质的提升。八、进阶实战将私有 Jar 包发布到 Nexus 私服私服的另一核心价值就是管理团队内部的私有 Jar 包下面教大家如何将自己的 Maven 项目打包发布到私服中。1. 配置项目的 pom.xml 文件在需要发布的 Maven 项目的pom.xml文件中添加如下分发管理配置指定发布到私服的对应仓库!-- 配置制品分发仓库也就是我们的Nexus私服 -- distributionManagement !-- Release发布版仓库 -- repository idnexus-maven/id nameNexus Release Repository/name urlhttp://localhost:8081/repository/maven-releases//url /repository !-- Snapshot快照版仓库 -- snapshotRepository idnexus-maven/id nameNexus Snapshot Repository/name urlhttp://localhost:8081/repository/maven-snapshots//url /snapshotRepository /distributionManagement关键说明这里的id必须和settings.xml中server标签的 id 完全一致才能关联上账号密码Maven 会自动根据项目的版本号判断发布到哪个仓库版本号带-SNAPSHOT后缀的会发布到快照仓库不带的会发布到发布仓库。2. 执行发布命令在项目根目录执行 Maven 发布命令mvn clean deploy执行成功后打开 Nexus 管理页面进入对应的maven-releases或maven-snapshots仓库就能看到我们发布的私有 Jar 包了。3. 团队使用私有 Jar 包其他成员只需按照上述步骤配置好 Maven 对接私服就可以直接在项目的 pom.xml 中引入这个私有依赖和引入公共依赖完全一样无需任何额外配置。九、踩坑指南常见问题与解决方案1. Nexus 启动失败提示 Java 版本不匹配问题原因Nexus 版本和本地 Java 版本不兼容解决方案核对 Nexus 官方的版本要求3.70.x 及以下使用 Java 8/11更高版本建议使用 Java 11配置正确的JAVA_HOME环境变量。2. 启动成功但浏览器无法访问 8081 端口问题原因端口被占用、防火墙拦截、IP 访问限制解决方案检查 8081 端口是否被其他程序占用可在nexus-xxx/etc/nexus.properties文件中修改默认端口关闭服务器的防火墙或放行 8081 端口检查 Nexus 配置是否绑定了 127.0.0.1修改为 0.0.0.0 允许所有 IP 访问。3. 执行 mvn 命令时提示权限不足无法拉取 / 发布依赖问题原因settings.xml中的账号密码错误或id没有和 mirror/repository 的 id 对应解决方案核对账号密码是否正确确保所有关联的id完全一致检查 Nexus 中对应用户的权限是否正常。4. 发布 Release 版本时提示仓库不允许重复发布问题原因Nexus 的 maven-releases 仓库默认配置为「不允许重复发布」同一个 Release 版本号不能多次发布解决方案最佳实践每次发布 Release 版本都升级版本号临时方案修改 maven-releases 仓库的配置将Deployment policy改为Allow redeploy。十、写在最后到这里我们就完成了从 0 到 1 搭建 Maven 私服 Nexus3 的全流程从原理认知、安装配置、镜像加速到本地对接、私有包发布覆盖了企业级开发的所有核心场景。Maven 私服不仅解决了依赖下载的速度问题更重要的是实现了团队依赖的统一管理、私有制品的规范化管控是企业级 DevOps 流程中不可或缺的一环。后续大家还可以基于 Nexus 扩展更多功能比如配置细粒度的用户权限、对接 Jenkins 实现自动化构建发布、配置仓库清理策略等等。