Catalog v2 提案：不可变的分类快照
决策日期： 2026-08-13
状态： 提案；安全机制、覆盖规则、打包方式与路径布局待定。
当前参考：pig ext与pig repo
范围： PIG 2.0 产品元数据的发布与读取模型。
决策
Catalog v2 将产品元数据分成多个有类型的数据文件，组成一份不可变、可验证的快照。 清单文件（manifest）记录平台、仓库、路由、包别名、扩展、兼容性、Pigsty 版本与公钥数据的 长度和哈希。所有文件一起校验，通过同一个指针激活，避免混用不同版本的仓库与扩展矩阵。
快照以内容摘要标识。系统、用户、便携环境与项目都选择完整快照，并从各自的存储位置读取。
背景
v1 Catalog 的相关信息分布在内嵌 CSV、仓库 YAML、Pigsty 变量、生成站点与更新流程中。 部分字段可以推导，却仍需重复维护；扩展矩阵也把项目、版本与包等不同对象压在同一条记录里。 独立更新后，很难确认这些数据来自同一次发布。
Catalog v2 要解决的是数据如何一起发布、校验和启用。
考虑过的方案
- 扩大
extension.csv或改用一个大 YAML。 不同数据类型需要独立的结构和校验规则。 - 立即使用 SQLite、protobuf 或定制二进制格式。 当前数据量尚不需要增加这类运行和调试成本。
- 按字段合并系统、用户与项目基础快照。 合并结果缺少单一发布者、摘要、兼容声明与签名。
- 只在缓存中保存当前快照和项目锁定版本。 清理缓存会破坏持久选择。
- 让用户文件覆盖官方信任根。 用户偏好不应削弱系统的安全策略。
- 后台静默更新并启用。 元数据变化会改变包解析结果，用户需要知道何时发生了更新。
契约
提案规定：
- 清单与小型数据文件使用确定性的 UTF-8 JSON，大型稀疏数据使用 JSONL。
- 直接校验清单原始字节，以及数据文件的长度和哈希，避免重新序列化产生歧义。
- 清单包含格式版本、单调递增的安全版本、创建与过期时间、发布通道及 PIG/Pigsty 兼容范围。
- 内嵌一份可用于恢复的基础快照。
- 将包管理器维护的基础快照、持久快照存储、可变状态指针与下载缓存分开存放。
- Linux 遵循 FHS/XDG，macOS 使用 Application Support 与 Caches。便携模式下的
PIG_HOME也分别存放配置、数据、状态、缓存与运行文件。 - 项目锁定文件记录快照身份与有序覆盖层；项目自身持久保存已验证的快照数据。
- 将“选择哪个摘要”与“到哪里读取对应数据”分成两个步骤。
- 用户与项目只能收紧系统安全策略。
- 更新先下载到私有暂存目录，逐层校验并同步到磁盘，再移入按内容寻址的存储，最后原子替换激活指针。
- 更新失败保留原快照；用户或系统通道更新不改变项目锁定版本。
- 离线导出包含验证元数据和公开信任材料，不包含私钥。
- 在一个兼容周期内，
ext reload与repo reload可以映射到完整快照更新；各数据文件统一激活。
Inventory、凭据、实时探测、已安装包状态、Ansible 事件、基础设施状态、操作确认与短期指标 继续由各自的系统管理。
影响
分类数据文件便于确定维护职责和校验规则，内容寻址便于回滚与离线导入。 项目自带所需快照后，部署不再依赖某个用户的全局缓存。系统软件包更新基础快照时， 用户已选择的快照保持不变。
这需要同时设计密钥轮换、过期、回滚保护、垃圾回收、路径权限、迁移、包管理器生命周期、 覆盖冲突与跨仓库生成流程。
扩展模型还需区分 SQL 扩展、上游项目、构建单元、发布版本、操作系统软件包、目标平台可用性
与展示规则。平台支持汇总、required_by 等派生字段由生成器计算。
验证与演进
实现前需比较 go-tuf 与最小签名清单方案，记录安全机制的选择。 两者均需通过错误签名、元数据过期、回滚、文件替换、快照混装、下载截断与离线验证测试。
其余测试覆盖各平台路径、root 与普通用户权限、只读目录、符号链接替换、磁盘写满、并发激活、 包升级与卸载、删除全局缓存后的项目运行，以及现有扩展和可用性数据的完整迁移。
本提案形成时的源码基线为
v1.8.0。
v1.9.0 仍使用内嵌与可独立更新的 v1 Catalog。
当前状态
Catalog v2 尚未实现。安全机制、路径与覆盖规则需要先完成决策和验证。
如果覆盖层的冲突与信任规则尚不成熟，可以先采用完整的自定义签名通道。
当前用法见 pig ext 与 pig repo。