managed on SOW

SOW v0.4.0

Mon, 24 Aug 2026 00:00:00 +0000

SOW 0.4.0 是一次面向 Managed 仓库的完整性与恢复版本：它明确了深度校验的 I/O 契约，禁止跨无关密钥拼装 RPM 信任，提供可审计的发布目标可变配置修正路径，并补齐 v0.3 迁移与发布中断恢复的剩余缺口。

SOW v0.3.0

Mon, 10 Aug 2026 00:00:00 +0000

SOW 0.3.0 围绕性能、持久性与产品边界完成了一次集中改进：Plain 仓库生成只需一遍包体处理； Managed 仓库消除了逐对象成员查询，复用经过认证的软件包事实，并用有界组提交提升载荷。正式交付的二进制与发布流水线也统一收敛到 SOW 实际支持的仓库工作流。

SOW v0.2.0

Sat, 08 Aug 2026 00:00:00 +0000

SOW 0.2.0 是 Pigsty 出品的自包含 RPM/DEB 仓库管理器，Release 资产以单个 Go 可执行文件覆盖 Linux 与 macOS 构建目标。

两种工作模式

Plain 模式 给目录顶层已有的 RPM 与 DEB 文件就地生成索引：

设计归档

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

设计归档解释 SOW 为什么采纳某项契约、否决了哪些替代方案，以及结论实际达到了哪一层证据。文章按 date 排列，记录设计理由首次形成可维护正文的日期；lastmod 记录后续编辑或与实现对齐的日期。功能实际在哪个版本交付，仍以发布注记与源码 Tag 为准。

设计原则

Sat, 08 Aug 2026 00:00:00 +0000

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

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

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

搭建 YUM 仓库

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

本教程从零创建一个 Managed RPM 仓库。你需要一个可写目录，以及一个或多个 RPM 文件。

1. 创建工作区

mkdir -p /srv/sow
cd /srv/sow
sow init .
sow repo new pigsty
sow dist new el9 --format rpm -r pigsty

Dist 名称由你定义。SOW 不会根据 el9 推断操作系统版本。

上手

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

SOW 生成 RPM/YUM 与 DEB/APT 静态仓库，本身不是 HTTP 守护进程。先选择一条相互隔离的运行路径：

Plain： sow create 在普通目录中为现有软件包重建索引。
Managed： 工作区持续记录成员关系、Dist、架构视图、策略、签名、Generation、审计历史与发布目标。

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

本教程从零创建一个 Managed DEB 仓库。你需要一个可写目录，以及一个或多个 DEB 文件。

1. 创建工作区

mkdir -p /srv/sow
cd /srv/sow
sow init .
sow repo new pigsty
sow dist new trixie --format deb -r pigsty

Dist 名称会成为 APT Suite。它由你定义；SOW 不会根据 trixie 推断发行版语义。

sow.yml 配置参考

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

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

Managed 工作区

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

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

第一个工作区

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

Managed 模式会持久保存配置、成员关系、Generation 与审计状态。下面从空目录开始。

初始化工作区

sow init /srv/sow
cd /srv/sow

init 创建：

功能

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

SOW 提供两条相互隔离的运行路径。Plain 模式无状态地重建一个目录；Managed 模式在工作区中持续记录软件包成员关系与不可变仓库 Generation。两者都不会暗中接管对方的状态。

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

SOW 只生成静态文件，不是 HTTP 服务器。本指南把可写 Workspace 与 Nginx 服务路径分开。

公共与私有路径

模式	公共单元	绝不能服务
Plain	传给 `sow create` 的目录	临时 `.sow-plain-stage-*` 输出；没有持久 journal
Managed	一个 Repository 的完整 `pool/ + dists/` 树	Workspace `sow.yml`、`.sow/`、SQLite、锁、日志与 staging

第一个工作区里的源 Repository 是 /srv/sow/local。不要把 /srv/sow 设为 document root。

核心概念

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

Plain 还是 Managed

两条运行路径相互独立。

	Plain	Managed
入口	`sow create DIR`	`init`、`repo`、`dist`、`add`、`rm`、`build`
状态	软件包目录	`sow.yml` 加私有 SQLite/操作日志
公共布局	平面 RPM/DEB 索引	Repository `pool/ + dists/`
格式	RPM 与 DEB 可共存于一个目录	每个 Dist 一种格式
架构视图	无	有
策略与审计	无	有
元数据签名与发布目标	无	有

目录内容已经等于目标仓库时使用 Plain。需要由 SOW 管理成员、策略、Generation、签名、审计或发布时使用 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 的那几个包。

演练构建 pigsty-infra 仓库

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

pgsty/infra-pkg 是 Pigsty Infra 软件包的上游构建源码。本教程假设双架构 RPM 与 DEB 已经构建完成，只处理后半程：从一堆包开始，用 SOW 建成真正可消费、可维护的 infra 仓库。

1. 把包集中到 ~/repo

本教程固定使用 ~/repo，不再为每条路径定义环境变量。先把已有包复制进两个输入目录：

sow add

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

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

sow rm

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

sow rm 把包从你选定的 Dist 的期望成员集中拿掉，并默认立即重建受影响的索引。它不会从 pool/ 删除字节——成员关系与内容是两个概念,回收由独立的保守操作 sow gc 完成。

sow ls

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

sow ls 是针对 Package Object 与 Dist Membership 的只读查询。它显示所选 Dist 应包含哪些包，以及这些成员是否已经进入当前 Built Generation。

语法

sow ls [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	选择 Dist；可重复	选择规则
`--json`	输出 `sow.cli/v1` Envelope	false

该命令没有 --pool、--match 或输出格式参数。

sow show

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

sow show 在所选 Repository 中解析一个包引用，并打印完整 Package Object。该命令只读，不获取写锁。

语法

sow show PACKAGE [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	将候选项收窄到指定 Dist；可重复	整个 Repository
`--json`	将结果包装进 `sow.cli/v1` Envelope	false

包引用

PACKAGE 可使用 sha256:<hex> 内容身份、规范的 rpm:<NEVRA> 或 deb:<name>=<version>:<arch> 坐标、完整包文件名或裸二进制包名。精确文法见包引用。

sow where

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

sow where 用于回答工作区中哪些 Dist 仍包含某个 Package Object。它默认搜索全部 Repository，只读且不获取写锁。

语法

sow where PACKAGE [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	将搜索限制到一个 Repository	全部 Repository
`-d, --dist NAME`	将搜索限制到指定 Dist；可重复	全部 Dist
`--json`	输出 `sow.cli/v1` Envelope	false

引用解析

PACKAGE 与 sow show 使用相同文法：SHA-256、规范 RPM/DEB 坐标、完整文件名或裸包名。

sow status

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

sow status 是低成本的 Repository 状态查询。它读取状态，但不哈希文件、不验签、不恢复 Operation、不构建元数据，也不获取写锁。

语法

sow status [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	只查看指定 Dist；可重复	全部 Dist
`--json`	输出 `sow.cli/v1` Envelope	false

Repository 状态

每个 Repository 同时跟踪 SQLite 中的 Desired Revision，以及公开 dists/ 树对应的 Built Generation。

sow build

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

sow build 是显式的 Desired-to-Built 收敛命令。它获取 Repository 写锁，恢复任何可裁决的未完成 Operation，渲染并验证完整 Generation，最后切换协议指针。

语法

sow build [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

参数	含义	默认值
`-j, --jobs N`	并行 Worker 数，不得小于 `1`	逻辑 CPU 数
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	构建指定 Dist；可重复	全部受影响 Dist
`-T, --timeout DUR`	最长等锁时间；`0` 表示无限等待	`0`
`-N, --no-wait`	锁被占用时立即失败	false
`--json`	将结果包装进 `sow.cli/v1` Envelope	false

不带 -d 时，SOW 收敛所选 Repository 中全部受影响 Dist；带 -d 时只收敛指定 Dist，未选择的变化继续保持 dirty。