单体仓库太大怎么办：如何缩小 Monorepo 体积并提升开发者效率

当单体仓库体积真正成为问题在某海外大型科技公司几乎所有产品变更都会经过同一个地方服务器端单体仓库。所谓单体仓库也就是 Monorepo是指一个单一、共享的 Git 仓库其中包含公司内部使用的众多服务和库。团队没有把代码分散到几十个较小的仓库中而是将大部分后端基础设施集中在同一个地方。这种架构简化了跨服务开发但也意味着这个仓库几乎处在所有构建工作的核心位置。在构建 AI 功能时工程师通常需要对排序系统、检索流程、评估逻辑和用户界面进行细微调整。所有这些工作都遵循同一个工程循环拉取最新代码、构建和测试、代码审查、合并并发布。随着时间推移团队开始注意到这个循环变得越来越慢。单体代码库已经增长到 87GB。下载完整代码库也就是“克隆”代码库需要一个多小时。许多持续集成CI任务也在反复承担同样的成本。此外仓库体积已经接近企业级代码托管平台 100GB 的限制这带来了真实的运维风险。在这篇文章中我们将分享团队如何将代码库从 87GB 缩减到 20GB减少了 77%如何将克隆代码库所需时间缩短到 15 分钟以内以及代码库为什么会增长到这种程度还有从大规模维护 Monorepo 单体代码库中学到的经验。为什么仓库体积会影响开发者效率要理解代码库体积为什么如此重要不妨先看工程师的实际工作方式。首次搭建开发环境时工程师需要克隆代码库也就是将完整代码库及其历史记录下载到本地。完成初始设置后日常工作负担会小得多。工程师只需要获取并拉取增量更新而不必重新下载所有内容。但首次克隆无法避免。当代码库达到 87GB 时这一步通常需要一个多小时。这项成本的影响并不只限于新员工入职。许多持续集成任务也就是每次代码变更后都会运行的自动化构建和测试工作流都会从一次全新的克隆开始。这意味着 CI 流水线会不断重复同样的开销。用于同步代码库的内部系统也必须处理比以往多得多的数据这增加了超时和性能下降的风险。与此同时代码库还在稳定增长。通常每天增长 20MB 到 60MB偶尔甚至超过 150MB。照这个速度几个月内就会触及企业级代码托管平台 100GB 的仓库大小上限。问题不仅在于代码库很大。即使以大型科技公司的规模来看这样的增长速度也远远超出了正常开发活动的预期。这说明问题不只是“存了什么”还在于“这些内容是如何被存储的”。Git 压缩机制为什么会导致仓库膨胀起初团队寻找的是导致代码库膨胀的常见原因大型二进制文件、意外提交的依赖项或者本不应该纳入版本控制的生成文件。但这些都无法解释当时的情况。增长模式指向了一个不那么显眼的因素Git 的增量压缩。Git 并不会将每个文件的每个版本都存储为完整副本。相反它会尝试通过存储相似文件之间的差异来节省空间。当某个文件存在多个版本时Git 会保留一个完整版本并将其他版本表示为相对于这个完整版本的增量也就是差异。在大多数代码仓库中这种方式非常有效能够保持较高的存储效率。问题在于Git 如何判断哪些文件足够相似值得拿来进行比较。默认情况下Git 在做增量压缩时只使用文件路径最后 16 个字符作为启发式规则来匹配文件。在许多代码库中这已经足够了。名称相似的文件通常也包含相关内容。但团队的国际化文件采用如下结构i18n/metaserver/[语言]/LC_MESSAGES/[文件名].po语言代码位于路径前部而不是最后 16 个字符中。因此Git 经常会计算不同语言文件之间的差异而不是同一语言内部文件的差异。例如对某个翻译文件进行一次小幅更新可能会被拿来和另一种语言中并不相关的文件进行比较。结果是Git 生成的并不是较小的差异而是更大的差异。于是例行翻译更新导致生成的压缩文件异常庞大。内容本身并没有异常问题出在目录结构与 Git 压缩算法之间存在错配。一旦理解了这种不匹配代码库快速增长的原因也就清楚了。如何在本地验证 Monorepo 优化方案一旦怀疑增量配对是根本原因团队就开始寻找方法影响 Git 在压缩过程中对文件的分组方式。团队发现了一个实验性参数它可以改变 Git 选择增量比较候选文件的方式不再只依赖路径最后 16 个字符而是遍历完整目录结构从而让相关文件更容易聚集到一起。团队使用这个参数在本地执行了一次重新打包。简单来说就是让 Git 重新组织并重新压缩仓库中的对象。结果立竿见影仓库大小从约 80GB 缩小到约 20GB。这验证了最初的假设问题不在于数据量本身而在于数据的打包方式。然而这次成功也暴露了一个新的限制。代码托管平台方表示这个实验性参数与他们依赖的一些服务器端优化不兼容包括用于加快克隆和获取速度的相关优化能力。也就是说虽然这个修复方案在本地有效但不能直接用于生产环境。团队需要一种既能实现相同体积缩减又能与代码托管平台基础设施兼容的方案。这意味着必须在平台能够安全支持的参数范围内工作而不是依赖实验性的客户端参数。为什么代码仓库优化无法只靠本地完成本地实验证明更优化的打包方式可以显著缩小代码库体积。但这里有一个关键限制你不能在本地重新打包代码库然后将其推送到代码托管平台并指望这些优化永久保留。代码托管平台会根据每个客户端缺少的内容在服务器端动态构建传输包。这意味着服务器自己的打包策略决定了克隆和获取操作的大小。即使本地镜像已经被完美优化平台在传输过程中仍会使用自己的配置重新打包。要永久缩小仓库体积并提升性能重新打包操作必须在代码托管平台的服务器上执行。$ git clone --mirror gitcode-hosting.example:internal/server.git server_mirror performance: 2795.152366000 s $ du -sh server_mirror 84G server_mirror $ git repack -adf --depth250 --window250 performance: 31205.079533000 s (~9h) $ du -sh server_mirror 20G server_mirror团队将发现分享给代码托管平台的支持团队并与他们合作寻找与其基础设施兼容的解决方案。对方建议不要依赖实验性参数而是使用调整后的 window 和 depth 参数进行更彻底的重新打包。这些设置控制 Git 搜索相似对象的范围以及允许的增量层数。更高的参数值会增加重新打包期间的计算时间但也能显著提高压缩率。团队在仓库的镜像克隆上测试了这种方法。重新打包大约耗时 9 小时但结果非常明显仓库大小从 84GB 缩小到 20GB。由于这种方法符合代码托管平台的服务器端优化策略因此可以安全地用于生产环境。如何安全上线仓库重新打包重新打包代码库会改变数十亿个对象在磁盘上的物理组织方式。它不会改变代码内容但会改变每次克隆、获取和推送操作背后的底层结构。鉴于单体仓库在开发工作流中的核心地位团队把这项工作视为一次生产基础设施变更。在正式上线前团队创建了一个测试镜像并让代码托管平台先在该镜像上执行重新打包。团队监控了拉取时长分布、推送成功率和 API 延迟以确保新的打包结构不会引入任何回归问题。镜像大小从 78GB 降至 18GB。虽然拉取延迟的尾部略有波动但考虑到体积减少了四倍这完全处于可接受范围内。团队也没有发现任何稳定性问题。完成验证后代码托管平台在一周内逐步将重新打包后的结构推向生产环境。他们每天更新一个副本先从读写副本开始并在周末预留缓冲时间以防需要回滚。这种分阶段方式确保了如果出现任何意外都可以安全回退。最终结果非常显著。代码库大小从 87GB 缩减至 20GB。许多情况下克隆时间从超过一小时缩短到 15 分钟以内。新工程师不再需要长时间等待才能完成开发环境搭建。CI 流水线启动更快运行也更稳定。同步代码库的内部服务也更不容易出现超时。此外由于代码库体积远低于代码托管平台的 100GB 限制团队也降低了高峰时段平台性能下降的风险。同样重要的是系统在整个部署过程中保持稳定。数据获取时长、推送成功率和 API 延迟都保持在预期范围内。团队在没有引入新运维风险的前提下实现了这些改进。Monorepo 优化后我们学到了什么除了仓库体积缩减本身这个项目也强化了团队对大型基础设施维护的一些认识。以下三点最为重要。增长并不只是提交数量的问题当团队最初注意到代码库膨胀时本能反应是去看新增内容大型文件、未使用的依赖项、生成产物。但根本原因与提交了什么无关而是与目录结构如何和 Git 的压缩启发式规则相互作用有关。国际化路径让 Git 倾向于计算不同语言文件之间的差异而不是在同一语言内部进行比较。因此例行翻译更新会生成过大的包文件。这种增长是结构性的而不是行为性的。工具本身就包含假设。当你的使用模式偏离这些假设时性能可能会随着时间推移悄悄下降。在这个案例中Git 的 16 字符路径启发式规则本身没有问题只是与仓库结构不兼容。正是理解了这些内部机制才让团队正确诊断出问题所在。有些修复需要与平台提供商合作团队已经找到了根本原因也在本地验证了修复方案。但由于代码托管平台决定了代码库如何打包和传输本地重新打包并不够。解决方案必须与平台的服务器端基础设施保持一致。这意味着团队需要向平台方提供清晰数据进行协作测试并在其支持的参数范围内工作。当你的系统依赖托管平台时一些问题就存在于你的代码和托管平台代码的交界处。建立稳定的合作关系以及共享的调试流程非常重要。把代码库健康状况视为生产基础设施代码库重新打包会改变数十亿个对象的物理结构。即使代码本身没有变化每个工程师和每个自动化系统都会与这个底层结构交互。因此团队处理这个项目的方式和处理任何生产基础设施变更一样在镜像上测试评估实际影响逐步部署并保留回滚路径。代码仓库有时会给人一种“被动存储”的感觉好像它只是随着时间推移不断增长。但当规模变大后它们就不再是被动的了。它们是关键基础设施直接影响开发者速度和持续集成可靠性。作为这项工作的一部分团队构建了一个定期运行的统计任务用于跟踪单体仓库的关键健康指标并将结果反馈到内部仪表盘。这个任务会监控仓库整体大小、增长速度、全新克隆所需时间以及存储空间在代码库不同部分的分布情况。如果增长速度再次加快或克隆时间开始变长团队就能及早发现问题而不是等到工程师已经明显感受到阻碍时才反应过来。对于研发团队来说代码库健康不应只停留在基础设施层面也需要和需求、开发、测试、发布、知识沉淀等研发管理流程连接起来。像PingCode 这类智能化研发管理工具可以帮助团队把研发过程中的目标、需求、缺陷、测试、发布和 Wiki 经验沉淀串联起来让仓库治理、CI/CD 稳定性和研发效能改进更容易被追踪和复盘。监控增长趋势并尽早调查异常情况是打造健康工程团队的重要组成部分。接下来如何持续维护单体仓库健康将代码库从 87GB 缩减到 20GB对构建方式产生了立竿见影的影响。新工程师几分钟内就能开始上手不再需要经历漫长的初始克隆过程。CI 流水线启动更快运行也更可靠。对于负责 AI 功能开发的团队来说这种改进尤其明显。他们的进展往往来自跨多个服务的大量迭代式变更因此在每个开发周期中都能直接感受到速度提升。这次调查也带来了结构性调整帮助团队防止类似问题再次发生。团队更新了国际化工作流使其与 Git 打包算法对文件的分组方式更加一致从而降低未来出现异常增量配对的可能性。同样重要的是团队现在能够更清晰地了解代码库增长趋势也对什么是“正常状态”有了更明确的认识。更广泛地说这个项目提供了一套可复制的操作指南。当增长速度超出预期时团队知道如何深入压缩层进行调查如何安全验证修复方案以及在必要时如何跨平台协作。随着产品持续演进单体仓库还会继续增长。但增长并不一定意味着摩擦。借助合适的工具和规范的管理对于每天依赖它的工程师来说这种增长可以做到几乎无感。