SOW:Pigsty 出品的软件仓库管理器 on SOW

SOW 0.2:文档站上线

Tue, 04 Aug 2026 00:00:00 +0000

发布日期: 2026-08-04 · 版本: sow 0.2.0-dev

SOW 是 Pigsty 出品的自包含软件仓库管理器:一个静态 Go 二进制, 在 Linux 与 macOS 上创建并维护 APT(DEB)与 YUM(RPM)软件仓库,而且整件事都由它自己完成 —— 从不调用 createrepo_c、dpkg-scanpackages、reprepro 或 modifyrepo_c。没有常驻服务,没有数据库,也没有需要一并安装的东西。名字取自那个动词: 把软件包播进仓库,仓库自己长起来。

下载与安装

Mon, 01 Jan 0001 00:00:00 +0000

SOW 是一个静态可执行文件。没有安装器,没有要装的软件包,没有要启用的服务, 在你第一次运行需要状态的命令之前,它甚至不会创建任何目录。安装它 = 把一个文件放进 PATH。

sow create

Mon, 01 Jan 0001 00:00:00 +0000

sow create 把一个已经放着 .rpm / .deb 的目录变成平面仓库（flat repository）：在包旁边写出索引文件。它就是 Plain 平面模式的全部——没有 sow.yml、没有 SQLite、不做工作区发现。本页讲清扫描规则、原子的 --pigsty 兼容操作，以及 --sign-with 的 RPM 包签名。

安装 SOW

Mon, 01 Jan 0001 00:00:00 +0000

SOW 以单个静态可执行文件分发。所谓安装,就是把这一个文件放到 PATH 上的某个位置。没有软件包要装,没有服务要启用,在你执行第一条需要落盘的命令之前,它也不会创建任何状态目录。

搭建 YUM 仓库

Mon, 01 Jan 0001 00:00:00 +0000

这篇教程从零搭出一个生产形态的 RPM 仓库。做完你会得到:一个工作区(Workspace),里面有名为 pigsty 的仓库(Repository)和一个 el9 Dist,由单一包池(pool)渲染出两个架构视图, debuginfo 噪声被过滤掉,每个包只保留最新版本,以及一份 dnf 能吃的 .repo 文件。

能力总览

Mon, 01 Jan 0001 00:00:00 +0000

SOW 是一个自包含的软件仓库管理器:一个纯静态 Go 二进制(CGO_ENABLED=0),在 Linux 与 macOS 上创建并维护 APT(DEB)与 YUM(RPM)软件仓库。它不调用 createrepo_c、dpkg-scanpackages、reprepro 或 modifyrepo_c,也不需要常驻进程。本页是覆盖面的地图,后续各页解释每一块是怎么实现的。

设计原则

Mon, 01 Jan 0001 00:00:00 +0000

SOW 首先不是一个“元数据生成器”，而是一个所有权与状态迁移系统，只是它的输出恰好是 APT 与 RPM 仓库。下面这些原则让整套系统保持可推理。

每个持久事实只有一个主人

每类持久事实都只有一个作用域与权威：

Plain 平面仓库

Mon, 01 Jan 0001 00:00:00 +0000

sow create 接手一个已经装着 .rpm 和 .deb 的目录,就地给它写一份索引。它的全部工作就是这个。本页讲清楚它读什么、写什么、承诺绝不碰什么,以及执行到一半被杀掉时怎么活下来。

sow init

Mon, 01 Jan 0001 00:00:00 +0000

sow init 创建根级 sow.yml 与私有状态目录 .sow/，这两样东西让一个目录成为工作区（Workspace）。它同时也是手写配置的收敛命令：如果 sow.yml 里已经声明了 Repository 与 Dist，init 会把还不存在的那些实体化出来，已完成的原样跳过。

搭建 APT 仓库

Mon, 01 Jan 0001 00:00:00 +0000

这篇教程搭一个托管 APT 仓库:按源码包分组的 Debian 风格包池、每个架构一份索引、by-hash 索引副本(让客户端不会撞上重建),以及现代 deb822 与传统单行两种客户端配置。

快速上手

Mon, 01 Jan 0001 00:00:00 +0000

这一页大约五分钟。你会把若干软件包放进一个目录,执行一条命令,用 HTTP 暴露出去, 然后用 dnf 或 apt 从中安装。不需要配置文件、不需要工作区、不需要数据库 —— Plain 平面模式只是在软件包旁边写出索引,除此之外什么都不做。

sow.yml 配置参考

Mon, 01 Jan 0001 00:00:00 +0000

sow.yml 是 Managed 托管工作区(Workspace)唯一的配置文件。它位于工作区根目录, 声明存在哪些仓库(Repository)与 Dist,并保存每次构建都要执行的成员策略与签名设置。 Plain 平面模式(sow create)完全不读它。

系统模型

Mon, 01 Jan 0001 00:00:00 +0000

SOW 刻意把模型分层：配置表达意图，数据库记录有主状态，公共树是确定性投影。任何一层都不能悄悄替代另一层。

对象层级

Workspace
├── Repository
│ ├── Package Object
│ ├── Dist
│ │ └── Membership -> Package Object
│ ├── Desired 状态
│ ├── Built Generation
│ └── Retained Generation 引用
└── Publication Target
 └── Repository + provider + prefix

Workspace

Workspace 提供发现、配置与协调，拥有 sow.yml、私有 .sow/ 目录和稳定锁路径；它不是包体去重域。

Managed 工作区

Mon, 01 Jan 0001 00:00:00 +0000

当同一个仓库要维护好几个月 —— 包成批到达、由策略决定谁留下、事后还得说清楚什么时候变了什么 —— 你需要的是 Managed 模式。本页讲三层模型、它产出的布局,以及命令怎么判断你说的是哪个仓库、哪个 Dist。

sow config

Mon, 01 Jan 0001 00:00:00 +0000

sow config 有两个只读子命令。config check 是对 sow.yml 的全量预检——每次手工改完配置以及在 CI 里都该跑一遍。config show 打印 SOW 实际算出来的配置，用它确认默认值、继承的架构与规范化别名是不是按你预期解析的。

包引用

Mon, 01 Jan 0001 00:00:00 +0000

sow rm、sow show、sow where 都接受一个 PACKAGE 参数。本页定义你能在那里写什么。三条命令共用同一套文法,只有对歧义名称的处理不同。

这里的内容与 sow add 无关 —— add 接受的是文件系统路径,不是包引用。

仓库签名

Mon, 01 Jan 0001 00:00:00 +0000

没签名的仓库,链路上任何人都能改写。这篇教程把这个洞堵上:生成签名钥、配置 SOW 对发布内容签名、手工验证签名,再打开客户端强制校验,让 dnf 与 apt 拒绝一切校验不过的东西。

单包体仓库

Mon, 01 Jan 0001 00:00:00 +0000

0.3 开发线调整了 RPM 物理布局，但保留 v0.2 确立的所有权模型。它的目标很精确：在一个 Repository 及其每个发布前缀内，每个 live Package Object 恰好只有一条包体路径。

开发线设计

本页描述已经落入 0.3 源码的布局；已发布 v0.2 的操作参考仍然使用 C2 view-local 硬链接。迁移现有 v0.2 仓库前，请先读设计演进。

第一个工作区

Mon, 01 Jan 0001 00:00:00 +0000

这一页大约十分钟,从零搭出一个 Managed 托管仓库:一个工作区、一个仓库、其中的一个 RPM Dist 与一个 DEB Dist,往两边添加软件包,最后看清楚磁盘上到底生成了什么。与 Plain 平面模式不同,工作区会记住你的意图 —— 你按名字增删软件包,而不是靠搬文件,SOW 只重建真正变化的部分。

sow repo

Mon, 01 Jan 0001 00:00:00 +0000

一个仓库（Repository）独占一份 pool/、一份 dists/、一个 SQLite 数据库与一个私有状态目录。它是锁、事务恢复、Generation 编号与 Changeset 的边界——跨仓库不去重，也不承诺跨仓库原子提交。 sow repo 管理的就是这条边界。

包池与架构视图

Mon, 01 Jan 0001 00:00:00 +0000

列一遍 Managed 仓库,你会在三个不同路径上看到同一个包文件,而 du 坚称它只占一份空间。这不是错觉,也不是符号链接。本页讲清楚这套投影模型 —— 它为什么存在、保证了什么,以及它对你的文件系统提出的那一条约束。

仓库布局

Mon, 01 Jan 0001 00:00:00 +0000

SOW 的磁盘布局是固定的。没有 path: 配置项,没有模板,也没有办法把仓库挪到别处 —— 每一条路径都由工作区根目录、一个已校验的名称和固定的相对片段推导而来。本页给出完整地图,让你清楚哪些该发布、哪些该复制、哪些必须留在本地。

对外服务

Mon, 01 Jan 0001 00:00:00 +0000

SOW 产出的是一个静态目录。任何能提供静态文件的东西都能服务它——没有守护进程、没有应用服务器、没有运行时组件。这篇教程讲清楚该把 web 服务器指向哪里、一份实测过的 Nginx 配置、一条命令的本地预览,以及怎么把整棵树搬到够不着构建机的主机上。

发布与恢复

Mon, 01 Jan 0001 00:00:00 +0000

构建与发布是两个独立状态迁移。构建产生与 target 无关的 Generation；发布把该 Generation 应用到一个供应商前缀，并记录足以在不猜测的前提下恢复的证据。

所有权拆分

Repository 作用域	Target prefix 作用域
Package Object	Publication Attempt
Desired 与 Built 状态	Applied Checkpoint
Generation 与 Changeset	远端 inventory
retained 包体/元数据引用	grace 与删除证据

这项拆分避免把 filesystem 发布成功当成 R2 的证据，也避免一个 target 的半完成尝试污染另一个。

核心概念

Mon, 01 Jan 0001 00:00:00 +0000

跑完快速上手、搭完第一个工作区之后, 只需要少数几个概念就能解释 SOW 的其余全部行为。本页讲清楚这些:两种模式与如何选型、 Managed 模型的四个层级,以及"你要什么"与"当前发布了什么"之间的分离。

sow dist

Mon, 01 Jan 0001 00:00:00 +0000

Dist 是一个仓库内、单一格式（rpm 或 deb）的具名包集合。客户端指向的就是它。一个仓库可以同时拥有 RPM Dist 与 DEB Dist，两者共用一份 pool/，但渲染进完全独立的 dists/ 子树。

成员策略

Mon, 01 Jan 0001 00:00:00 +0000

策略回答的是这个问题:“我把整个构建目录倒进了这个 Dist,但我不想要 debuginfo 包,而且每个包只留最新版本。“两条规则完成这件事,它们按固定顺序执行,并且作用于完整候选集,而不是你这次恰好 add 的那几个包。

从 createrepo_c / reprepro 迁移

Mon, 01 Jan 0001 00:00:00 +0000

你已经有一个仓库了。这篇教程换掉构建它的工具,而不弄坏消费它的客户端——包括没人会提醒你的那些残留文件,以及应该在动手前而不是动手后知道的布局差异。

兼容性边界

Mon, 01 Jan 0001 00:00:00 +0000

“兼容”太宽泛，不足以成为工程结论。一个包可能安装成功，但镜像工具拒绝同一份元数据；一棵树可能在 POSIX 磁盘上去重，上传后却变成多个完整对象。因此 SOW 把兼容性拆成独立门禁。

退出码

Mon, 01 Jan 0001 00:00:00 +0000

每条 sow 命令都以七个退出码之一结束。它们是稳定的、对所有命令一致, 并且就是设计来给脚本做分支判断的 —— 区分"这件事失败了"和"这件事被正确地拒绝了", 正是设置多个非零码的全部意义。

JSON 输出

Mon, 01 Jan 0001 00:00:00 +0000

所有产出数据的命令都接受 --json。输出是 stdout 上的一行版本化信封 —— 不管是哪条命令产生的,都能直接管道给 jq。

sow status --json

{"schema":"sow.cli/v1","command":"status","ok":true,"repository":"pigsty","operation":null,
 "result":{"repository":"pigsty","status":"clean","ready_to_copy":true,"desired_revision":4,
 "built_generation":4,"dirty_dists":[],"dirty_reasons":[],"pending":{"count":0,"bytes":0},
 "recent_operation":{"id":"8632724976452398569","kind":"add","state":"done",
 "created_at":"2026-08-04T04:07:17.665377Z","updated_at":"2026-08-04T04:07:18.293848Z"},
 "repository_locked":false},"errors":[]}

(此处为便于阅读做了折行,实际输出是一行。)

sow add

Mon, 01 Jan 0001 00:00:00 +0000

sow add 是主要的写入路径。它解析你指定的包，从包头推导格式与架构，执行 Dist 的成员策略，并且—— 除非你加 --skip——在返回前重建全部受影响的索引。命令退出码为 0 时，客户端已经能看到新包了。

签名模型

Mon, 01 Jan 0001 00:00:00 +0000

客户端会对一个仓库提两个不同的问题,SOW 用两套彼此独立的机制分别回答。把它们混为一谈,是"我明明签了名,dnf 还是报错"这类问题最常见的来源 —— 所以本页先把两者拆开。

设计演进

Mon, 01 Jan 0001 00:00:00 +0000

SOW 的旧文档来自三套实质不同的系统。缺少版本边界时，互相矛盾的结论看起来像同时成立。本页保留有价值的决策，同时明确它们各自的作用域。

时间线

版本线	主要问题	物理模型	处置
V1 实验（2026-07）	纳管 Pigsty 既有 APT/YUM 树与远端发布流程	Git/CAS、route-aware 投影、edge/provider 契约	归档为研究与实现证据
v0.2.0	交付紧凑的本地 Plain + Managed 仓库管理器	根 Pool + C2 view-local RPM 硬链接	已发布；操作文档继续在线
0.3 开发线	每个 Repository/target prefix 只发布一份正典包体	根 Pool + 纯元数据 view + target-scoped 发布	源码已实现；发布证据待完成

V1 留下了什么

V1 大范围探索了既有仓库纳管、远端发布、供应商 fencing、边缘鉴权、迁移、恢复与大仓库证据。它具体的 Git/CAS/route 模型大多已被替换，但几条原则保留下来：

sow rm

Mon, 01 Jan 0001 00:00:00 +0000

sow rm 把包从你选定的 Dist 的期望成员集中拿掉，并默认立即重建受影响的索引。它绝不从 pool/ 删除字节——成员关系与内容是两个概念，而且系统没有垃圾回收。

语法

sow rm PACKAGE... [-c|--check] [--skip] [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

参数

参数	说明	默认
`-c, --check`	只预览：计算并打印方案，不写任何东西	关闭
`--skip`	只更新期望状态，不构建	关闭
`-j, --jobs N`	并发 worker 数	逻辑 CPU 数
`-C, --workdir DIR`	工作区发现的起始目录	当前目录
`-r, --repo NAME`	选择一个仓库	按选择规则
`-d, --dist NAME`	选择一个 Dist；可重复	按选择规则
`-T, --timeout DUR`	等待锁的最长时间；`0` 无限等待	`0`
`-N, --no-wait`	锁被占用时立即失败	false
`--json`	输出版本化 JSON envelope	false

--check 与 --skip 互斥：

兼容性

Mon, 01 Jan 0001 00:00:00 +0000

SOW 输出的是标准 rpm-md 与 Debian archive 元数据,所以问题不在于客户端"能不能"读, 而在于哪些客户端确实被验证过。本页给出实测矩阵、二进制支持的平台, 以及少数几条忽略了就会出问题的约束。

事务与恢复

Mon, 01 Jan 0001 00:00:00 +0000

仓库工具翻车通常是两种难堪的姿势之一:留下一份指向已不存在的包的索引,或者把自己的数据库搞坏、只能从头重建。SOW 的设计目标是让这两件事都不可能发生,本页讲清楚支撑这一点的机制。

sow ls / show / where

Mon, 01 Jan 0001 00:00:00 +0000

三条命令回答三个不同的问题。ls 列出一个 Dist 应该包含什么，show 详细查看某一个包对象，where 找出哪些 Dist（跨仓库）在提供某个包。三者都是只读的，不取写锁，共用同一套 --json envelope。

可观测与审计

Mon, 01 Jan 0001 00:00:00 +0000

四条只读命令回答四个不同的问题,而且每一条都拒绝替另外三条干活。这种分离是刻意的:一个偶尔会把整仓哈希一遍的"便宜状态检查"没法放进循环,一个会偷偷修东西的"完整校验"没法当证据用。

sow build / status / check / changes

Mon, 01 Jan 0001 00:00:00 +0000

一个概念一条命令。status 是便宜的读，check 是完整校验，build 是唯一会改变公开树的命令， changes 给出两代之间的物理文件差分。四条放在一页，因为你几乎总是一起用它们。

sow log

Mon, 01 Jan 0001 00:00:00 +0000

仓库内的每条写命令，都会先在该仓库的 SQLite 中提交一条应用级 Operation，然后才产生任何外部文件副作用。这条记录让崩溃恢复成为可能——而当 Operation 进入终态之后，同一条记录就是你的审计轨迹。 sow log 读的就是它。

页面不存在

Mon, 01 Jan 0001 00:00:00 +0000

你访问的页面可能已被移动、删除,或从未存在。

请回到文档首页,或使用 ⌘K / Ctrl K 站内搜索。