前两天有个同事跑过来问我他在 Nexus 里传了一个 jar明明文件已经成功上传了但跑去 Components 页面搜索死活搜不到这个组件可切换到 Assets 搜索又能看到这个文件。他一脸困惑地问我是不是 Nexus 出了 Bug。其实这不是 Bug而是大多数人一开始接触 Nexus 时都会绕进去的一个概念坑**组件Component和资产Asset**并不是一回事。平时我们挂在嘴边的上传个 jar 包拉一个 npm 包同步一份 wheel 文件说的都是资产层面的操作而真正决定这个文件能不能被 Maven 或 pip 解析、能不能出现在制品列表里的是组件层面的元数据。这篇我结合自己日常维护 Nexus 仓库的经验把这个组件 vs 资产的模型彻底拆开讲一遍。等你把这两个词背后的数据模型搞清楚了再回头去看仓库的存储结构、清理策略、权限配置视野会完全不一样。尤其是团队里有人总是遇到文件上传成功但列表搜不到删除组件后磁盘没变小权限配了还是看不到依赖这类问题十有八九都是没搞清楚这两个概念。1. 为什么 Nexus 非要搞出组件和资产两个概念1.1 一次上传背后其实是两套数据模型先看一个最简单的场景你在 Nexus 的 maven-releases 仓库里通过 Upload 表单上传了一个service-demo-1.0.0.jar。从页面上看你只做了一件事——传了个文件。但 Nexus 内部实际做了两件事在**资产Asset**层面这个 jar 文件被完整地进到了仓库对应的 Blob Store 里生成了文件路径、校验和、Content-Type、大小、上传时间等一系列物理属性。在**组件Component**层面Nexus 会去解析这个文件所属的制品坐标识别出它是com.example:service-demo:1.0.0这个组件的某一个具体文件并在组件索引里写入或更新对应的元数据记录。为什么要把同一个上传动作拆成两层模型来处理因为一个制品在现实世界里根本不是单一文件。还是拿 Maven 举例子com.example:service-demo:1.0.0这个制品通常由 pom 文件、主 jar、sources jar、javadoc jar 以及对应的 sha1、md5 校验文件组成。如果 Nexus 把文件当唯一模型那这七八个文件在仓库里就是七八条平级记录完全没有办法表达它们其实是同一个发布版本这个逻辑关系。组件的存在就是为了把这些散落的物理文件合并成一个逻辑单元。以后无论是查询、删除、清理还是做权限控制都可以直接对着组件操作而不是对着七八个文件分别操作。1.2 组件和资产的典型关系一对多组件和资产的关系用一句话总结就是一个组件下可以挂多个资产但一个资产生来只属于一个组件。你可以用组件为父、资产为子来理解父的维度是制品逻辑子的维度是具体文件。就拿上面那个 Maven 制品来说层级示例组件com.example:service-demo:1.0.0资产 1service-demo-1.0.0.pom资产 2service-demo-1.0.0.jar资产 3service-demo-1.0.0-sources.jar资产 4service-demo-1.0.0.pom.sha1资产 5service-demo-1.0.0.jar.sha1这里我额外提一个容易踩的认知误区组件和资产并不是一一对应的。在一些简单的仓库格式里比如 raw 仓库只存一个孤立文件你会看到一个组件只带一个资产于是产生组件就是资产的错觉。但只要走到 Maven、pypi、npm 这类复杂格式里一对多的结构立刻就会显现出来。你在 UI 里看到的那个组件详情页其实就是一个制品版本的所有资产汇总页。之所以强调这一点是因为不少人配置清理策略时习惯按文件名去匹配结果发现清理掉一个文件后同一个组件下的其他文件还在或者在删除一个组件时又惊讶地发现底下一堆资产全没了。理解了父子关系这些现象就不会再让你感到意外。1.3 用生活化的方式理解这套模型如果你觉得组件资产太抽象我建议你想象成一套图书管理系统组件是书的书目条目资产是这本书实体的多个电子文件。比如说《Novell 网络管理实战》这本书ISBN 是固定的书目信息是固定的这就是一个组件。可这本书可能有 PDF 版、EPUB 版、MOBI 版甚至还有一个附录表格的单独文件这些都是同一本书下的不同资产。在 Nexus 里也一样Maven 的 GAV 坐标就是书目编号jar、pom、sources 就是这本书的不同格式文件。这样你就容易理解两个关键行为如果你要下架一本书肯定希望把 PDF、EPUB 全删掉而不是只删其中一个文件同样你在仓库里删除一个组件Nexus 会把挂在它下面的所有资产一起清掉。反过来如果你想临时只保留某个格式那操作对象就应该是资产而不是组件。模型本身不复杂复杂的是很多人没分清自己到底想操作哪个层级。2. 资产的本质仓库里真正躺着的那个文件2.1 资产身上到底挂了哪些信息资产是仓库存储结构中最物理的一层。它不是一个简单的文件指针而是带着一整套元数据的数据实体。我通过 Nexus 的 REST API 拉取一条资产记录时比较关键的字段有这么几个id资产在 Nexus 内部数据库里的唯一标识。repository资产归属于哪个仓库跨仓库的资产是不能互相引用的。path资产在仓库内的虚拟路径例如/com/example/service-demo/1.0.0/service-demo-1.0.0.jar。这个路径也是浏览器直接访问的下载路径。downloadUrl带上前缀的完整下载地址格式一般是http://仓库地址/repository/仓库名/路径。contentType文件媒体类型用于标识 jar、pom、whl、tgz 等格式浏览器和客户端工具会根据这个值决定如何处理下载内容。lastModified资产最后修改时间。checksum资产内容的校验和包含 sha1、sha256、md5 等多项摘要。Nexus 在计算和校验时都依赖这些值。attributes针对不同仓库格式解析出来的额外属性。Maven2 格式下会带 groupId、artifactId、version、classifier、packaging。看一个我在调试时经常复制的资产 JSON 片段格式大体长这样具体 id 值会因环境而异{ id: bWElMURlZmF1bHQlM0RzZXJ2aWNlLWRlbW8tMS4wLjAtamFy, repository: maven-releases, format: maven2, downloadUrl: http://nexus.local:8081/repository/maven-releases/com/example/service-demo/1.0.0/service-demo-1.0.0.jar, path: /com/example/service-demo/1.0.0/service-demo-1.0.0.jar, contentType: application/java-archive, lastModified: 2024-05-20T10:25:31.87100:00, checksum: { sha1: f7c1f4a2d1b2a9c1e2d3f4a5b6c7d8e9f0a1b2c3, sha256: a1b2c3d4e5f60718293a4b5c6d7e8f9012345678 }, attributes: { maven2: { groupId: com.example, artifactId: service-demo, version: 1.0.0, classifier: , packaging: jar } } }字段里最容易忽略的是attributes。不同格式的资产解析属性完全不同npm 包会带 package 信息pypi 会带 name 和 versionraw 格式则可能很简陋。在界面里点击一个资产名称你看到的详细页其实就是把这些内外字段渲染出来了。写自动化脚本做资产盘点的时候优先解析这些字段往往比自己去拼正则可靠得多。2.2 资产和 Blob Store 之间是什么关系很多人以为 Nexus 里的资产就是一个存储在某个目录下的普通文件其实不是。资产的二进制内容实际存放在Blob Store里而资产表只是记录了这个逻辑文件对应 Blob Store 里的哪一块数据。Blob Store 是 Nexus 底层的对象存储实现保存数据时并不按文件名平铺而是按照内容哈希分片存放。直接到服务器上看 Blob Store 目录你会看到一串串看起来毫无规律的分隔目录和二进制文件根本找不到service-demo-1.0.0.jar这个名字。这是因为 Nexus 刻意这么设计将文件的逻辑路径与物理存储解耦这样同一个文件块可以被系统统一管理也方便做去重和一致性校验。理解了这层关系你现在看到的现象就能解释了你在 UI 里删除一个组件或资产Nexus 只是先删掉了数据库里对应的逻辑记录Blob Store 里的物理数据并不会立刻消失。真正回收空间必须在删除之后执行Compact blob store任务。这个任务会扫描所有 Blob把已经被标记删除或不再被任何资产引用的数据块清理掉然后你才会看到磁盘占用真正降下来。有个运维上的注意点永远不要在 Blob Store 目录里手动删文件哪怕你确认它没用。因为 Blob Store 的索引信息和数据库里的资产记录相互关联手动删除会造成索引不一致轻则清理任务报错重则导致整个仓库无法启动。我见过有人图省事直接进目录删了大文件结果仓库列表全部异常最后只能靠恢复数据库和 Reconcile 任务慢慢补教训相当惨痛。2.3 怎么用界面和 API 查看资产在 Nexus 界面里最常用的入口是仓库下的Browse菜单。你看到左侧那个按目录展开的文件树每个节点就是一个资产的路径。点开任何一个文件右边会展示资产详情路径、下载 URL、校验和、最后修改时间、格式属性等。另一个入口是全局搜索。搜索框默认搜索的是组件如果你想按资产文件名搜需要把右侧的搜索范围切到 Asset。建议你亲手试一次同样输入一个 jar 文件名在 Component 范围和 Asset 范围下的搜索结果完全不同。这就是我同事踩的坑的根源——他在默认的组件搜索里找文件名当然找不到。命令行下资产相关操作的 API 入口是# 列出仓库中的资产支持按 name 过滤 curl -u admin:admin123 http://nexus.local:8081/service/rest/v1/assets?repositorymaven-releasesnameservice-demo-1.0.0.jar # 获取单个资产详情 curl -u admin:admin123 http://nexus.local:8081/service/rest/v1/assets/asset-id实际返回里items数组中的每一条就是一条完整的资产记录。写脚本做批量下载、迁移、盘点时这个接口是主力工具。不过要注意分页Nexus 接口默认返回数量有限数据多时记得用continuationToken拉下一页不然容易漏数据。3. 组件的本质逻辑上的坐标实体3.1 不同仓库格式下的组件坐标组件这层模型的核心是坐标Coordinates。所谓坐标就是能唯一定位一个逻辑制品的一组属性不同格式有不同的坐标定义。Maven2 格式坐标由groupId、artifactId、version三元组构成标准叫法是 GAV。Maven 客户端解析依赖时就是根据 GAV 去仓库里找对应组件再从组件下面捞资产。npm 格式坐标是nameversion两个字段。更严格地说是 package name 和版本号。pypi 格式坐标同样是nameversion对应的是 PyPI 上某个包的一个发布版本。Docker 格式坐标拆分更复杂涉及镜像仓库名、镜像名、标签和平台架构等。raw 格式本身不做强约束一个组件可能只对应一个路径下的文件更像是一个兜底模型。这些坐标不仅影响 Nexus 内部怎么组织数据也决定客户端怎么请求。Maven 里的mvn dependency:get -Dartifactcom.example:service-demo:1.0.0本质上就是告诉 Nexus请把坐标是 GAV 的组件找出来解析它的资产然后给我该下载的文件。你把这个流程反向思考就能理解为什么 Nexus 要维护组件索引而不是简单地把文件堆在目录里——因为客户端根本不会按随机文件名来找制品它只认坐标。3.2 组件、仓库、格式三者如何协作组件不是一个孤立的实体它身上有三个关键维度所属仓库repository、所属格式format、坐标信息。举个例子com.example:service-demo:1.0.0这个组件在 maven-releases 仓库里存在指的是一个被 upload 功能正常解析过的 Maven 制品。同一个 GAV你换成 raw 仓库上传Nexus 甚至不会解析出 groupId、artifactId因为 raw 格式根本不理解 Maven 坐标。这个设计对权限和隔离非常有用。Nexus 的权限模型里权限点通常是仓库视图级别的格式决定你能配置出哪类权限仓库决定你在哪个作用域内生效。给一个第三方团队开放 maven-public 仓库的 browse 和 read 权限他们只能读取公共仓库里的组件即使他们拿到了内网某个 release 仓库的网络地址没有对应权限照样拉不到任何组件。组件的坐标只是逻辑标识真正决定能否访问的是它所在仓库和当前账号的权限。实际做系统规划时不同环境用不同仓库来隔离是最常见的做法maven-snapshots 放开发快照maven-releases 放正式版本中间还可以再套一层 maven-public 聚合仓库给团队统一访问。从组件角度看每个仓库都是独立的组件命名空间仓库之间天然隔离避免互相污染。3.3 组件的生命周期和联动删除组件的生命周期从第一次上传匹配它的某个资产时开始。比如你往 maven-releases 上传了service-demo-1.0.0.pom但还没传 jarNexus 就会先生成一个空白组件等你再把service-demo-1.0.0.jar传上去它不会新建组件而是把新资产挂到那个已存在的组件下面。这个过程不需要任何额外配置Nexus 根据坐标自动归并。组件生命周期里最容易踩坑的是删除的联动效果。在 Nexus 界面里删除一个组件Nexus 不会让你先删除它下面的资产而是直接连带删除该组件下的全部资产。这对第一次操作的人来说很冲击只是想清理一个旧版本结果连带 pom、jar、sources 全部没了。反过来也有一些细节要留意。如果你在 UI 里删除了某个组件下的一个资产比如只删了 sources jar组件本身仍然存在只是下面资产列表少了一项。这就好比一本书还在但把附录撕掉了。两种操作的目标层级不同影响范围完全不同。删除时先想清楚你要打的是组件这个大目标还是资产这个小目标这是我踩过多次坑后总结的第一条经验。组件的覆盖更新也值得一说。重新上传同版本的一个资产时Nexus 会覆盖 Blob Store 里的内容但资产 id 可能不变lastModified 会更新。如果版本发布策略允许重新发布Release 仓库默认不让重新部署同版本你会看到组件还在原地资产内部已经换了一套新内容。这点在排查明明改了代码重新上传下载下来的 jar 还是旧内容的问题时特别关键——往往不是 Nexus 缓存了而是仓库策略不允许覆盖上传直接被拒了。4. 组件与资产概念在实操里的几个关键场景4.1 局域网离线环境用 Nexus 搭建私有 PyPI 源很多团队会遇到内网环境没外网的问题这时用 Nexus 搭建私有 PyPI 源是最常见的方案。表面上这是个离线搬运问题但一旦你理解了组件和资产的区别就会知道搭建的关键是把整套组件搬进来而不是只搬文件。思路是这样的先在能联网的机器上准备好目标包的全部组件及它们依赖的所有组件。以requests2.31.0为例我会这样操作在联网机器的临时目录里执行pip download requests2.31.0 -d /tmp/pypi-pkgs让它把所有依赖也一并下载下来。如果涉及跨平台部署加上平台限制参数例如--platform manylinux2014_x86_64 --only-binary:all:避免下载到源码包后在内网装不上。把这些下载好的 .whl 文件分门别类考到内网机器上。在 Nexus 里创建一个pypi (hosted)仓库比如命名为pypi-internal。进入 Upload 页面选择 pypi-internal 仓库填写组件坐标name和version比如 requests 和 2.31.0然后选中对应的 .whl 文件上传。如果同一个版本还有.tar.gz源码包也一并作为第二个资产上传。在内网客户端的pip.conf里替换 index-url[global] index-url http://nexus.local:8081/repository/pypi-internal/simple trusted-host nexus.local注意pip 客户端解析的是simple页面这个页面返回的内容是 Nexus 根据组件元数据动态生成的。如果你只通过 raw 仓库把 .whl 文件扔进去不创建 pypi 格式的组件pip 是找不到包的因为 pip 走的是 PyPI 的 simple API 协议不是简单文件列表。这就是文件存在 vs 组件存在最直观的差异。如果你习惯用命令行上传可以调用组件的 REST APIcurl -u admin:admin123 -X POST \ http://nexus.local:8081/service/rest/v1/components?repositorypypi-internal \ -F pypi.namerequests \ -F pypi.version2.31.0 \ -F pypi.assetrequests-2.31.0-py3-none-any.whl如果同一个组件需要传多个文件就追加多个-F pypi.asset文件路径参数。之前我接入内网环境时遇到最常见的报错是No matching distribution found for requests。排查思路很固定先确认目标包及其依赖是否都作为组件上传了再确认 pip 访问的 index-url 指向的是否是 pypi hosted 仓库的/simple路径最后用curl直接访问 simple 页面看看是否存在对应包名和版本。如果 simple 页面里根本搜不到该包组件那问题大概率出在只传了资产没形成组件。4.2 清理策略怎么选组件级还是资产级Nexus 的清理策略Cleanup Policy是运维中避不开的一个环节。它的关键点同样在于你要在哪个层级做匹配和删除。创建清理策略时你会看到两类匹配条件一类偏向组件维度一类偏向资产维度。以 Maven 仓库为例组件级匹配按group、name、version的表达式匹配组件。比如version .*-SNAPSHOT可以匹配所有快照版本组件。资产级匹配按asset name、asset path、asset attributes匹配具体文件。比如匹配name包含sources.jar的文件。实际操作时我会给两类场景分别建策略场景推荐层级理由清理所有 SNAPSHOT 旧版本组件级一个快照版本对应一个组件删除组件可以连带清理该版本下所有资产只清理 sources/javadoc 附件资产级这些只是可选附件删除它们不影响主 jar 组件的可用性保留最近 N 个版本其余全删组件级以版本为单位做判断最清晰不会误伤其他附件按文件最后访问时间清理资产级针对具体文件的访问频率做清理一个经常被忽略的细节是清理策略触发后资产记录会被删除但 Blob Store 里的物理空间不会马上释放。你必须另外创建一个Compact blob store的任务或者手动触发一次 compaction磁盘占用才会下降。很多团队的警报一直显示磁盘快满但组件明明删了一大堆就是因为少了这一步。我个人的建议是默认优先在组件级维度做清理因为组件是逻辑单元删除动作干净且结果可预期。资产级清理适合只想去掉某些附件的场景但用的时候要反复确认正则表达式别把主文件也匹配进去了。4.3 配置权限时如何区分组件和资产Nexus 的权限模型里仓库视图权限是最常用的一类。你给某个账号分配权限时需要选择某个仓库的某个格式视图再勾选动作包括browse、read、edit、add、delete。很多人配完权限后经常搞不清楚为什么用户能看到列表但下载不了文件通常就是没理解 browse 和 read 的区别browse允许查看仓库的目录结构和组件/资产列表但内容不一定能拿到。read允许读取元数据和下载资产文件本身。add允许上传新的资产从而新建或更新组件。edit允许修改组件/资产的基本属性常用于维护场景。delete允许删除组件或资产。实际操作中我一般这么分给普通开发同事开某仓库的browseread保证他们能搜到组件、能下载依赖但绝对不能 add 和 delete避免误传误删。给 CI 构建账号在 release 仓库上开add让它能把构建产物传上来但禁止删除。给管理员账号才开全部权限。组件和资产的区分在权限上的体现非常直接delete权限一旦放开用户既可以在组件列表里点删除也可以在资产列表里逐个删。如果你们希望允许删资产但禁止删组件虽然很罕见Nexus 原生权限模型没法做到这么细就需要通过角色和 REST API 的组合来控制而不是简单勾选权限就能完成。这一点知道就行大多数团队不会用到这么复杂的管控。配置权限后记得做实际验证不要只看配置页面。我试过用匿名账号访问某个仓库UI 上明明能看到组件树但点击下载 jar 文件时直接 403。排查了半天发现匿名角色只有 browse 权限read 权限没勾上。这个案例说明在看类似访问问题时先顺着我能看到什么、为什么看不到内容这样的链路去推比盲目改仓库配置高效得多。5. 常见问题排查和我的避坑记录5.1 文件明明上传了搜索组件却搜不到这是组件 vs 资产最容易踩的坑也是我同事当时的疑惑。文件上传成功Assets 页面能看到但组件搜索为空从根本上讲只有两种原因一种是格式问题。你使用的是 raw 仓库或者自建仓库格式Nexus 没有把该文件解析成有标准坐标的组件。这时组件索引确实不存在自然搜不到。解决办法是换用正确的仓库格式maven2、pypi、npm或者通过 REST API 按对应格式上传。另一种是搜索方式问题。UI 默认按组件坐标搜索如果你只有文件名比如service-demo-1.0.0.jar而组件坐标是com.example:service-demo:1.0.0那么默认搜索当然匹配不到。把搜索范围切到 Asset输入文件名一下子就能找到。你在排查时先到 Browse 页面确认资产的真实路径再决定用哪个维度的关键字搜索会少走很多弯路。5.2 删除了组件磁盘空间却没降删除组件后第一件事是去验证资产是否还存在于 UI 中。如果资产列表里已经没有了说明逻辑记录已经删除剩下的是 Blob Store 物理空间未回收的问题。此时去管理后台执行 Compact blob store 任务即可。但如果资产列表里还能看到文件那大概率是删除没成功或者执行清理策略时匹配条件没生效。我遇到过一种情况清理策略配置的是组件级匹配但仓库里有些文件是通过 raw 上传方式进来的它们根本没有组件所以清理策略根本碰不到这些孤儿资产。这时要切换到资产级策略按路径或名称去匹配。也有更极端的情况数据库里资产记录和 Blob Store 已经不一致UI 搜不到文件但 Blob 占用还在那就需要用到 Nexus 的Reconcile component database任务让系统重新扫描 Blob Store把一致性修复回来后再做清理。5.3 组件信息和资产路径对不上有时你会看到组件下的资产路径和期望的路径不一致比如 Maven 仓库里出现了demo-1.0.0.jar直接挂在根目录而不是按com/example/demo/1.0.0/目录结构存放。这种情况通常是手工通过 raw 上传或者某些客户端工具没有按标准 API 上传导致的。Nexus 不会帮你纠正资产路径它只会把资产和组件坐标之间的关系记录清楚。如果路径不对Maven 客户端下载时依然可能失败因为 Maven 会按 GAV 坐标拼接标准路径去请求而不会去记忆你的自定义路径。解决方法是删除这个组件重新用正确的格式和标准 API 上传。5.4 权限配置后用户看不到依赖组件这个问题通常出在仓库组Repository Group和权限的配合上。用户访问的是一个聚合仓库但组件实际存放在后面某个 hosted 仓库里。如果你只给用户开了聚合仓库的权限而没给背后的 hosted 仓库开 read 权限就会遇到组件列表能显示、但依赖解析失败或下载 403 的情况。按照组件在哪个仓库就由哪个仓库的权限决定这条规则去排查很快就能定位。给账号同时配上聚合仓库和底层仓库的 browse/read 权限问题基本迎刃而解。5.5 我的排查顺序建议根据这几年的维护经验遇到文件在却用不了权限有却下不了这类问题我建议你按下面的顺序排查先确认文件真实存在于哪个仓库、哪个路径用 Browse 页面看不要只凭记忆。判断这个问题是组件级还是资产级客户端能不能解析出坐标如果客户端要的是坐标那么必须有对应组件如果只是要一个直接下载链接那么资产存在就够。检查该组件/资产所在仓库的权限确认当前账号具备 read 权限。涉及磁盘空间和清理效果时记得把逻辑删除和物理回收分开看待前者查组件和资产列表后者查 Compact blob store 任务执行记录。这个顺序虽然朴素但能覆盖绝大多数异常场景。我自己从踩坑到把流程固化成这套套路之后收到的紧急排查求助明显少了很多。最后再分享一个个人习惯我会定期用 REST API 把组件和资产清单拉下来做一次对比看看有没有有资产没组件或有组件没资产的异常记录。在 Nexus 这套模型下两种层级本来就应该保持一个比较清晰的父子关系一旦大量出现不匹配通常意味着有上传方式不对、清理策略误配或者 Blob Store 异常的问题正在萌芽。提前发现总比等到磁盘满了再去救火舒服得多。