Software Heritage 依据代码身份归档，地址只是线索

2023 年 2 月，Software Heritage 社群成员齐聚联合国教科文组织总部。画面中的人、会场和保存工作横幅，让档案馆的全球规模有了具体参照：耐久性既来自存储设计，也来自制度实践。摄影：Inria/B. Fourrier。[7]

仓库 URL 回答的是一个脆弱的问题：今天到哪里还能访问这个项目？ Software Heritage 要回答的问题更难：即使托管平台、分支名称或所属项目日后发生变化，你指的究竟是哪一份源代码制品？

这一差别让 Software Heritage 的意义远超“GitHub 备份”。它抓取公共代码托管平台和软件包仓库，记录历次访问，把多种版本控制格式转换成统一的对象模型，并为保存下来的文件、目录、修订、发布和仓库快照分配内在标识符。[1][2] 最终建立起来的是一座源代码档案馆：基本单元是拥有自身身份的对象，地址页面退居访问入口。

它的规模已经达到基础设施量级。本文于 2026 年 8 月撰写时，档案馆的公开计数器显示，系统内已有超过 290 亿个内容对象、60 亿个修订和4.38 亿个 origin。[6] 与此同时，项目的 2026 年路线图指出，GitHub 的增长速度已经超过现有收录能力，积压的 origin 超过 1.4 亿个。[5] 两组事实需要放在一起看：Software Heritage 规模庞大、持续运转，也有独特用途；这些规模仍不等于每一个公共仓库都能被实时复制。

封面照片拍摄于 2023 年，当时社群成员在联合国教科文组织总部参加一场以源代码作为文献遗产为题的研讨会。[7] 镜头有意对准会议室里的人，服务器机架和虚构的“代码云”都没有入镜。一座以超越托管公司寿命为目标的档案馆，既依赖哈希算法，也同样依赖维护人员、记忆机构、资金、标准和传承安排。

一次访问把位置记录为证据

Software Heritage 从一个 origin（源地址）开始：源代码可以从这里取得，通常表现为仓库或软件包 URL。枚举器会列出代码托管平台或发行服务上的 origin，调度器决定应该访问哪些地址，加载器则理解 origin 实际采用的格式——Git、Mercurial、Subversion、软件包归档等——并把取回的对象及其关系写入档案馆。[1]

这条流水线把普通代码托管浏览常常混在一起的三项事实分开：

origin 说明材料在何处被观察到；
一次访问说明档案馆在何时查看了那里，以及加载是否成功；
快照说明此次访问发现了哪一组可见分支或引用。[2]

假设一个库从一家代码托管平台迁往另一家，某个发行服务又建立了镜像，同时有 50 个下游项目把同一文件直接纳入各自的代码库。这些位置都是有意义的来源记录，却不会凭空产生 50 份不同的文件内容。Software Heritage 可以保留材料被观察到的多条路径，同时只保存一份相同制品。反过来，一个熟悉的 URL 也无法证明，它当前的 main 分支仍含有论文、审计报告或发布说明当初引用的源代码。

这是使用档案馆的第一个实际理由：它把易变的位置转换成带日期的观察记录。一次成功访问比书签更能说明问题，不过它记录的仍是抓取程序在当时能够看到的内容。因此，排队中的 Save Code Now 请求只说明请求已经登记，归档访问完成后才有相应的观察记录；某个 origin 没有出现在最新抓取中时，也不能只因其托管平台广受使用便认定它已经保存。[1][5]

图结构给源代码赋予排架号

档案馆的中心是一张 Merkle 有向无环图。文件内容位于叶节点；目录指向文件内容和其他目录；修订指向目录状态和父修订；发布指向修订；快照汇集在一个 origin 观察到的各项引用。分叉与合并让它超出单棵树，成为一张图。各个节点依据内在标识符去重，因此，同一文件和共享历史不会在每个包含它们的仓库中重复保存。[2]

Software Heritage 标识符，也就是 SWHID，把这套模型呈现给用户。其核心形式以 swh:1: 开头，随后是对象类型，例如文件内容使用 cnt、目录使用 dir、修订使用 rev、发布使用 rel、快照使用 snp，最后接上密码学对象标识符。核心 SWHID 可以从制品本身计算得到；它本身是标识符，解析器可以把它转换成可浏览的档案页面。[3]

对象类型的选择会直接影响引用含义。文件内容 SWHID 标识的是字节，文件名和周边目录树不在它的记录范围内。目录 SWHID 则捕捉一棵源代码树，即使更高层的版本控制元数据已经丢失，仍可重新计算。项目规范因此建议用目录标识符建立稳健的源代码引用，并在条件允许时附上 anchor，把这棵树重新连到某次发布或修订。[3]

限定信息可以补回上下文，同时保持内在身份不变。一个标识符可以带上 origin、与某次访问对应的快照、图中的锚点、路径，甚至具体行号范围。研究论文由此能够指向一段准确的代码，并保留返回所观察仓库的完整链条。[3] 哈希回答“是哪一份制品？”，限定信息回答“它出现在哪一份已记录的上下文中？”

这里还要划清一条重要界线。SWHID 一致只能确立制品身份，无法据此判定代码由谁编写、许可证是否允许预定用途、代码是否含有漏洞、仓库在归档前是否遭到入侵，或源代码如今是否仍可完成构建。这些问题分属来源、政策、安全和环境。档案馆能为相关核验提供格外有力的证据，哈希值本身不会替这些问题作出结论。

档案馆靠一支系统舰队运转

公开呈现的图结构很容易遮住维持它运转所需的机器体系。在生产架构中，源代码数据块存放于按内容寻址的 Ceph 对象存储，其前方有一个针对特定工作负载设计的 Winery 层。图结构和元数据由 Cassandra 提供服务，Kafka 日志记录新增内容，让依赖它的服务和镜像能够跟随数据流。Elasticsearch 支持按 origin URL 搜索，独立的压缩图服务则加快图遍历。就连公开计数器也采用 HyperLogLog 估算值，省去反复统计数十亿行数据的代价。[1]

这些组件各自对应不同形态的工作负载。收录过程要持续与数千个外部服务交互，故障随时会发生。不可变数据块适合去重和以追加为主的存储；来源记录与图的边需要结构化查询；镜像需要有序的变更数据流；为读者重建仓库又是另一类任务。

2026 年路线图的价值，在于它把工程现状写得具体，架构没有被包装成神话。文档说明，一部分基础设施虽已复制到镜像站点，灾难性故障发生后仍缺少快速恢复工具，因此项目把完善备份和简化恢复列为优先事项。路线图还把 GitHub 收录积压、图压缩自动化以及未来对 Git SHA-256 的支持列为待完成工作。[5] 对采用者而言，这些内容既是健康的维护信号——责任归属与技术债务清晰可见——也划出了使用条件。“已保存”不能解读成零恢复时间保证。

Software Heritage 的每个公开视图也无法在字面上始终保持只追加。其架构为下架请求设置了阻止和遮蔽流程，也设有调整公开个人身份信息的办法。[1] 长期保存必须与法律责任和对人的责任并存。持久引用旨在承受平台的日常变动，例外性的移除或遮蔽流程仍然存在。

恢复内容需要“烹制”

去重让各个对象都可寻址，也意味着熟悉的仓库包未必会作为一个现成文件等候下载。Vault 会异步组装一组相关对象，也就是“烹制”它们。根据所请求的对象和重建方式，它可以准备扁平 tar 归档、Git fast-export 数据流或裸 Git 仓库。请求依次经历 new、pending、done、failed 等状态；烹制完成的包会进入缓存，过期后需要重新准备。[4]

这种工作方式清楚标出了档案馆的实际运行角色。它很适合充当独立的保存与验证层；部署流水线若要求低延迟克隆镜像，则应继续使用专门的镜像服务。如果代码托管平台在 09:00 消失，而 09:05 的发布不能中断，团队应保留自己经过测试的镜像或备份。如果需要在仓库于 2034 年消失后证明一篇 2024 年论文分析的是哪棵源代码树，带有限定信息的 SWHID 与经过测试的 Vault 取回流程才更贴合需求。

取回操作也无法重现从未进入源代码档案的上下文。问题讨论、CI 日志、软件包签名密钥、托管的发布二进制文件、外部数据集、机密信息、容器注册表和第三方服务，都有机会成为项目运行的必要条件，即使源代码树完好无损。Software Heritage 的核心模型保存源代码制品、历史和观察来源；团队应另行导出或保存协作与运行体系中的其余部分。[1][2]

一份小而明确的保存约定

发布开源软件的团队可以从一组范围有限、能够验证的做法开始：

归档一个经过选择的状态。 完成一次重要发布后，确认公开 origin 已有一次成功访问。需要时使用 Save Code Now，并等待处理完成，只记录请求本身还不够。
记录制品本身，分支名称只作辅助。 保存已发布源代码树的目录 SWHID，并保留指向相应修订或发布的 anchor。引用需要对外分享时，再附上 origin 和访问上下文。[3]
演练取回。 请求相应的 Vault 包，将其恢复到一个空目录中，并确认源代码树或仓库计算得到的标识符符合预期。[4]
保存运行所需的外部条件。 在适合的档案或备份中留存依赖锁定文件、工具链版本、构建说明、外部数据引用以及必需的二进制制品。源代码身份是可复现性的地基，整座建筑还需要这些材料。
停机时间重要时，保留更快的恢复途径。 Software Heritage 增加了制度与技术层面的独立性；团队仍需保留经过测试的备份，并实际测量它能否达到所需的恢复目标。[5]

这份约定尤其适合研究发布、公共部门代码、历史项目，以及无法保证某一家代码托管平台永远存在的小型基金会。它同日常 Git 实践并行采用的成本也很低：开发协作仍在原有平台，档案馆专注留存。代码托管平台可以继续为协作优化，Software Heritage 则继续为记忆优化。

这套分工才是理解该项目的入口。URL 标出一扇门，分支名称标出不断移动的指针，Software Heritage 标识符则指向一份制品；访问和限定信息保留了返回某个地点与时刻的轨迹。这些层次彼此分清，档案馆的用途便会显现；当抓取延迟、恢复工作和制度依赖始终可见时，这份可信度也有了依据。

cronfeed.work