设计注记

决策日期： 2026-10-16 状态： Implemented（已实现），纳入 v1.10.0 候选版本，尚未发布。 当前参考： pig ext 目录计数 范围： 目录总数与默认列表成员；包安装和 SQL 启用方式仍由各条目定义。 决策 统一用目录记录数表示扩展总数，包括已打包的 SQL 工具与保留的生命周期记录。 CLI 根据实际加载或下载的目录计算总数。 背景 目录同时服务于软件包发现和 PostgreSQL 扩展发现。已打包的 SQL 工具即使没有控制文件， 不支持 CREATE …

决策日期： 2026-10-05 状态： Released（已发布），随 v1.9.0 交付。 下述验收修订已实现（Implemented），纳入 v1.10.0 候选版本，尚未发布。 当前参考： pig build、运维安全契约与发布历史 范围： 一键配置 Xray 客户端与服务端；Linux 客户端和服务端，以及 macOS 客户端。共享 Nginx 入口仍是独立部署边界。 决策 为 pig build proxy 增加明确的 client 与 server 子命令。新工作流采用 …

决策日期： 2026-10-04 状态： Released（已发布），随 v1.9.0 交付。 当前参考： pig repo 范围： 配置仓库时安装已有的内嵌 Pigsty 公钥。 决策 当所选模块包含当前平台可用的 pigsty-infra 或 pigsty-pgsql 仓库时，先准备内嵌 Pigsty 公钥，再修改仓库定义。该逻辑放在共享配置流程中，使 repo add、repo set 以及复用此流程的调用方保持一致。已有公钥文件直接复用，自动安装尽最大努力； 所选仓库元数据显式引用签名 …

决策日期： 2026-09-03 状态： Released（已发布），随 v1.8.1 交付。 当前参考： pig build 范围： pig build ext 与 pig build pkg 的调试包策略；单个包的产物仍以其配方为权威。 决策 pig build ext 与 pig build pkg 默认请求平台的正常调试包产物。普通构建时，PIG 不再传入禁用参数；只有需要更小或更快产物集合的用户，才显式使用 --nodbg 退出。 在 RPM 系统上，普通构建保留发行版的 …

决策日期： 2026-08-14 状态： 已实现并随 pig v1.8.0 发布。 当前参考： pig sty boot 范围： 准备 Pigsty 控制节点及其软件来源，不包括部署数据库集群。 决策 pig sty boot 应当是一套原生、能够处理失败的控制节点引导工作流。 它在提权前解析显式来源，准备在线或离线仓库，只安装必要的控制节点软件包，证明 Ansible 真正可用， 并执行有边界的收尾检查。 仓库替换具有事务语义：软件包准备失败时恢复原有仓库定义。 可选便利功能可以告警，但无效 …

决策日期： 2026-08-13 状态： 提案；安全机制、覆盖规则、打包方式与路径布局待定。 当前参考： pig ext 与 pig repo 范围： PIG 2.0 产品元数据的发布与读取模型。 决策 Catalog v2 将产品元数据分成多个有类型的数据文件，组成一份不可变、可验证的快照。 清单文件（manifest）记录平台、仓库、路由、包别名、扩展、兼容性、Pigsty 版本与公钥数据的 长度和哈希。所有文件一起校验，通过同一个指针激活，避免混用不同版本的仓库与扩展矩阵。 快照以内容摘 …

决策日期： 2026-08-13 状态： 提案，待审议，尚未实现。 当前参考： PIG 文档与发布历史 范围： 未来 PIG 2.0 / Pigsty 5.0 的候选产品边界与验证门槛。 决策 提案方向是让 PIG 成为从空白控制节点到经过校验、可以部署的 Pigsty Inventory 的统一初始化入口。 PIG 负责 Catalog 选择与解析、执行计划、流程编排、结构化结果与脱敏执行记录； 软件包事务、配置应用与基础设施状态继续委托给 DNF/APT、Ansible 和未来的基础设施工 …

决策日期： 2026-07-21 状态： 已实现并随 pig v1.6.0 发布。 当前参考： pig pt 范围： Patronictl 集群命令，以及 PIG 拥有的配置选择、参数设置、服务、状态和日志辅助功能。 决策 pig pt 是已安装 patronictl 的透明启动器。PIG 选择配置并分派少量本地辅助命令； 其它命令词及其后的所有参数原样传递，保留原生提示、终端行为、输出格式与退出码。 PIG 不再维护一份持续变化的 Patronictl 命令树副本。 背景 镜像 …

决策日期： 2026-07-18 状态： 随 v1.6.0 发布；v1.6.2 加入仪表盘 schema v2 支持。 当前参考： pig sty grafana 范围： 仪表盘导入、导出、清理，以及部分组织与用户偏好设置。 决策 PIG 使用原生 HTTP 客户端管理 Grafana 仪表盘。本地 JSON 路径选择单个仪表盘、一个文件夹或 完整仪表盘目录。装载、导出与清理采用同一套选择规则，破坏性操作可以先预览。 默认目录是 Pigsty 仪表盘集合，用户也可以选择其他符合格式的目录。 清 …

决策日期： 2026-07-18 状态： 适配器随 v1.6.0 发布，仍为实验功能；早期版本存储设计已被取代。 当前参考： pig inventory cmdb 范围： 与 Pigsty 既有 CMDB 交换声明，而不是再设计一个配置数据库。 决策 PIG 必须复用 Pigsty 已经提供的 CMDB。它的职责是有边界的适配：校验静态 Inventory， 将声明装载到既有表中，导出既有投影，检查一致性，并安全切换 Ansible 的静态与动态数据源。 PIG 不拥有第二套 schema、迁 …

决策日期： 2026-07-18 状态： 已实现并随 pig v1.6.0 发布。 下述验收修订已实现（Implemented），纳入 v1.10.0 候选版本，尚未发布。 当前参考： pig inventory 范围： 静态 Pigsty Inventory 的查看、局部编辑、校验、比较与安全写入。 决策 PIG 同时把 pigsty.yml 视为配置声明和人工维护的源文档。语义解析器负责判断 Inventory 的含义， 原始字节则决定它的书写方式。局部编辑只替换指定的源范围，并在原子写入 …

决策日期： 2026-07-02 状态： pg、pb、pt、pitr 已于 v1.5.0 交付；2026-08-29 的 do 与 build proxy 修订已随 v1.8.1 发布。下述验收修订已实现（Implemented），面向 v1.10.0；源码证据见验证章节，尚未发布。 当前参考： pig pg、pig pb、pig pitr、pig do 与 pig build 范围： PIG 实现的运维命令；透明上游命令继续采用上游的确认与退出行为。 决策 操作便利性不能模糊操作含义。PIG …

决策日期： 2026-06-30 状态： 已实现；新命令继续采用此布局。 当前参考： pig 命令总览与源码仓库 范围： Go 源码归属与命令注册方式，而不是公开命令分类本身。 决策 cmd 包保持扁平。一个顶层命令对应一个顶层 Go 文件：pg.go、pb.go、pt.go、 pe.go、sty.go、do.go、repo.go 等。即使命令树很复杂，也继续留在这个入口文件中， 除非另有明确的布局决策。 文件可以很长，但只应包含 Cobra 关注点：名称、别名、注解、参数、实参校验、帮助、注 …

决策日期： 2026-03-21 状态： 2026-03-23 实现，随 pig v1.3.2 发布。 当前参考： pig pg tune 范围： 根据硬件、PostgreSQL 版本与工作负载类型生成初始配置。 决策 pig pg tune 计算 PostgreSQL 核心参数，输出结果供用户审阅。命令探测 CPU、内存与磁盘容量， 接受用户指定的覆盖值，并按选定的工作负载类型计算。文本输出展示生成的参数；JSON 和 YAML 输出 包含输入条件与参数。用户审阅结果后，选择需要的参数，通过 …

决策日期： 2026-02-18；生产契约于 2026-08-14 定稿。 状态： 已实现并随 pig v1.8.0 发布。 当前参考： pig sty conf 范围： 从受信 Pigsty 模板生成一份经过校验的静态 Inventory，不是任意 YAML 转换器。 决策 pig sty conf 应当像一台小型编译器：解析一个安全模板，读取结构，应用一组有边界的结构化变更， 校验完整候选文件，并且只在所有必要阶段成功后原子提交输出。 命令不调用旧 configure 脚本，也不回退到原始 …

决策日期： 2026-02-12 状态： 随 pig v1.1.0 发布，之后随命令层演进调整。下述验收修订已实现（Implemented），纳入 v1.10.0 候选版本，尚未发布。 当前参考： pig 命令总览 范围： PIG 命令的自动化接口，以及外部工具的原生透传接口。 决策 PIG 为终端用户提供文本，为自动化提供结构化结果。产生稳定数据的命令提供 JSON 或 YAML 与状态码， 支持计划的工作流还提供执行计划。pig pt 等透明透传命令保留外部工具的输出、提示与退出码。 背景 …