设计归档
设计归档解释 SOW 在仓库布局、状态模型和发布流程上的选择。 文章日期记录决策成文时间，修改日期记录后续修订。
了解当前设计，可以从以下文章开始：
历史系列介绍 v0.1 产品计划、设计决策与测试，以及 v0.2 重构和后续版本，并链接到对应源码快照。 当前命令见 SOW 文档，各版本变化见发布说明。
协同发布决策记录
SOW v0.4.0 为什么保留原生发布后端，没有采用早期的 rclone 提案。
SOW 设计演进：从路由图到仓库引擎
SOW 如何从 v0.1 软件分发平台转为仓库引擎，以及 v0.2 到 v0.5 如何改进这一模型。
设计原则
SOW 为什么分别管理软件包存储、仓库构建与发布。
系统模型
工作区、仓库、发行版与构建快照如何组织软件包和发布记录。
发布与恢复
SOW 如何上传仓库、继续中断的发布，以及清理不再使用的文件。
为什么 SOW 每个仓库只保留一棵包体树
每个仓库共用一个包池，各发行版视图只保存元数据，避免重复包副本。
SOW v0.1 到底证明了什么
汇总 v0.1 的 112 份验证报告，涵盖客户端兼容性、规模、恢复、迁移与云存储行为。
v0.2 重置：用 Plain 与 Managed 取代万能控制面
SOW 如何用 Plain 与 Managed 两条执行路径、明确所有权和 SQLite 状态，替换 v0.1 的 Git/CAS/Edge 平台。
SOW v0.1 决策账本：哪些被保留，哪些已退役
逐项整理 v0.1 现存的 44 份 ADR：当时解决什么问题，后来是延续、演化、仅服务迁移，还是随 V1 一同退役。
SOW v0.1 原始计划：软件仓库的 Git
SOW 为什么最初选择 Git/CAS/Route/Edge 控制面，这套模型解决了什么，又为何后来转为仓库引擎。
-
协同发布决策记录
SOW 0.4.0 保留了原生 filesystem 与 r2 发布后端。早期提案曾计划使用 rclone，并增加远端审计和预览命令。 最终选择原生后端，是因为 SOW 需要逐项记录条件写入及其结果。 当前命令语法见 sow publish。 为什么保留原生后端 发布计划为每个文件记录预期 SHA-256 和操作。后端需要创建不可变对象，避免覆盖已有内容，并按条件更新可变入口文件。 SOW 记录操作结果，用于中断后继续发布。 批量复制工具需要额外的身份与检查点模型才能保留这些规则。0.4 选择 …
SOW 0.4.0 保留了原生 filesystem 与 r2 发布后端。早期提案曾计划使用 rclone，并增加远端审计和预览命令。 最终选择原生后端，是因为 SOW 需要逐项记录条件写入及其结果。 当前命令语法见 sow publish。 为什么保留原生后端 发布计划为每个文件记录预期 SHA-256 和操作。后端需要创建不可变对象，避免覆盖已有内容，并按条件更新可变入口文件。 SOW 记录操作结果，用于中断后继续发布。 批量复制工具需要额外的身份与检查点模型才能保留这些规则。0.4 选择 …
-
SOW 设计演进：从路由图到仓库引擎
SOW 在 v0.1 中探索了以 Git 为核心的软件分发控制面，在 v0.2 中转为仓库引擎。 本文记录这次变化，以及后续到 v0.5.0 的改进。 下文版本号指正式 Git 标签。部分归档计划曾用“v0.2”“v0.3”指代开发中的设计； 其中在 RPM 视图内创建硬链接的 C2 布局，已在 v0.2.0 发布前被替换。 早期工作的细节见四篇配套文章： v0.1 原始产品计划说明最初的范围，以及范围为何过大。 v0.1 决策账本记录现存的 44 份 ADR 及其后续变化。 v0.1 到底证明 …
SOW 在 v0.1 中探索了以 Git 为核心的软件分发控制面，在 v0.2 中转为仓库引擎。 本文记录这次变化，以及后续到 v0.5.0 的改进。 下文版本号指正式 Git 标签。部分归档计划曾用“v0.2”“v0.3”指代开发中的设计； 其中在 RPM 视图内创建硬链接的 C2 布局，已在 v0.2.0 发布前被替换。 早期工作的细节见四篇配套文章： v0.1 原始产品计划说明最初的范围，以及范围为何过大。 v0.1 决策账本记录现存的 44 份 ADR 及其后续变化。 v0.1 到底证明 …
-
设计原则
SOW 分别管理包存储、仓库构建和发布。以下原则说明各类状态由谁保存，以及操作如何使用这些状态。 每类记录由一个对象管理 记录 管理范围 包体与包身份 Repository Desired 成员关系与 Built 状态 Repository Generation 与变更集 Repository 目标绑定与修订记录 Repository 与发布目标 发布尝试与检查点 Repository 与目标前缀 远端清单与删除记录 Repository 与目标前缀 每个 Repository 分别保存自己的包 …
SOW 分别管理包存储、仓库构建和发布。以下原则说明各类状态由谁保存，以及操作如何使用这些状态。 每类记录由一个对象管理 记录 管理范围 包体与包身份 Repository Desired 成员关系与 Built 状态 Repository Generation 与变更集 Repository 目标绑定与修订记录 Repository 与发布目标 发布尝试与检查点 Repository 与目标前缀 远端清单与删除记录 Repository 与目标前缀 每个 Repository 分别保存自己的包 …
-
系统模型
SOW 用配置文件保存仓库设置，用 SQLite 记录托管状态，用公共目录向客户端提供文件。 模型分别记录选中的软件包、已完成的构建，以及已发布的内容。 对象 Workspace（工作区） ├── Repository（仓库） │ ├── Pool：包对象 │ ├── Dist：成员关系与策略 │ ├── Desired（期望状态） │ ├── Built Generation（已构建快照） │ └── 保留的 Generation └── 发布目标 └── Repository + 存储后端 …
SOW 用配置文件保存仓库设置，用 SQLite 记录托管状态，用公共目录向客户端提供文件。 模型分别记录选中的软件包、已完成的构建，以及已发布的内容。 对象 Workspace（工作区） ├── Repository（仓库） │ ├── Pool：包对象 │ ├── Dist：成员关系与策略 │ ├── Desired（期望状态） │ ├── Built Generation（已构建快照） │ └── 保留的 Generation └── 发布目标 └── Repository + 存储后端 …
-
发布与恢复
构建生成本地快照（Generation）。发布把快照中的文件上传到目标，并记录进度，以便中断后继续。 每个目标分别保存检查点，记录上次完成发布的内容。 状态归属 Repository 记录 目标记录 软件包、Desired 状态与 Built 状态 发布尝试与检查点 Generation 与变更集 远端清单 保留的包和元数据引用 宽限期与删除记录 发布顺序 固定发布计划 -> 上传包体 -> 上传不可变元数据 -> 记录提交意图 -> 按视图逐一更新协议入口文件 -> 校验存储与公共 URL …
构建生成本地快照（Generation）。发布把快照中的文件上传到目标，并记录进度，以便中断后继续。 每个目标分别保存检查点，记录上次完成发布的内容。 状态归属 Repository 记录 目标记录 软件包、Desired 状态与 Built 状态 发布尝试与检查点 Generation 与变更集 远端清单 保留的包和元数据引用 宽限期与删除记录 发布顺序 固定发布计划 -> 上传包体 -> 上传不可变元数据 -> 记录提交意图 -> 按视图逐一更新协议入口文件 -> 校验存储与公共 URL …
-
为什么 SOW 每个仓库只保留一棵包体树
这项决策起草于 2026-08-05，随 2026-08-08 的 SOW v0.2.0 发布。SOW 0.5.0 仍使用这一布局： 每个仓库保存一棵包体树，各发行版视图引用同一棵树。 决策 每个 Repository 的公共目录如下： <repository>/ pool/ # 包体 dists/ <dist>/ <architecture>/ # RPM 元数据 上图展示 RPM 视图。APT 索引位于 dists/<dist>/main/binary-<architecture>/， …
这项决策起草于 2026-08-05，随 2026-08-08 的 SOW v0.2.0 发布。SOW 0.5.0 仍使用这一布局： 每个仓库保存一棵包体树，各发行版视图引用同一棵树。 决策 每个 Repository 的公共目录如下： <repository>/ pool/ # 包体 dists/ <dist>/ <architecture>/ # RPM 元数据 上图展示 RPM 视图。APT 索引位于 dists/<dist>/main/binary-<architecture>/， …
-
SOW v0.1 到底证明了什么
v0.1 归档包含 112 份报告，日期从 2026-07-11 到 7 月 31 日。 它们记录了客户端测试、规模测量、故障恢复、迁移和云存储实验。 本文汇总主要结果，并链接到代表性报告。 每项结果对应报告中记录的源码版本、测试数据、客户端与环境。 当前支持情况见兼容性参考。 证据时间线 时间 报告数 主要工作 2026-07-11 3 真实 APT/DNF 基线、72,310 个包的清单扫描、5 万个上游包的流式处理 2026-07-12 35 APT/YUM 协议、CAS/GC、发布顺序、 …
v0.1 归档包含 112 份报告，日期从 2026-07-11 到 7 月 31 日。 它们记录了客户端测试、规模测量、故障恢复、迁移和云存储实验。 本文汇总主要结果，并链接到代表性报告。 每项结果对应报告中记录的源码版本、测试数据、客户端与环境。 当前支持情况见兼容性参考。 证据时间线 时间 报告数 主要工作 2026-07-11 3 真实 APT/DNF 基线、72,310 个包的清单扫描、5 万个上游包的流式处理 2026-07-12 35 APT/YUM 协议、CAS/GC、发布顺序、 …
-
v0.2 重置：用 Plain 与 Managed 取代万能控制面
2026-07-31，v0.1 源码基线封存后，SOW 开始了一次产品重置。 目标是构建一个小型仓库引擎，替代 Pigsty 日常软件包构建工作流。 重置保留了已有的完整性与恢复经验，同时移除了大部分控制面。 最终形成的分工沿用至今：Plain 重建调用者拥有的目录，Managed 管理仓库及其历史。 开发设计最初在 RPM 视图内使用 C2 硬链接，随后在 8 月 8 日发布 v0.2.0 前被替换。 部分归档计划曾把 C2 构建称为“v0.2.0”，但正式标签已经采用单一包池与纯元数据视图。 …
2026-07-31，v0.1 源码基线封存后，SOW 开始了一次产品重置。 目标是构建一个小型仓库引擎，替代 Pigsty 日常软件包构建工作流。 重置保留了已有的完整性与恢复经验，同时移除了大部分控制面。 最终形成的分工沿用至今：Plain 重建调用者拥有的目录，Managed 管理仓库及其历史。 开发设计最初在 RPM 视图内使用 C2 硬链接，随后在 8 月 8 日发布 v0.2.0 前被替换。 部分归档计划曾把 C2 构建称为“v0.2.0”，但正式标签已经采用单一包池与纯元数据视图。 …
-
SOW v0.1 决策账本：哪些被保留，哪些已退役
v0.1.0 标签中有 44 份架构决策记录（ADR），编号为 0001 至 0045，缺少 0006。 每份 ADR 记录一个问题、当时的决策及实现必须满足的条件。 下表说明仓库模型变化后，各项决策的后续情况。 状态 含义 保留 原则以基本相同的范围继续用于当前 SOW。 演化 问题仍在，但所有权或实现已经改变。 迁移历史 决策用于 Pigsty/V1 切换。 退役 决策属于已移除的 Git/CAS/Route/Edge 模型。 决策日期从 2026-07-11 到 7 月 28 日 …
v0.1.0 标签中有 44 份架构决策记录（ADR），编号为 0001 至 0045，缺少 0006。 每份 ADR 记录一个问题、当时的决策及实现必须满足的条件。 下表说明仓库模型变化后，各项决策的后续情况。 状态 含义 保留 原则以基本相同的范围继续用于当前 SOW。 演化 问题仍在，但所有权或实现已经改变。 迁移历史 决策用于 Pigsty/V1 切换。 退役 决策属于已移除的 Git/CAS/Route/Edge 模型。 决策日期从 2026-07-11 到 7 月 28 日 …
-
SOW v0.1 原始计划：软件仓库的 Git
v0.1 计划始于 2026-07-11，并于 7 月 31 日封存为 v0.1.0。 它计划用一个 Go 控制面替换 Pigsty 的 Makefile 与 rclone 工作流，统一管理 APT、YUM 和静态制品。 范围包括本地状态、包历史、上游同步、渠道、视图、快照、双云发布、CDN 行为、商业访问控制和迁移。 当时的核心说法是：“制品仓库的 Git”。 软件分发确实需要不可变内容、可变名称、历史、晋级、 发布与回滚。这个类比帮助描述了需求，也扩大了产品范围。 …
v0.1 计划始于 2026-07-11，并于 7 月 31 日封存为 v0.1.0。 它计划用一个 Go 控制面替换 Pigsty 的 Makefile 与 rclone 工作流，统一管理 APT、YUM 和静态制品。 范围包括本地状态、包历史、上游同步、渠道、视图、快照、双云发布、CDN 行为、商业访问控制和迁移。 当时的核心说法是：“制品仓库的 Git”。 软件分发确实需要不可变内容、可变名称、历史、晋级、 发布与回滚。这个类比帮助描述了需求，也扩大了产品范围。 …