基于Nexus搭建内网npm仓库：代理缓存、私有包发布与离线运维实践

先把结论摆在前面我所说的“本地仓库”不是在开发机上把 node_modules 拷贝来拷贝去而是在公司内网里架一台常驻的 npm registry 服务器让整个团队的所有机器都从它这里拉包、发私包同时由它统一缓存公网依赖。我把这套基于 Nexus 的内网仓库方案在我们组跑通之后npm 相关的幺蛾子一下少了一大半构建机和离线网络的开发机也不再天天闹情绪了。这篇文章就是把这套环境从零搭起来、踩平坑、稳定运行的全过程适合正在被内网开发环境逼疯的前端、全栈和搞构建运维的同事参考。1. 内网环境拉 npm 依赖问题从来不只在“速度”1.1 我踩的三个真实场景慢、断、乱我最初动手折腾是因为连续碰到三件糟心事。第一件是“慢”。组里有十几号人每次新增依赖或者有人改了 package-lock.json所有人都得去公网 registry 重新拉一遍。高峰期的时候一个npm ci跑三五分钟是常事碰上网络波动直接卡在某个 tarball 上下不动。第二件是“断”。机房的构建服务器本身是有外网访问权限的但权限列表经常调整。有一阵子上游 npm 仓库调整构建机连续两天拉不到某个新增依赖整个发布流程堵死在第一步。这种问题最烦人的不是技术难度而是你没法控制外部依赖源什么时候抽风。第三件是“乱”。团队里陆陆续续开始有内部公共组件有人说传到公网有人说打压缩包发到群聊。传公网不现实发群聊更是灾难——版本覆盖、遗漏文件、nobody knows which one is latest。没有一个专门的“内部 npm 仓库”私有包就只能靠人肉管理而人肉管理基本等于没有管理。1.2 先想清楚内网仓库到底要解决哪些问题动手之前别急着下载安装先盘一盘你到底要解决什么问题。我的经验是可以拆成四件事加速公网依赖装过一次之后内部缓存直接供给后续所有人不用反复穿透公网。可用性即使上游源抖动、断连已缓存过的包依然可安装构建任务不会因为外网故障掉线。私有发布内部组件有正规的版本管理、权限控制而不是微信群传文件。可控与可复现团队统一 registry 入口锁文件指向内网地址构建环境不再因外部仓库差异而行为漂移。想清楚这四点之后方案选型也就有标准了。1.3 为什么是 Nexus和 Verdaccio、纯镜像源放在一起比一比当时我对比过三个方向结论很明确。方案优点缺点/边界只改 npm 镜像源配置简单国内镜像确实快一点解决不了私有包发布依赖源不在自己手里离线/受限网络依然没招Verdaccio轻量、纯 npm 场景、部署快权限体系偏弱缓存代理能力一般对多格式仓库无能为力Nexus Repository Manager代理托管分组三位一体权限成熟blob 存储机制完善重一些学习成本略高但是内网里最省心的选择我当时选 Nexus 还有一个私心Nexus 不只支持 npm还支持 Maven、Docker、PyPI、NuGet 等格式。组里 Java 后端用的 Maven 仓库迟早也要内网化与其分别部署两套系统重复运维不如统一用 Nexus 一锅端。事实证明这个决定省了很多事。2. 安装 Nexus真正容易翻车的几处细节2.1 下载与版本选择别拿到什么就装什么Nexus 有 OSS开源免费版和 Pro 两个系列我们的规模用 OSS 完全足够直接去官网下载即可。注意下载的时候看准产品名别下错了。从 3.30 之后的版本开始官方对 JDK 的支持已经比较成熟。我部署时用的是 3.7x 系列JDK 用的 11这里我要多提醒一句不要一上来就上最新版 JDK。Nexus 的启动脚本和部分 JVM 参数对新版本 JDK 的兼容性并不总是跟手装好之后启动不了再换 JDK 非常闹心。老老实实选一个主流的 LTS 版本Java 11 即可把精力留给后面的仓库配置。2.2 启动前的三个参数端口、堆内存、文件句柄很多第一次装 Nexus 的人启动失败都是栽在这三个参数上。端口。默认是 8081如果这台机器上已经有其他服务占用了 8081可以改。配置文件在安装目录下的etc/nexus.properties找到application-port改掉即可。我这边因为要并排跑好几个工具直接把端口改成了 8082避免后续冲突。堆内存。Nexus 的 JVM 参数写在bin/nexus.vmoptions。里面有一对最关键的值-Xms和-Xmx。默认配置对小团队来说往往偏保守而对大团队又可能不够用。我的建议是刚开始搭建、组件量不多时给小团队 2G 堆内存就够用了如果代理的仓库多、缓存组件量大堆内存给到 4G-8G 会更稳。Nexus 缓存命中快除了磁盘 IO内存索引也占一份功劳。文件句柄。在 Linux 上部署ulimit -n至少要开到 65536。这个很多人会忽略一旦并发上来日志里会出现Too many open files表现就是仓库无响应、拉包卡死。这不是 Java 代码问题是系统资源限制先改/etc/security/limits.conf再加启动参数别等出问题再改。2.3 启动、查看日志和找回 admin 初始密码启动命令很简单cd /opt/nexus/bin ./nexus start启动是异步的别跑完命令就急着访问页面先看日志tail -f /opt/sonatype-work/nexus3/log/nexus.log看到类似Started Sonatype Nexus OSS之后再打开浏览器访问http://服务器IP:端口/。这里有个容易被卡住的地方Nexus 初始管理员密码不是默认admin/admin123而是系统首次启动时随机生成的一个临时密码存放在数据目录下cat /opt/sonatype-work/nexus3/admin.password拿着这个临时密码登录系统会强制要求重设。如果忘了去看日志就会陷入“明明文档说 admin 登录怎么密码不对”的困惑里。2.4 用 Docker 部署时容易忽略的目录权限想省事直接 Docker 部署也完全可行官方有sonatype/nexus3镜像。但这里有一个大坑容器里的 Nexus 进程默认以uid 200运行如果你宿主机的挂载目录权限不对容器会直接报目录不可写启动失败。解决办法很简单给数据目录授权mkdir -p /data/nexus chown -R 200:200 /data/nexus docker run -d --name nexus \ -p 8081:8081 \ -v /data/nexus:/nexus-data \ sonatype/nexus3如果你用 Docker 只是图方便记住一点数据卷/nexus-data是整个 Nexus 的全部家当程序容器随便换卷里的数据不能丢。3. 仓库设计是后半程省心的关键proxy、hosted、group 的角色分工很多人第一次用 Nexus 的时候看到仓库类型列表头晕。别急内网 npm 仓库只需要记住三种类型你把它们的角色想象成一个公司的采购部、仓库部和服务台就通了。3.1 三种仓库类型的本质区别proxy代理仓库相当于采购部。它替你去公网把 npm 包买回来下载并放在自己的仓库里缓存。下次再有人要同一个包直接从本地货架拿不再出门采购。hosted托管仓库相当于仓库部的自有货架。专门放我们自己产出的私有组件别人没有只有我们内部有。group组合仓库相当于统一服务台。把采购部拿回来的公网包和自有货架上的私包合并成一个入口客户端只认这一个地址完全不用分辨某个包来自哪里。3.2 npm proxy一个上游地址决定缓存命中率创建 npm proxy 仓库的时候最关键的参数是“Remote storage”也就是上游源地址。这里有两条路官方源https://registry.npmjs.org/国内镜像源比如https://registry.npmmirror.com/我一开始直接用官方源后来发现团队大多在境内官方源虽然稳定但速度上限不高改成了 npmmirror 镜像作为上游缓存命中后的体验倒没区别但首次拉包速度快了不少。这里想强调一点proxy 仓库配置的上游地址只是“缓存不回源”的兜底真正给团队带来体验提升的是 Nexus 的缓存层所以上游选一个访问最顺的地址即可。创建步骤也很直接登录后台左侧菜单选择Repository→Repositories。点击Create repository选择npm (proxy)。填写 Name比如npm-proxy填入 Remote storage 地址。保存。3.3 npm hosted私有包一定要带组织 scope创建 npm hosted 仓库就更简单了选择npm (hosted)填好仓库名比如npm-hosted按提示保存即可。但这里有一个直接影响后续可用性的规范私有包名尽量全部使用 scope 格式也就是公司名/包名。为什么因为公网 npm 的包名是由官方注册中心全局管理的一个裸包名foo在公网可能已经存在你发布到内网 hosted 的时候虽然不冲突但在 group 组合仓库里一旦和公网包重名默认规则和后续解析都会变得混乱。用company/foo形式的包名天然隔离发布和拉取都一目了然还能保证每个私有包都有明确的归属。3.4 npm group把所有开发机的配置成本降到最低创建 group 仓库的时候Nexus 会让你选择Member repositories。我把npm-hosted放在列表最前面npm-proxy放在后面。为什么这个顺序重要因为 group 仓库在搜索组件时按成员顺序进行谁排前面谁先被命中。我把私有托管仓库放前面是为了保证以后如果出现同名包私有版本优先这个规则在线上真正跑起来之后会省掉很多解释成本。到这里你其实已经完成了核心规划所有开发机统一配置npm-group地址私有包发布到npm-hostednpm-group内部自动组合先找自有货架再找公网缓存。3.5 匿名访问与权限内网也不是完全放开仓库建好之后先别急着广播给所有人去Security→Anonymous access看一眼。默认情况下匿名用户是可以读取仓库内容的内网拉包不需要登录。这个行为对开发效率是友好的但有两个注意点匿名可读不意味着匿名可写。私有包发布必须在 authenticated 状态下进行不要为了省事把匿名用户的权限放开到可上传否则仓库会被垃圾包塞满。如果你的安全要求比较高、希望每次拉包都要认证也可以关闭匿名访问但代价是所有人的.npmrc里都要配置认证信息维护成本会上升。我的选择是匿名只读团队内部开一只专门用于发布的账号权限最小化平时开发机零配置即用。4. 开发机接入registry 切换、登录认证与私有包发布4.1 registry 配置的三个层级与两种做法Nexus 侧准备好了客户端配置反而简单。对前端开发来说核心就是改 npm registry 地址。npm 的配置文件.npmrc有三个层级项目级项目根目录的.npmrc对本项目生效。用户级~/.npmrc对当前用户所有项目生效。全局级npm 安装目录下的.npmrc对整台机器所有用户生效。最稳妥的团队实践是在项目根目录提交一份.npmrc把内网 group 地址写进去让仓库地址跟代码走。示例registryhttp://192.168.1.20:8081/repository/npm-group/这样任何人 clone 项目之后无需额外配置就能直接访问内网仓库不用每个人手工敲命令。如果你只是自己一台机器想临时切换用命令也可以npm config set registry http://192.168.1.20:8081/repository/npm-group/4.2 npm login 与发布私有包的完整链路对于私有包发布先登录内网仓库。这里有个关键认知登录认证跟公开 registry 的登录方式不是一回事Nexus 在 npm Bearer Token 场景下需要额外启用安全 Realm否则你会撞上 401。先看官方流程# 登录内网仓库 npm login --registryhttp://192.168.1.20:8081/repository/npm-group/ # 发布私有包 npm publish --registryhttp://192.168.1.20:8081/repository/npm-hosted/登录成功之后npm 会把生成的 token 写到~/.npmrc里。这个 token 很重要我吃过亏有人把带 token 的.npmrc直接提交到了 git 仓库等于把仓库的操作权限泄露了。所以团队必须约定任何包含认证信息的.npmrc一律进.gitignore。发布私有包之前package.json 里的 name 一定要按company/pkg-name的格式写。如果你忘了带 scope会看到 Nexus 直接拒绝发布这不是报错乱写而是它在强制你走规范路径。4.3 npm 401 与 npm.ps1 被禁两个常见拦路虎401 问题。我第一次给组里同事配登录时怎么登录都是 401。查到最后问题出在 Nexus 的 Security Realm 没有启用npm Bearer Token Realm。解决路径后台Security→Realms把npm Bearer Token Realm选中并添加到 Active 列表里保存之后再重新登录就能通过了。这个坑在官方文档里写得不够显眼但几乎每个初配 Nexus npm 仓库的人都会踩一次。PowerShell 执行策略问题。很多 Windows 同事会遇到这个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1 因为在此系统上禁止运行脚本。这是 Windows PowerShell 默认执行策略太保守阻止了 npm 的脚本运行。解决办法是在管理员 PowerShell 里执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned执行完重开终端。这个和 Nexus 没有直接关系但它会卡住你接入内网仓库的第一步顺手记录一下。4.4 锁文件里的 resolved一个容易被忽视的迁移点还有一个细节等真正把项目迁移到内网仓库时才会发现package-lock.json里的resolved字段记录的是生成锁文件时使用的下载地址可能是https://registry.npmjs.org/...或镜像源地址。团队切换内网仓库后如果某台机器只能访问内网安装过程中还是会尝试去解析锁文件里的公网地址于是又卡住。解决办法有两个统一registry之后删掉旧锁文件重新npm install再生成一份让resolved全部指向内网 group 地址然后提交锁文件或者用脚本批量替换锁文件里的域名前缀比如把https://registry.npmjs.org/换成http://内网地址/repository/npm-group/。我更推荐第一种重新生成锁文件顺便还能校验一遍依赖版本是否一致省得手工替换留下隐患。5. 内网仓库跑起来之后缓存效果、CI 接入、离线铺底与故障排查5.1 缓存命中后的实际体验秒下与稳仓库搭好、开发机切过去之后最直观的感受是npm install变快了。在此之前所有人拉同一批依赖每次都是每个客户端单独去公网拉。现在第一个同事装了某依赖Nexus 缓存下来其他人再装基本是秒下因为流量走的是内网。这里说说 Nexus 的缓存判断逻辑它是以包版本为粒度缓存的同一个版本只回源一次。日常迭代中如果依赖版本没有变化缓存可以一直在如果你升级了大版本新的版本才会再次触发回源。也就是说缓存是“够用才取”策略非常经济。5.2 构建机接入Jenkins/GitLab Runner 的离线改造内网仓库真正的价值高地其实在 CI 构建机上。很多团队的构建机位于受控网络环境外网访问要么受限要么不稳定。以前构建机每次跑前端流水线第一步就是去公网拉依赖慢且不可控。接入内网仓库后构建机只需要做两步改造在构建机全局的 npm 配置里把 registry 指向内网 group 地址在 CI 流水线脚本中构建前端项目时加上--registry参数或者在项目.npmrc里统一声明。我在 Jenkins 里是这样处理的npm ci --registryhttp://192.168.1.20:8081/repository/npm-group/这样构建机的流量全部走内网和外界网络断开也不影响依赖安装只要 Nexus 缓存里已经有对应版本。构建时间从原来的几分钟压缩到几十秒稳定性提升非常明显。5.3 完全离线环境用 npm pack 给仓库铺底如果你的环境比“内网可访问外网”更严格也就是部署环境完全离线那就要考虑给 Nexus 仓库“铺底”。具体路径是在一台有公网访问权限的机器上用npm pack把目标依赖及其依赖树抓成本地 tgz 文件拷贝到离线网络内再通过 Nexus 后台的 Upload 功能上传到 npm hosted 仓库或者直接在离线环境的开发机上把缓存铺好。这是纯离线版的内网仓库初始化方式。要注意的是上传 npm 包的时候Nexus 除了要求 tgz 资产文件之外还需要对应的 package.json 元数据。习惯了公网 registry 的自动解析后第一次手动上传会有点不习惯但这是 Nexus 校验包完整性的必要步骤不能跳过。完全离线环境下这种“先铺底再安装”的方式虽然前期繁琐但比在离线容器里硬啃node_modules文件包要规范得多。5.4 负缓存、磁盘清理与数据备份三个运维习惯这套系统稳定跑起来之后剩下的就是日常维护了。我有三个实际经验负缓存的问题。Nexus 的 npm proxy 仓库默认有一个 Negative Cache 机制上游返回 404 时也会被缓存一段时间。这个机制本意是防止上游抖动但在团队频繁发布新版本时会有副作用同一个版本号在公网刚发布、开发机去内网仓库拉时如果短暂触发了 404后续一段时间内所有机器都会被 404 卡住。我的做法是把 Negative Cache 的 TTL 调短必要时直接关闭。这个参数在仓库配置的HTTP/HTTPS或Proxy相关选项里按实际团队迭代频率去调。磁盘清理。Nexus 的 blob store 会随着使用量持续增长。日常要留意数据目录所在磁盘的使用率。如果磁盘报警不要直接去删blobs目录下的文件这样会导致 Nexus 索引错乱。正确做法是使用 Nexus 后台的Maintenance→Cleanup任务先配置 Cleanup Policy再定时压缩 blob store。另外 Nexus 自带 Blob Store 的Compact任务可以定期执行。备份策略。Nexus 没有提供一键导出全部配置的功能最可靠的备份方式就是整个备份数据目录sonatype-work/nexus3。我的习惯是每天凌晨用系统任务对数据目录做快照保留最近若干天版本。注意一点导出或快照早期如果进程仍在写数据会导致备份数据不一致。稳妥的做法是在业务低峰期执行备份并配合数据库/task 的一致性处理。这个“整体备份数据目录”的习惯在关键时刻救过我一次。写在最后从零搭完这套内网 npm 仓库到现在我最大的感受是这个钱花得值这个坑也踩得值。Nexus 的内网仓库方案不是那种“装上就能躺赢”的工具它需要你花时间理解 proxy、hosted、group 的角色划分也需要你踩一遍 401、负缓存、磁盘备份这些真实的坑。但只要把架构理顺、把客户端规范定好后续几乎是一劳永逸的。最后再分享一个小经验不要一开始就把所有团队的权限、规则、清理策略全部配好先以最小可用状态跑起来只建一个 group、一个 proxy、一个 hosted让几个核心同事真实使用两周。两周之内必然暴露配置问题、权限问题、锁文件问题这时候再迭代优化比纸上谈兵的规划要高效得多。