4.2 仓库管理与本地缓存卫生学

4.2 仓库管理与本地缓存卫生学

本节摘要：本地仓库按坐标分目录缓存构件，_remote.repositories 与 maven-metadata.xml 记录来源与版本索引，RELEASE 与 SNAPSHOT 需要不同的存放与更新策略。缓存污染、目录膨胀与来源混杂是三大卫生问题。本节给出仓库策略表与清创流程。

打开你家的仓库看一眼

多数工程师从没打开过本地仓库目录。现在看一眼，它就藏在用户主目录的 .m2 之下，结构完全按坐标展开：

repository/
  com/fasterxml/jackson/core/jackson-databind/2.13.4/
    jackson-databind-2.13.4.jar          构件本体
    jackson-databind-2.13.4.pom          构件的依赖清单
    jackson-databind-2.13.4.jar.sha1     校验和
    _remote.repositories                 来源记录：从哪个仓库下载
  com/shop/rule/rule-sdk/2.2-SNAPSHOT/
    maven-metadata.xml                   版本索引：该坐标有哪些版本
    maven-metadata-nexus.xml             来自 nexus 仓库的索引副本
    rule-sdk-2.2-20230815.032418-9.jar   带时间戳的快照本体
​

两个不起眼的文件值得认识。_remote.repositories 记录"这份文件从哪个仓库名下来"——它参与一个经典故障：换了仓库名（比如镜像改名）后，Maven 可能拒绝复用本地缓存而重新下载，日志刷屏但构建不出错，围观者一头雾水。maven-metadata.xml 是版本索引，SNAPSHOT 的"找最新"就靠各仓库的 metadata 合并结果，它损坏的症状是"明明发布了新快照，构建拉到的还是旧的"。

三大卫生问题与清创流程

问题一：缓存膨胀。 几年用下来仓库冲到几十 GB，装满了废弃项目的旧版本与从未用过的传递依赖。治理原则是"清创不清库"：

# 盘点：按体积排序找出大头
du -sh repository/*/* | sort -rh | head -20
# 优先清除：已下线项目的 groupId 目录
# 次优清除：明确废弃的大版本目录
# 永不清除：正在用的版本与全部 RELEASE
​

问题二：缓存污染。 第 3.4 节讲过 .lastUpdated 与损坏文件，这里补一个组织层面的措施：CI 机器的本地仓库定期"清零重建"，开发机的仓库只做精确清创。两者的风险承受度不同——CI 的缓存坏了影响所有人，重建成本（一次全量下载）由夜间时段吸收。

问题三：来源混杂。 同一构件可能从不同仓库进入缓存，版本策略各异。治理靠的是分仓策略，下一小节展开。

分仓策略：RELEASE 与 SNAPSHOT 的不同待遇

两类版本的仓库行为差异（第 1.2 节表）在治理层升级为分仓策略：

图：仓库策略全景

分仓的落地靠两处配置协作：distributionManagement 声明"我要发布到哪"，repositories 声明"我从哪拉"：

<!-- 风险工程族父 POM 的发布声明 -->
<distributionManagement>
  <repository>
    <id>nexus-releases</id>
    <!-- id 必须与 settings 里 server 的 id 对上 凭证才挂得上 -->
    <url>私服地址/repository/risk-releases/</url>
  </repository>
  <snapshotRepository>
    <id>nexus-snapshots</id>
    <url>私服地址/repository/risk-snapshots/</url>
  </snapshotRepository>
</distributionManagement>
​

mvn deploy 按当前版本号自动路由：带 -SNAPSHOT 后缀进快照仓，否则进发布仓，配置上不存在歧义空间。

一个值得跑一遍的验证实验：故意把同版本号 deploy 两次（发布仓），第二次的报错就是"不可变语义"的执法现场——仓库直接拒绝覆盖，日志给出该版本已存在的明确提示。把这个报错截图放进团队 wiki 的"常见报错"页，新人遇到时不至于误判成网络故障。反向实验也做一遍：同版本快照 deploy 两次，两次都成功，仓库里留下两个时间戳版本——两相对照，两类仓库的语义差异就不再是表格里的名词，而是亲手触发过的行为。

卫生学的最后一块拼图是定期体检制度：每季度跑一次三问自检——缓存里废弃项目的体积占比多少（膨胀问题）、快照仓最老的快照几岁了（清理策略是否真的在执行）、发布仓里有没有"同名版本内容不同"的迹象（不可变语义是否被绕过过）。三问的答案决定下季度的清理动作。没有体检制度的仓库治理，通常在两年后变成"谁也不敢动但谁都嫌它慢"的暗房。

⚠️ 常见坑：用"改版本号重新 deploy"来修正发布仓里的问题版本。发布仓的语义是不可变，覆盖式修复会砸掉所有已经拉取该版本的机器的信任基础——它们的本地缓存与远端不一致，第 3 章的随机漂移故障随时开演。正确动作永远是发布新版本（哪怕只差一个补丁号）。

💡 关键直觉：把 RELEASE 仓当"档案馆"管理——进馆的卷宗不许涂改，查阅永远可信；把 SNAPSHOT 仓当"草稿间"管理——门不上锁但定期清空。两类语义混在一个仓里，就同时失去档案馆的可信与草稿间的灵活。

本节要点回顾

• 本地仓库即坐标展开的缓存：_remote.repositories 记来源，maven-metadata 做版本索引，两者损坏各有典型症状；
• 清创不清库：按体积盘点、按废弃项目精确清理，CI 定期重建、开发机精确清创；
• 分仓是治理核心：RELEASE 禁覆盖走流程长保留，SNAPSHOT 可覆盖短清理仅内联；
• 发布路由自动化：distributionManagement 按 SNAPSHOT 后缀自动分仓，id 与 settings 凭证严格对齐；
• 不可变是信任基础：修 RELEASE 版本的唯一正确姿势是发新版本。

仓库策略已定，但它需要一台真正的"中央仓库"来承载——下一节进入私服选型：Nexus 与 Artifactory 的正面对决。