配置定制

使用声明式的配置文件描述你需要的基础设施与集群

每个 Pigsty 部署都有一个对应的配置清单。它可以存储在 YAML 格式的本地配置文件中，或从 CMDB 或任何 Ansible 兼容格式动态生成。 Pigsty 默认使用一个单一的 YAML 配置文件，即 pigsty.yml，位于 Pigsty 主目录中。

configure 脚本将根据您的环境和输入生成具有良好默认值的 pigsty.yml 文件脚手架，但它是 可选的：您始终可以直接编辑 pigsty.yml 文件，如 配置教程 所示。

配置结构

清单由两部分组成：全局变量 和多个组。您可以在 all.children 中定义新集群。并使用全局变量描述基础设施：all.vars。它看起来像这样：

all:                  # 顶级对象：all
  vars: {...}         # 全局参数
  children:           # 组定义
    infra:            # 组定义：'infra'
      hosts: {...}        # 组成员：'infra'
      vars:  {...}        # 组参数：'infra'
    etcd:    {...}    # 组定义：'etcd'
    pg-meta: {...}    # 组定义：'pg-meta'
    pg-test: {...}    # 组定义：'pg-test'
    redis-test: {...} # 组定义：'redis-test'
    # ...

在 conf/ 目录下有大量示例，在 configure 期间也可以用作 配置模板。

集群定义

每个 Ansible 组可能代表一个集群，可以是节点集群、PostgreSQL 集群、Redis 集群、Etcd 集群或 MinIO 集群等…

集群定义由两部分组成：hosts 和 vars。您可以在 <cls>.hosts 中定义集群成员，并在 <cls>.vars 中使用参数描述集群。这是一个 3 节点 HA PostgreSQL 集群的示例：

all:
  children:    # 所有组
    pg-test:   # 组名
      hosts:   # 组主机（集群成员）
        10.10.10.11: { pg_seq: 1, pg_role: primary } # 主机 1
        10.10.10.12: { pg_seq: 2, pg_role: replica } # 主机 2
        10.10.10.13: { pg_seq: 3, pg_role: offline } # 主机 3
      vars:    # 组变量（集群参数）
        pg_cluster: pg-test

集群级别的 vars 将覆盖全局变量，主机级别的 vars 将覆盖集群变量和全局变量。

参数优先级

参数是定义部署中所有实体的键值对。键是字符串名称，值可以是五种类型之一：布尔值、字符串、数字、数组或对象。

参数可以在不同级别设置，具有以下优先级：

级别	位置	描述	优先级
CLI 参数	命令行	通过 `-e` CLI 参数	最高 (5)
主机变量	`<group>.hosts.<host>`	特定于单个主机的参数	高 (4)
组变量	`<group>.vars`	组/集群中主机共享的参数	中等 (3)
全局变量	`all.vars`	所有主机共享的参数	低 (2)
默认值	`<roles>/default/main.yml`	角色实现默认值	最低 (1)

以下是关于参数优先级的一些示例：

使用 Playbook CLI 参数 -e pg_clean=true 强制删除现有数据库
使用主机变量上的实例级别参数 pg_role 覆盖 pg 实例角色
使用组变量上的集群级别参数 pg_cluster 覆盖 pg 集群名称。
使用全局变量上的全局参数 node_ntp_servers 指定全局 NTP 服务器
如果没有设置 pg_version，Pigsty 将使用角色实现的默认值（默认为 17）

身份参数

除了强制性的 身份参数 外，每个参数都有一个适当的默认值；身份参数用作标识符，必须明确设置。例如上述片段中的 pg_cluster、pg_role 和 pg_seq。

不同模块的身份参数：

模块	身份参数
PGSQL	`pg_cluster`, `pg_seq`, `pg_role`
NODE	`nodename`, `node_cluster`
ETCD	`etcd_cluster`, `etcd_seq`
MINIO	`minio_cluster`, `minio_seq`
REDIS	`redis_cluster`, `redis_node`, `redis_instances`
INFRA	`infra_seq`

教程

以下是一个定义单节点 PostgreSQL 集群的完整配置示例：

all:
  children:

    # 定义一个单节点 PostgreSQL 集群
    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
      vars:
        pg_cluster: pg-meta

        # 定义业务数据库
        pg_databases:
          - name: meta
            baseline: cmdb.sql
            comment: "pigsty meta database"
            schemas: [pigsty]
            extensions: [ postgis, vector ]

        # 定义业务用户
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }

    # 基础设施组
    infra:
      hosts:
        10.10.10.10: { infra_seq: 1 }
      vars:
        repo_enabled: false   # 单节点模式禁用本地仓库

    # ETCD 组
    etcd:
      hosts:
        10.10.10.10: { etcd_seq: 1 }
      vars:
        etcd_cluster: etcd

  # 全局变量
  vars:
    version: v4.0.0                   # pigsty 版本字符串
    admin_ip: 10.10.10.10             # 管理节点 IP 地址
    region: china                     # 上游镜像区域

    # 密码配置（请务必修改！）
    grafana_admin_password: pigsty
    pg_admin_password: DBUser.DBA
    pg_monitor_password: DBUser.Monitor
    pg_replication_password: DBUser.Replicator
    patroni_password: Patroni.API
    haproxy_admin_password: pigsty

    # PostgreSQL 配置
    pg_version: 17                    # PostgreSQL 大版本
    pg_conf: oltp.yml                 # 调优模板

配置模板

Pigsty 提供了丰富的 配置模板，涵盖各种使用场景：

模板	说明
`meta`	单节点默认配置（默认）
`rich`	下载安装所有扩展
`slim`	精简安装，仅 PG + ETCD
`ha/full`	4 节点沙箱环境
`ha/simu`	42 节点仿真环境
`app/supa`	自托管 Supabase
`ivory`	IvorySQL Oracle 兼容
`mssql`	Babelfish MSSQL 兼容

使用 configure 脚本选择模板：

./configure -c rich          # 使用 rich 模板
./configure -c ha/full       # 使用 4 节点沙箱模板
./configure -c app/supa      # 使用 Supabase 模板

切换配置源

要使用不同的配置模板，您可以将模板的内容复制到 Pigsty 源码目录的 pigsty.yml 文件中，并按需进行相应调整。

您也可以在执行 Ansible 剧本时，通过 -i 命令行参数，显式指定使用的配置文件，例如：

./node.yml -i files/pigsty/rpmbuild.yml    # 使用 rpmbuild 配置文件，而不是默认的 pigsty.yml

如果您希望修改默认的配置文件名称与位置，您也可以修改源码根目录下的 ansible.cfg 的 inventory 参数，将其指向您的配置文件路径。

Pigsty 允许您使用数据库（CMDB）作为动态配置源，而不是使用静态配置文件。 Pigsty 提供了三个便利脚本：

脚本	功能
`bin/inventory_load`	将 `pigsty.yml` 配置文件的内容加载到本机 PostgreSQL 数据库中
`bin/inventory_cmdb`	切换配置源为本地 PostgreSQL 数据库
`bin/inventory_conf`	切换配置源为本地静态配置文件 `pigsty.yml`

参数参考

Pigsty 有 290+ 个参数，分为以下 32 个参数组，详情请参考各模块参数文档：

模块	参数组	描述	数量
`INFRA`	`META`	Pigsty 元数据	4
`INFRA`	`CA`	自签名公私钥基础设施 CA	3
`INFRA`	`INFRA_ID`	基础设施门户，Nginx 域名	2
`INFRA`	`REPO`	本地软件仓库	9
`INFRA`	`INFRA_PACKAGE`	基础设施软件包	2
`INFRA`	`NGINX`	Nginx 网络服务器	7
`INFRA`	`DNS`	DNSMASQ 域名服务器	3
`INFRA`	`PROMETHEUS`	Prometheus 时序数据库全家桶	18
`INFRA`	`GRAFANA`	Grafana 可观测性全家桶	6
`INFRA`	`LOKI`	Loki 日志服务	4
`NODE`	`NODE_ID`	节点身份参数	5
`NODE`	`NODE_DNS`	节点域名 & DNS 解析	6
`NODE`	`NODE_PACKAGE`	节点仓库源 & 安装软件包	5
`NODE`	`NODE_TUNE`	节点调优与内核特性开关	10
`NODE`	`NODE_ADMIN`	管理员用户与 SSH 凭证管理	7
`NODE`	`NODE_TIME`	时区，NTP 服务与定时任务	5
`NODE`	`NODE_VIP`	可选的主机节点集群 L2 VIP	8
`NODE`	`HAPROXY`	使用 HAProxy 对外暴露服务	10
`NODE`	`NODE_EXPORTER`	主机节点监控与注册	3
`NODE`	`PROMTAIL`	Promtail 日志收集组件	4
`DOCKER`	`DOCKER`	Docker 容器服务（可选）	4
`ETCD`	`ETCD`	Etcd DCS 集群	10
`MINIO`	`MINIO`	MinIO S3 对象存储	15
`REDIS`	`REDIS`	Redis 缓存	20
`PGSQL`	`PG_ID`	PG 身份参数	11
`PGSQL`	`PG_BUSINESS`	PG 业务对象定义	12
`PGSQL`	`PG_INSTALL`	安装 PG 软件包 & 扩展	10
`PGSQL`	`PG_BOOTSTRAP`	使用 Patroni 初始化 HA PG 集群	39
`PGSQL`	`PG_PROVISION`	创建 PG 数据库内对象	9
`PGSQL`	`PG_BACKUP`	使用 pgBackRest 设置备份仓库	5
`PGSQL`	`PG_SERVICE`	对外暴露服务，绑定 VIP，DNS	9
`PGSQL`	`PG_EXPORTER`	PG 监控，服务注册	15

意见反馈

这个页面对您有帮助吗？

感谢反馈！请告诉我们如何改进。

抱歉给您带来不便。请告诉我们如何改进。

最后修改 2025-12-31: routine doc polish (6193687)