Windows内网Nexus私服搭建：Maven/npm/PyPI仓库配置实践

简介基于 Nexus Repository Manager 3.15.2 官方发行版打包的 Windows 私服资源包面向需要在局域网内搭建 Maven 私服的开发或运维人员。将压缩包部署在一台具备外网权限的机器上即可让团队成员统一从内网私服拉取依赖降低远程仓库访问延迟提升构建一致性与安全性。压缩包共 149.78MBrar 格式适配 Windows x64 环境适合初建私服或已有私服做升级维护的团队直接下载使用。目前已有 145 人浏览学习主要面向刚接触 Nexus 的开发者也适合希望规范依赖管理、减少外网故障影响的团队参考。资源内含 Nexus 3 完整服务程序安装后支持配置 Maven 中央仓库代理并可通过 proxy、hosted、group 三类仓库实现依赖缓存、团队私有构件发布以及统一仓库聚合访问有效减少重复从公网下载构件带来的带宽消耗为中型或分布式研发团队提供更稳定的内网构件源。 我最早接触 Nexus还是因为公司内部要搭一套统一的 Maven 私服。那时候团队里每个人都在本地仓库里翻依赖新同事入职光配环境就得折腾半天。后来换到 Nexus 3.x才真正体会到什么叫一个仓库管全家。这个nexus-3.15.2-win64.rar我用了挺长时间虽然是 2019 年的版本但在 Windows 服务器上跑得相当稳。这篇文章我把自己从下载、安装、配置到实际建仓踩过的坑全部整理出来包括局域网离线环境怎么用 Nexus 建立 pypi 库npm 仓库怎么配权限以及那些网上搜不到、只能自己试出来的细节。如果你正准备在 Windows 上搭一套 Nexus 私服或者已经被 Nexus 的配置搞得有点懵这篇应该能让你少走不少弯路。1. 为什么选 nexus-3.15.2-win64 而不是最新版很多朋友一上来就问为什么不直接用 Nexus 3.x 最新版这里有个很现实的场景。企业内网环境往往不能随便访问外网下载依赖而 Nexus 这类私服工具本身又是基础设施一旦装上就希望长期稳定运行不太想隔三差五升级。nexus-3.15.2这个版本在 3.x 系列里属于比较成熟的一代它同时支持 Maven、npm、NuGet、Docker、PyPI 等主流仓库格式功能上已经覆盖了绝大多数团队的需求而且对系统资源的要求相对友好。另一个重要的原因是兼容性。很多公司的 Windows Server 还停留在 2012 R2 或者 2016最新的 Nexus 版本对操作系统和 JDK 版本有更高要求。而 3.15.2 搭配 JDK 8 就能跑得很顺畅不需要额外折腾更高版本的 JDK。如果你所在的环境是内网隔离没法随便升级 JDK 或者系统组件这个版本就显得格外稳妥。还有一点是配置习惯。3.15.2 的 Web 管理界面、REST API、权限模型和后续版本差别不大你在这个版本上学会的操作以后升级到新版本也不需要重新学。再加上网上关于这个版本的教程最多、遇到的坑基本上都有人趟过了真出问题排查起来也快。所以我个人一直觉得如果只是为了搭建内部依赖管理服务不必盲目追新选一个稳定、资料全、够用的版本反而是更理性的选择。2. 安装部署前的环境准备2.1 JDK 版本选择与配置这里必须先说清楚一件事Nexus 3.x 是基于 Java 开发的所以装之前必须要有一个可用的 JDK。推荐用 JDK 864 位版本别用太新的 JDK。因为 3.15.2 这个版本发布的时候主流就是 JDK 8你用 JDK 11 或者更高版本来跑大概率会碰到一些奇怪的警告甚至直接启动报错。JDK 装好之后一定要配好JAVA_HOME环境变量。很多新手就是卡在这一步——Nexus 启动脚本会去读JAVA_HOME找不到就直接退出。配置方法很简单右键此电脑 - 属性 - 高级系统设置 - 环境变量在系统变量里新建JAVA_HOME值填你 JDK 安装的根路径比如C:\Program Files\Java\jdk1.8.0_202。然后在Path里追加%JAVA_HOME%\bin。验证是否配好打开命令行输入java -version能正常输出版本号就说明 OK。不要跳过这个环节我见过有人 JDK 没配好就双击 Nexus 启动脚本结果窗口一闪而过完全不知道发生了什么。另外如果你机器上装了多个 JDK 版本还需要确认命令行里实际调用的是不是 JDK 8可以用where java查看路径避免别的地方有个旧版本干扰判断。2.2 解压目录与目录结构规划下载下来的nexus-3.15.2-win64.rar解压后会出现两个目录一个是nexus-3.15.2这是程序主目录另一个是sonatype-work这是数据目录存放所有仓库数据、配置、日志和临时文件。这两个目录最好放在同一个父目录下方便以后备份和迁移。路径规划上我有个习惯性建议尽量放在不含空格和中文的路径下比如D:\DevTools\nexus3\避免某些脚本或者命令行操作因为路径问题报错。这一点在 Windows 上尤其重要很多隐藏问题都是路径带空格导致的。网上有朋友把 Nexus 放在C:\Program Files\下面结果权限不够导致无法写入sonatype-work目录折腾了半天。所以如果你不想和 UAC 权限较劲就老老实实放到一个普通目录。解压完成之后别急着双击启动。先把sonatype-work目录确认一下权限——如果当前登录用户不是管理员有些公司电脑策略比较严后续写数据会失败。最简单的方法是用管理员身份运行启动脚本或者直接给sonatype-work目录添加当前用户的完全控制权限。注意不要直接把压缩包里的目录拖到桌面或者临时目录去解压桌面路径通常带用户名的中文或空格而且系统临时目录可能被清理导致 Nexus 数据丢失。3. 启动与初始化流程3.1 启动命令与端口配置Nexus 在 Windows 下的启动脚本在nexus-3.15.2\bin\目录下名字叫nexus.exe。用命令行进入这个目录执行nexus.exe /run程序就会以前台方式启动日志直接输出到当前窗口方便观察启动过程。我调试阶段习惯用/run因为一旦报错可以立刻在窗口里看到原因。确认没问题之后再注册成 Windows 服务长期运行。如果不需要前台调试可以用nexus.exe /install安装成系统服务然后通过nexus.exe /start启动。这种方式最大的好处是服务器重启之后 Nexus 会自动跟着启动不用手动去开对无人值守的内网服务器来说非常实用。默认端口是 8081安装完成后浏览器访问http://localhost:8081就能打开管理界面。如果 8081 被其他程序占了需要修改配置文件。配置文件路径在nexus-3.15.2\etc\nexus-default.properties用记事本打开找到application-port8081这一行改成你需要的端口保存后重启服务。另外还要注意如果服务器开了防火墙记得放行对应端口。很多人内网访问不了 Nexus不是程序没跑起来而是防火墙把端口拦了。这个检查顺序一定要记牢先看本机http://localhost:8081能不能开能开再排查防火墙和网络。3.2 初次访问与管理员密码重置首次启动完浏览器访问 Nexus 界面会提示你登录。初始管理员账号是admin密码会生成在一个叫admin.password的文件里路径在sonatype-work\nexus3\admin.password。用记事本打开复制里面的字符串登录后系统会强制要求修改密码。很多人第一次找这个文件找了半天。记住不是在程序主目录下而是在sonatype-work\nexus3\下。如果目录里没有这个文件有可能是之前启动过但异常退出了或者用的用户不对。删掉sonatype-work\nexus3\下的lock文件再重启试试。登录进去之后第一件事是去设置 - 系统 - 匿名访问里看看默认策略。Nexus 默认开启了匿名访问也就是说所有人都可以拉取公开仓库的内容。如果只是内部使用建议直接关闭匿名访问强制所有请求都要带账号信息。这样做的目的不只是安全考虑更重要的是后期可以通过用户行为日志追踪到具体是谁拉取了哪个包排查问题的时候特别管用。4. 仓库类型选择与创建流程Nexus 3 核心概念是四种仓库类型proxy代理仓库、hosted宿主仓库、group仓库组和raw原始仓库。理解这四种类型基本上就理解了 Nexus 的全部用法。proxy用来代理远程中央仓库比如 Maven Central、npmjs.org、PyPI 官方源。你请求一个依赖如果本地没有缓存它就远程拉取一份存到本地下次直接从缓存返回。这是内网环境节省带宽、提升拉取速度的关键。hosted存放自有制品比如公司内部的公共库、自己打包的 npm 包、内部的 Python 包等这些不该放到外网仓库的东西就可以放在 hosted 仓库里。group把多个仓库聚合在一起提供一个统一的访问入口。客户端只需要配置这一个地址不用关心具体的包在哪个仓库里这种模式最常见。raw不区分格式纯粹做文件存储适合放一些二进制文件、脚本、配置文件等类似一个简单的文件服务器。创建仓库的入口在管理界面的设置 - 仓库 - Repositories - Create repository。选择对应格式Maven 选maven2npm 选npmPyPI 选pypi再选类型即可。以 Maven 为例创建proxy仓库需要填远程仓库地址推荐用中央仓库地址比如https://repo1.maven.org/maven2/同时可以设置Automatically Blocking这个选项意思是远程仓库连不通时自动进入离线模式不影响本地缓存的读取。实际使用中我建议每个格式至少建三个仓库一个proxy负责缓存外部依赖一个hosted放自有制品然后再建一个group把这两个仓库组合起来。默认的maven-public就是这样一组配置你往里添加新的仓库成员就行。这样客户端只用配group的地址既能找到自有包也能从公共仓库拉依赖。5. 实际场景一局域网离线环境搭建 PyPI 私有源5.1 离线环境的痛点与应对思路内网隔离环境开发 Python 项目默认的pip install没法访问外网很多包根本下不了。网上的常见做法是手动下载 wheel 包再分发非常繁琐而且版本冲突的时候更是让人头大。用 Nexus 建一个 PyPI 代理仓库再配合离线缓存导入就能解决这个问题。思路是这样的在能访问外网或者已有完整依赖包的环境里把需要的包全部收集齐上传到 Nexus 的 hosted 仓库。内网的机器配置好 pip 源指向 Nexus 地址之后所有人都从内网源下载安装速度和稳定性都有保障。如果你后续有可以临时访问外网的窗口期也可以配一个 proxy 仓库自动缓存但纯离线环境主要靠 hosted 仓库手动上传。5.2 创建 PyPI 仓库与上传包登录 Nexus创建一个pypi (hosted)仓库名字可以叫pypi-internal。在仓库配置里Deployment policy选择Allow redeploy方便同版本覆盖上传。保存之后你会得到一个仓库地址http://[服务器IP]:8081/repository/pypi-internal/。上传包有几种方式。最简单的是直接在 Web 界面的Upload功能里选择文件上传一次可以传多个.tar.gz和.whl文件。这种方式适合数量不多的场景但如果包很多推荐用twine批量上传。本机装好 twine 之后创建或修改文件%USERPROFILE%\.pypirc[distutils] index-servers nexus [nexus] repository http://[服务器IP]:8081/repository/pypi-internal/ username admin password admin然后执行twine upload -r nexus your_package.whl上传成功后内网其他机器只需要配置 pip 源pip install -i http://[服务器IP]:8081/repository/pypi-internal/simple your_package记得在包名后面加上--trusted-host [服务器IP]因为内网一般没有 HTTPS 证书pip 会拒绝访问。这一步很多人漏了导致一直连接失败其实只要加上--trusted-host参数就通了。5.3 离线批量导入既有依赖包如果你之前已经有了一批完整的依赖比如某一个目录下全是.whl和.tar.gz可以写个脚本批量上传到 Nexus 仓库里省去一个个点界面的功夫。这里我提供一个简单的 Python 脚本思路遍历目录文件逐个调用 twine 上传。注意控制上传并发别一次性压太多导致 Nexus 卡死一般同时跑 2 到 3 个上传任务就差不多了。这样一个流程走通之后整个团队在离线环境下装 Python 包就和外网一样方便而且版本统一、来源可控不会再出现每个人本地包版本不一致导致的诡异问题。6. 实际场景二Maven 仓库的私服搭建与优化6.1 Maven 仓库的初始化与代理仓库配置如果你主要是做 Java 开发Nexus 的 Maven 私服估计是使用频率最高的。Nexus 自带默认的maven-central代理仓库指向 Maven 中央仓库开箱即用。但默认配置不一定适合所有场景比如国内网络访问中央仓库速度慢或者内网策略要求必须走指定的镜像源这时候就需要手动调整代理地址。在maven-central仓库的Remote Storage字段里可以改成公司内部或者访问更快的镜像地址。我这里用的是中央仓库地址大家可以结合自己网络情况更换。配置完代理仓库之后还需要维护好maven-public这个仓库组把代理仓库、宿主仓库都放进去。客户端方面需要修改settings.xml。这个文件在 Maven 安装目录的conf目录下或者是在用户目录下的.m2目录里。在mirrors节点中添加mirror idnexus/id mirrorOf*/mirrorOf nameNexus Repository/name urlhttp://[服务器IP]:8081/repository/maven-public//url /mirrormirrorOf配置成*表示所有仓库请求都走 Nexus这样最省心。同时发布内部制品时要配置distributionManagement指向maven-releases或maven-snapshots宿主仓库distributionManagement repository idreleases/id urlhttp://[服务器IP]:8081/repository/maven-releases//url /repository snapshotRepository idsnapshots/id urlhttp://[服务器IP]:8081/repository/maven-snapshots//url /snapshotRepository /distributionManagement这里的id要和settings.xml里servers节点中配置的服务器 id 一致否则会报认证错误。6.2 版本释放策略与快照管理Maven 仓库有个很实用的机制Release 版本不允许覆盖Snapshot 版本可以重复发布。这是 Nexus 默认的Deployment policy决定的。maven-releases仓库默认是Disable redeploy防止有人不小心覆盖正式版本而maven-snapshots允许重复部署方便开发过程中频繁迭代。我建议保持这个默认策略不要为了省事把所有仓库都改成允许覆盖。我在实际项目里见过有人把 releases 仓库改成允许 redeploy结果某个同事误操作把老版本覆盖了线上构建直接拉到错的依赖排查了半天才发现是仓库内容被动了。如果确实需要重新发布某个 Release 版本可以考虑在 Nexus 上临时开启允许覆盖发布完再改回来尽量不要长期开这个权限。7. npm 仓库的配置与权限管理实战7.1 npm 代理与宿主仓库创建npm 场景和 Maven 类似建一个npm (proxy)仓库指向官方源https://registry.npmjs.org/建一个npm (hosted)仓库存放公司内部包再用一个npm (group)仓库聚合。客户端配置.npmrc文件把 registry 指向 group 仓库的地址即可registryhttp://[服务器IP]:8081/repository/npm-group/这里有一个容易踩的坑npm 对仓库返回的元数据有严格格式要求如果配错仓库类型比如把raw仓库当成 npm 仓库用会导致npm install报错或者拉不到包。另外Nexus 3.15.2 的 npm 代理仓库对某些特殊包名的支持不是特别完美如果你碰到某个包在官方源正常但通过 Nexus 拉不到的情况可以尝试在代理仓库设置里关掉Caching选项再测试必要时清理一下缓存。7.2 设置仓库级访问权限权限管理这块是很多团队容易忽略的。Nexus 默认的管理员账号权限很大如果每个人都用admin登录不小心删掉某个仓库或者改坏配置的风险很高。我建议至少创建三类账号管理员、开发者、只读用户。具体操作是设置 - 安全 - 用户创建用户并分配角色。我们可以复用系统预置的nx-admin管理员、nx-deployment可以部署和拉取等角色也可以自定义角色。创建自定义角色时在Privileges里勾选对应仓库的read、browse、edit、add等权限。比如开发者的角色可以这样配对npm-group、npm-hosted有read和browse权限对npm-hosted有add和edit权限。这样开发者可以从私有源拉取包也能发布自己的包但没有权限去修改代理仓库的配置。只读用户比如 CI 服务器使用的账号只需要read和browse权限就足够了。提示修改完权限之后记得用新账号实际测一下拉取和发布操作不要只看界面上权限树打勾了就觉得万事大吉。Nexus 的权限体系层级比较多仓库组和底层仓库权限是分开管理的有时候漏掉某一个 browse 权限界面上看起来正常但客户端就是 401 或者 403。7.3 私有包发布注意事项发布私有 npm 包时需要保证包名符合 npm 规范并且最好加上公司前缀以区分外部同名包比如company/package-name。这种 scoped 包在 Nexus 上需要先在仓库里创建对应的命名空间否则上传会被拒绝。另外要注意npm publish默认会把整个目录下的文件都打进去包括node_modules、.env等敏感或冗余文件。建议在package.json里配置files字段或者添加.npmignore尽量让发布出去的包干净小巧。我在实际项目中见过把包含数据库密码的配置文件发布到内部仓库的事情真要追究起来是很严重的安全事件。8. 常见问题与排查技巧实录8.1 启动失败或无响应Nexus 启动失败的原因排第一的是JAVA_HOME没配好第二是端口被占用第三是sonatype-work目录权限不够。遇到启动窗口一闪而过的情况先打开命令行手动执行nexus.exe /run前台运行会输出具体的错误日志比瞎猜省时间得多。如果提示端口被占用用这个命令查netstat -ano | findstr 8081找到占用进程的 PID然后在任务管理器里看看是什么程序该关的关掉。另外如果你之前安装过其他版本的 Nexus旧服务可能还在后台运行端口冲突会非常隐蔽。8.2 拉取依赖时出现 401 或 403这个问题几乎都是权限配置导致的。Nexus 默认情况下代理仓库允许匿名访问但如果你按照我前面的建议关闭了匿名访问那么所有客户端请求都要带认证信息。Maven 的settings.xml、npm 的_authToken、pip 的账号密码都需要正确配置。排查思路是先用浏览器访问仓库 URL能弹窗让你输账号密码说明认证是正常的。如果浏览器直接 401可能是仓库组配置有问题check 一下该仓库是否被正确加入了 group。如果浏览器能访问但客户端不行重点检查客户端配置文件里的用户名密码是否加密或转义正确。8.3 磁盘空间与清理策略sonatype-work目录会随着时间增长变得越来越大。代理仓库的缓存、日志、数据库文件都是存储占用大户。建议在 Nexus 管理界面设置定时任务设置 - 系统 - 任务 - Create task选择Admin - Compact blob store来压缩 blob 存储或者设置自动删除旧快照的策略。如果你发现磁盘空间告急可以先查一下sonatype-work\nexus3\db目录的大小这是嵌入式数据库通常体积最大。不建议手动删除里面的文件要用 Nexus 自带的清理功能否则容易导致数据损坏。此外Nexus 的日志放在sonatype-work\nexus3\log目录下时间长了也会积累很多文件同样可以通过定时任务清理。8.4 备份与迁移Nexus 3 的备份没有官方一键方案最稳妥的做法是定期停服后复制整个sonatype-work目录。热备份容易导致数据文件不一致尤其是数据库正在写入的时候直接复制恢复时很可能报错。如果你没法停服可以使用 Nexus 自带的备份任务功能在任务里创建一个Admin - Backup类型的任务它会把配置和数据库导出到一个指定的目录。注意这不会备份 blob 存储里的实际制品所以最好还是配合文件系统级别的快照方案。迁移到新服务器时装好相同版本的 Nexus停掉服务用备份的sonatype-work整个替换新环境的对应目录再启动即可。版本尽量保持一致跨大版本迁移可能会遇到数据库升级问题比较折腾。9. 从日常维护角度看到的几个小建议最后分享几个我在日常使用中总结出来的小习惯不算什么高深技巧但确实帮我省了不少事。第一Nexus 的管理界面访问速度如果变慢先别急着排查硬件。很大概率是 Blob Store 碎片太多了跑一次压缩任务会有明显改善。第二仓库组的成员顺序是有讲究的。请求进来之后会按顺序查找命中后直接返回所以把访问频率最高的仓库放在列表最前面能稍微提升一点性能。第三创建完任何仓库之后第一时间用客户端实际测一下拉取和发布而不是等到团队同事来反馈问题。nexus-3.15.2-win64这个版本虽然老了点但作为一个内网依赖管理基础设施它的稳定性和功能完整度我觉得是达标的。我目前内部的 Maven、npm、PyPI 仓库都是跑在这个版本上最长的一台服务器已经稳定运行了两年多没重启过 Nexus 进程。如果你也正好处于选型阶段而且环境是 Windows 内网这个版本的方案可以放心参考。本文还有配套的精品资源点击获取