设计注记
设计注记解释 PIG 为什么采用今天的行为。每篇注记都会标明决策日期、实现与发布边界、 被否决的替代方案，以及对应的当前用户文档。
把 Pigsty 控制节点引导设计成可恢复事务
为什么 pig sty boot 在提权前解析来源、分离硬失败与收尾告警，并在软件源准备失败时恢复仓库定义。
Catalog v2 提案：不可变 typed snapshot，而不是更大的 CSV
一套候选的可验证 Catalog 模型：typed target、内容寻址 snapshot、显式激活、项目 pin 与离线导入。
PIG 2.0 产品方向：一份提案，而不是发布契约
PIG 2.0 的候选边界：稳定的 Pigsty 初始化前门、可验证 Catalog 客户端，以及保持显式部署的薄编排层。
让 Patronictl 自己说话
为什么 pig pt 不再镜像 Patronictl 命令树，而是只保留少量 PIG 本地辅助功能的透明启动器。
用有边界的 Grafana 客户端替代仪表盘脚本
为什么 pig sty grafana 只拥有仪表盘生命周期与偏好设置的一小段 HTTP 契约，而不成为通用 Grafana 管理客户端。
复用 Pigsty 已经拥有的 CMDB
为什么 PIG 撤销全新的 revision store 设计，转而成为 Pigsty 既有 PostgreSQL CMDB 的轻量受控适配器。
编辑声明，保留文档：无损 Pigsty Inventory
为什么 pig inventory 将 YAML 语义与源字节分离，让局部编辑能够保留注释、顺序、锚点与格式。
危险操作只有一套语法：PIG 运维 CLI 安全契约
PIG 如何分离底层原语与编排器、显式表达破坏性意图，并防止别名或结构化输出改变操作含义。
为什么 PIG 保持扁平的 Cobra 命令层
一个顶层命令对应 cmd 中一个文件，具体行为进入 cli 与 internal 包的源码布局决策。
七成正确的调优器：界定 pig pg tune 的边界
为什么 pig pg tune 只生成确定性的硬件相关核心参数，而不把自己包装成完整的生产 PostgreSQL 调优方案。
先编译和校验，再提交：原生 sty conf 流水线
为什么 pig sty conf 把 Inventory 生成视为带路径安全、结构化变更、秘密纪律和原子输出的编译流水线。
从面向人类到 Agent-Native：PIG 的 CLI 契约
为什么 PIG 将人类文本、结构化结果、执行计划与环境上下文分开，而不是把 JSON 当成最后附加的格式选项。
-
把 Pigsty 控制节点引导设计成可恢复事务
决策日期： 2026-08-14 状态： 已实现并随 pig v1.8.0 发布。 当前参考： pig sty boot 范围： 准备 Pigsty 控制节点及其软件来源，不包括部署数据库集群。 决策 pig sty boot 应当是一套原生、能够处理失败的控制节点引导工作流。 它在提权前解析显式来源，准备在线或离线仓库，只安装必要的控制节点软件包，证明 Ansible 真正可用， 并执行有边界的收尾检查。 仓库替换具有事务语义：软件包准备失败时恢复原有仓库定义。 可选便利功能可以告警，但无效 …
决策日期： 2026-08-14 状态： 已实现并随 pig v1.8.0 发布。 当前参考： pig sty boot 范围： 准备 Pigsty 控制节点及其软件来源，不包括部署数据库集群。 决策 pig sty boot 应当是一套原生、能够处理失败的控制节点引导工作流。 它在提权前解析显式来源，准备在线或离线仓库，只安装必要的控制节点软件包，证明 Ansible 真正可用， 并执行有边界的收尾检查。 仓库替换具有事务语义：软件包准备失败时恢复原有仓库定义。 可选便利功能可以告警，但无效 …
-
Catalog v2 提案：不可变 typed snapshot，而不是更大的 CSV
决策日期： 2026-08-13 状态： 实现前提案；安全机制、overlay 范围、打包方式与路径 ADR 仍未决定。 当前参考： pig ext 与 pig repo描述 v1 Catalog 行为。 范围： PIG 2.0 产品元数据的候选发布与消费模型，不包含 Inventory 或实时系统状态。 决策 Catalog v2 应当是一份由多个 typed target 组成的不可变、可验证 snapshot。 Manifest 将平台、仓库、路由、package alias、扩展、兼容 …
决策日期： 2026-08-13 状态： 实现前提案；安全机制、overlay 范围、打包方式与路径 ADR 仍未决定。 当前参考： pig ext 与 pig repo描述 v1 Catalog 行为。 范围： PIG 2.0 产品元数据的候选发布与消费模型，不包含 Inventory 或实时系统状态。 决策 Catalog v2 应当是一份由多个 typed target 组成的不可变、可验证 snapshot。 Manifest 将平台、仓库、路由、package alias、扩展、兼容 …
-
PIG 2.0 产品方向：一份提案，而不是发布契约
决策日期： 2026-08-13 状态： 等待 owner 审议的提案；尚未实现，也不是 PIG 2.0 发布承诺。 当前参考： PIG 文档与当前 v1.8.1 发布 范围： 未来 PIG 2.0 / Pigsty 5.0 的候选产品边界与验证门槛。 决策 提案方向是让 PIG 成为从空白控制节点到经过校验、可以部署的 Pigsty Inventory 的稳定初始化前门。 PIG 拥有 Catalog 选择、解析、计划、有边界的执行编排、结构化结果与脱敏 receipt； 软件包事务、配置应 …
决策日期： 2026-08-13 状态： 等待 owner 审议的提案；尚未实现，也不是 PIG 2.0 发布承诺。 当前参考： PIG 文档与当前 v1.8.1 发布 范围： 未来 PIG 2.0 / Pigsty 5.0 的候选产品边界与验证门槛。 决策 提案方向是让 PIG 成为从空白控制节点到经过校验、可以部署的 Pigsty Inventory 的稳定初始化前门。 PIG 拥有 Catalog 选择、解析、计划、有边界的执行编排、结构化结果与脱敏 receipt； 软件包事务、配置应 …
-
让 Patronictl 自己说话
决策日期： 2026-07-21 状态： 已实现并随 pig v1.6.0 发布。 当前参考： pig pt 范围： Patronictl 集群命令，以及 PIG 拥有的配置选择、参数设置、服务、状态和日志辅助功能。 决策 pig pt 是已安装 patronictl 的透明启动器。PIG 选择配置并分派少量本地辅助命令； 其它命令 token 及其后的所有参数原样传递，保留原生提示、终端行为、输出格式与退出码。 PIG 不再维护一份持续变化的 Patronictl 命令树副本。 背景 镜像 …
决策日期： 2026-07-21 状态： 已实现并随 pig v1.6.0 发布。 当前参考： pig pt 范围： Patronictl 集群命令，以及 PIG 拥有的配置选择、参数设置、服务、状态和日志辅助功能。 决策 pig pt 是已安装 patronictl 的透明启动器。PIG 选择配置并分派少量本地辅助命令； 其它命令 token 及其后的所有参数原样传递，保留原生提示、终端行为、输出格式与退出码。 PIG 不再维护一份持续变化的 Patronictl 命令树副本。 背景 镜像 …
-
用有边界的 Grafana 客户端替代仪表盘脚本
决策日期： 2026-07-18 状态： v1.6.0 实现；Grafana dashboard schema v2 支持随后在 v1.6.2 交付。 当前参考： pig sty grafana 范围： Pigsty 拥有的仪表盘目录、仪表盘与界面偏好；不是通用 Grafana provisioning。 决策 PIG 应通过有边界的原生 HTTP 客户端管理 Pigsty 随附的 Grafana 资产。 它可以检查就绪状态、列出托管资产、装载或初始化仪表盘、导出仪表盘、只清理自己拥有的资产， …
决策日期： 2026-07-18 状态： v1.6.0 实现；Grafana dashboard schema v2 支持随后在 v1.6.2 交付。 当前参考： pig sty grafana 范围： Pigsty 拥有的仪表盘目录、仪表盘与界面偏好；不是通用 Grafana provisioning。 决策 PIG 应通过有边界的原生 HTTP 客户端管理 Pigsty 随附的 Grafana 资产。 它可以检查就绪状态、列出托管资产、装载或初始化仪表盘、导出仪表盘、只清理自己拥有的资产， …
-
复用 Pigsty 已经拥有的 CMDB
决策日期： 2026-07-18 状态： 全新 revision store 已被取代；复用既有 CMDB 的薄适配器已经实现，但仍为实验功能。 当前参考： pig inventory cmdb 范围： 与 Pigsty 既有 CMDB 交换声明，而不是再设计一个配置数据库。 决策 PIG 必须复用 Pigsty 已经提供的 CMDB。它的职责是有边界的适配：校验静态 Inventory， 将声明装载到既有表中，导出既有投影，检查一致性，并安全切换 Ansible 的静态与动态数据源。 PIG …
决策日期： 2026-07-18 状态： 全新 revision store 已被取代；复用既有 CMDB 的薄适配器已经实现，但仍为实验功能。 当前参考： pig inventory cmdb 范围： 与 Pigsty 既有 CMDB 交换声明，而不是再设计一个配置数据库。 决策 PIG 必须复用 Pigsty 已经提供的 CMDB。它的职责是有边界的适配：校验静态 Inventory， 将声明装载到既有表中，导出既有投影，检查一致性，并安全切换 Ansible 的静态与动态数据源。 PIG …
-
编辑声明，保留文档：无损 Pigsty Inventory
决策日期： 2026-07-18 状态： 已实现并随 pig v1.6.0 发布。 当前参考： pig inventory 范围： 静态 Pigsty Inventory 的查看、局部编辑、校验、比较与安全写入。 决策 PIG 同时把 pigsty.yml 视为语义声明和人工维护的源文档。语义解析器负责判断 Inventory 的含义， 原始字节则决定它的书写方式。局部编辑只替换有边界的源范围，并在原子写入前重新解析完整候选文件。 这样可以避免 YAML 工具常见的失败模式：逻辑上正确的一次编 …
决策日期： 2026-07-18 状态： 已实现并随 pig v1.6.0 发布。 当前参考： pig inventory 范围： 静态 Pigsty Inventory 的查看、局部编辑、校验、比较与安全写入。 决策 PIG 同时把 pigsty.yml 视为语义声明和人工维护的源文档。语义解析器负责判断 Inventory 的含义， 原始字节则决定它的书写方式。局部编辑只替换有边界的源范围，并在原子写入前重新解析完整候选文件。 这样可以避免 YAML 工具常见的失败模式：逻辑上正确的一次编 …
-
危险操作只有一套语法：PIG 运维 CLI 安全契约
决策日期： 2026-07-02 状态： pg、pb、pt、pitr 已于 v1.5.0 交付；2026-08-29 的 do 与 build proxy 修订已随 v1.8.1 发布。 当前参考： pig pg、pig pb、pig pitr、pig do 与 pig build 范围： PIG 自己拥有的运维命令；透明上游命令继续采用上游的确认与退出行为。 决策 操作便利性不能模糊操作含义。PIG 明确区分底层原语与多阶段编排器，显式表达破坏性意图， 谨慎分配别名，并要求计划与结构化结果描 …
决策日期： 2026-07-02 状态： pg、pb、pt、pitr 已于 v1.5.0 交付；2026-08-29 的 do 与 build proxy 修订已随 v1.8.1 发布。 当前参考： pig pg、pig pb、pig pitr、pig do 与 pig build 范围： PIG 自己拥有的运维命令；透明上游命令继续采用上游的确认与退出行为。 决策 操作便利性不能模糊操作含义。PIG 明确区分底层原语与多阶段编排器，显式表达破坏性意图， 谨慎分配别名，并要求计划与结构化结果描 …
-
为什么 PIG 保持扁平的 Cobra 命令层
决策日期： 2026-06-30 状态： 当前仍在执行的仓库架构。 当前参考： pig 命令总览与源码仓库 范围： Go 源码归属与命令注册方式，而不是公开命令分类本身。 决策 cmd 包保持扁平。一个顶层命令对应一个顶层 Go 文件：pg.go、pb.go、pt.go、 pe.go、sty.go、do.go、repo.go 等。即使命令树很复杂，也继续留在这个入口文件中， 除非另有明确的布局决策。 文件可以很长，但只应包含 Cobra 关注点：名称、别名、注解、参数、实参校验、帮助、注册和选 …
决策日期： 2026-06-30 状态： 当前仍在执行的仓库架构。 当前参考： pig 命令总览与源码仓库 范围： Go 源码归属与命令注册方式，而不是公开命令分类本身。 决策 cmd 包保持扁平。一个顶层命令对应一个顶层 Go 文件：pg.go、pb.go、pt.go、 pe.go、sty.go、do.go、repo.go 等。即使命令树很复杂，也继续留在这个入口文件中， 除非另有明确的布局决策。 文件可以很长，但只应包含 Cobra 关注点：名称、别名、注解、参数、实参校验、帮助、注册和选 …
-
七成正确的调优器：界定 pig pg tune 的边界
决策日期： 2026-03-21 状态： 2026-03-23 实现，并随 pig v1.3.2 发布。 当前参考： pig pg tune 范围： 为单个本地 PostgreSQL 实例生成确定性的首轮配置，不是完整的生产设计服务。 决策 pig pg tune 只回答一个有边界的问题：给定 CPU 数量、内存、磁盘容量与工作负载画像， 这台机器的 PostgreSQL 核心参数应该采用怎样的合理起点？ 它追求的是“七成正确”的初始值。命令尽可能探测硬件，允许显式覆盖，计算少量高影响参数， …
决策日期： 2026-03-21 状态： 2026-03-23 实现，并随 pig v1.3.2 发布。 当前参考： pig pg tune 范围： 为单个本地 PostgreSQL 实例生成确定性的首轮配置，不是完整的生产设计服务。 决策 pig pg tune 只回答一个有边界的问题：给定 CPU 数量、内存、磁盘容量与工作负载画像， 这台机器的 PostgreSQL 核心参数应该采用怎样的合理起点？ 它追求的是“七成正确”的初始值。命令尽可能探测硬件，允许显式覆盖，计算少量高影响参数， …
-
先编译和校验，再提交：原生 sty conf 流水线
决策日期： 2026-02-18；生产契约于 2026-08-14 定稿。 状态： 已实现并随 pig v1.8.0 发布。 当前参考： pig sty conf 范围： 从受信 Pigsty 模板生成一份经过校验的静态 Inventory，不是任意 YAML 转换器。 决策 pig sty conf 应当像一台小型编译器：解析一个安全模板，读取结构，应用一组有边界的结构化变更， 校验完整候选文件，并且只在所有必要阶段成功后原子提交输出。 命令不调用旧 configure 脚本，也不回退到原始 …
决策日期： 2026-02-18；生产契约于 2026-08-14 定稿。 状态： 已实现并随 pig v1.8.0 发布。 当前参考： pig sty conf 范围： 从受信 Pigsty 模板生成一份经过校验的静态 Inventory，不是任意 YAML 转换器。 决策 pig sty conf 应当像一台小型编译器：解析一个安全模板，读取结构，应用一组有边界的结构化变更， 校验完整候选文件，并且只在所有必要阶段成功后原子提交输出。 命令不调用旧 configure 脚本，也不回退到原始 …
-
从面向人类到 Agent-Native：PIG 的 CLI 契约
决策日期： 2026-02-12 状态： 在 pig v1.1.0 中实现，之后继续通过命令层重构收敛。 当前参考： pig 命令总览 范围： PIG 自己拥有的命令及其机器消费契约；不透明的透传命令保留原生接口。 决策 PIG 应当既适合人在终端中使用，也适合自动化 Agent 调用，而且不要求任何一方解析另一方的展示格式。 面向人的文本保持简洁、便于操作；真正拥有稳定结果的命令提供明确的 JSON/YAML 结果、状态码与执行计划。 仅仅转发外部工具的命令则保留原生输出流、提示与退出码，不 …
决策日期： 2026-02-12 状态： 在 pig v1.1.0 中实现，之后继续通过命令层重构收敛。 当前参考： pig 命令总览 范围： PIG 自己拥有的命令及其机器消费契约；不透明的透传命令保留原生接口。 决策 PIG 应当既适合人在终端中使用，也适合自动化 Agent 调用，而且不要求任何一方解析另一方的展示格式。 面向人的文本保持简洁、便于操作；真正拥有稳定结果的命令提供明确的 JSON/YAML 结果、状态码与执行计划。 仅仅转发外部工具的命令则保留原生输出流、提示与退出码，不 …