- 架构背景与演进动力
1.1 从单体到碎片化：.NET 的开源征程
在.NET Framework 时代，构建系统主要围绕 Windows 操作系统紧密集成，采用传统的封闭式开发模式。然而，随着.NET Core 的推出，微软开启了彻底的开源与跨平台转型。为了适应开源社区的协作习惯，并实现不同组件（如 Runtime, SDK, ASP.NET Core, Roslyn 编译器等）的独立迭代，.NET 团队最初采用了极为分散的多存储库（Multi-Repo）策略1。
在这种模式下，.NET 平台被拆解为数十甚至上百个独立的 Git 存储库。每个存储库拥有独立的构建管道、版本控制历史和发布周期。这种架构在初期极大地促进了各个组件团队的敏捷性，使得负责 JIT 编译器的团队与负责 ASP.NET 路由的团队能够互不干扰地并行开发 。
1.2 分布式依赖图的系统性崩溃
随着.NET 生态系统的壮大，这种完全解耦的架构逐渐暴露出严重的系统性缺陷，特别是在构建整个.NET SDK 产品时。这些存储库并非真正独立，而是通过复杂的依赖关系相互连接，形成了一个庞大的有向无环图 (DAG) 3。
1.2.1 一致性延迟 (Coherency Latency)
在分布式图中，变更的传播是线性的且极其缓慢。例如，当 Roslyn 编译器团队修复了一个底层 Bug 并发布新版本后，该变更必须沿着依赖链逐级向下传播：首先更新 Runtime，Runtime 构建发布后更新 ASP.NET Core，最后才能到达 SDK 和 Installer。这个过程可能长达数天甚至数周。在此期间，处于依赖树不同层级的组件可能基于不同版本的上游组件构建，导致整个产品在任意时间点都处于"非一致性"状态。
1.2.2 钻石依赖与版本地狱
分布式架构最典型的问题是钻石依赖 (Diamond Dependency)。假设存储库 A 和存储库 B 都依赖于存储库 C 的不同版本，而下游的存储库 D 同时依赖于 A 和 B。当 D 尝试构建时，就会遇到版本冲突（NuGet Hell）。解决这种冲突通常需要人工介入，强制统一依赖版本，这不仅耗时，还容易引入运行时错误。
1.2.3 跨栈重构的死锁
当开发人员需要进行跨越多个技术栈的重构时（例如，在 Runtime 中引入新 API 并在 SDK 中立即使用），分布式架构构成了巨大的阻碍。开发者必须先在 Runtime 提交代码，等待构建发布，然后在 SDK 中升级依赖。这种"多阶段提交"不仅效率低下，而且使得原子性变更变得不可能，严重阻碍了架构层面的技术演进。
1.3 统一构建 (Unified Build) 的战略转折
为了解决上述问题，微软提出了 统一构建 (Unified Build) 愿景，其核心目标是能够从单一的源码提交 (Single Commit) 构建出完整的.NET SDK 产品。这不仅是内部工程效率的需求，也是为了满足 Linux 发行版（如 Fedora, Debian, Ubuntu）的合规性要求。Linux 社区有着严格的"源码构建"政策，要求软件包必须能够在其基础设施上从源代码从头编译，而不依赖预构建的二进制文件（Binary Blobs）。
为了实现这一目标，必须打破物理存储库的边界，建立一个逻辑上的统一视图。虚拟单体存储库 (VMR) 应运而生，它成为了 Unified Build 的物理载体和操作核心。
- 虚拟单体存储库 (VMR) 的架构解析
VMR (dotnet/dotnet) 并非传统意义上的单体存储库，而是一种混合架构模式。它巧妙地平衡了现有工程流程的惯性与统一构建的需求。
2.1 定义 "虚拟" 与 "单体"
VMR 的设计哲学包含两个核心维度：
单体性 (Monolithic): 从构建系统的角度看，VMR 就是一个标准的单体库。它包含了构建.NET SDK 所需的所有源代码、构建脚本、基础设施定义和测试用例。在这个存储库上的任意一个 Git Commit SHA，都唯一且完整地定义了该时刻.NET 产品的全貌。
虚拟性 (Virtual): 从开发工作流的角度看，它是一个"投影"或"镜像"。原始的产品存储库（如 dotnet/runtime, dotnet/sdk）依然存在，并且是大多数开发人员日常工作的"主战场"。VMR 中的代码并非凭空产生，而是通过自动化机制从这些产品存储库同步而来的。因此，VMR 是各组件的聚合体，而非替代品 。
2.2 文件系统与存储模型
VMR 的目录结构经过精心设计，以映射并整合来自数十个上游存储库的内容。
src/ 目录： 这是 VMR 的核心。每个上游产品存储库的内容被映射到 src/ 下的一个子目录中。例如，dotnet/runtime 的源码被放置在 src/runtime，dotnet/aspnetcore 被放置在 src/aspnetcore。这种物理上的聚合使得跨组件的搜索、重构和构建成为可能。
eng/ 目录： 包含共享的工程基础设施，特别是 Arcade 工具集。这是.NET 团队通用的构建系统核心。
eng/common/： 这是一个特殊的引导目录，包含用于启动构建过程的脚本。这些文件通常从 Arcade 存储库同步而来，用于确保所有组件使用一致的构建工具版本。
source-manifest.json： 这是 VMR 的"数据库"或"注册表"。由于 VMR 是由多个上游仓库聚合而成，系统必须精确记录 VMR 当前状态对应于上游仓库的哪个 Commit SHA。该 JSON 文件维护了组件名称、远程仓库 URL 以及当前同步的 Git Hash 的映射关系，是实现双向同步的关键元数据。
2.3 存储模型的特殊处理
为了适应.NET 的庞大规模和特殊构建需求，VMR 在存储模型上做了一些非标准 Git 的处理：
子模块实体化 (Hard Copy vs Pointers): 与 Git Submodules 仅存储指向外部仓库的指针不同，VMR 将子模块的代码物理复制并提交到 VMR 的 Git 树中。这意味着 src/runtime 下不仅有文件，而且这些文件是 VMR 历史的一部分。这样做是为了支持离线构建（Source Build），确保即使在没有网络连接的环境下，只要克隆了 VMR，就拥有了构建所需的一切代码。
文件屏蔽与路径映射 (Cloaking): 上游存储库中可能包含一些不适合放入 VMR 的文件，例如大尺寸的二进制测试数据、Windows 专用的闭源组件，或者违反 Linux 发行版许可协议的文件。VMR 的同步机制支持配置"屏蔽规则"，在同步过程中自动剔除这些路径/文件。这类似于 .gitignore，但发生在同步逻辑层面。
- 同步机制详解：Maestro 与 Darc
VMR 的生命力在于其同步机制。如果没有高效、准确的同步，VMR 将迅速与上游存储库脱节，失去其作为"真相来源"的价值。微软为此构建了一套复杂的依赖流系统，核心组件包括云服务 Maestro 和命令行工具 Darc。
3.1 同步架构的演进阶段
VMR 的同步机制并非一蹴而就，而是经历了三个阶段的迭代 ：
阶段一：Source Build Tarball (源码构建压缩包)
在.NET 6 时代，所谓的"单体"仅仅是一个巨大的 Tarball 压缩包，专门提供给 Linux 合作伙伴。它通过一系列补丁（Patches）将各个仓库的源码拼凑在一起。这种方式缺乏版本控制历史，调试极其困难，被描述为"脆弱且不透明"。
阶段二：VMR-lite (单向只读镜像)
2022 年 10 月，微软建立了只读的 VMR。同步是单向的：从产品存储库流向 VMR。这解决了代码可见性和历史追踪问题，但由于是单向的，开发者无法直接在 VMR 中修复集成错误，必须回到原仓库修改，导致反馈循环过长。
阶段三：Writable VMR (双向读写同步) 从.NET 10 Preview 5 开始，VMR 变为可读写。引入了"扁平化流 (Flat Flow)"模型，允许代码在产品存储库和 VMR 之间双向流动。这标志着 VMR 正式成为生产级的基础设施。
3.2 控制平面：Maestro (产品构建服务)
Maestro（也被称为产品构建服务，Product Construction Service）是编排整个.NET 构建生态系统的"大脑"。它是一个运行在 Azure 上的微服务，负责监听存储库状态、计算依赖关系并触发代码流。
Maestro 的核心职责：
订阅管理 (Subscription Management): Maestro 维护着一张庞大的订阅图。订阅定义了"源仓库"与"目标仓库"之间的关系。例如，dotnet/runtime 的 main 分支订阅了 dotnet/dotnet (VMR) 的 main 分支。
自动 PR 创建: 当源仓库产生新的构建时，Maestro 会计算差异，并自动在目标仓库创建 Pull Request (PR)。
冲突检测: 如果同步过程中发现文件冲突，Maestro 会标记 PR 并通知相关维护者（通常是 @dotnet/product-construction 团队）。
3.3 开发者工具：Darc CLI
Darc 是开发者与 Maestro 服务交互的本地命令行接口。它允许开发者查看、添加或更新订阅，并在本地模拟同步过程。
核心命令解析 :
darc get-subscriptions: 列出当前仓库或指定仓库的所有活跃订阅。输出通常包含源仓库 URL、目标分支、更新频率等信息。
darc add-subscription: 创建新的依赖流通道。例如，将 dotnet/arcade 的更新流向 dotnet/msbuild。
darc update-subscription: 修改现有订阅的参数，如排除特定的资产（Excluded Assets）或调整批处理策略。
darc vmr forwardflow / backflow: （虽然文档未详细展开，但推测存在）用于在本地触发 VMR 的正向或反向同步逻辑，帮助开发者验证变更 。
3.4 代码流算法 (Code Flow Algorithm)
VMR 的同步通过两种主要的代码流模式实现：正向流 (Forward Flow) 和 反向流 (Backflow)。
3.4.1 正向流 (Forward Flow): 产品库 -> VMR
当开发者在 dotnet/runtime 合并了一个 PR 后：
触发: Maestro 检测到构建成功。
补丁生成: 系统根据 VMR 中记录的 source-manifest.json 获取上一次同步的 Commit SHA，并与当前最新的 Commit SHA 进行对比。使用 git diff --patch --binary 生成包含了二进制差异的补丁文件。
路径重写: 补丁中的文件路径会被重写，加上前缀（如 src/runtime/），以匹配 VMR 的目录结构。
应用与提交: 补丁应用到 VMR 分支上，并更新 source-manifest.json 中的 SHA 记录。这个过程是自动化的。
3.4.2 反向流 (Backflow): VMR -> 产品库
当开发者直接在 VMR 中进行跨组件修改（例如同时修改 Runtime 和 SDK）并合并后：
逆向映射: 系统识别出哪些文件属于哪个子组件。
分支与 PR: 针对每个受影响的产品存储库，系统会创建一个包含源码变更的 PR。
依赖更新: 关键点在于，反向流不仅包含源码，还包含 VMR 构建出的新二进制包版本。这意味着，当反向流回到 dotnet/runtime 时，该仓库的 Version.Details.xml 也会被更新，指向 VMR 构建出的最新依赖。这保证了产品库始终基于最新的全栈环境进行构建。
3.5 状态追踪与防环路设计
双向同步最容易导致的问题是死循环（Ping-Pong Effect）：A 的变更同步给 B，B 的构建触发同步回 A。为了防止这种情况，.NET 团队采用了严格的状态追踪机制。
eng/Version.Details.xml: 在产品库中，此文件记录了该仓库依赖的 VMR 版本。
src/source-manifest.json: 在 VMR 中，此文件记录了包含的各产品库版本。
同步逻辑会检查这些元数据。如果 Maestro 发现 VMR 中的变更实际上就是源自产品库最近的一次提交，它会识别为"已同步"，从而通过空操作（No-Op）切断循环。
- 统一构建 (Unified Build) 与供应链安全
VMR 的建立不仅仅是为了方便代码管理，更是 Unified Build 的基石。它改变了.NET 产品的构建范式，从水平分层构建转向垂直切片构建。
4.1 垂直构建 (Vertical Builds)
在旧的模式下，构建是水平的：先构建所有 Runtime，再构建所有 ASP.NET。而在 VMR 中，构建是垂直的。 一个垂直构建会基于 VMR 的单一 Commit，按照依赖顺序（Toolset -> Runtime -> ASP.NET -> SDK）在一次构建流水线中从源码编译出整个栈。
优势：
消除时间差: 任何代码变更都会立即在全栈范围内进行验证。
简化发布: 发布.NET 10 Preview 1 只需要对 VMR 的特定 Commit 打标签，而不需要协调几十个仓库的 Commit 组合。
4.2 Linux 源码构建 (Source Build) 与发行版合规
Linux 发行版（如 Fedora, Red Hat）对软件包有严格的"源码构建"要求。他们不信任上游厂商提供的预编译二进制文件，因为这些文件可能包含后门或未修补的漏洞，且无法审计。
VMR 通过提供一个自包含的 Git 仓库，完美支持了这一需求：
离线能力: VMR 包含了所有必要的源码（通过实体化的子模块），不依赖构建时的 git clone 操作。
预制脚本: prep-source-build.sh 脚本用于准备环境。
引用包 (Reference Packages): 为了解决循环依赖（如构建 C# 编译器需要 C# 编译器），Unified Build 引入了 dotnet/source-build-reference-packages。这些是仅包含 API 定义（元数据）的文本格式包，可以轻易地从源码生成，作为自举（Bootstrapping）的起点 5。
4.3 可重现构建 (Reproducible Builds)
供应链安全的核心是可重现性。即：在不同环境、不同时间，使用相同的源码应当生成比特级完全一致（Bit-for-bit identical）的二进制文件 15。
VMR 架构极大地促进了这一点：
输入确定性: 单一 Commit 锁定了所有源代码输入。
环境一致性: eng/common 锁定了所有构建工具链版本。
路径规范化: 编译器配置被调整为忽略绝对路径（如 /home/user/src），使用相对路径或确定性路径映射（Source Link），确保构建产物不包含构建机器的元数据 16。
这使得第三方（如企业安全团队或政府机构）可以独立验证微软发布的.NET SDK 是否真的由公开的源码构建而来，从而防止类似 SolarWinds 的供应链攻击。
- 开发者工作流与体验
VMR 的引入对开发者的日常工作流产生了深远影响，形成了"内循环"与"外循环"并存的局面。
5.1 内循环 (Inner Loop)：产品库开发
对于绝大多数日常任务（如修复 System.String 中的 Bug），开发者依然工作在 dotnet/runtime 等独立产品库中。
流程: Fork -> Clone -> Branch -> Commit -> PR。
优势: 保持了较小的仓库体积（相比 VMR），IDE 加载速度快，构建时间短。
同步: 变更合并后，开发者无需手动操作，Maestro 会自动将其正向流转到 VMR。
5.2 外循环 (Outer Loop)：VMR 开发
当任务涉及跨仓库修改时，开发者切换到 VMR。
场景: 修改 Roslyn 编译器的一个接口，并同时更新 Runtime 中对该接口的调用。
流程: Clone dotnet/dotnet -> 修改 src/roslyn 和 src/runtime -> 本地全量构建验证 -> 提交 PR 给 VMR。
优势: 原子性提交，一次性解决所有破坏性变更（Breaking Changes），无需临时向后兼容代码 。
5.3 痛点与挑战
尽管 VMR 解决了架构问题，但也给开发者带来了一些"痛点"：
仓库体积: VMR 非常庞大，Clone 和 Checkout 的时间显著增加。
构建时间: 垂直构建整个.NET 栈需要消耗大量的计算资源和时间，普通开发者的笔记本电脑可能难以通过 VMR 进行全量调试。
权限控制: 在多仓库模式下，权限可以细分（如只有特定团队能合并 Runtime 代码）。在 VMR 中，权限管理变得更加复杂，需要通过 CODEOWNERS 文件精细控制目录级权限，防止误操作 。
- 架构对比分析
为了更清晰地定位 VMR 的架构属性，我们将其与业界其他主流方案进行对比。
表 1：VMR 与 传统 Monorepo 及 Git Submodules 的深度对比
特性 分布式多仓库 (Legacy.NET) 标准 Monorepo (Google/Meta) 虚拟单体库 (.NET VMR) Git Submodules 方案
代码存储 物理分散，逻辑连接 物理集中，单一仓库 物理集中（镜像），逻辑分散（开发） 物理分散，指针连接
版本控制工具 Standard Git Custom (Piper, Mononoke) + Virtual FS Standard Git (需启用长路径支持) Standard Git
构建一致性 低 (存在一致性延迟) 极高 (原子性) 高 (通过 Maestro 同步保障) 低 (依赖指针更新，易碎)
离线构建支持 困难 (需拉取 NuGet 包) 原生支持 原生支持 (代码实体化) 中等 (需递归 Clone)
开发环境成本 低 (仅需 Clone 相关库) 高 (需专用工具支持大库) 中/高 (VMR 庞大，但可选产品库) 低
跨组件重构 极难 (多阶段提交) 容易 (原子提交) 容易 (在 VMR 中原子提交) 困难 (需多库协调)
文件屏蔽 (Cloaking) 不适用 支持 (构建规则控制) 原生支持 (同步时过滤) 不支持 (全量拉取)
6.1 与 Google 模式的区别
Google 和 Meta 使用单一的巨型仓库（Monolith），所有开发者直接在其中工作。这需要极其昂贵的定制基础设施（如虚拟文件系统 VFS for Git, Piper）。微软并未强制.NET 社区使用这种重型设施，因为开源贡献者通常只使用标准的 Git 客户端。VMR 作为一个"投影"，兼容了标准 Git 工具链，虽然牺牲了一定的实时性（同步延迟），但换取了对开源社区的友好度 。
6.2 为什么不直接使用 Git Submodules？
Git Submodules 在处理大规模项目时非常脆弱。如果上游仓库重写了历史（Force Push），子模块指针就会失效。此外，Submodules 无法处理"文件屏蔽"需求（即在 Linux 构建中剔除 Windows 二进制文件）。VMR 通过物理复制和补丁机制，彻底解耦了对上游 Git 历史的依赖，实现了更健壮的控制。
- 挑战、局限性与未来展望
7.1 分支对齐与 "Snapping"
一个主要挑战是如何保持 VMR 分支与数十个产品库分支的精确对齐。特别是在发布窗口期（Snap），所有仓库必须几乎同时切出 release/x.y 分支。现在，这一过程由 VMR 中心化驱动：VMR 先切分支，然后通过自动化工具强制所有下游产品库切分，以防止历史错位 。
7.2 合并冲突的复杂性
随着 VMR 变为可写，双向同步带来的合并冲突不可避免。如果一个文件在 VMR 中被修改（重构），同时在产品库中被修改（Bug修复），同步 PR 就会失败。目前这主要依赖人工介入解决。未来的改进方向可能是引入更智能的语义合并工具。孤由韧掩