参数列表

Pigsty 提供了约 280+ 配置参数，用于描述整个环境与各个模块的方方面面。
Module:
Categories:

Pigsty 提供了 280+ 参数，用于描述数据库集群与整个环境的方方面面。

序号 参数 模块 参数组 类型 层次 中文说明
101 version INFRA META string G pigsty 版本字符串
102 admin_ip INFRA META ip G 管理节点 IP 地址
103 region INFRA META enum G 上游镜像区域：default,china,europe
104 proxy_env INFRA META dict G 下载包时使用的全局代理环境变量
105 ca_method INFRA CA enum G CA处理方式：create,recreate,copy，默认为没有则创建
106 ca_cn INFRA CA string G CA CN名称，固定为 pigsty-ca
107 cert_validity INFRA CA interval G 证书有效期，默认为 20 年
108 infra_seq INFRA INFRA_ID int I 基础设施节号，必选身份参数
109 infra_portal INFRA INFRA_ID dict G 通过Nginx门户暴露的基础设施服务列表
110 repo_enabled INFRA REPO bool G/I 在此基础设施节点上创建软件仓库？
111 repo_home INFRA REPO path G 软件仓库主目录，默认为/www
112 repo_name INFRA REPO string G 软件仓库名称，默认为 pigsty
113 repo_endpoint INFRA REPO url G 仓库的访问点：域名或 ip:port 格式
114 repo_remove INFRA REPO bool G/A 构建本地仓库时是否移除现有上游仓库源定义文件？
115 repo_modules INFRA REPO string G/A 启用的上游仓库模块列表，用逗号分隔
116 repo_upstream INFRA REPO upstream[] G 上游仓库源定义：从哪里下载上游包？
117 repo_packages INFRA REPO string[] G 从上游仓库下载哪些软件包？
118 repo_extra_packages INFRA REPO string[] G/C/I 从上游仓库下载哪些额外的软件包？
119 repo_url_packages INFRA REPO string[] G 使用URL下载的额外软件包列表
120 infra_packages INFRA INFRA_PACKAGE string[] G 在基础设施节点上要安装的软件包
121 infra_packages_pip INFRA INFRA_PACKAGE string G 在基础设施节点上使用 pip 安装的包
130 nginx_enabled INFRA NGINX bool G/I 在此基础设施节点上启用 nginx？
131 nginx_exporter_enabled INFRA NGINX bool G/I 在此基础设施节点上启用 nginx_exporter？
132 nginx_sslmode INFRA NGINX enum G nginx SSL模式？disable,enable,enforce
133 nginx_home INFRA NGINX path G nginx 内容目录，默认为 /www，通常和仓库目录一致
134 nginx_port INFRA NGINX port G nginx 监听端口，默认为 80
135 nginx_ssl_port INFRA NGINX port G nginx SSL监听端口，默认为 443
136 nginx_navbar INFRA NGINX index[] G nginx 首页导航链接列表
140 dns_enabled INFRA DNS bool G/I 在此基础设施节点上设置dnsmasq？
141 dns_port INFRA DNS port G DNS 服务器监听端口，默认为 53
142 dns_records INFRA DNS string[] G 由 dnsmasq 解析的动态 DNS 记录
150 prometheus_enabled INFRA PROMETHEUS bool G/I 在此基础设施节点上启用 prometheus？
151 prometheus_clean INFRA PROMETHEUS bool G/A 初始化Prometheus的时候清除现有数据？
152 prometheus_data INFRA PROMETHEUS path G Prometheus 数据目录，默认为 /data/prometheus
153 prometheus_sd_dir INFRA PROMETHEUS path G Prometheus 服务发现目标文件目录
154 prometheus_sd_interval INFRA PROMETHEUS interval G Prometheus 目标刷新间隔，默认为 5s
155 prometheus_scrape_interval INFRA PROMETHEUS interval G Prometheus 抓取 & 评估间隔，默认为 10s
156 prometheus_scrape_timeout INFRA PROMETHEUS interval G Prometheus 全局抓取超时，默认为 8s
157 prometheus_options INFRA PROMETHEUS arg G Prometheus 额外的命令行参数选项
158 pushgateway_enabled INFRA PROMETHEUS bool G/I 在此基础设施节点上设置 pushgateway？
159 pushgateway_options INFRA PROMETHEUS arg G pushgateway 额外的命令行参数选项
160 blackbox_enabled INFRA PROMETHEUS bool G/I 在此基础设施节点上设置 blackbox_exporter？
161 blackbox_options INFRA PROMETHEUS arg G blackbox_exporter 额外的命令行参数选项
162 alertmanager_enabled INFRA PROMETHEUS bool G/I 在此基础设施节点上设置 alertmanager？
163 alertmanager_options INFRA PROMETHEUS arg G alertmanager 额外的命令行参数选项
164 exporter_metrics_path INFRA PROMETHEUS path G exporter 指标路径，默认为 /metrics
165 exporter_install INFRA PROMETHEUS enum G 如何安装 exporter？none,yum,binary
166 exporter_repo_url INFRA PROMETHEUS url G 通过 yum 安装exporter时使用的yum仓库文件地址
170 grafana_enabled INFRA GRAFANA bool G/I 在此基础设施节点上启用 Grafana？
171 grafana_clean INFRA GRAFANA bool G/A 初始化Grafana期间清除数据？
172 grafana_admin_username INFRA GRAFANA username G Grafana 管理员用户名，默认为 admin
173 grafana_admin_password INFRA GRAFANA password G Grafana 管理员密码，默认为 pigsty
174 grafana_plugin_cache INFRA GRAFANA path G Grafana 插件缓存 tarball 的路径
175 grafana_plugin_list INFRA GRAFANA string[] G 使用 grafana-cli 下载的 Grafana 插件
176 loki_enabled INFRA LOKI bool G/I 在此基础设施节点上启用 loki？
177 loki_clean INFRA LOKI bool G/A 是否删除现有的 loki 数据？
178 loki_data INFRA LOKI path G loki 数据目录，默认为 /data/loki
179 loki_retention INFRA LOKI interval G loki 日志保留期，默认为 15d
201 nodename NODE NODE_ID string I node 实例标识，如缺失则使用主机名，可选
202 node_cluster NODE NODE_ID string C node 集群标识，如缺失则使用默认值’nodes’，可选
203 nodename_overwrite NODE NODE_ID bool C 用 nodename 覆盖节点的主机名吗？
204 nodename_exchange NODE NODE_ID bool C 在剧本主机之间交换 nodename 吗？
205 node_id_from_pg NODE NODE_ID bool C 如果可行，是否借用 postgres 身份作为节点身份？
210 node_write_etc_hosts NODE NODE_DNS bool G/C/I 是否修改目标节点上的 /etc/hosts？
211 node_default_etc_hosts NODE NODE_DNS string[] G /etc/hosts 中的静态 DNS 记录
212 node_etc_hosts NODE NODE_DNS string[] C /etc/hosts 中的额外静态 DNS 记录
213 node_dns_method NODE NODE_DNS enum C 如何处理现有DNS服务器：add,none,overwrite
214 node_dns_servers NODE NODE_DNS string[] C /etc/resolv.conf 中的动态域名服务器列表
215 node_dns_options NODE NODE_DNS string[] C /etc/resolv.conf 中的DNS解析选项
220 node_repo_modules NODE NODE_PACKAGE enum C 在节点上启用哪些软件源模块？默认为 local 使用本地源
221 node_repo_remove NODE NODE_PACKAGE bool C 配置节点软件仓库时，删除节点上现有的仓库吗？
223 node_packages NODE NODE_PACKAGE string[] C 要在当前节点上安装的软件包列表
224 node_default_packages NODE NODE_PACKAGE string[] G 默认在所有节点上安装的软件包列表
230 node_disable_firewall NODE NODE_TUNE bool C 禁用节点防火墙？默认为 true
231 node_disable_selinux NODE NODE_TUNE bool C 禁用节点 selinux？默认为 true
232 node_disable_numa NODE NODE_TUNE bool C 禁用节点 numa，禁用需要重启
233 node_disable_swap NODE NODE_TUNE bool C 禁用节点 Swap，谨慎使用
234 node_static_network NODE NODE_TUNE bool C 重启后保留 DNS 解析器设置，即静态网络，默认启用
235 node_disk_prefetch NODE NODE_TUNE bool C 在 HDD 上配置磁盘预取以提高性能
236 node_kernel_modules NODE NODE_TUNE string[] C 在此节点上启用的内核模块列表
237 node_hugepage_count NODE NODE_TUNE int C 主机节点分配的 2MB 大页数量，优先级比比例更高
238 node_hugepage_ratio NODE NODE_TUNE float C 主机节点分配的内存大页占总内存比例，0 默认禁用
239 node_overcommit_ratio NODE NODE_TUNE float C 节点内存允许的 OverCommit 超额比率 (50-100)，0 默认禁用
240 node_tune NODE NODE_TUNE enum C 节点调优配置文件：无，oltp,olap,crit,tiny
241 node_sysctl_params NODE NODE_TUNE dict C 额外的 sysctl 配置参数，k:v 格式
250 node_data NODE NODE_ADMIN path C 节点主数据目录，默认为 /data
251 node_admin_enabled NODE NODE_ADMIN bool C 在目标节点上创建管理员用户吗？
252 node_admin_uid NODE NODE_ADMIN int C 节点管理员用户的 uid 和 gid
253 node_admin_username NODE NODE_ADMIN username C 节点管理员用户的名称，默认为 dba
254 node_admin_ssh_exchange NODE NODE_ADMIN bool C 是否在节点集群之间交换管理员 ssh 密钥
255 node_admin_pk_current NODE NODE_ADMIN bool C 将当前用户的 ssh 公钥添加到管理员的 authorized_keys 中吗？
256 node_admin_pk_list NODE NODE_ADMIN string[] C 要添加到管理员用户的 ssh 公钥
260 node_timezone NODE NODE_TIME string C 设置主机节点时区，空字符串跳过
261 node_ntp_enabled NODE NODE_TIME bool C 启用 chronyd 时间同步服务吗？
262 node_ntp_servers NODE NODE_TIME string[] C /etc/chrony.conf 中的 ntp 服务器列表
263 node_crontab_overwrite NODE NODE_TIME bool C 写入 /etc/crontab 时，追加写入还是全部覆盖？
264 node_crontab NODE NODE_TIME string[] C 在 /etc/crontab 中的 crontab 条目
270 vip_enabled NODE NODE_VIP bool C 在此节点集群上启用 L2 vip 吗？
271 vip_address NODE NODE_VIP ip C 节点 vip 地址的 ipv4 格式，启用 vip 时为必要参数
272 vip_vrid NODE NODE_VIP int C 所需的整数，1-254，在同一 VLAN 中应唯一
273 vip_role NODE NODE_VIP enum I 可选，master/backup，默认为 backup，用作初始角色
274 vip_preempt NODE NODE_VIP bool C/I 可选，true/false，默认为 false，启用 vip 抢占
275 vip_interface NODE NODE_VIP string C/I 节点 vip 网络接口监听，默认为 eth0
276 vip_dns_suffix NODE NODE_VIP string C 节点 vip DNS 名称后缀，默认为空字符串
277 vip_exporter_port NODE NODE_VIP port C keepalived exporter 监听端口，默认为 9650
280 haproxy_enabled NODE HAPROXY bool C 在此节点上启用 haproxy 吗？
281 haproxy_clean NODE HAPROXY bool G/C/A 清除所有现有的 haproxy 配置吗？
282 haproxy_reload NODE HAPROXY bool A 配置后重新加载 haproxy 吗？
283 haproxy_auth_enabled NODE HAPROXY bool G 启用 haproxy 管理页面的身份验证？
284 haproxy_admin_username NODE HAPROXY username G haproxy 管理用户名，默认为 admin
285 haproxy_admin_password NODE HAPROXY password G haproxy 管理密码，默认为 pigsty
286 haproxy_exporter_port NODE HAPROXY port C haproxy exporter 的端口，默认为 9101
287 haproxy_client_timeout NODE HAPROXY interval C haproxy 客户端连接超时，默认为 24h
288 haproxy_server_timeout NODE HAPROXY interval C haproxy 服务器端连接超时，默认为 24h
289 haproxy_services NODE HAPROXY service[] C 要在节点上对外暴露的 haproxy 服务列表
290 node_exporter_enabled NODE NODE_EXPORTER bool C 在此节点上配置 node_exporter 吗？
291 node_exporter_port NODE NODE_EXPORTER port C node exporter 监听端口，默认为 9100
292 node_exporter_options NODE NODE_EXPORTER arg C node_exporter 的额外服务器选项
293 promtail_enabled NODE PROMTAIL bool C 启用 promtail 日志收集器吗？
294 promtail_clean NODE PROMTAIL bool G/A 初始化期间清除现有的 promtail 状态文件吗？
295 promtail_port NODE PROMTAIL port C promtail 监听端口，默认为 9080
296 promtail_positions NODE PROMTAIL path C promtail 位置状态文件路径
401 docker_enabled DOCKER DOCKER bool G/C/I 在当前节点上启用 Docker？默认不启用
402 docker_cgroups_driver DOCKER DOCKER enum G/C/I Docker CGroup 文件系统驱动：cgroupfs,systemd
403 docker_registry_mirrors DOCKER DOCKER string[] G/C/I Docker 仓库镜像列表
404 docker_image DOCKER DOCKER string[] G/C/I Docker 待拉取的镜像列表，默认为空列表
405 docker_image_cache DOCKER DOCKER path[] G/C/I Docker 待导入的镜像压缩包路径，默认为 /tmp/docker/*.tgz
501 etcd_seq ETCD ETCD int I etcd 实例标识符，必填
502 etcd_cluster ETCD ETCD string C etcd 集群名，默认固定为 etcd
503 etcd_safeguard ETCD ETCD bool G/C/A etcd 防误删保险，阻止清除正在运行的 etcd 实例？
504 etcd_clean ETCD ETCD bool G/C/A etcd 清除指令：在初始化时清除现有的 etcd 实例？
505 etcd_data ETCD ETCD path C etcd 数据目录，默认为 /data/etcd
506 etcd_port ETCD ETCD port C etcd 客户端端口，默认为 2379
507 etcd_peer_port ETCD ETCD port C etcd 同伴端口，默认为 2380
508 etcd_init ETCD ETCD enum C etcd 初始集群状态，新建或已存在
509 etcd_election_timeout ETCD ETCD int C etcd 选举超时，默认为 1000ms
510 etcd_heartbeat_interval ETCD ETCD int C etcd 心跳间隔，默认为 100ms
601 minio_seq MINIO MINIO int I minio 实例标识符，必填
602 minio_cluster MINIO MINIO string C minio 集群名称，默认为 minio
603 minio_clean MINIO MINIO bool G/C/A 初始化时清除 minio？默认为 false
604 minio_user MINIO MINIO username C minio 操作系统用户，默认为 minio
605 minio_node MINIO MINIO string C minio 节点名模式
606 minio_data MINIO MINIO path C minio 数据目录，使用 {x...y} 指定多个磁盘
607 minio_domain MINIO MINIO string G minio 外部域名，默认为 sss.pigsty
608 minio_port MINIO MINIO port C minio 服务端口，默认为 9000
609 minio_admin_port MINIO MINIO port C minio 控制台端口，默认为 9001
610 minio_access_key MINIO MINIO username C 根访问密钥，默认为 minioadmin
611 minio_secret_key MINIO MINIO password C 根密钥，默认为 minioadmin
612 minio_extra_vars MINIO MINIO string C minio 服务器的额外环境变量
613 minio_alias MINIO MINIO string G minio 部署的客户端别名
614 minio_buckets MINIO MINIO bucket[] C 待创建的 minio 存储桶列表
615 minio_users MINIO MINIO user[] C 待创建的 minio 用户列表
701 redis_cluster REDIS REDIS string C Redis数据库集群名称，必选身份参数
702 redis_instances REDIS REDIS dict I Redis节点上的实例定义
703 redis_node REDIS REDIS int I Redis节点编号，正整数，集群内唯一，必选身份参数
710 redis_fs_main REDIS REDIS path C Redis主数据目录，默认为 /data
711 redis_exporter_enabled REDIS REDIS bool C Redis Exporter 是否启用？
712 redis_exporter_port REDIS REDIS port C Redis Exporter监听端口
713 redis_exporter_options REDIS REDIS string C/I Redis Exporter命令参数
720 redis_safeguard REDIS REDIS bool G/C/A 禁止抹除现存的Redis
721 redis_clean REDIS REDIS bool G/C/A 初始化Redis是否抹除现存实例
722 redis_rmdata REDIS REDIS bool G/C/A 移除Redis实例时是否一并移除数据？
723 redis_mode REDIS REDIS enum C Redis集群模式：sentinel，cluster，standalone
724 redis_conf REDIS REDIS string C Redis配置文件模板，sentinel 除外
725 redis_bind_address REDIS REDIS ip C Redis监听地址，默认留空则会绑定主机IP
726 redis_max_memory REDIS REDIS size C/I Redis可用的最大内存
727 redis_mem_policy REDIS REDIS enum C Redis内存逐出策略
728 redis_password REDIS REDIS password C Redis密码，默认留空则禁用密码
729 redis_rdb_save REDIS REDIS string[] C Redis RDB 保存指令，字符串列表，空数组则禁用RDB
730 redis_aof_enabled REDIS REDIS bool C Redis AOF 是否启用？
731 redis_rename_commands REDIS REDIS dict C Redis危险命令重命名列表
732 redis_cluster_replicas REDIS REDIS int C Redis原生集群中每个主库配几个从库？
733 redis_sentinel_monitor REDIS REDIS master[] C Redis哨兵监控的主库列表，只在哨兵集群上使用
801 pg_mode PGSQL PG_ID enum C pgsql 集群模式: pgsql,citus,mssql,polar,ivory,oracle,gpsql
802 pg_cluster PGSQL PG_ID string C pgsql 集群名称, 必选身份参数
803 pg_seq PGSQL PG_ID int I pgsql 实例号, 必选身份参数
804 pg_role PGSQL PG_ID enum I pgsql 实例角色, 必选身份参数, 可为 primary，replica，offline
805 pg_instances PGSQL PG_ID dict I 在一个节点上定义多个 pg 实例，使用 {port:ins_vars} 格式
806 pg_upstream PGSQL PG_ID ip I 级联从库或备份集群或的复制上游节点IP地址
807 pg_shard PGSQL PG_ID string C pgsql 分片名，对 citus 与 gpsql 等水平分片集群为必选身份参数
808 pg_group PGSQL PG_ID int C pgsql 分片号，正整数，对 citus 与 gpsql 等水平分片集群为必选身份参数
809 gp_role PGSQL PG_ID enum C 这个集群的 greenplum 角色，可以是 master 或 segment
810 pg_exporters PGSQL PG_ID dict C 在该节点上设置额外的 pg_exporters 用于监控远程 postgres 实例
811 pg_offline_query PGSQL PG_ID bool I 设置为 true 将此只读实例标记为特殊的离线从库，承载 Offline 服务，允许离线查询
820 pg_users PGSQL PG_BUSINESS user[] C postgres 业务用户
821 pg_databases PGSQL PG_BUSINESS database[] C postgres 业务数据库
822 pg_services PGSQL PG_BUSINESS service[] C postgres 业务服务
823 pg_hba_rules PGSQL PG_BUSINESS hba[] C postgres 的业务 hba 规则
824 pgb_hba_rules PGSQL PG_BUSINESS hba[] C pgbouncer 的业务 hba 规则
831 pg_replication_username PGSQL PG_BUSINESS username G postgres 复制用户名，默认为 replicator
832 pg_replication_password PGSQL PG_BUSINESS password G postgres 复制密码，默认为 DBUser.Replicator
833 pg_admin_username PGSQL PG_BUSINESS username G postgres 管理员用户名，默认为 dbuser_dba
834 pg_admin_password PGSQL PG_BUSINESS password G postgres 管理员明文密码，默认为 DBUser.DBA
835 pg_monitor_username PGSQL PG_BUSINESS username G postgres 监控用户名，默认为 dbuser_monitor
836 pg_monitor_password PGSQL PG_BUSINESS password G postgres 监控密码，默认为 DBUser.Monitor
837 pg_dbsu_password PGSQL PG_BUSINESS password G/C dbsu 密码，默认为空字符串意味着不设置 dbsu 密码，最好不要设置。
840 pg_dbsu PGSQL PG_INSTALL username C 操作系统 dbsu 名称，默认为 postgres，最好不要更改
841 pg_dbsu_uid PGSQL PG_INSTALL int C 操作系统 dbsu uid 和 gid，对于默认的 postgres 用户和组为 26
842 pg_dbsu_sudo PGSQL PG_INSTALL enum C dbsu sudo 权限, none,limit,all,nopass，默认为 limit，有限sudo权限
843 pg_dbsu_home PGSQL PG_INSTALL path C postgresql 主目录，默认为 /var/lib/pgsql
844 pg_dbsu_ssh_exchange PGSQL PG_INSTALL bool C 在 pgsql 集群之间交换 postgres dbsu ssh 密钥
845 pg_version PGSQL PG_INSTALL enum C 要安装的 postgres 主版本，默认为 16
846 pg_bin_dir PGSQL PG_INSTALL path C postgres 二进制目录，默认为 /usr/pgsql/bin
847 pg_log_dir PGSQL PG_INSTALL path C postgres 日志目录，默认为 /pg/log/postgres
848 pg_packages PGSQL PG_INSTALL string[] C 要安装的 pg 包，${pg_version} 将被替换为实际主版本号
849 pg_extensions PGSQL PG_INSTALL string[] C 要安装的 pg 扩展，${pg_version} 将被替换为实际主版本号
850 pg_safeguard PGSQL PG_BOOTSTRAP bool G/C/A 防误删保险，禁止清除正在运行的 postgres 实例？默认为 false
851 pg_clean PGSQL PG_BOOTSTRAP bool G/C/A 在 pgsql 初始化期间清除现有的 postgres？默认为 true
852 pg_data PGSQL PG_BOOTSTRAP path C postgres 数据目录，默认为 /pg/data
853 pg_fs_main PGSQL PG_BOOTSTRAP path C postgres 主数据的挂载点/路径，默认为 /data
854 pg_fs_bkup PGSQL PG_BOOTSTRAP path C pg 备份数据的挂载点/路径，默认为 /data/backup
855 pg_storage_type PGSQL PG_BOOTSTRAP enum C pg 主数据的存储类型，SSD、HDD，默认为 SSD，影响自动优化的参数。
856 pg_dummy_filesize PGSQL PG_BOOTSTRAP size C /pg/dummy 的大小，默认保留 64MB 磁盘空间用于紧急抢修
857 pg_listen PGSQL PG_BOOTSTRAP ip(s) C/I postgres/pgbouncer 的监听地址，用逗号分隔的IP列表，默认为 0.0.0.0
858 pg_port PGSQL PG_BOOTSTRAP port C postgres 监听端口，默认为 5432
859 pg_localhost PGSQL PG_BOOTSTRAP path C postgres 的 Unix 套接字目录，用于本地连接
860 pg_namespace PGSQL PG_BOOTSTRAP path C 在 etcd 中的顶级键命名空间，被 patroni & vip 用于高可用管理
861 patroni_enabled PGSQL PG_BOOTSTRAP bool C 如果禁用，初始化期间不会创建 postgres 集群
862 patroni_mode PGSQL PG_BOOTSTRAP enum C patroni 工作模式：default,pause,remove
863 patroni_port PGSQL PG_BOOTSTRAP port C patroni 监听端口，默认为 8008
864 patroni_log_dir PGSQL PG_BOOTSTRAP path C patroni 日志目录，默认为 /pg/log/patroni
865 patroni_ssl_enabled PGSQL PG_BOOTSTRAP bool G 使用 SSL 保护 patroni RestAPI 通信？
866 patroni_watchdog_mode PGSQL PG_BOOTSTRAP enum C patroni 看门狗模式：automatic,required,off，默认为 off
867 patroni_username PGSQL PG_BOOTSTRAP username C patroni restapi 用户名，默认为 postgres
868 patroni_password PGSQL PG_BOOTSTRAP password C patroni restapi 密码，默认为 Patroni.API
869 pg_primary_db PGSQL PG_BOOTSTRAP string C 指定集群中首要使用的数据库名，Citus等模式会用到，默认为 postgres
870 pg_parameters PGSQL PG_BOOTSTRAP dict C 覆盖 postgresql.auto.conf 中的 PostgreSQL 参数
871 pg_files PGSQL PG_BOOTSTRAP path[] C 拷贝至PGDATA目录中的额外文件列表 (例如许可证文件)
872 pg_conf PGSQL PG_BOOTSTRAP enum C 配置模板：oltp,olap,crit,tiny，默认为 oltp.yml
873 pg_max_conn PGSQL PG_BOOTSTRAP int C postgres 最大连接数，auto 将使用推荐值
874 pg_shared_buffer_ratio PGSQL PG_BOOTSTRAP float C postgres 共享缓冲区内存比率，默认为 0.25，范围 0.1~0.4
875 pg_rto PGSQL PG_BOOTSTRAP int C 恢复时间目标（秒），默认为 30s
876 pg_rpo PGSQL PG_BOOTSTRAP int C 恢复点目标（字节），默认为 1MiB
877 pg_libs PGSQL PG_BOOTSTRAP string C 预加载的库，默认为 timescaledb,pg_stat_statements,auto_explain
878 pg_delay PGSQL PG_BOOTSTRAP interval I 备份集群主库的WAL重放应用延迟，用于制备延迟从库
879 pg_checksum PGSQL PG_BOOTSTRAP bool C 为 postgres 集群启用数据校验和？
880 pg_pwd_enc PGSQL PG_BOOTSTRAP enum C 密码加密算法：md5,scram-sha-256
881 pg_encoding PGSQL PG_BOOTSTRAP enum C 数据库集群编码，默认为 UTF8
882 pg_locale PGSQL PG_BOOTSTRAP enum C 数据库集群本地化设置，默认为 C
883 pg_lc_collate PGSQL PG_BOOTSTRAP enum C 数据库集群排序，默认为 C
884 pg_lc_ctype PGSQL PG_BOOTSTRAP enum C 数据库字符类型，默认为 en_US.UTF8
890 pgbouncer_enabled PGSQL PG_BOOTSTRAP bool C 如果禁用，则不会配置 pgbouncer 连接池
891 pgbouncer_port PGSQL PG_BOOTSTRAP port C pgbouncer 监听端口，默认为 6432
892 pgbouncer_log_dir PGSQL PG_BOOTSTRAP path C pgbouncer 日志目录，默认为 /pg/log/pgbouncer
893 pgbouncer_auth_query PGSQL PG_BOOTSTRAP bool C 使用 AuthQuery 来从 postgres 获取未列出的业务用户？
894 pgbouncer_poolmode PGSQL PG_BOOTSTRAP enum C 池化模式：transaction,session,statement，默认为 transaction
895 pgbouncer_sslmode PGSQL PG_BOOTSTRAP enum C pgbouncer 客户端 SSL 模式，默认为禁用
900 pg_provision PGSQL PG_PROVISION bool C 在引导后置备 postgres 集群内部的业务对象？
901 pg_init PGSQL PG_PROVISION string G/C 为集群模板提供初始化脚本，默认为 pg-init
902 pg_default_roles PGSQL PG_PROVISION role[] G/C postgres 集群中的默认预定义角色和系统用户
903 pg_default_privileges PGSQL PG_PROVISION string[] G/C 由管理员用户创建数据库内对象时的默认权限
904 pg_default_schemas PGSQL PG_PROVISION string[] G/C 要创建的默认模式列表
905 pg_default_extensions PGSQL PG_PROVISION extension[] G/C 要创建的默认扩展列表
906 pg_reload PGSQL PG_PROVISION bool A 更改HBA后，是否立即重载 postgres 配置
907 pg_default_hba_rules PGSQL PG_PROVISION hba[] G/C postgres 基于主机的认证规则，全局PG默认HBA
908 pgb_default_hba_rules PGSQL PG_PROVISION hba[] G/C pgbouncer 默认的基于主机的认证规则，全局PGB默认HBA
910 pgbackrest_enabled PGSQL PG_BACKUP bool C 在 pgsql 主机上启用 pgbackrest？
911 pgbackrest_clean PGSQL PG_BACKUP bool C 在初始化时删除以前的 pg 备份数据？
912 pgbackrest_log_dir PGSQL PG_BACKUP path C pgbackrest 日志目录，默认为 /pg/log/pgbackrest
913 pgbackrest_method PGSQL PG_BACKUP enum C pgbackrest 使用的仓库：local,minio,等…
914 pgbackrest_repo PGSQL PG_BACKUP dict G/C pgbackrest 仓库定义
921 pg_weight PGSQL PG_SERVICE int I 在服务中的相对负载均衡权重，默认为 100，范围 0-255
922 pg_service_provider PGSQL PG_SERVICE string G/C 专用的 haproxy 节点组名称，或默认空字符，使用本地节点上的 haproxy
923 pg_default_service_dest PGSQL PG_SERVICE enum G/C 如果 svc.dest=‘default’，默认服务指向哪里？postgres 或 pgbouncer，默认指向 pgbouncer
924 pg_default_services PGSQL PG_SERVICE service[] G/C postgres 默认服务定义列表，全局共用。
931 pg_vip_enabled PGSQL PG_SERVICE bool C 是否为 pgsql 主节点启用 L2 VIP？默认不启用
932 pg_vip_address PGSQL PG_SERVICE cidr4 C vip 地址的格式为 /，启用 vip 时为必选参数
933 pg_vip_interface PGSQL PG_SERVICE string C/I 监听的 vip 网络接口，默认为 eth0
934 pg_dns_suffix PGSQL PG_SERVICE string C pgsql dns 后缀，默认为空
935 pg_dns_target PGSQL PG_SERVICE enum C PG DNS 解析到哪里？auto、primary、vip、none 或者特定的 IP 地址
940 pg_exporter_enabled PGSQL PG_EXPORTER bool C 在 pgsql 主机上启用 pg_exporter 吗？
941 pg_exporter_config PGSQL PG_EXPORTER string C pg_exporter 配置文件/模板名称
942 pg_exporter_cache_ttls PGSQL PG_EXPORTER string C pg_exporter 收集器阶梯TTL配置，默认为4个由逗号分隔的秒数：‘1,10,60,300’
943 pg_exporter_port PGSQL PG_EXPORTER port C pg_exporter 监听端口，默认为 9630
944 pg_exporter_params PGSQL PG_EXPORTER string C pg_exporter dsn 中传入的额外 URL 参数
945 pg_exporter_url PGSQL PG_EXPORTER pgurl C 如果指定，则覆盖自动生成的 postgres DSN 连接串
946 pg_exporter_auto_discovery PGSQL PG_EXPORTER bool C 监控是否启用自动数据库发现？默认启用
947 pg_exporter_exclude_database PGSQL PG_EXPORTER string C 启用自动发现时，排除在外的数据库名称列表，用逗号分隔
948 pg_exporter_include_database PGSQL PG_EXPORTER string C 启用自动发现时，只监控这个列表中的数据库，名称用逗号分隔
949 pg_exporter_connect_timeout PGSQL PG_EXPORTER int C pg_exporter 连接超时，单位毫秒，默认为 200
950 pg_exporter_options PGSQL PG_EXPORTER arg C pg_exporter 的额外命令行参数选项
951 pgbouncer_exporter_enabled PGSQL PG_EXPORTER bool C 在 pgsql 主机上启用 pgbouncer_exporter 吗？
952 pgbouncer_exporter_port PGSQL PG_EXPORTER port C pgbouncer_exporter 监听端口，默认为 9631
953 pgbouncer_exporter_url PGSQL PG_EXPORTER pgurl C 如果指定，则覆盖自动生成的 pgbouncer dsn 连接串
954 pgbouncer_exporter_options PGSQL PG_EXPORTER arg C pgbouncer_exporter 的额外命令行参数选项

INFRA

关于基础设施组件的配置参数：本地软件源，Nginx，DNSMasq，Prometheus，Grafana，Loki，Alertmanager，Pushgateway，Blackbox_exporter 等…

META

这一小节指定了一套 Pigsty 部署的元数据：包括版本号，管理员节点 IP 地址，软件源镜像上游区域 和下载软件包时使用的 http(s) 代理。

version: v2.8.0                   # pigsty 版本号
admin_ip: 10.10.10.10             # 管理节点IP地址
region: default                   # 上游镜像区域：default,china,europe
proxy_env:                        # 全局HTTPS代理，用于下载、安装软件包。
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
  # http_proxy:  # set your proxy here: e.g http://user:pass@proxy.xxx.com
  # https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com
  # all_proxy:   # set your proxy here: e.g http://user:pass@proxy.xxx.com

version

参数名称： version， 类型： string， 层次：G

Pigsty 版本号字符串，默认值为当前版本：v3.0.4。

Pigsty 内部会使用版本号进行功能控制与内容渲染。

Pigsty使用语义化版本号，版本号字符串通常以字符 v 开头。

admin_ip

参数名称： admin_ip， 类型： ip， 层次：G

管理节点的 IP 地址，默认为占位符 IP 地址：10.10.10.10

由该参数指定的节点将被视为管理节点，通常指向安装 Pigsty 时的第一个节点，即中控节点。

默认值 10.10.10.10 是一个占位符，会在 configure 过程中被替换为实际的管理节点 IP 地址。

许多参数都会引用此参数，例如：

在这些参数中，字符串 ${admin_ip} 会被替换为 admin_ip 的真实取值。使用这种机制，您可以为不同的节点指定不同的中控管理节点。

region

参数名称： region， 类型： enum， 层次：G

上游镜像的区域，默认可选值为：upstream mirror region: default,china,europe，默认为： default

如果一个不同于 default 的区域被设置，且在 repo_upstream 中有对应的条目，将会使用该条目对应 baseurl 代替 default 中的 baseurl。

例如，如果您的区域被设置为 china，那么 Pigsty 会尝试使用中国地区的上游软件镜像站点以加速下载，如果某个上游软件仓库没有对应的中国地区镜像，那么会使用默认的上游镜像站点替代。 同时，在 repo_url_packages 中定义的 URL 地址，也会进行从 repo.pigsty.io 到 repo.pigsty.cc 的替换，以使用国内的镜像源。

proxy_env

参数名称： proxy_env， 类型： dict， 层次：G

下载包时使用的全局代理环境变量，默认值指定了 no_proxy，即不使用代理的地址列表：

proxy_env:
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.aliyuncs.com,mirrors.tuna.tsinghua.edu.cn,mirrors.zju.edu.cn"
  #http_proxy: 'http://username:password@proxy.address.com'
  #https_proxy: 'http://username:password@proxy.address.com'
  #all_proxy: 'http://username:password@proxy.address.com'

当您在中国大陆地区从互联网上游安装时，特定的软件包可能会被墙，您可以使用代理来解决这个问题。

请注意，如果使用了 Docker 模块，那么这里的代理服务器配置也会写入 Docker Daemon 配置文件中。

请注意，如果在 ./configure 过程中指定了 -x 参数，那么当前环境中的代理配置信息将会被自动填入到生成的 pigsty.yaml 文件中。

CA

Pigsty 使用的自签名 CA 证书，用于支持高级安全特性。

ca_method: create                 # CA处理方式：create,recreate,copy，默认为没有则创建
ca_cn: pigsty-ca                  # CA CN名称，固定为 pigsty-ca
cert_validity: 7300d              # 证书有效期，默认为 20 年

ca_method

参数名称： ca_method， 类型： enum， 层次：G

CA处理方式：create , recreate ,copy，默认为没有则创建

默认值为： create，即如果不存在则创建一个新的 CA 证书。

  • create：如果 files/pki/ca 中不存在现有的CA，则创建一个全新的 CA 公私钥对，否则就直接使用现有的 CA 公私钥对。
  • recreate：总是创建一个新的 CA 公私钥对，覆盖现有的 CA 公私钥对。注意，这是一个危险的操作。
  • copy：假设files/pki/ca 目录下已经有了一对CA公私钥对，并将 ca_method 设置为 copy，Pigsty 将会使用现有的 CA 公私钥对。如果不存在则会报错

如果您已经有了一对 CA 公私钥对，可以将其复制到 files/pki/ca 目录下，并将 ca_method 设置为 copy，Pigsty 将会使用现有的 CA 公私钥对，而不是新建一个。

请注意，务必保留并备份好一套部署新生成的 CA 私钥文件。

ca_cn

参数名称： ca_cn， 类型： string， 层次：G

CA CN名称，固定为 pigsty-ca，不建议修改。

你可以使用以下命令来查看节点上的 Pigsty CA 证书： openssl x509 -text -in /etc/pki/ca.crt

cert_validity

参数名称： cert_validity， 类型： interval， 层次：G

签发证书的有效期，默认为 20 年，对绝大多数场景都足够了。默认值为： 7300d

INFRA_ID

Infrastructure identity and portal definition.

#infra_seq: 1                     # infra node identity, explicitly required
infra_portal:                     # infra services exposed via portal
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:9090" }
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9093" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }

infra_seq

参数名称： infra_seq， 类型： int， 层次：I

基础设施节号，必选身份参数，所以不提供默认值，必须在基础设施节点上显式指定。

infra_portal

参数名称： infra_portal， 类型： dict， 层次：G

通过Nginx门户暴露的基础设施服务列表，默认情况下，Pigsty 会通过 Nginx 对外暴露以下服务：

infra_portal:
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:9090" }
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9093" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }

每条记录由一个 Key 与一个 Value 字典组成，name 作为键，代表组件名称，value 中唯一一个必选字段为 domain ，代表域名。

  • domain 是用于外部访问此上游服务器的域名。域名将被添加到Nginx SSL证书的 SAN 字段中，此字段为必选项目。
    • 默认记录 的 name 是固定的，其他模块会引用它，所以不要修改默认条目的 名称。
  • endpoint 是一个可以内部访问的TCP端口，如果指定，Nginx会将请求转发至此 endpoint 指定的地址。
    • endpoint 中 如果包含 ${admin_ip} ，则将在运行时被实际的 admin_ip 替换。
  • path 是一个可以本地访问的路径，如果指定将作为本地 Web 服务器的根，Nginx会将 domain 对应的请求转发至这里。
    • endpoint 与 path 互斥，你只能在一个条目中二选一：是上游 Proxy，还是本地 Web Server。
  • 如果 websocket 设置为 true，http协议将自动为 Websocket 连接升级。
    • 当上游用到 WebSocket 时，可以启用此选项（例如 Grafana/Jupyter）
  • 如果给定了 scheme（http 或 https），它将被用作 proxy_pass URL的一部分。
    • 作为 Proxy 时，当上游要求 Proxy 使用 HTTPS 而不是 HTTP 时使用此选项。（例如 MinIO ）

REPO

本节配置是关于本地软件仓库的。 Pigsty 默认会在基础设施节点上启用一个本地软件仓库（APT / YUM）。

在初始化过程中，Pigsty 会从互联网上游仓库（由 repo_upstream 指定）下载所有软件包及其依赖项（由 repo_packages 指定）到 {{ nginx_home }} / {{ repo_name }} （默认为 /www/pigsty），所有软件及其依赖的总大小约为1GB左右。

创建本地软件仓库时，如果仓库已存在（判断方式：仓库目录目录中有一个名为 repo_complete 的标记文件）Pigsty 将认为仓库已经创建完成，跳过软件下载阶段，直接使用构建好的仓库。

如果某些软件包的下载速度太慢，您可以通过使用 proxy_env 配置项来设置下载代理来完成首次下载，或直接下载预打包的 离线软件包，离线软件包本质上就是在同样操作系统上构建好的本地软件源。

repo_enabled: true                # create a yum repo on this infra node?
repo_home: /www                   # repo home dir, `/www` by default
repo_name: pigsty                 # repo name, pigsty by default
repo_endpoint: http://${admin_ip}:80 # access point to this repo by domain or ip:port
repo_remove: true                 # remove existing upstream repo
repo_modules: infra,node,pgsql    # install upstream repo during repo bootstrap
#repo_upstream: []                # where to download
#repo_packages: []                # which packages to download
#repo_extra_packages: []          # extra packages to download
repo_url_packages:                # extra packages from url
  - { name: "pev.html"    ,url: "https://repo.pigsty.io/etc/pev-1.12.1.html"    }
  - { name: "chart.tgz"   ,url: "https://repo.pigsty.io/etc/chart-1.0.0.tgz"    }
  - { name: "plugins.tgz" ,url: "https://repo.pigsty.io/etc/plugins-11.3.0.tgz" }

repo_enabled

参数名称： repo_enabled， 类型： bool， 层次：G/I

是否在当前的基础设施节点上启用本地软件源？默认为： true，即所有 Infra 节点都会设置一个本地软件仓库。

如果您有多个基础设施节点，可以只保留 1 ～ 2 个节点作为软件仓库，其他节点可以通过设置此参数为 false 来避免重复软件下载构建。

repo_home

参数名称： repo_home， 类型： path， 层次：G

本地软件仓库的家目录，默认为 Nginx 的根目录，也就是： /www，我们不建议您修改此目录。如果修改，需要和 nginx_home

repo_name

参数名称： repo_name， 类型： string， 层次：G

本地仓库名称，默认为 pigsty，更改此仓库的名称是不明智的行为。

repo_endpoint

参数名称： repo_endpoint， 类型： url， 层次：G

其他节点访问此仓库时使用的端点，默认值为：http://${admin_ip}:80。

Pigsty 默认会在基础设施节点 80/443 端口启动 Nginx，对外提供本地软件源（静态文件）服务。

如果您修改了 nginx_port 与 nginx_ssl_port，或者使用了不同于中控节点的基础设施节点，请相应调整此参数。

如果您使用了域名，可以在 node_default_etc_hosts、node_etc_hosts、或者 dns_records 中添加解析。

repo_remove

参数名称： repo_remove， 类型： bool， 层次：G/A

在构建本地软件源时，是否移除现有的上游仓库定义？默认值： true。

当启用此参数时，/etc/yum.repos.d 中所有已有仓库文件会被移动备份至/etc/yum.repos.d/backup，在 Debian 系上是移除 /etc/apt/sources.list 和 /etc/apt/sources.list.d，将文件备份至 /etc/apt/backup 中。

因为操作系统已有的源内容不可控，使用 Pigsty 验证过的上游软件源可以提高从互联网下载软件包的成功率与速度。

但在一些特定情况下（例如您的操作系统是某种 EL/Deb 兼容版，许多软件包使用了自己的私有源），您可能需要保留现有的上游仓库定义，此时可以将此参数设置为 false。

repo_modules

参数名称： repo_modules， 类型： string， 层次：G/A

哪些上游仓库模块会被添加到本地软件源中，默认值： infra,node,pgsql

当 Pigsty 尝试添加上游仓库时，会根据此参数的值来过滤 repo_upstream 中的条目，只有 module 字段与此参数值匹配的条目才会被添加到本地软件源中。

模块以逗号分隔，可用的模块列表请参考 repo_upstream 中的定义

repo_upstream

参数名称： repo_upstream， 类型： upstream[]， 层次：G

构建本地软件源时，从哪里下载上游软件包？本参数没有默认值，如果用户不在配置文件中显式指定，则会从根据当前节点的操作系统族，从定义于 roles/node_id/vars 中的 repo_upstream_default 变量中加载获取。

对于 EL （7，8，9）系统，默认使用的软件源如下所示：

- { name: pigsty-local   ,description: 'Pigsty Local'      ,module: local   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://${admin_ip}/pigsty'  }} # used by intranet nodes
- { name: pigsty-infra   ,description: 'Pigsty INFRA'      ,module: infra   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/yum/infra/$basearch' ,china: 'https://repo.pigsty.cc/yum/infra/$basearch' }}
- { name: pigsty-pgsql   ,description: 'Pigsty PGSQL'      ,module: pgsql   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/yum/pgsql/el$releasever.$basearch' ,china: 'https://repo.pigsty.cc/yum/pgsql/el$releasever.$basearch' }}
- { name: nginx          ,description: 'Nginx Repo'        ,module: infra   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://nginx.org/packages/rhel/$releasever/$basearch/' }}
- { name: baseos         ,description: 'EL 8+ BaseOS'      ,module: node    ,releases: [  8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/BaseOS/$basearch/os/'     ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/BaseOS/$basearch/os/'          ,europe: 'https://mirrors.xtom.de/rocky/$releasever/BaseOS/$basearch/os/'     }}
- { name: appstream      ,description: 'EL 8+ AppStream'   ,module: node    ,releases: [  8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/AppStream/$basearch/os/'  ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/AppStream/$basearch/os/'       ,europe: 'https://mirrors.xtom.de/rocky/$releasever/AppStream/$basearch/os/'  }}
- { name: extras         ,description: 'EL 8+ Extras'      ,module: node    ,releases: [  8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/extras/$basearch/os/'     ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/extras/$basearch/os/'          ,europe: 'https://mirrors.xtom.de/rocky/$releasever/extras/$basearch/os/'     }}
- { name: powertools     ,description: 'EL 8 PowerTools'   ,module: node    ,releases: [  8  ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/PowerTools/$basearch/os/' ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/PowerTools/$basearch/os/'      ,europe: 'https://mirrors.xtom.de/rocky/$releasever/PowerTools/$basearch/os/' }}
- { name: crb            ,description: 'EL 9 CRB'          ,module: node    ,releases: [    9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://dl.rockylinux.org/pub/rocky/$releasever/CRB/$basearch/os/'        ,china: 'https://mirrors.aliyun.com/rockylinux/$releasever/CRB/$basearch/os/'             ,europe: 'https://mirrors.xtom.de/rocky/$releasever/CRB/$basearch/os/'        }}
- { name: epel           ,description: 'EL 8+ EPEL'        ,module: node    ,releases: [  8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://download.fedoraproject.org/pub/epel/$releasever/Everything/$basearch/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/epel/$releasever/Everything/$basearch/' ,europe: 'https://mirrors.xtom.de/epel/$releasever/Everything/$basearch/'     }}
- { name: pgdg-common    ,description: 'PostgreSQL Common' ,module: pgsql   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-extras    ,description: 'PostgreSQL Extra'  ,module: pgsql   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rhel$releasever-extras/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg-el8fix    ,description: 'PostgreSQL EL8FIX' ,module: pgsql   ,releases: [  8  ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-centos8-sysupdates/redhat/rhel-8-x86_64/' } }
- { name: pgdg-el9fix    ,description: 'PostgreSQL EL9FIX' ,module: pgsql   ,releases: [    9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/'  ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/' , europe: 'https://mirrors.xtom.de/postgresql/repos/yum/common/pgdg-rocky9-sysupdates/redhat/rhel-9-x86_64/' }}
- { name: pgdg17         ,description: 'PostgreSQL 17'     ,module: pgsql   ,releases: [  8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/17/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17-nonfree ,description: 'PostgreSQL 17+'    ,module: pgsql   ,releases: [  8,9] ,arch: [x86_64         ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' }}
- { name: timescaledb    ,description: 'TimescaleDB'       ,module: pgsql   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packagecloud.io/timescale/timescaledb/el/$releasever/$basearch'  }}
# these repos are not used by default, but can be enabled by setting repo_modules
- { name: pgdg12         ,description: 'PostgreSQL 12'     ,module: pg12    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/12/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/12/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/12/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg12-nonfree ,description: 'PostgreSQL 12+'    ,module: pg12    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/12/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/non-free/12/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/12/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg13         ,description: 'PostgreSQL 13'     ,module: pg13    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/13/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/13/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/13/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg13-nonfree ,description: 'PostgreSQL 13+'    ,module: pg13    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/13/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/non-free/13/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/13/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg14         ,description: 'PostgreSQL 14'     ,module: pg14    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/14/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/14/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/14/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg14-nonfree ,description: 'PostgreSQL 14+'    ,module: pg14    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/14/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg15         ,description: 'PostgreSQL 15'     ,module: pg15    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/15/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/15/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/15/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg15-nonfree ,description: 'PostgreSQL 15+'    ,module: pg15    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/15/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg16         ,description: 'PostgreSQL 16'     ,module: pg16    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/16/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/16/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg16-nonfree ,description: 'PostgreSQL 16+'    ,module: pg16    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/16/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17         ,description: 'PostgreSQL 17'     ,module: pg17    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/17/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/17/redhat/rhel-$releasever-$basearch' }}
- { name: pgdg17-nonfree ,description: 'PostgreSQL 17+'    ,module: pg17    ,releases: [7,8,9] ,arch: [x86_64         ] ,baseurl: { default: 'https://download.postgresql.org/pub/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' ,europe: 'https://mirrors.xtom.de/postgresql/repos/yum/non-free/17/redhat/rhel-$releasever-$basearch' }}
- { name: docker-ce      ,description: 'Docker CE'         ,module: docker  ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.docker.com/linux/centos/$releasever/$basearch/stable'    ,china: 'https://mirrors.aliyun.com/docker-ce/linux/centos/$releasever/$basearch/stable'  ,europe: 'https://mirrors.xtom.de/docker-ce/linux/centos/$releasever/$basearch/stable' }}
- { name: kubernetes     ,description: 'Kubernetes'        ,module: kube    ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://pkgs.k8s.io/core:/stable:/v1.31/rpm/', china: 'https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.31/rpm/' }}
- { name: wiltondb       ,description: 'WiltonDB'          ,module: mssql   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.copr.fedorainfracloud.org/results/wiltondb/wiltondb/epel-$releasever-$basearch/', china: 'https://repo.pigsty.cc/yum/mssql/el$releasever.$basearch' }}
- { name: ivorysql       ,description: 'IvorySQL'          ,module: ivory   ,releases: [7,8,9] ,arch: [x86_64         ] ,baseurl: { default: 'https://repo.pigsty.io/yum/ivory/el$releasever.$basearch', china: 'https://repo.pigsty.cc/yum/ivory/el$releasever.$basearch' }}
- { name: mysql          ,description: 'MySQL'             ,module: mysql   ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.mysql.com/yum/mysql-8.0-community/el/$releasever/$basearch/', china: 'https://mirrors.tuna.tsinghua.edu.cn/mysql/yum/mysql-8.0-community-el7-$basearch/' }}
- { name: grafana        ,description: 'Grafana'           ,module: grafana ,releases: [7,8,9] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://rpm.grafana.com' }}

对于 Debian （11，12）或 Ubuntu （20.04，22.04），默认使用的软件源如下所示：

- { name: pigsty-local  ,description: 'Pigsty Local'     ,module: local     ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://${admin_ip}/pigsty ./' }}
- { name: pigsty-pgsql  ,description: 'Pigsty PgSQL'     ,module: pgsql     ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/apt/pgsql/${distro_codename} ${distro_codename} main', china: 'https://repo.pigsty.cc/apt/pgsql/${distro_codename} ${distro_codename} main' }}
- { name: pigsty-infra  ,description: 'Pigsty Infra'     ,module: infra     ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.pigsty.io/apt/infra/ generic main' ,china: 'https://repo.pigsty.cc/apt/infra/ generic main' }}
- { name: nginx         ,description: 'Nginx'            ,module: infra     ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://nginx.org/packages/${distro_name} ${distro_codename} nginx' }}
- { name: base          ,description: 'Debian Basic'     ,module: node      ,releases: [11,12         ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://deb.debian.org/debian/ ${distro_codename} main non-free-firmware'         ,china: 'https://mirrors.aliyun.com/debian/ ${distro_codename} main restricted universe multiverse' }}
- { name: updates       ,description: 'Debian Updates'   ,module: node      ,releases: [11,12         ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://deb.debian.org/debian/ ${distro_codename}-updates main non-free-firmware' ,china: 'https://mirrors.aliyun.com/debian/ ${distro_codename}-updates main restricted universe multiverse' }}
- { name: security      ,description: 'Debian Security'  ,module: node      ,releases: [11,12         ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://security.debian.org/debian-security ${distro_codename}-security main non-free-firmware' }}
- { name: base          ,description: 'Ubuntu Basic'     ,module: node      ,releases: [      20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}           main universe multiverse restricted' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}           main restricted universe multiverse' }}
- { name: updates       ,description: 'Ubuntu Updates'   ,module: node      ,releases: [      20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-backports main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-updates   main restricted universe multiverse' }}
- { name: backports     ,description: 'Ubuntu Backports' ,module: node      ,releases: [      20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-security  main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-backports main restricted universe multiverse' }}
- { name: security      ,description: 'Ubuntu Security'  ,module: node      ,releases: [      20,22,24] ,arch: [x86_64         ] ,baseurl: { default: 'https://mirrors.edge.kernel.org/ubuntu/ ${distro_codename}-updates   main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu/ ${distro_codename}-security  main restricted universe multiverse' }}
- { name: base          ,description: 'Ubuntu Basic'     ,module: node      ,releases: [      20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}           main universe multiverse restricted' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}           main restricted universe multiverse' }}
- { name: updates       ,description: 'Ubuntu Updates'   ,module: node      ,releases: [      20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-backports main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-updates   main restricted universe multiverse' }}
- { name: backports     ,description: 'Ubuntu Backports' ,module: node      ,releases: [      20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-security  main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-backports main restricted universe multiverse' }}
- { name: security      ,description: 'Ubuntu Security'  ,module: node      ,releases: [      20,22,24] ,arch: [        aarch64] ,baseurl: { default: 'http://ports.ubuntu.com/ubuntu-ports/ ${distro_codename}-updates   main restricted universe multiverse' ,china: 'https://mirrors.aliyun.com/ubuntu-ports/ ${distro_codename}-security  main restricted universe multiverse' }}
- { name: pgdg          ,description: 'PGDG'             ,module: pgsql     ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'http://apt.postgresql.org/pub/repos/apt/ ${distro_codename}-pgdg main' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/postgresql/repos/apt/ ${distro_codename}-pgdg main' }}
- { name: citus         ,description: 'Citus'            ,module: pgsql     ,releases: [11,12,20,22   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packagecloud.io/citusdata/community/${distro_name}/ ${distro_codename} main' } }
- { name: timescaledb   ,description: 'Timescaledb'      ,module: pgsql     ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://packagecloud.io/timescale/timescaledb/${distro_name}/ ${distro_codename} main' }}
# these repos are not used by default, but can be enabled by setting repo_modules
- { name: grafana      ,description: 'Grafana'           ,module: grafana   ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://apt.grafana.com stable main' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/grafana/apt/ stable main' }}
- { name: pgml         ,description: 'PostgresML'        ,module: pgml      ,releases: [         22   ] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://apt.postgresml.org ${distro_codename} main'  }}
- { name: wiltondb     ,description: 'WiltonDB'          ,module: mssql     ,releases: [      20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://ppa.launchpadcontent.net/wiltondb/wiltondb/ubuntu/ ${distro_codename} main', china: 'https://repo.pigsty.cc/apt/mssql/ ${distro_codename} main'  }}
- { name: mysql        ,description: 'MySQL'             ,module: mysql     ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://repo.mysql.com/apt/${distro_name} ${distro_codename} mysql-8.0 mysql-tools', china: 'https://mirrors.tuna.tsinghua.edu.cn/mysql/apt/${distro_name} ${distro_codename} mysql-8.0 mysql-tools' }}
- { name: docker-ce    ,description: 'Docker'            ,module: docker    ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.docker.com/linux/${distro_name} ${distro_codename} stable' ,china: 'https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux//${distro_name} ${distro_codename} stable' }}
- { name: kubernetes   ,description: 'Kubernetes'        ,module: kube      ,releases: [11,12,20,22,24] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /', china: 'https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.31/deb/ /' }}

Pigsty 构建配置模板 oss.yml 提供了不同操作系统下的默认值。

repo_packages

参数名称： repo_packages， 类型： string[]， 层次：G

字符串数组类型，每一行都是 由空格分隔 的软件包列表字符串，指定将要使用 repotrack 或 apt download 下载到本地的软件包（及其依赖）。

本参数没有默认值，即默认值为未定义状态。如果该参数没有被显式定义，那么 Pigsty 会从 roles/node_id/vars 中定义的 repo_packages_default 变量中加载获取默认值，默认值为：

[ node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-utility ]

该参数中的每个元素，都会在上述文件中定义的 package_map 中，根据特定的操作系统发行版大版本进行翻译。例如在 EL 系统上会翻译为：

node-bootstrap:          "ansible python3 python3-pip python3-virtualenv python3-requests python3-jmespath python3-cryptography dnf-utils modulemd-tools createrepo_c sshpass"
infra-package:           "nginx dnsmasq etcd haproxy vip-manager pg_exporter pgbackrest_exporter redis_exporter redis minio mcli ferretdb duckdb"
infra-addons:            "grafana loki logcli promtail prometheus2 alertmanager pushgateway node_exporter blackbox_exporter nginx_exporter keepalived_exporter"
node-package1:           "lz4 unzip bzip2 zlib yum pv jq git ncdu make patch bash lsof wget uuid tuned nvme-cli numactl grubby sysstat iotop htop rsync tcpdump perf flamegraph chkconfig"
node-package2:           "netcat socat ftp lrzsz net-tools ipvsadm bind-utils telnet audit ca-certificates readline vim-minimal keepalived chrony openssl openssh-server openssh-clients"
pgsql-utility:           "patroni patroni-etcd pgbouncer pgbackrest pgbadger pg_activity pg_timetable pgFormatter pg_filedump pgxnclient timescaledb-tools pgcopydb pgloader"

而在 Debian 系统上会被翻译为对应的 Debian DEB 包名：

node-bootstrap:          "ansible python3 python3-pip python3-venv python3-jmespath dpkg-dev sshpass ftp linux-tools-generic"
infra-package:           "nginx dnsmasq etcd haproxy vip-manager pg-exporter pgbackrest-exporter redis-exporter redis minio mcli ferretdb duckdb"
infra-addons:            "grafana loki logcli promtail prometheus2 alertmanager pushgateway node-exporter blackbox-exporter nginx-exporter keepalived-exporter"
node-package1:           "lz4 unzip bzip2 zlib1g pv jq git ncdu make patch bash lsof wget uuid tuned nvme-cli numactl sysstat iotop htop rsync tcpdump acl chrony"
node-package2:           "netcat-openbsd socat lrzsz net-tools ipvsadm dnsutils telnet ca-certificates libreadline-dev vim-tiny keepalived openssl openssh-server openssh-client"
pgsql-utility:           "patroni pgbouncer pgbackrest pgbadger pg-activity pg-timetable pgformatter postgresql-filedump pgxnclient timescaledb-tools pgcopydb pgloader"

作为一个使用约定，repo_packages 中通常包括了那些与 PostgreSQL 大版本号无关的软件包（例如 Infra，Node 和 PGDG Common 等部分），而 PostgreSQL 大版本相关的软件包（内核，扩展），通常在 repo_extra_packages 中指定，方便用户切换 PG 大版本。

repo_extra_packages

参数名称： repo_extra_packages， 类型： string[]， 层次：G/C/I

用于在不修改 repo_packages 的基础上，指定额外需要下载的软件包（通常是 PG 大版本相关的软件包），默认值为空列表。

如果该参数没有被显式定义，那么 Pigsty 会从 roles/node_id/vars 中定义的 repo_extra_packages_default 变量中加载获取默认值，默认值为：

[ pgsql-main ]

该参数中的每个元素，都会在上述文件中定义的 package_map 中，根据特定的操作系统发行版大版本进行翻译。例如在 EL 系统上会翻译为：

postgresql$v* pg_repack_$v* wal2json_$v* pgvector_$v*

而在 Debian 系统上会被翻译为对应的 Debian DEB 包名：

postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-server-dev-$v postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector

这里的 $v 会被替换为 pg_version，即当前 PG 大版本号 （默认为 17）。通常用户可以在这里指定 PostgreSQL 大版本相关的软件包，而不影响 repo_packages 中定义的其他 PG 大版本无关的软件包。

repo_url_packages

参数名称： repo_url_packages， 类型： object[] | string[]， 层次：G

直接使用 URL 从互联网上下载的软件包，默认为一些额外可选的资源包：

repo_url_packages:                # extra packages from url
  - { name: "pev.html"    ,url: "https://repo.pigsty.io/etc/pev-1.12.1.html"    } # Explain Visualizer
  - { name: "chart.tgz"   ,url: "https://repo.pigsty.io/etc/chart-1.0.0.tgz"    } # Grafana Maps
  - { name: "plugins.tgz" ,url: "https://repo.pigsty.io/etc/plugins-11.1.4.tgz" } # Grafana Plugins

这几个都是可选的加装项：例如，如果不下载 plugins.tgz，Grafana 初始化的时候就会直接从互联网上下载插件，这样会导致初始化时间变长（而且有可能被墙），但是不会影响最终结果。

您可以直接在本参数中使用 URL 字符串作为数组元素，也可以使用 Pigsty v3 新引入的对象结构，显式指定 URL 与文件名称。

请注意，本参数会收到 region 变量的影响，如果您在中国大陆地区，Pigsty 会自动将 URL 替换为国内镜像站点，即将 URL 里的 repo.pigsty.io 替换为 repo.pigsty.cc。

INFRA_PACKAGE

这些软件包只会在 INFRA 节点上安装，包括普通的 RPM/DEB 软件包，以及 PIP 软件包。

infra_packages

参数名称： infra_packages， 类型： string[]， 层次：G

字符串数组类型，每一行都是 由空格分隔 的软件包列表字符串，指定将要在 Infra 节点上安装的软件包列表。

本参数没有默认值，即默认值为未定义状态。如果用户不在配置文件中显式指定本参数，则 Pigsty 会从根据当前节点的操作系统族，从定义于 roles/node_id/vars 中的 infra_packages_default 变量中加载获取默认值。

默认值（EL系操作系统）：

infra_packages:                   # packages to be installed on infra nodes
  - grafana,loki,logcli,promtail,prometheus2,alertmanager,pushgateway
  - node_exporter,blackbox_exporter,nginx_exporter,pg_exporter
  - nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli

默认值（Debian/Ubuntu）：

infra_packages:                   # packages to be installed on infra nodes
  - grafana,loki,logcli,promtail,prometheus2,alertmanager,pushgateway
  - node-exporter,blackbox-exporter,nginx-exporter,pg-exporter
  - nginx,dnsmasq,ansible,etcd,python3-requests,redis,mcli

infra_packages_pip

参数名称： infra_packages_pip， 类型： string， 层次：G

Infra 节点上要使用 pip 额外安装的软件包，包名使用逗号分隔，默认值是空字符串，即不安装任何额外的 python 包。

NGINX

Pigsty 会通过 Nginx 代理所有的 Web 服务访问：Home Page、Grafana、Prometheus、AlertManager 等等。 以及其他可选的工具，如 PGWe、Jupyter Lab、Pgadmin、Bytebase 等等，还有一些静态资源和报告，如 pev、schemaspy 和 pgbadger。

最重要的是，Nginx 还作为本地软件仓库（Yum/Apt）的 Web 服务器，用于存储和分发 Pigsty 的软件包。

nginx_enabled: true               # enable nginx on this infra node?
nginx_exporter_enabled: true      # enable nginx_exporter on this infra node?
nginx_sslmode: enable             # nginx ssl mode? disable,enable,enforce
nginx_home: /www                  # nginx content dir, `/www` by default
nginx_port: 80                    # nginx listen port, 80 by default
nginx_ssl_port: 443               # nginx ssl listen port, 443 by default
nginx_navbar:                     # nginx index page navigation links
  - { name: CA Cert ,url: '/ca.crt'   ,desc: 'pigsty self-signed ca.crt'   }
  - { name: Package ,url: '/pigsty'   ,desc: 'local yum repo packages'     }
  - { name: PG Logs ,url: '/logs'     ,desc: 'postgres raw csv logs'       }
  - { name: Reports ,url: '/report'   ,desc: 'pgbadger summary report'     }
  - { name: Explain ,url: '/pigsty/pev.html' ,desc: 'postgres explain visualizer' }

nginx_enabled

参数名称： nginx_enabled， 类型： bool， 层次：G/I

是否在当前的 Infra 节点上启用 Nginx？默认值为： true。

nginx_exporter_enabled

参数名称： nginx_exporter_enabled， 类型： bool， 层次：G/I

在此基础设施节点上启用 nginx_exporter ？默认值为： true。

如果禁用此选项，还会一并禁用 /nginx 健康检查 stub，当您安装使用的 Nginx 版本不支持此功能是可以考虑关闭此开关

nginx_sslmode

参数名称： nginx_sslmode， 类型： enum， 层次：G

Nginx 的 SSL工作模式？有三种选择：disable , enable , enforce， 默认值为 enable，即启用 SSL，但不强制使用。

  • disable：只监听 nginx_port 指定的端口服务 HTTP 请求。
  • enable：同时会监听 nginx_ssl_port 指定的端口服务 HTTPS 请求。
  • enforce：所有链接都会被渲染为默认使用 https://

nginx_home

参数名称： nginx_home， 类型： path， 层次：G

Nginx服务器静态文件目录，默认为： /www

Nginx服务器的根目录，包含静态资源和软件仓库文件。最好不要随意修改此参数，修改时需要与 repo_home 参数保持一致。

nginx_port

参数名称： nginx_port， 类型： port， 层次：G

Nginx 默认监听的端口（提供HTTP服务），默认为 80 端口，最好不要修改这个参数。

当您的服务器 80 端口被占用时，可以考虑修改此参数，但是需要同时修改 repo_endpoint ，以及 node_repo_local_urls 所使用的端口并与这里保持一致。

nginx_ssl_port

参数名称： nginx_ssl_port， 类型： port， 层次：G

Nginx SSL 默认监听的端口，默认为 443，最好不要修改这个参数。

nginx_navbar

参数名称： nginx_navbar， 类型： index[]， 层次：G

Nginx 首页上的导航栏内容，默认值：

nginx_navbar:                     # nginx index page navigation links
  - { name: CA Cert ,url: '/ca.crt'   ,desc: 'pigsty self-signed ca.crt'   }
  - { name: Package ,url: '/pigsty'   ,desc: 'local yum repo packages'     }
  - { name: PG Logs ,url: '/logs'     ,desc: 'postgres raw csv logs'       }
  - { name: Reports ,url: '/report'   ,desc: 'pgbadger summary report'     }
  - { name: Explain ,url: '/pigsty/pev.html' ,desc: 'postgres explain visualizer' }

每一条记录都会被渲染为一个导航链接，链接到 Pigsty 首页的 App 下拉菜单，所有的 App 都是可选的，默认挂载在 Pigsty 默认服务器下的 http://pigsty/ 。

url 参数指定了 App 的 URL PATH，但是如果 URL 中包含 ${grafana} 字符串，它会被自动替换为 infra_portal 中定义的 Grafana 域名。

所以您可以将一些使用 Grafana 的数据应用挂载到 Pigsty 的首页导航栏中。

DNS

Pigsty 默认会在 Infra 节点上启用 DNSMASQ 服务，用于解析一些辅助域名，例如 h.pigsty a.pigsty p.pigsty g.pigsty 等等，以及可选 MinIO 的 sss.pigsty。

解析记录会记录在 Infra 节点的 /etc/hosts.d/default 文件中。 要使用这个 DNS 服务器，您必须将 nameserver <ip> 添加到 /etc/resolv 中，node_dns_servers 参数可以解决这个问题。

dns_enabled: true                 # setup dnsmasq on this infra node?
dns_port: 53                      # dns server listen port, 53 by default
dns_records:                      # dynamic dns records resolved by dnsmasq
  - "${admin_ip} h.pigsty a.pigsty p.pigsty g.pigsty"
  - "${admin_ip} api.pigsty adm.pigsty cli.pigsty ddl.pigsty lab.pigsty git.pigsty sss.pigsty wiki.pigsty"

dns_enabled

参数名称： dns_enabled， 类型： bool， 层次：G/I

是否在这个 Infra 节点上启用 DNSMASQ 服务？默认值为： true。

如果你不想使用默认的 DNS 服务器，（比如你已经有了外部的DNS服务器，或者您的供应商不允许您使用 DNS 服务器）可以将此值设置为 false 来禁用它。 并使用 node_default_etc_hosts 和 node_etc_hosts 静态解析记录代替。

dns_port

参数名称： dns_port， 类型： port， 层次：G

DNSMASQ 的默认监听端口，默认是 53，不建议修改 DNS 服务默认端口。

dns_records

参数名称： dns_records， 类型： string[]， 层次：G

由 dnsmasq 负责解析的动态 DNS 记录，一般用于将一些辅助域名解析到本地，例如 h.pigsty a.pigsty p.pigsty g.pigsty 等等。这些记录会被写入到基础设置节点的 /etc/hosts.d/default 文件中。

dns_records:                      # dynamic dns records resolved by dnsmasq
  - "${admin_ip} h.pigsty a.pigsty p.pigsty g.pigsty"
  - "${admin_ip} api.pigsty adm.pigsty cli.pigsty ddl.pigsty lab.pigsty git.pigsty sss.pigsty wiki.pigsty"

PROMETHEUS

Prometheus 被用作时序数据库，用于存储和分析监控指标数据，进行指标预计算，评估告警规则。

prometheus_enabled: true          # enable prometheus on this infra node?
prometheus_clean: true            # clean prometheus data during init?
prometheus_data: /etc/prometheus/targets # prometheus data dir, `/etc/prometheus/targets` by default
prometheus_sd_interval: 5s        # prometheus target refresh interval, 5s by default
prometheus_scrape_interval: 10s   # prometheus scrape & eval interval, 10s by default
prometheus_scrape_timeout: 8s     # prometheus global scrape timeout, 8s by default
prometheus_options: '--storage.tsdb.retention.time=15d' # prometheus extra server options
pushgateway_enabled: true         # setup pushgateway on this infra node?
pushgateway_options: '--persistence.interval=1m' # pushgateway extra server options
blackbox_enabled: true            # setup blackbox_exporter on this infra node?
blackbox_options: ''              # blackbox_exporter extra server options
alertmanager_enabled: true        # setup alertmanager on this infra node?
alertmanager_options: ''          # alertmanager extra server options
exporter_metrics_path: /metrics   # exporter metric path, `/metrics` by default
exporter_install: none            # how to install exporter? none,yum,binary
exporter_repo_url: ''             # exporter repo file url if install exporter via yum

prometheus_enabled

参数名称： prometheus_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 Prometheus？ 默认值为 true，即所有基础设施节点默认都会安装启用 Prometheus。

例如，如果您有多个元节点，默认情况下，Pigsty会在所有元节点上部署Prometheus。如果您想一台用于Prometheus监控指标收集，一台用于Loki日志收集，则可以在其他元节点的实例层次上将此参数设置为false。

prometheus_clean

参数名称： prometheus_clean， 类型： bool， 层次：G/A

是否在执行 Prometheus 初始化的时候清除现有 Prometheus 数据？默认值为 true。

prometheus_data

参数名称： prometheus_data， 类型： path， 层次：G

Prometheus数据库目录, 默认位置为 /data/prometheus。

prometheus_sd_dir

参数名称： prometheus_sd_dir， 类型： path， 层次：G

Prometheus 静态文件服务发现的对象存储目录，默认值为 /etc/prometheus/targets。

prometheus_sd_interval

参数名称： prometheus_sd_interval， 类型： interval， 层次：G

Prometheus 静态文件服务发现的刷新周期，默认值为 5s。

这意味着 Prometheus 每隔这样长的时间就会重新扫描一次 prometheus_sd_dir （默认为：/etc/prometheus/targets 目录），以发现新的监控对象。

prometheus_scrape_interval

参数名称： prometheus_scrape_interval， 类型： interval， 层次：G

Prometheus 全局指标抓取周期, 默认值为 10s。在生产环境，10秒 - 30秒是一个较为合适的抓取周期。如果您需要更精细的的监控数据粒度，则可以调整此参数。

prometheus_scrape_timeout

参数名称： prometheus_scrape_timeout， 类型： interval， 层次：G

Prometheus 全局抓取超时，默认为 8s。

设置抓取超时可以有效避免监控系统查询导致的雪崩，设置原则是，本参数必须小于并接近 prometheus_scrape_interval ，确保每次抓取时长不超过抓取周期。

prometheus_options

参数名称： prometheus_options， 类型： arg， 层次：G

Prometheus 的额外的命令行参数，默认值：--storage.tsdb.retention.time=15d

默认的参数会为 Prometheus 配置一个 15 天的保留期限来限制磁盘使用量。

pushgateway_enabled

参数名称： pushgateway_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 PushGateway？ 默认值为 true，即所有基础设施节点默认都会安装启用 PushGateway。

pushgateway_options

参数名称： pushgateway_options， 类型： arg， 层次：G

PushGateway 的额外的命令行参数，默认值：--persistence.interval=1m，即每分钟进行一次持久化操作。

blackbox_enabled

参数名称： blackbox_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 BlackboxExporter ？ 默认值为 true，即所有基础设施节点默认都会安装启用 BlackboxExporter 。

BlackboxExporter 会向节点 IP 地址， VIP 地址，PostgreSQL VIP 地址发送 ICMP 报文测试网络连通性。

blackbox_options

参数名称： blackbox_options， 类型： arg， 层次：G

BlackboxExporter 的额外的命令行参数，默认值：空字符串。

alertmanager_enabled

参数名称： alertmanager_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 AlertManager ？ 默认值为 true，即所有基础设施节点默认都会安装启用 AlertManager 。

alertmanager_options

参数名称： alertmanager_options， 类型： arg， 层次：G

AlertManager 的额外的命令行参数，默认值：空字符串。

exporter_metrics_path

参数名称： exporter_metrics_path， 类型： path， 层次：G

监控 exporter 暴露指标的 HTTP 端点路径，默认为： /metrics ，不建议修改此参数。

exporter_install

参数名称： exporter_install， 类型： enum， 层次：G

（弃用参数）安装监控组件的方式，有三种可行选项：none, yum, binary

指明安装Exporter的方式：

  • none：不安装，（默认行为，Exporter已经在先前由 node_pkg 任务完成安装）
  • yum：使用yum（apt）安装（如果启用yum安装，在部署Exporter前执行yum安装 node_exporter 与 pg_exporter ）
  • binary：使用拷贝二进制的方式安装（从元节点中直接拷贝node_exporter 与 pg_exporter 二进制，不推荐）

使用yum安装时，如果指定了exporter_repo_url（不为空），在执行安装时会首先将该URL下的REPO文件安装至/etc/yum.repos.d中。这一功能可以在不执行节点基础设施初始化的环境下直接进行Exporter的安装。 不推荐普通用户使用binary安装，这种模式通常用于紧急故障抢修与临时问题修复。

exporter_repo_url

参数名称： exporter_repo_url， 类型： url， 层次：G

（弃用参数）监控组件的 Yum Repo URL

默认为空，当 exporter_install 为 yum 时，该参数指定的Repo会被添加至节点源列表中。

GRAFANA

Pigsty 使用 Grafana 作为监控系统前端。它也可以做为数据分析与可视化平台，或者用于低代码数据应用开发，制作数据应用原型等目的。

grafana_enabled: true             # enable grafana on this infra node?
grafana_clean: true               # clean grafana data during init?
grafana_admin_username: admin     # grafana admin username, `admin` by default
grafana_admin_password: pigsty    # grafana admin password, `pigsty` by default
grafana_plugin_cache: /www/pigsty/plugins.tgz # path to grafana plugins cache tarball
grafana_plugin_list:              # grafana plugins to be downloaded with grafana-cli
  - volkovlabs-echarts-panel
  - volkovlabs-image-panel
  - volkovlabs-form-panel
  - volkovlabs-variable-panel
  - volkovlabs-grapi-datasource
  - marcusolsson-static-datasource
  - marcusolsson-json-datasource
  - marcusolsson-dynamictext-panel
  - marcusolsson-treemap-panel
  - marcusolsson-calendar-panel
  - marcusolsson-hourly-heatmap-panel
  - knightss27-weathermap-panel
loki_enabled: true                # enable loki on this infra node?
loki_clean: false                 # whether remove existing loki data?
loki_data: /data/loki             # loki data dir, `/data/loki` by default
loki_retention: 15d               # loki log retention period, 15d by default

grafana_enabled

参数名称： grafana_enabled， 类型： bool， 层次：G/I

是否在Infra节点上启用Grafana？默认值为： true，即所有基础设施节点默认都会安装启用 Grafana。

grafana_clean

参数名称： grafana_clean， 类型： bool， 层次：G/A

是否在初始化 Grafana 时一并清理其数据文件？默认为：true。

该操作会移除 /var/lib/grafana/grafana.db，确保 Grafana 全新安装。

grafana_admin_username

参数名称： grafana_admin_username， 类型： username， 层次：G

Grafana管理员用户名，admin by default

grafana_admin_password

参数名称： grafana_admin_password， 类型： password， 层次：G

Grafana管理员密码，pigsty by default

提示：请务必在生产部署中修改此密码参数！

grafana_plugin_cache

参数名称： grafana_plugin_cache， 类型： path， 层次：G

Grafana 插件缓存地址，一个指向 Tarball 的路径，默认值为：/www/pigsty/plugins.tgz

如果该文件存在，Pigsty会直接将其解压至：/var/lib/grafana/plugins 中并跳过从互联网下载 Grafana 插件的步骤。

grafana_plugin_list

参数名称： grafana_plugin_list， 类型： string[]， 层次：G

列表中的 Grafana 插件将会被下载，默认包含了来自 volkovlabs 与 marusolsson 的几个实用扩展。

grafana_plugin_list:              # grafana plugins to be downloaded with grafana-cli
  - volkovlabs-echarts-panel
  - volkovlabs-image-panel
  - volkovlabs-form-panel
  - volkovlabs-variable-panel
  - volkovlabs-grapi-datasource
  - marcusolsson-static-datasource
  - marcusolsson-json-datasource
  - marcusolsson-dynamictext-panel
  - marcusolsson-treemap-panel
  - marcusolsson-calendar-panel
  - marcusolsson-hourly-heatmap-panel
  - knightss27-weathermap-panel

每个数组元素是一个字符串，表示插件的名称。插件会通过grafana-cli plugins install的方式进行安装。

LOKI

Loki 是Grafana提供的轻量级日志收集/检索平台，它可以提供一个集中查询服务器/数据库日志的地方。

loki_enabled

参数名称： loki_enabled， 类型： bool， 层次：G/I

是否在当前 Infra 节点上启用 Loki ？ 默认值为 true，即所有基础设施节点默认都会安装启用 Loki 。

loki_clean

参数名称： loki_clean， 类型： bool， 层次：G/A

是否在安装Loki时清理数据库目录？默认值： false，现有日志数据在初始化时会保留。

loki_data

参数名称： loki_data， 类型： path， 层次：G

Loki的数据目录，默认值为： /data/loki

loki_retention

参数名称： loki_retention， 类型： interval， 层次：G

Loki日志默认保留天数，默认保留 15d 。

NODE

NODE 模块负责将主机节点调整到期待的目标状态，并将其纳入 Pigsty 的监控系统中。

NODE_ID

每个节点都有身份参数，通过在<cluster>.hosts与<cluster>.vars中的相关参数进行配置。

Pigsty使用IP地址作为数据库节点的唯一标识，该IP地址必须是数据库实例监听并对外提供服务的IP地址，但不宜使用公网IP地址。 尽管如此，用户并不一定非要通过该IP地址连接至该数据库。例如，通过SSH隧道或跳板机中转的方式间接操作管理目标节点也是可行的。 但在标识数据库节点时，首要IPv4地址依然是节点的核心标识符。这一点非常重要，用户应当在配置时保证这一点。 IP地址即配置清单中主机的inventory_hostname ，体现为<cluster>.hosts对象中的key。

node-test:
  hosts:
    10.10.10.11: { nodename: node-test-1 }
    10.10.10.12: { nodename: node-test-2 }
    10.10.10.13: { nodename: node-test-3 }
  vars:
    node_cluster: node-test

除此之外，在Pigsty监控系统中，节点还有两个重要的身份参数：nodename 与 node_cluster，这两者将在监控系统中被用作节点的 实例标识（ins） 与 集群标识 （cls）。

node_load1{cls="pg-meta", ins="pg-meta-1", ip="10.10.10.10", job="nodes"}
node_load1{cls="pg-test", ins="pg-test-1", ip="10.10.10.11", job="nodes"}
node_load1{cls="pg-test", ins="pg-test-2", ip="10.10.10.12", job="nodes"}
node_load1{cls="pg-test", ins="pg-test-3", ip="10.10.10.13", job="nodes"}

在执行默认的PostgreSQL部署时，因为Pigsty默认采用节点独占1:1部署，因此可以通过 node_id_from_pg 参数，将数据库实例的身份参数（ pg_cluster 借用至节点的ins与cls标签上。

名称 类型 层级 必要性 说明
inventory_hostname ip - 必选 节点IP地址
nodename string I 可选 节点名称
node_cluster string C 可选 节点集群名称 
#nodename:                # [实例] # 节点实例标识，如缺失则使用现有主机名，可选，无默认值
node_cluster: nodes       # [集群] # 节点集群标识，如缺失则使用默认值'nodes'，可选
nodename_overwrite: true          # 用 nodename 覆盖节点的主机名吗？
nodename_exchange: false          # 在剧本主机之间交换 nodename 吗？
node_id_from_pg: true             # 如果可行，是否借用 postgres 身份作为节点身份？

nodename

参数名称： nodename， 类型： string， 层次：I

主机节点的身份参数，如果没有显式设置，则会使用现有的主机 Hostname 作为节点名。本参数虽然是身份参数，但因为有合理默认值，所以是可选项。

如果启用了 node_id_from_pg 选项（默认启用），且 nodename 没有被显式指定， 那么 nodename 会尝试使用 ${pg_cluster}-${pg_seq} 作为实例身份参数，如果集群没有定义 PGSQL 模块，那么会回归到默认值，也就是主机节点的 HOSTNAME。

node_cluster

参数名称： node_cluster， 类型： string， 层次：C

该选项可为节点显式指定一个集群名称，通常在节点集群层次定义才有意义。使用默认空值将直接使用固定值nodes作为节点集群标识。

如果启用了 node_id_from_pg 选项（默认启用），且 node_cluster 没有被显式指定，那么 node_cluster 会尝试使用 ${pg_cluster}-${pg_seq} 作为集群身份参数，如果集群没有定义 PGSQL 模块，那么会回归到默认值 nodes。

nodename_overwrite

参数名称： nodename_overwrite， 类型： bool， 层次：C

是否使用 nodename 覆盖主机名？默认值为 true，在这种情况下，如果你设置了一个非空的 nodename ，那么它会被用作当前主机的 HOSTNAME 。

当 nodename 配置为空时，如果 node_id_from_pg 参数被配置为 true （默认为真），那么 Pigsty 会尝试借用1:1定义在节点上的 PostgreSQL 实例的身份参数作为主机的节点名。 也就是 {{ pg_cluster }}-{{ pg_seq }}，如果该节点没有安装 PGSQL 模块，则会回归到默认什么都不做的状态。

因此，如果您将 nodename 留空，并且没有启用 node_id_from_pg 参数时，Pigsty不会对现有主机名进行任何修改。

nodename_exchange

参数名称： nodename_exchange， 类型： bool， 层次：C

是否在剧本节点间交换主机名？默认值为：false

启用此参数时，同一批组执行 node.yml 剧本的节点之间会相互交换节点名称，写入/etc/hosts中。

node_id_from_pg

参数名称： node_id_from_pg， 类型： bool， 层次：C

从节点上 1:1 部署的 PostgreSQL 实例/集群上借用身份参数？ 默认值为 true。

Pigsty 中的 PostgreSQL 实例与节点默认使用 1:1 部署，因此，您可以从数据库实例上“借用” 身份参数。 此参数默认启用，这意味着一套 PostgreSQL 集群如果没有特殊配置，主机节点集群和实例的身份参数默认值是与数据库身份参数保持一致的。对于问题分析，监控数据处理都提供了额外便利。

NODE_DNS

Pigsty会为节点配置静态DNS解析记录与动态DNS服务器。

如果您的节点供应商已经为您配置了DNS服务器，您可以将 node_dns_method 设置为 none 跳过DNS设置。

node_write_etc_hosts: true        # modify `/etc/hosts` on target node?
node_default_etc_hosts:           # static dns records in `/etc/hosts`
  - "${admin_ip} h.pigsty a.pigsty p.pigsty g.pigsty"
node_etc_hosts: []                # extra static dns records in `/etc/hosts`
node_dns_method: add              # how to handle dns servers: add,none,overwrite
node_dns_servers: ['${admin_ip}'] # dynamic nameserver in `/etc/resolv.conf`
node_dns_options:                 # dns resolv options in `/etc/resolv.conf`
  - options single-request-reopen timeout:1

node_write_etc_hosts

参数名称： node_write_etc_hosts， 类型： bool， 层次：G|C|I

是否修改目标节点上的 /etc/hosts？例如，在容器环境中通常不允许修改此配置文件。

node_default_etc_hosts

参数名称： node_default_etc_hosts， 类型： string[]， 层次：G

默认写入所有节点 /etc/hosts 的静态DNS记录，默认值为：

["${admin_ip} h.pigsty a.pigsty p.pigsty g.pigsty"]

node_default_etc_hosts 是一个数组，每个元素都是一条 DNS 记录，格式为 <ip> <name>，您可以指定多个用空格分隔的域名。

这个参数是用于配置全局静态DNS解析记录的，如果您希望为单个集群与实例配置特定的静态DNS解析，则可以使用 node_etc_hosts 参数。

node_etc_hosts

参数名称： node_etc_hosts， 类型： string[]， 层次：C

写入节点 /etc/hosts 的额外的静态DNS记录，默认值为：[] 空数组。

本参数与 node_default_etc_hosts，形式一样，但用途不同：适合在集群/实例层面进行配置。

node_dns_method

参数名称： node_dns_method， 类型： enum， 层次：C

如何配置DNS服务器？有三种选项：add、none、overwrite，默认值为 add。

  • add：将 node_dns_servers 中的记录追加至/etc/resolv.conf，并保留已有DNS服务器。（默认）
  • overwrite：使用将 node_dns_servers 中的记录覆盖/etc/resolv.conf
  • none：跳过DNS服务器配置，如果您的环境中已经配置有DNS服务器，则可以直接跳过DNS配置。

node_dns_servers

参数名称： node_dns_servers， 类型： string[]， 层次：C

配置 /etc/resolv.conf 中的动态DNS服务器列表：默认值为： ["${admin_ip}"]，即将管理节点作为首要DNS服务器。

node_dns_options

参数名称： node_dns_options， 类型： string[]， 层次：C

/etc/resolv.conf 中的DNS解析选项，默认值为：

- "options single-request-reopen timeout:1"

如果 node_dns_method 配置为add或overwrite，则本配置项中的记录会被首先写入/etc/resolv.conf 中。具体格式请参考Linux文档关于/etc/resolv.conf的说明

NODE_PACKAGE

Pigsty会为纳入管理的节点配置Yum源，并安装软件包。

node_repo_modules: local          # upstream repo to be added on node, local by default.
node_repo_remove: true            # remove existing repo on node?
node_packages: [ ]                # packages to be installed current nodes
#node_default_packages:           # default packages to be installed on all nodes

node_repo_modules

参数名称： node_repo_modules， 类型： string， 层次：C/A

需要在节点上添加的的软件源模块列表，形式同 repo_modules。默认值为 local，即使用 repo_upstream 中 local 所指定的本地软件源。

当 Pigsty 纳管节点时，会根据此参数的值来过滤 repo_upstream 中的条目，只有 module 字段与此参数值匹配的条目才会被添加到节点的软件源中。

node_repo_remove

参数名称： node_repo_remove， 类型： bool， 层次：C/A

是否移除节点已有的软件仓库定义？默认值为：true。

如果启用，则Pigsty会 移除 节点上/etc/yum.repos.d中原有的配置文件，并备份至/etc/yum.repos.d/backup。 在 Debian/Ubuntu 系统上，则是 /etc/apt/sources.list(.d) 备份至 /etc/apt/backup。

node_packages

参数名称： node_packages， 类型： string[]， 层次：C

在当前节点上要安装并升级的软件包列表，默认值为：[openssh-server] ，即在安装时会将 sshd 升级到最新版本（避免安全漏洞）。

每一个数组元素都是字符串：由逗号分隔的软件包名称。形式上与 node_packages_default 相同。本参数通常用于在节点/集群层面指定需要额外安装的软件包。

在本参数中指定的软件包，会 升级到可用的最新版本，如果您需要保持现有节点软件版本不变（存在即可），请使用 node_default_packages 参数。

node_default_packages

参数名称： node_default_packages， 类型： string[]， 层次：G

默认在所有节点上安装的软件包，默认值是 EL 7/8/9 通用的 RPM 软件包列表，数组，每个元素为逗号分隔的包名：

字符串数组类型，每一行都是 由空格分隔 的软件包列表字符串，指定默认在所有节点上安装的软件包列表。

在此变量中指定的软件包，只要求 存在，而不要求 最新。如果您需要安装最新版本的软件包，请使用 node_packages 参数。

本参数没有默认值，即默认值为未定义状态。如果用户不在配置文件中显式指定本参数，则 Pigsty 会从根据当前节点的操作系统族，从定义于 roles/node_id/vars 中的 node_packages_default 变量中加载获取默认值。

默认值（EL系操作系统）：

- lz4,unzip,bzip2,pv,jq,git,ncdu,make,patch,bash,lsof,wget,uuid,tuned,nvme-cli,numactl,sysstat,iotop,htop,rsync,tcpdump
- python3,python3-pip,socat,lrzsz,net-tools,ipvsadm,telnet,ca-certificates,openssl,keepalived,etcd,haproxy,chrony
- zlib,yum,audit,bind-utils,readline,vim-minimal,node_exporter,grubby,openssh-server,openssh-clients

默认值（Debian/Ubuntu）：

- lz4,unzip,bzip2,pv,jq,git,ncdu,make,patch,bash,lsof,wget,uuid,tuned,nvme-cli,numactl,sysstat,iotop,htop,rsync,tcpdump
- python3,python3-pip,socat,lrzsz,net-tools,ipvsadm,telnet,ca-certificates,openssl,keepalived,etcd,haproxy,chrony
- zlib1g,acl,dnsutils,libreadline-dev,vim-tiny,node-exporter,openssh-server,openssh-client

本参数形式上与 node_packages 相同，但本参数通常用于全局层面指定所有节点都必须安装的默认软件包

NODE_TUNE

主机节点特性、内核模块与参数调优模板。

node_disable_firewall: true       # disable node firewall? true by default
node_disable_selinux: true        # disable node selinux? true by default
node_disable_numa: false          # disable node numa, reboot required
node_disable_swap: false          # disable node swap, use with caution
node_static_network: true         # preserve dns resolver settings after reboot
node_disk_prefetch: false         # setup disk prefetch on HDD to increase performance
node_kernel_modules: [ softdog, br_netfilter, ip_vs, ip_vs_rr, ip_vs_wrr, ip_vs_sh ]
node_hugepage_count: 0            # number of 2MB hugepage, take precedence over ratio
node_hugepage_ratio: 0            # node mem hugepage ratio, 0 disable it by default
node_overcommit_ratio: 0          # node mem overcommit ratio, 0 disable it by default
node_tune: oltp                   # node tuned profile: none,oltp,olap,crit,tiny
node_sysctl_params: { }           # sysctl parameters in k:v format in addition to tuned

node_disable_firewall

参数名称： node_disable_firewall， 类型： bool， 层次：C

关闭节点防火墙？默认关闭防火墙：true。

如果您在受信任的内网部署，可以关闭防火墙。在 EL 下是 firewalld 服务，在 Ubuntu下是 ufw 服务。

node_disable_selinux

参数名称： node_disable_selinux， 类型： bool， 层次：C

关闭节点SELINUX？默认关闭SELinux：true。

如果您没有操作系统/安全专家，请关闭 SELinux。

当使用 Kubernetes 模块时，请关闭 SELinux。

node_disable_numa

参数名称： node_disable_numa， 类型： bool， 层次：C

是否关闭NUMA？默认不关闭NUMA：false。

注意，关闭NUMA需要重启机器后方可生效！如果您不清楚如何绑核，在生产环境使用数据库时建议关闭 NUMA。

node_disable_swap

参数名称： node_disable_swap， 类型： bool， 层次：C

是否关闭 SWAP ？ 默认不关闭SWAP：false。

通常情况下不建议关闭 SWAP，例外情况是如果您有足够的内存用于独占式 PostgreSQL 部署，则可以关闭 SWAP 提高性能。

例外：当您的节点用于部署 Kubernetes 模块时，应当禁用SWAP。

node_static_network

参数名称： node_static_network， 类型： bool， 层次：C

是否使用静态DNS服务器, 类型：bool，层级：C，默认值为：true，默认启用。

启用静态网络，意味着您的DNS Resolv配置不会因为机器重启与网卡变动被覆盖，建议启用，或由网络工程师负责配置。

node_disk_prefetch

参数名称： node_disk_prefetch， 类型： bool， 层次：C

是否启用磁盘预读？默认不启用：false。

针对HDD部署的实例可以优化性能，使用机械硬盘时建议启用。

node_kernel_modules

参数名称： node_kernel_modules， 类型： string[]， 层次：C

启用哪些内核模块？默认启用以下内核模块：

node_kernel_modules: [ softdog, br_netfilter, ip_vs, ip_vs_rr, ip_vs_wrr, ip_vs_sh ]

形式上是由内核模块名称组成的数组，声明了需要在节点上安装的内核模块。

node_hugepage_count

参数名称： node_hugepage_count， 类型： int， 层次：C

在节点上分配 2MB 大页的数量，默认为 0，另一个相关的参数是 node_hugepage_ratio。

如果这两个参数 node_hugepage_count 和 node_hugepage_ratio 都为 0（默认），则大页将完全被禁用，本参数的优先级相比 node_hugepage_ratio 更高，因为它更加精确。

如果设定了一个非零值，它将被写入 /etc/sysctl.d/hugepage.conf 中应用生效；负值将不起作用，高于 90% 节点内存的数字将被限制为节点内存的 90%

如果不为零，它应该略大于pg_shared_buffer_ratio 的对应值，这样才能让 PostgreSQL 用上大页。

node_hugepage_ratio

参数名称： node_hugepage_ratio， 类型： float， 层次：C

节点内存大页占内存的比例，默认为 0，有效范围：0 ~ 0.40

此内存比例将以大页的形式分配，并为PostgreSQL预留。 node_hugepage_count 是具有更高优先级和精度的参数版本。

默认值：0，这将设置 vm.nr_hugepages=0 并完全不使用大页。

本参数应该等于或略大于pg_shared_buffer_ratio，如果不为零。

例如，如果您为Postgres共享缓冲区默认分配了25%的内存，您可以将此值设置为 0.27 ~ 0.30，并在初始化后使用 /pg/bin/pg-tune-hugepage 精准回收浪费的大页。

node_overcommit_ratio

参数名称： node_overcommit_ratio， 类型： int， 层次：C

节点内存超额分配比率，默认为：0。这是一个从 0 到 100+ 的整数。

默认值：0，这将设置 vm.overcommit_memory=0，否则将使用 vm.overcommit_memory=2， 并使用此值作为 vm.overcommit_ratio。

建议在 pgsql 独占节点上设置 vm.overcommit_ratio，避免内存过度提交。

node_tune

参数名称： node_tune， 类型： enum， 层次：C

针对机器进行调优的预制方案，基于tuned 提供服务。有四种预制模式：

  • tiny：微型虚拟机
  • oltp：常规OLTP模板，优化延迟（默认值）
  • olap：常规OLAP模板，优化吞吐量
  • crit：核心金融业务模板，优化脏页数量

通常，数据库的调优模板 pg_conf应当与机器调优模板配套。

node_sysctl_params

参数名称： node_sysctl_params， 类型： dict， 层次：C

使用 K:V 形式的 sysctl 内核参数，会添加到 tuned profile 中，默认值为： {} 空对象。

这是一个 KV 结构的字典参数，Key 是内核 sysctl 参数名，Value 是参数值。你也可以考虑直接在 roles/node/templates 中的 tuned 模板中直接定义额外的 sysctl 参数。

NODE_ADMIN

这一节关于主机节点上的管理员，谁能登陆，怎么登陆。

node_data: /data                  # node main data directory, `/data` by default
node_admin_enabled: true          # create a admin user on target node?
node_admin_uid: 88                # uid and gid for node admin user
node_admin_username: dba          # name of node admin user, `dba` by default
node_admin_ssh_exchange: true     # exchange admin ssh key among node cluster
node_admin_pk_current: true       # add current user's ssh pk to admin authorized_keys
node_admin_pk_list: []            # ssh public keys to be added to admin user

node_data

参数名称： node_data， 类型： path， 层次：C

节点的主数据目录，默认为 /data。

如果该目录不存在，则该目录会被创建。该目录应当由 root 拥有，并拥有 777 权限。

node_admin_enabled

参数名称： node_admin_enabled， 类型： bool， 层次：C

是否在本节点上创建一个专用管理员用户？默认值为：true。

Pigsty默认会在每个节点上创建一个管理员用户（拥有免密sudo与ssh权限），默认的管理员名为dba (uid=88)的管理用户，可以从元节点上通过SSH免密访问环境中的其他节点并执行免密sudo。

node_admin_uid

参数名称： node_admin_uid， 类型： int， 层次：C

管理员用户UID，默认值为：88。

请尽可能确保 UID 在所有节点上都相同，可以避免一些无谓的权限问题。

如果默认 UID 88 已经被占用，您可以选择一个其他 UID ，手工分配时请注意UID命名空间冲突。

node_admin_username

参数名称： node_admin_username， 类型： username， 层次：C

管理员用户名，默认为 dba 。

node_admin_ssh_exchange

参数名称： node_admin_ssh_exchange， 类型： bool， 层次：C

在节点集群间交换节点管理员SSH密钥, 类型：bool，层级：C，默认值为：true

启用时，Pigsty会在执行剧本时，在成员间交换SSH公钥，允许管理员 node_admin_username 从不同节点上相互访问。

node_admin_pk_current

参数名称： node_admin_pk_current， 类型： bool， 层次：C

是否将当前节点 & 用户的公钥加入管理员账户，默认值是： true

启用时，将会把当前节点上执行此剧本的管理用户的SSH公钥（~/.ssh/id_rsa.pub）拷贝至目标节点管理员用户的 authorized_keys 中。

生产环境部署时，请务必注意此参数，此参数会将当前执行命令用户的默认公钥安装至所有机器的管理用户上。

node_admin_pk_list

参数名称： node_admin_pk_list， 类型： string[]， 层次：C

可登陆管理员的公钥列表，默认值为：[] 空数组。

数组的每一个元素为字符串，内容为写入到管理员用户~/.ssh/authorized_keys中的公钥，持有对应私钥的用户可以以管理员身份登录。

生产环境部署时，请务必注意此参数，仅将信任的密钥加入此列表中。

NODE_TIME

关于主机时间/时区/NTP/定时任务的相关配置。

时间同步对于数据库服务来说非常重要，请确保系统 chronyd 授时服务正常运行。

node_timezone: ''                 # 设置节点时区，空字符串表示跳过
node_ntp_enabled: true            # 启用chronyd时间同步服务？
node_ntp_servers:                 # `/etc/chrony.conf`中的ntp服务器
  - pool pool.ntp.org iburst
node_crontab_overwrite: true      # 覆盖还是追加到`/etc/crontab`？
node_crontab: [ ]                 # `/etc/crontab`中的crontab条目

node_timezone

参数名称： node_timezone， 类型： string， 层次：C

设置节点时区，空字符串表示跳过。默认值是空字符串，默认不会修改默认的时区（即使用通常的默认值UTC）

在中国地区使用时，建议设置为 Asia/Hong_Kong。

node_ntp_enabled

参数名称： node_ntp_enabled， 类型： bool， 层次：C

启用chronyd时间同步服务？默认值为：true

此时 Pigsty 将使用 node_ntp_servers 中指定的 NTP服务器列表覆盖节点的 /etc/chrony.conf。

如果您的节点已经配置好了 NTP 服务器，那么可以将此参数设置为 false 跳过时间同步配置。

node_ntp_servers

参数名称： node_ntp_servers， 类型： string[]， 层次：C

在 /etc/chrony.conf 中使用的 NTP 服务器列表。默认值为：["pool pool.ntp.org iburst"]

本参数是一个数组，每一个数组元素是一个字符串，代表一行 NTP 服务器配置。仅当 node_ntp_enabled 启用时生效。

Pigsty 默认使用全球 NTP 服务器 pool.ntp.org，您可以根据自己的网络环境修改此参数，例如 cn.pool.ntp.org iburst，或内网的时钟服务。

您也可以在配置中使用 ${admin_ip} 占位符，使用管理节点上的时间服务器。

node_ntp_servers: [ 'pool ${admin_ip} iburst' ]

node_crontab_overwrite

参数名称： node_crontab_overwrite， 类型： bool， 层次：C

处理 node_crontab 中的定时任务时，是追加还是覆盖？默认值为：true，即覆盖。

如果您希望在节点上追加定时任务，可以将此参数设置为 false，Pigsty 将会在节点的 crontab 上 追加，而非 覆盖所有 定时任务。

node_crontab

参数名称： node_crontab， 类型： string[]， 层次：C

定义在节点 /etc/crontab 中的定时任务：默认值为：[] 空数组。

每一个数组数组元素都是一个字符串，代表一行定时任务。使用标准的 cron 格式定义。

例如，以下配置会以 postgres 用户在每天凌晨1点执行全量备份任务。

node_crontab: 
  - '00 01 * * * postgres /pg/bin/pg-backup full' ] # make a full backup every 1am

NODE_VIP

您可以为节点集群绑定一个可选的 L2 VIP，默认不启用此特性。L2 VIP 只对一组节点集群有意义，该 VIP 会根据配置的优先级在集群中的节点之间进行切换，确保节点服务的高可用。

请注意，L2 VIP 只能 在同一 L2 网段中使用，这可能会对您的网络拓扑产生额外的限制，如果不想受此限制，您可以考虑使用 DNS LB 或者 Haproxy 实现类似的功能。

当启用此功能时，您需要为这个 L2 VIP 显式分配可用的 vip_address 与 vip_vrid，用户应当确保这两者在同一网段内唯一。

vip_enabled: false                # enable vip on this node cluster?
# vip_address:         [IDENTITY] # node vip address in ipv4 format, required if vip is enabled
# vip_vrid:            [IDENTITY] # required, integer, 1-254, should be unique among same VLAN
vip_role: backup                  # optional, `master/backup`, backup by default, use as init role
vip_preempt: false                # optional, `true/false`, false by default, enable vip preemption
vip_interface: eth0               # node vip network interface to listen, `eth0` by default
vip_dns_suffix: ''                # node vip dns name suffix, empty string by default
vip_exporter_port: 9650           # keepalived exporter listen port, 9650 by default

vip_enabled

参数名称： vip_enabled， 类型： bool， 层次：C

是否在当前这个节点集群中配置一个由 Keepalived 管理的 L2 VIP ？ 默认值为： false。

vip_address

参数名称： vip_address， 类型： ip， 层次：C

节点 VIP 地址，IPv4 格式（不带 CIDR 网段后缀），当节点启用 vip_enabled 时，这是一个必选参数。

本参数没有默认值，这意味着您必须显式地为节点集群分配一个唯一的 VIP 地址。

vip_vrid

参数名称： vip_vrid， 类型： int， 层次：C

VRID 是一个范围从 1 到 254 的正整数，用于标识一个网络中的 VIP，当节点启用 vip_enabled 时，这是一个必选参数。

本参数没有默认值，这意味着您必须显式地为节点集群分配一个网段内唯一的 ID。

vip_role

参数名称： vip_role， 类型： enum， 层次：I

节点 VIP 角色，可选值为： master 或 backup，默认值为 backup

该参数的值会被设置为 keepalived 的初始状态。

vip_preempt

参数名称： vip_preempt， 类型： bool， 层次：C/I

是否启用 VIP 抢占？可选参数，默认值为 false，即不抢占 VIP。

所谓抢占，是指一个 backup 角色的节点，当其优先级高于当前存活且正常工作的 master 角色的节点时，是否取抢占其 VIP？

vip_interface

参数名称： vip_interface， 类型： string， 层次：C/I

节点 VIP 监听使用的网卡，默认为 eth0。

您应当使用与节点主IP地址（即：你填入清单中IP地址）所使用网卡相同的名称。

如果你的节点有着不同的网卡名称，你可以在实例/节点层次对其进行覆盖。

vip_dns_suffix

参数名称： vip_dns_suffix， 类型： string， 层次：C/I

节点集群 L2 VIP 使用的DNS名称，默认是空字符串，即直接使用集群名本身作为DNS名。

vip_exporter_port

参数名称： vip_exporter_port， 类型： port， 层次：C/I

keepalived exporter 监听端口号，默认为：9650。

HAPROXY

HAProxy 默认在所有节点上安装启用，并以类似于 Kubernetes NodePort 的方式对外暴露服务。

PGSQL 模块对外服务使用到了 Haproxy。

haproxy_enabled: true             # 在此节点上启用haproxy？
haproxy_clean: false              # 清理所有现有的haproxy配置？
haproxy_reload: true              # 配置后重新加载haproxy？
haproxy_auth_enabled: true        # 为haproxy管理页面启用身份验证
haproxy_admin_username: admin     # haproxy管理用户名，默认为`admin`
haproxy_admin_password: pigsty    # haproxy管理密码，默认为`pigsty`
haproxy_exporter_port: 9101       # haproxy管理/导出端口，默认为9101
haproxy_client_timeout: 24h       # 客户端连接超时，默认为24小时
haproxy_server_timeout: 24h       # 服务器端连接超时，默认为24小时
haproxy_services: []              # 需要在节点上暴露的haproxy服务列表

haproxy_enabled

参数名称： haproxy_enabled， 类型： bool， 层次：C

在此节点上启用haproxy？默认值为： true。

haproxy_clean

参数名称： haproxy_clean， 类型： bool， 层次：G/C/A

清理所有现有的haproxy配置？默认值为 false。

haproxy_reload

参数名称： haproxy_reload， 类型： bool， 层次：A

配置后重新加载 haproxy？默认值为 true，配置更改后会重新加载haproxy。

如果您希望在应用配置前进行手工检查，您可以使用命令参数关闭此选项，并进行检查后再应用。

haproxy_auth_enabled

参数名称： haproxy_auth_enabled， 类型： bool， 层次：G

为haproxy管理页面启用身份验证，默认值为 true，它将要求管理页面进行http基本身份验证。

建议不要禁用认证，因为您的流量控制页面将对外暴露，这是比较危险的。

haproxy_admin_username

参数名称： haproxy_admin_username， 类型： username， 层次：G

haproxy 管理员用户名，默认为：admin。

haproxy_admin_password

参数名称： haproxy_admin_password， 类型： password， 层次：G

haproxy管理密码，默认为 pigsty

在生产环境中请务必修改此密码！

haproxy_exporter_port

参数名称： haproxy_exporter_port， 类型： port， 层次：C

haproxy 流量管理/指标对外暴露的端口，默认为：9101

haproxy_client_timeout

参数名称： haproxy_client_timeout， 类型： interval， 层次：C

客户端连接超时，默认为 24h。

设置一个超时可以避免难以清理的超长的连接，但如果您真的需要一个长连接，您可以将其设置为更长的时间。

haproxy_server_timeout

参数名称： haproxy_server_timeout， 类型： interval， 层次：C

服务端连接超时，默认为 24h。

设置一个超时可以避免难以清理的超长的连接，但如果您真的需要一个长连接，您可以将其设置为更长的时间。

haproxy_services

参数名称： haproxy_services， 类型： service[]， 层次：C

需要在此节点上通过 Haproxy 对外暴露的服务列表，默认值为： [] 空数组。

每一个数组元素都是一个服务定义，下面是一个服务定义的例子：

haproxy_services:                   # list of haproxy service

  # expose pg-test read only replicas
  - name: pg-test-ro                # [REQUIRED] service name, unique
    port: 5440                      # [REQUIRED] service port, unique
    ip: "*"                         # [OPTIONAL] service listen addr, "*" by default
    protocol: tcp                   # [OPTIONAL] service protocol, 'tcp' by default
    balance: leastconn              # [OPTIONAL] load balance algorithm, roundrobin by default (or leastconn)
    maxconn: 20000                  # [OPTIONAL] max allowed front-end connection, 20000 by default
    default: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'
    options:
      - option httpchk
      - option http-keep-alive
      - http-check send meth OPTIONS uri /read-only
      - http-check expect status 200
    servers:
      - { name: pg-test-1 ,ip: 10.10.10.11 , port: 5432 , options: check port 8008 , backup: true }
      - { name: pg-test-2 ,ip: 10.10.10.12 , port: 5432 , options: check port 8008 }
      - { name: pg-test-3 ,ip: 10.10.10.13 , port: 5432 , options: check port 8008 }

每个服务定义会被渲染为 /etc/haproxy/<service.name>.cfg 配置文件，并在 Haproxy 重载后生效。

NODE_EXPORTER

node_exporter_enabled: true       # setup node_exporter on this node?
node_exporter_port: 9100          # node exporter listen port, 9100 by default
node_exporter_options: '--no-collector.softnet --no-collector.nvme --collector.tcpstat --collector.processes'

node_exporter_enabled

参数名称： node_exporter_enabled， 类型： bool， 层次：C

在当前节点上启用节点指标收集器？默认启用：true

node_exporter_port

参数名称： node_exporter_port， 类型： port， 层次：C

对外暴露节点指标使用的端口，默认为 9100。

node_exporter_options

参数名称： node_exporter_options， 类型： arg， 层次：C

节点指标采集器的命令行参数，默认值为：

--no-collector.softnet --no-collector.nvme --collector.tcpstat --collector.processes

该选项会启用/禁用一些指标收集器，请根据您的需要进行调整。

PROMTAIL

Promtail 是与 Loki 配套的日志收集组件，会收集各个模块产生的日志并发送至基础设施节点上的 LOKI 服务。

  • INFRA： 基础设施组件的日志只会在 Infra 节点上收集。

    • nginx-access: /var/log/nginx/access.log
    • nginx-error: /var/log/nginx/error.log
    • grafana: /var/log/grafana/grafana.log

  • NODES：主机相关的日志，所有节点上都会启用收集。

    • syslog: /var/log/messages （Debian上为 /var/log/syslog）
    • dmesg: /var/log/dmesg
    • cron: /var/log/cron

  • PGSQL：PostgreSQL 相关的日志，只有节点配置了 PGSQL 模块才会启用收集。

    • postgres: /pg/log/postgres/*
    • patroni: /pg/log/patroni.log
    • pgbouncer: /pg/log/pgbouncer/pgbouncer.log
    • pgbackrest: /pg/log/pgbackrest/*.log

  • REDIS：Redis 相关日志，只有节点配置了 REDIS 模块才会启用收集。

    • redis: /var/log/redis/*.log

日志目录会根据这些参数的配置自动调整：pg_log_dir, patroni_log_dir, pgbouncer_log_dir, pgbackrest_log_dir

promtail_enabled: true            # enable promtail logging collector?
promtail_clean: false             # purge existing promtail status file during init?
promtail_port: 9080               # promtail listen port, 9080 by default
promtail_positions: /var/log/positions.yaml # promtail position status file path

promtail_enabled

参数名称： promtail_enabled， 类型： bool， 层次：C

是否启用Promtail日志收集服务？默认值为： true

promtail_clean

参数名称： promtail_clean， 类型： bool， 层次：G/A

是否在安装 Promtail 时移除已有状态信息？默认值为： false。

默认不会清理，当您选择清理时，Pigsty会在部署Promtail时移除现有状态文件 promtail_positions，这意味着Promtail会重新收集当前节点上的所有日志并发送至Loki。

promtail_port

参数名称： promtail_port， 类型： port， 层次：C

Promtail 监听使用的默认端口号， 默认为：9080

promtail_positions

参数名称： promtail_positions， 类型： path， 层次：C

Promtail 状态文件路径，默认值为：/var/log/positions.yaml。

Promtail记录了所有日志的消费偏移量，定期写入由本参数指定的文件中。

DOCKER

您可以使用 docker.yml 剧本，在节点上安装并启用 Docker。

docker_enabled: false             # enable docker on this node?
docker_cgroups_driver: systemd    # docker cgroup fs driver: cgroupfs,systemd
docker_registry_mirrors: []       # docker registry mirror list
docker_image: []                  # docker image to be pulled after bootstrap
docker_image_cache: /tmp/docker/*.tgz # docker image cache file/glob, `/tmp/docker/*.tgz` by default

docker_enabled

参数名称： docker_enabled， 类型： bool， 层次：G/C/I

是否在当前节点启用Docker？默认为： false，即不启用。

docker_cgroups_driver

参数名称： docker_cgroups_driver， 类型： enum， 层次：G/C/I

Docker使用的 CGroup FS 驱动，可以是 cgroupfs 或 systemd，默认值为： systemd

docker_registry_mirrors

参数名称： docker_registry_mirrors， 类型： string[]， 层次：G/C/I

Docker使用的镜像仓库地址，默认值为：[] 空数组。

您可以使用Docker镜像站点加速镜像拉取，下面是一些例子：

[ "https://mirror.ccs.tencentyun.com" ]         # 腾讯云内网的镜像站点
["https://registry.cn-hangzhou.aliyuncs.com"]   # 阿里云镜像站点，需要登陆

如果拉取速度太慢，您也可以考虑：docker login quay.io 使用其他的 Registry。

docker_image

参数名称： docker_image， 类型： string[]， 层次：G/C/I

Docker 待拉取的镜像列表，默认为空列表 []。

在这里指定的 Docker 镜像名称会在安装阶段自动拉取。

docker_image_cache

参数名称： docker_image_cache， 类型： path[]， 层次：G/C/I

本地 Docker 镜像离线缓存包路径列表， 数组，默认为 ["/tmp/docker/*.tgz"]。

您可以使用 docker save | gzip 的方式将镜像打包，并通过此参数在 Docker 安装阶段自动导入。

匹配该参数的 tarball 将使用以下方式 导入 Docker 中：

cat *.tgz | gzip -d -c - | docker load

ETCD

ETCD 是一个分布式、可靠的键值存储，用于分布式系统的最关键数据。Pigsty使用 etcd 作为DCS，这对 PostgreSQL 的高可用性非常重要。

Pigsty为etcd集群使用一个硬编码的集群组名 etcd，它可以是一套现有的外部 etcd 集群，或者默认由 Pigsty 使用 etcd.yml 剧本部署创建的新etcd集群。

#etcd_seq: 1                      # etcd实例标识符，需要显式指定
#etcd_cluster: etcd               # etcd集群和组名称，默认为etcd
etcd_safeguard: false             # 组织清除正在运行的etcd实例？
etcd_clean: true                  # 在初始化过程中清除现有的etcd？
etcd_data: /data/etcd             # etcd数据目录，默认为/data/etcd
etcd_port: 2379                   # etcd客户端端口，默认为2379
etcd_peer_port: 2380              # etcd对等端口，默认为2380
etcd_init: new                    # etcd初始集群状态，新建或现有
etcd_election_timeout: 1000       # etcd选举超时，默认为1000ms
etcd_heartbeat_interval: 100      # etcd心跳间隔，默认为100ms

etcd_seq

参数名称： etcd_seq， 类型： int， 层次：I

etcd 实例标号， 这是必选参数，必须为每一个 etcd 实例指定一个唯一的标号。

以下是一个3节点etcd集群的示例，分配了 1 ～ 3 三个标号。

etcd: # dcs service for postgres/patroni ha consensus
  hosts:  # 1 node for testing, 3 or 5 for production
    10.10.10.10: { etcd_seq: 1 }  # etcd_seq required
    10.10.10.11: { etcd_seq: 2 }  # assign from 1 ~ n
    10.10.10.12: { etcd_seq: 3 }  # odd number please
  vars: # cluster level parameter override roles/etcd
    etcd_cluster: etcd  # mark etcd cluster name etcd
    etcd_safeguard: false # safeguard against purging
    etcd_clean: true # purge etcd during init process

etcd_cluster

参数名称： etcd_cluster， 类型： string， 层次：C

etcd 集群 & 分组名称，默认值为硬编码值 etcd。

当您想要部署另外的 etcd 集群备用时，可以修改此参数并使用其他集群名。

etcd_safeguard

参数名称： etcd_safeguard， 类型： bool， 层次：G/C/A

安全保险参数，防止清除正在运行的etcd实例？默认值为 false。

如果启用安全保险，etcd.yml 剧本不会清除正在运行的etcd实例。

etcd_clean

参数名称： etcd_clean， 类型： bool， 层次：G/C/A

在初始化时清除现有的 etcd ？默认值为true。

如果启用，etcd.yml 剧本将清除正在运行的 etcd 实例，这将使其成为一个真正幂等的剧本（总是抹除现有集群）。

但是如果启用了etcd_safeguard，即使设置了此参数，剧本依然会在遇到运行中的 etcd 实例时中止，避免误删。

etcd_data

参数名称： etcd_data， 类型： path， 层次：C

etcd 数据目录，默认为/data/etcd 。

etcd_port

参数名称： etcd_port， 类型： port， 层次：C

etcd 客户端端口号，默认为2379。

etcd_peer_port

参数名称： etcd_peer_port， 类型： port， 层次：C

etcd peer 端口，默认为 2380 。

etcd_init

参数名称： etcd_init， 类型： enum， 层次：C

etcd初始集群状态，可以是new或existing，默认值：new。

默认将创建一个独立的新etcd集群，当尝试向现有etcd集群添加新成员时，应当使用 existing。

etcd_election_timeout

参数名称： etcd_election_timeout， 类型： int， 层次：C

etcd 选举超时，默认为 1000 (毫秒)，也就是 1 秒。

etcd_heartbeat_interval

参数名称： etcd_heartbeat_interval， 类型： int， 层次：C

etcd心跳间隔，默认为 100 (毫秒)。

MINIO

MinIO 是一个与S3兼容的对象存储服务，它被用作PostgreSQL的可选的集中式备份存储库。

但你也可以将其用于其他目的，如存储大文件、文档、图片和视频。

#minio_seq: 1                     # minio instance identifier, REQUIRED
minio_cluster: minio              # minio cluster name, minio by default
minio_clean: false                # cleanup minio during init?, false by default
minio_user: minio                 # minio os user, `minio` by default
minio_node: '${minio_cluster}-${minio_seq}.pigsty' # minio node name pattern
minio_data: '/data/minio'         # minio data dir(s), use {x...y} to specify multi drivers
minio_domain: sss.pigsty          # minio external domain name, `sss.pigsty` by default
minio_port: 9000                  # minio service port, 9000 by default
minio_admin_port: 9001            # minio console port, 9001 by default
minio_access_key: minioadmin      # root access key, `minioadmin` by default
minio_secret_key: minioadmin      # root secret key, `minioadmin` by default
minio_extra_vars: ''              # extra environment variables
minio_alias: sss                  # alias name for local minio deployment
minio_buckets: [ { name: pgsql }, { name: infra },  { name: redis } ]
minio_users:
  - { access_key: dba , secret_key: S3User.DBA, policy: consoleAdmin }
  - { access_key: pgbackrest , secret_key: S3User.Backup, policy: readwrite }

minio_seq

参数名称： minio_seq， 类型： int， 层次：I

MinIO 实例标识符，必需的身份参数。没有默认值，您必须手动分配。

minio_cluster

参数名称： minio_cluster， 类型： string， 层次：C

MinIO 集群名称，默认为 minio。当部署多个MinIO集群时，可以使用此参数进行区分。

minio_clean

参数名称： minio_clean， 类型： bool， 层次：G/C/A

是否在初始化时清理 MinIO ？默认为 false，即不清理现有数据。

minio_user

参数名称： minio_user， 类型： username， 层次：C

MinIO 操作系统用户名，默认为 minio。

minio_node

参数名称： minio_node， 类型： string， 层次：C

MinIO 节点名称模式，用于多节点部署。

默认值为：${minio_cluster}-${minio_seq}.pigsty，即以实例名 + .pigsty 后缀作为默认的节点名。

minio_data

参数名称： minio_data， 类型： path， 层次：C

MinIO 数据目录（们），默认值：/data/minio，这是单节点部署的常见目录。

对于多个磁盘部署，您可以使用 {x...y} 的记法来指定多个驱动器。

minio_domain

参数名称： minio_domain， 类型： string， 层次：G

MinIO 服务域名，默认为sss.pigsty。

客户端可以通过此域名访问 MinIO S3服务。此名称将注册到本地DNSMASQ，并包含在SSL证书字段中。

minio_port

参数名称： minio_port， 类型： port， 层次：C

MinIO 服务端口，默认为9000。

minio_admin_port

参数名称： minio_admin_port， 类型： port， 层次：C

MinIO 控制台端口，默认为9001。

minio_access_key

参数名称： minio_access_key， 类型： username， 层次：C

根访问用户名（access key），默认为minioadmin。

minio_secret_key

参数名称： minio_secret_key， 类型： password， 层次：C

根访问密钥（secret key），默认为minioadmin。

请务必在生产部署中更改此参数！

minio_extra_vars

参数名称： minio_extra_vars， 类型： string， 层次：C

MinIO 服务器的额外环境变量。查看Minio Server 文档以获取完整列表。

默认值为空字符串，您可以使用多行字符串来传递多个环境变量。

minio_alias

参数名称： minio_alias， 类型： string， 层次：G

本地MinIO集群的MinIO别名，默认值：sss，它将被写入基础设施节点/管理员用户的客户端别名配置文件中。

minio_buckets

参数名称： minio_buckets， 类型： bucket[]， 层次：C

默认创建的minio存储桶列表：

minio_buckets: [ { name: pgsql }, { name: infra },  { name: redis } ]

为模块PGSQL、INFRA和REDIS创建了三个默认的存储桶。

minio_users

参数名称： minio_users， 类型： user[]， 层次：C

要创建的minio用户列表，默认值：

minio_users:
  - { access_key: dba , secret_key: S3User.DBA, policy: consoleAdmin }
  - { access_key: pgbackrest , secret_key: S3User.Backup, policy: readwrite }

默认配置会为 PostgreSQL DBA 和 pgBackREST 创建两个默认用户。

请务必在您的部署中调整这些凭证！

REDIS

Redis 模块包含了20个配置参数。

#redis_cluster:             <集群> # Redis数据库集群名称，必选身份参数
#redis_node: 1              <节点> # Redis节点上的实例定义
#redis_instances: {}        <节点> # Redis节点编号，正整数，集群内唯一，必选身份参数
redis_fs_main: /data              # Redis主数据目录，默认为 `/data`
redis_exporter_enabled: true      # Redis Exporter 是否启用？
redis_exporter_port: 9121         # Redis Exporter监听端口
redis_exporter_options: ''        # Redis Exporter命令参数
redis_safeguard: false            # 禁止抹除现存的Redis
redis_clean: true                 # 初始化Redis是否抹除现存实例
redis_rmdata: true                # 移除Redis实例时是否一并移除数据？
redis_mode: standalone            # Redis集群模式：sentinel，cluster，standalone
redis_conf: redis.conf            # Redis配置文件模板，sentinel 除外
redis_bind_address: '0.0.0.0'     # Redis监听地址，默认留空则会绑定主机IP
redis_max_memory: 1GB             # Redis可用的最大内存
redis_mem_policy: allkeys-lru     # Redis内存逐出策略
redis_password: ''                # Redis密码，默认留空则禁用密码
redis_rdb_save: ['1200 1']        # Redis RDB 保存指令，字符串列表，空数组则禁用RDB
redis_aof_enabled: false          # Redis AOF 是否启用？
redis_rename_commands: {}         # Redis危险命令重命名列表
redis_cluster_replicas: 1         # Redis原生集群中每个主库配几个从库？

redis_cluster

参数名称： redis_cluster， 类型： string， 层次：C

身份参数，必选参数，必须显式在集群层面配置，将用作集群内资源的命名空间。

需要遵循特定命名规则：[a-z][a-z0-9-]*，以兼容不同约束对身份标识的要求，建议使用redis-作为集群名前缀。

redis_node

参数名称： redis_node， 类型： int， 层次：I

Redis节点序列号，身份参数，必选参数，必须显式在节点（Host）层面配置。

自然数，在集群中应当是唯一的，用于区别与标识集群内的不同节点，从0或1开始分配。

redis_instances

参数名称： redis_instances， 类型： dict， 层次：I

当前 Redis 节点上的 Redis 实例定义，必选参数，必须显式在节点（Host）层面配置。

内容为JSON KV对象格式。Key为数值类型端口号，Value为该实例特定的JSON配置项。

redis-test: # redis native cluster: 3m x 3s
  hosts:
    10.10.10.12: { redis_node: 1 ,redis_instances: { 6379: { } ,6380: { } ,6381: { } } }
    10.10.10.13: { redis_node: 2 ,redis_instances: { 6379: { } ,6380: { } ,6381: { } } }
  vars: { redis_cluster: redis-test ,redis_password: 'redis.test' ,redis_mode: cluster, redis_max_memory: 32MB }

每一个Redis实例在对应节点上监听一个唯一端口，实例配置项中replica_of 用于设置一个实例的上游主库地址，构建主从复制关系。

redis_instances:
    6379: {}
    6380: { replica_of: '10.10.10.13 6379' }
    6381: { replica_of: '10.10.10.13 6379' }

redis_fs_main

参数名称： redis_fs_main， 类型： path， 层次：C

Redis使用的主数据盘挂载点，默认为/data，Pigsty会在该目录下创建redis目录，用于存放Redis数据。

所以实际存储数据的目录为 /data/redis，该目录的属主为操作系统用户 redis，内部结构详情请参考 FHS：Redis

redis_exporter_enabled

参数名称： redis_exporter_enabled， 类型： bool， 层次：C

是否启用Redis监控组件 Redis Exporter？

默认启用，在每个Redis节点上部署一个，默认监听 redis_exporter_port 9121 端口。所有本节点上 Redis 实例的监控指标都由它负责抓取。

redis_exporter_port

参数名称： redis_exporter_port， 类型： port， 层次：C

Redis Exporter监听端口，默认值为：9121

redis_exporter_options

参数名称： redis_exporter_options， 类型： string， 层次：C/I

传给 Redis Exporter 的额外命令行参数，会被渲染到 /etc/defaut/redis_exporter 中，默认为空字符串。

redis_safeguard

参数名称： redis_safeguard， 类型： bool， 层次：G/C/A

Redis的防误删安全保险开关：打开后无法使用剧本抹除正在运行的 Redis 实例。

默认值为 false，如果设置为 true，那么当剧本遇到正在运行的 Redis 实例时，会中止初始化/抹除的操作，避免误删。

redis_clean

参数名称： redis_clean， 类型： bool， 层次：G/C/A

Redis清理开关：是否在初始化的过程中抹除运行中的Redis实例？默认值为：true。

剧本 redis.yml 会在执行时抹除具有相同定义的现有 Redis 实例，这样可以保证剧本的幂等性。

如果您不希望 redis.yml 这样做，可以将此参数设置为 false，那么当剧本遇到正在运行的 Redis 实例时，会中止初始化/抹除的操作，避免误删。

如果安全保险参数 redis_safeguard 已经打开，那么本参数的优先级低于该参数。

redis_rmdata

参数名称： redis_rmdata， 类型： bool， 层次：G/C/A

移除 Redis 实例的时候，是否一并移除 Redis 数据目录？默认为 true。

数据目录包含了 Redis 的 RDB与AOF文件，如果不抹除它们，那么新拉起的 Redis 实例将会从这些备份文件中加载数据。

redis_mode

参数名称： redis_mode， 类型： enum， 层次：C

Redis集群的工作模式，有三种选项：standalone, cluster, sentinel，默认值为 standalone

  • standalone：默认，独立的Redis主从模式
  • cluster： Redis原生集群模式
  • sentinel：Redis高可用组件：哨兵

当使用standalone模式时，Pigsty会根据 replica_of 参数设置Redis主从复制关系。

当使用cluster模式时，Pigsty会根据 redis_cluster_replicas 参数使用所有定义的实例创建原生Redis集群。

redis_conf

参数名称： redis_conf， 类型： string， 层次：C

Redis 配置模板路径，Sentinel除外。

默认值：redis.conf，这是一个模板文件，位于 roles/redis/templates/redis.conf。

如果你想使用自己的 Redis 配置模板，你可以将它放在 templates/ 目录中，并设置此参数为模板文件名。

注意： Redis Sentinel 使用的是另一个不同的模板文件，即 roles/redis/templates/redis-sentinel.conf。

redis_bind_address

参数名称： redis_bind_address， 类型： ip， 层次：C

Redis服务器绑定的IP地址，空字符串将使用配置清单中定义的主机名。

默认值：0.0.0.0，这将绑定到此主机上的所有可用 IPv4 地址。

在生产环境中出于安全性考虑，建议仅绑定内网 IP，即将此值设置为空字符串 ''

redis_max_memory

参数名称： redis_max_memory， 类型： size， 层次：C/I

每个 Redis 实例使用的最大内存配置，默认值：1GB。

redis_mem_policy

参数名称： redis_mem_policy， 类型： enum， 层次：C

Redis 内存回收策略，默认值：allkeys-lru，

  • noeviction：内存达限时不保存新值：当使用主从复制时仅适用于主库
  • allkeys-lru：保持最近使用的键；删除最近最少使用的键（LRU）
  • allkeys-lfu：保持频繁使用的键；删除最少频繁使用的键（LFU）
  • volatile-lru：删除带有真实过期字段的最近最少使用的键
  • volatile-lfu：删除带有真实过期字段的最少频繁使用的键
  • allkeys-random：随机删除键以为新添加的数据腾出空间
  • volatile-random：随机删除带有过期字段的键
  • volatile-ttl：删除带有真实过期字段和最短剩余生存时间（TTL）值的键。

详情请参阅Redis内存回收策略。

redis_password

参数名称： redis_password， 类型： password， 层次：C/N

Redis 密码，空字符串将禁用密码，这是默认行为。

注意，由于 redis_exporter 的实现限制，您每个节点只能设置一个 redis_password。这通常不是问题，因为 pigsty 不允许在同一节点上部署两个不同的 Redis 集群。

请在生产环境中使用强密码

redis_rdb_save

参数名称： redis_rdb_save， 类型： string[]， 层次：C

Redis RDB 保存指令，使用空列表则禁用 RDB。

默认值是 ["1200 1"]：如果最近20分钟至少有1个键更改，则将数据集转储到磁盘。

详情请参考 Redis持久化。

redis_aof_enabled

参数名称： redis_aof_enabled， 类型： bool， 层次：C

启用 Redis AOF 吗？默认值是 false，即不使用 AOF。

redis_rename_commands

参数名称： redis_rename_commands， 类型： dict， 层次：C

重命名 Redis 危险命令，这是一个 k:v 字典：old: new，old是待重命名的命令名称，new是重命名后的名字。

默认值：{}，你可以通过设置此值来隐藏像 FLUSHDB 和 FLUSHALL 这样的危险命令，下面是一个例子：

{
  "keys": "op_keys",
  "flushdb": "op_flushdb",
  "flushall": "op_flushall",
  "config": "op_config"  
}

redis_cluster_replicas

参数名称： redis_cluster_replicas， 类型： int， 层次：C

在 Redis 原生集群中，应当为一个 Master/Primary 实例配置多少个从库？默认值为： 1，即每个主库配一个从库。

redis_sentinel_monitor

参数名称： redis_sentinel_monitor， 类型： master[]， 层次：C

Redis哨兵监控的主库列表，只在哨兵集群上使用。每个待纳管的主库定义方式如下所示：

redis_sentinel_monitor:  # primary list for redis sentinel, use cls as name, primary ip:port
  - { name: redis-src, host: 10.10.10.45, port: 6379 ,password: redis.src, quorum: 1 }
  - { name: redis-dst, host: 10.10.10.48, port: 6379 ,password: redis.dst, quorum: 1 }

其中，name，host 是必选参数，port，password，quorum 是可选参数，quorum 用于设置判定主库失效所需的法定人数数，通常大于哨兵实例数的一半（默认为1）。

PGSQL

PGSQL 模块需要在 Pigsty 管理的节点上安装（即节点已经配置了 NODE 模块），同时还要求您的部署中有一套可用的 ETCD 集群来存储集群元数据。

在单个节点上安装 PGSQL 模块将创建一个独立的 PGSQL 服务器/实例，即主实例。 在额外节点上安装将创建只读副本，可以作为备用实例，并用于承载分担只读请求。 您还可以创建用于 ETL/OLAP/交互式查询的离线实例， 使用同步备库 和 法定人数提交 来提高数据一致性， 甚至搭建备份集群 和 延迟集群 以快速应对人为失误与软件缺陷导致的数据损失。

您可以定义多个 PGSQL 集群并进一步组建一个水平分片集群： Pigsty 支持原生的 citus 集群组，可以将您的标准 PGSQL 集群原地升级为一个分布式的数据库集群。

PG_ID

以下是一些常用的参数，用于标识 PGSQL 模块中的实体：集群、实例、服务等…

# pg_cluster:           #CLUSTER  # pgsql 集群名称，必需的标识参数
# pg_seq: 0             #INSTANCE # pgsql 实例序列号，必需的标识参数
# pg_role: replica      #INSTANCE # pgsql 角色，必需的，可以是 primary,replica,offline
# pg_instances: {}      #INSTANCE # 在节点上定义多个 pg 实例，使用 `{port:ins_vars}` 格式
# pg_upstream:          #INSTANCE # 备用集群或级联副本的 repl 上游 ip 地址
# pg_shard:             #CLUSTER  # pgsql 分片名称，分片集群的可选标识
# pg_group: 0           #CLUSTER  # pgsql 分片索引号，分片集群的可选标识
# gp_role: master       #CLUSTER  # 此集群的 greenplum 角色，可以是 master 或 segment
pg_offline_query: false #INSTANCE # 设置为 true 以在此实例上启用离线查询

您必须显式指定这些身份参数，它们没有默认值：

名称 类型 级别 扩展说明
pg_cluster string C PG 数据库集群名称
pg_seq number I PG 数据库实例 ID
pg_role enum I PG 数据库实例角色
pg_shard string C 数据库分片名称
pg_group number C 数据库分片序号
  • pg_cluster: 它标识集群的名称，该名称在集群级别配置。
  • pg_role: 在实例级别配置，标识 ins 的角色。只有 primary 角色会特别处理。如果不填写，默认为 replica 角色和特殊的 delayed 和 offline 角色。
  • pg_seq: 用于在集群内标识 ins，通常是从 0 或 1 递增的整数，一旦分配就不会更改。
  • {{ pg_cluster }}-{{ pg_seq }} 用于唯一标识 ins，即 pg_instance。
  • {{ pg_cluster }}-{{ pg_role }} 用于标识集群内的服务，即 pg_service。
  • pg_shard 和 pg_group 用于水平分片集群，仅用于 citus、greenplum 和 matrixdb。

pg_cluster、pg_role、pg_seq 是核心标识参数，对于任何 Postgres 集群都是必选的，并且必须显式指定。以下是一个示例：

pg-test:
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: replica}
    10.10.10.12: {pg_seq: 2, pg_role: primary}
    10.10.10.13: {pg_seq: 3, pg_role: replica}
  vars:
    pg_cluster: pg-test

所有其他参数都可以从全局配置或默认配置继承，但标识参数必须明确指定和手动分配。

pg_mode

参数名称： pg_mode， 类型： enum， 层次：C

PostgreSQL 集群模式，默认值为 pgsql，即标准的 PostgreSQL 集群。

可用的模式选项包括：

  • pgsql：标准的 PostgreSQL 集群
  • citus：Citus 分布式数据库集群
  • mssql：Babelfish MSSQL 线缆协议兼容内核
  • ivory：IvorySQL Oracle 兼容内核
  • polar：PolarDB for PostgreSQL 内核
  • oracle：PolarDB for Oracle 内核
  • gpsql：Greenplum 并行数据库集群（监控）

如果 pg_mode 设置为 citus 或 gpsql，则需要两个额外的必选身份参数 pg_shard 和 pg_group 来定义水平分片集群的身份。

在这两种情况下，每一个 PostgreSQL 集群都是一组更大的业务单元的一部分。

pg_cluster

参数名称： pg_cluster， 类型： string， 层次：C

PostgreSQL 集群名称，必选的身份标识参数,没有默认值

集群名将用作资源的命名空间。

集群命名需要遵循特定的命名模式：[a-z][a-z0-9-]*，即，只使用数字与小写字母，且不以数字开头，以符合标识上的不同约束的要求。

pg_seq

参数名称： pg_seq， 类型： int， 层次：I

PostgreSQL 实例序列号，必选的身份标识参数，无默认值。

此实例的序号，在其集群内是唯一分配的，通常使用自然数，从0或1开始分配，通常不会回收重用。

pg_role

参数名称： pg_role， 类型： enum， 层次：I

PostgreSQL 实例角色，必选的身份标识参数，无默认值。取值可以是：primary, replica, offline

PGSQL 实例的角色，可以是：primary、replica、standby 或 offline。

  • primary: 主实例，在集群中有且仅有一个。
  • replica: 用于承载在线只读流量的副本，高负载下可能会有轻微复制延迟（10ms~100ms, 100KB）。
  • offline: 用于处理离线只读流量的离线副本，如统计分析/ETL/个人查询等。

pg_instances

参数名称： pg_instances， 类型： dict， 层次：I

使用 {port:ins_vars} 的形式在一台主机上定义多个 PostgreSQL 实例。

此参数是为在单个节点上的多实例部署保留的参数，Pigsty 尚未实现此功能，并强烈建议独占节点部署。

pg_upstream

参数名称： pg_upstream， 类型： ip， 层次：I

备份集群或级联从库的上游实例 IP 地址。

在集群的 primary 实例上设置 pg_upstream ，表示此集群是一个备份集群，该实例将作为 standby leader，从上游集群接收并应用更改。

对非 primary 实例设置 pg_upstream 参数将指定一个具体实例作为物理复制的上游，如果与主实例 ip 地址不同，此实例将成为 级联副本 。确保上游 IP 地址是同一集群中的另一个实例是用户的责任。

pg_shard

参数名称： pg_shard， 类型： string， 层次：C

PostgreSQL 水平分片名称，对于分片集群来说（例如 citus 集群），这是的必选标识参数。

当多个标准的 PostgreSQL 集群一起以水平分片方式为同一业务提供服务时，Pigsty 将此组集群标记为 水平分片集群。

pg_shard 是分片组名称。它通常是 pg_cluster 的前缀。

例如，如果我们有一个分片组 pg-citus，并且其中有4个集群，它们的标识参数将是：

cls pg_shard: pg-citus
cls pg_group = 0:   pg-citus0
cls pg_group = 1:   pg-citus1
cls pg_group = 2:   pg-citus2
cls pg_group = 3:   pg-citus3

pg_group

参数名称： pg_group， 类型： int， 层次：C

PostgreSQL 水平分片集群的分片索引号，对于分片集群来说（例如 citus 集群），这是的必选标识参数。

此参数与 pg_shard 配对使用，通常可以使用非负整数作为索引号。

gp_role

参数名称： gp_role， 类型： enum， 层次：C

PostgreSQL 集群的 Greenplum/Matrixdb 角色，可以是 master 或 segment。

  • master: 标记 postgres 集群为 greenplum 主实例（协调节点），这是默认值。
  • segment 标记 postgres 集群为 greenplum 段集群（数据节点）。

此参数仅用于 Greenplum/MatrixDB 数据库 （pg_mode 为 gpsql），对于普通的 PostgreSQL 集群没有意义。

pg_exporters

参数名称： pg_exporters， 类型： dict， 层次：C

额外用于监控远程 PostgreSQL 实例的 Exporter 定义，默认值：{}

如果您希望监控远程 PostgreSQL 实例，请在监控系统所在节点（Infra节点）集群上的 pg_exporters 参数中定义它们，并使用 pgsql-monitor.yml 剧本来完成部署。

pg_exporters: # list all remote instances here, alloc a unique unused local port as k
    20001: { pg_cluster: pg-foo, pg_seq: 1, pg_host: 10.10.10.10 }
    20004: { pg_cluster: pg-foo, pg_seq: 2, pg_host: 10.10.10.11 }
    20002: { pg_cluster: pg-bar, pg_seq: 1, pg_host: 10.10.10.12 }
    20003: { pg_cluster: pg-bar, pg_seq: 1, pg_host: 10.10.10.13 }

pg_offline_query

参数名称： pg_offline_query， 类型： bool， 层次：I

设置为 true 以在此实例上启用离线查询，默认为 false。

当某个 PostgreSQL 实例启用此参数时， 属于 dbrole_offline 分组的用户可以直接连接到该 PostgreSQL 实例上执行离线查询（慢查询，交互式查询，ETL/分析类查询）。

带有此标记的实例在效果上类似于为实例设置 pg_role = offline ，唯一的区别在于 offline 实例默认不会承载 replica 服务的请求，是作为专用的离线/分析从库实例而存在的。

如果您没有富余的实例可以专门用于此目的，则可以挑选一台普通的从库，在实例层次启用此参数，以便在需要时承载离线查询。

PG_BUSINESS

定制集群模板：用户，数据库，服务，权限规则。

用户需重点关注此部分参数，因为这里是业务声明自己所需数据库对象的地方。

默认的数据库用户及其凭据，强烈建议在生产环境中修改这些用户的密码。

# postgres business object definition, overwrite in group vars
pg_users: []                      # postgres business users
pg_databases: []                  # postgres business databases
pg_services: []                   # postgres business services
pg_hba_rules: []                  # business hba rules for postgres
pgb_hba_rules: []                 # business hba rules for pgbouncer
# global credentials, overwrite in global vars
pg_dbsu_password: ''              # dbsu password, empty string means no dbsu password by default
pg_replication_username: replicator
pg_replication_password: DBUser.Replicator
pg_admin_username: dbuser_dba
pg_admin_password: DBUser.DBA
pg_monitor_username: dbuser_monitor
pg_monitor_password: DBUser.Monitor

pg_users

参数名称： pg_users， 类型： user[]， 层次：C

PostgreSQL 业务用户列表，需要在 PG 集群层面进行定义。默认值为：[] 空列表。

每一个数组元素都是一个 用户/角色 定义，例如：

- name: dbuser_meta               # 必需，`name` 是用户定义的唯一必选字段
  password: DBUser.Meta           # 可选，密码，可以是 scram-sha-256 哈希字符串或明文
  login: true                     # 可选，默认情况下可以登录
  superuser: false                # 可选，默认为 false，是超级用户吗？
  createdb: false                 # 可选，默认为 false，可以创建数据库吗？
  createrole: false               # 可选，默认为 false，可以创建角色吗？
  inherit: true                   # 可选，默认情况下，此角色可以使用继承的权限吗？
  replication: false              # 可选，默认为 false，此角色可以进行复制吗？
  bypassrls: false                # 可选，默认为 false，此角色可以绕过行级安全吗？
  pgbouncer: true                 # 可选，默认为 false，将此用户添加到 pgbouncer 用户列表吗？（使用连接池的生产用户应该显式定义为 true）
  connlimit: -1                   # 可选，用户连接限制，默认 -1 禁用限制
  expire_in: 3650                 # 可选，此角色过期时间：从创建时 + n天计算（优先级比 expire_at 更高）
  expire_at: '2030-12-31'         # 可选，此角色过期的时间点，使用 YYYY-MM-DD 格式的字符串指定一个特定日期（优先级没 expire_in 高）
  comment: pigsty admin user      # 可选，此用户/角色的说明与备注字符串
  roles: [dbrole_admin]           # 可选，默认角色为：dbrole_{admin,readonly,readwrite,offline}
  parameters: {}                  # 可选，使用 `ALTER ROLE SET` 针对这个角色，配置角色级的数据库参数
  pool_mode: transaction          # 可选，默认为 transaction 的 pgbouncer 池模式，用户级别
  pool_connlimit: -1              # 可选，用户级别的最大数据库连接数，默认 -1 禁用限制
  search_path: public             # 可选，根据 postgresql 文档的键值配置参数（例如：使用 pigsty 作为默认 search_path）

pg_databases

参数名称： pg_databases， 类型： database[]， 层次：C

PostgreSQL 业务数据库列表，需要在 PG 集群层面进行定义。默认值为：[] 空列表。

每一个数组元素都是一个 业务数据库 定义，例如：

- name: meta                      # 必选，`name` 是数据库定义的唯一必选字段
  baseline: cmdb.sql              # 可选，数据库 sql 的基线定义文件路径（ansible 搜索路径中的相对路径，如 files/）
  pgbouncer: true                 # 可选，是否将此数据库添加到 pgbouncer 数据库列表？默认为 true
  schemas: [pigsty]               # 可选，要创建的附加模式，由模式名称字符串组成的数组
  extensions:                     # 可选，要安装的附加扩展： 扩展对象的数组
    - { name: postgis , schema: public }  # 可以指定将扩展安装到某个模式中，也可以不指定（不指定则安装到 search_path 首位模式中）
    - { name: timescaledb }               # 例如有的扩展会创建并使用固定的模式，就不需要指定模式。
  comment: pigsty meta database   # 可选，数据库的说明与备注信息
  owner: postgres                 # 可选，数据库所有者，默认为 postgres
  template: template1             # 可选，要使用的模板，默认为 template1，目标必须是一个模板数据库
  encoding: UTF8                  # 可选，数据库编码，默认为 UTF8（必须与模板数据库相同）
  locale: C                       # 可选，数据库地区设置，默认为 C（必须与模板数据库相同）
  lc_collate: C                   # 可选，数据库 collate 排序规则，默认为 C（必须与模板数据库相同），没有理由不建议更改。
  lc_ctype: C                     # 可选，数据库 ctype 字符集，默认为 C（必须与模板数据库相同）
  tablespace: pg_default          # 可选，默认表空间，默认为 'pg_default'
  allowconn: true                 # 可选，是否允许连接，默认为 true。显式设置 false 将完全禁止连接到此数据库
  revokeconn: false               # 可选，撤销公共连接权限。默认为 false，设置为 true 时，属主和管理员之外用户的 CONNECT 权限会被回收
  register_datasource: true       # 可选，是否将此数据库注册到 grafana 数据源？默认为 true，显式设置为 false 会跳过注册
  connlimit: -1                   # 可选，数据库连接限制，默认为 -1 ，不限制，设置为正整数则会限制连接数。
  pool_auth_user: dbuser_meta     # 可选，连接到此 pgbouncer 数据库的所有连接都将使用此用户进行验证（启用 pgbouncer_auth_query 才有用）
  pool_mode: transaction          # 可选，数据库级别的 pgbouncer 池化模式，默认为 transaction
  pool_size: 64                   # 可选，数据库级别的 pgbouncer 默认池子大小，默认为 64
  pool_size_reserve: 32           # 可选，数据库级别的 pgbouncer 池子保留空间，默认为 32，当默认池子不够用时，最多再申请这么多条突发连接。
  pool_size_min: 0                # 可选，数据库级别的 pgbouncer 池的最小大小，默认为 0
  pool_max_db_conn: 100           # 可选，数据库级别的最大数据库连接数，默认为 100

在每个数据库定义对象中，只有 name 是必选字段，其他的字段都是可选项。

pg_services

参数名称： pg_services， 类型： service[]， 层次：C

PostgreSQL 服务列表，需要在 PG 集群层面进行定义。默认值为：[] ，空列表。

用于在数据库集群层面定义额外的服务，数组中的每一个对象定义了一个服务，一个完整的服务定义样例如下：

- name: standby                   # 必选，服务名称，最终的 svc 名称会使用 `pg_cluster` 作为前缀，例如：pg-meta-standby
  port: 5435                      # 必选，暴露的服务端口（作为 kubernetes 服务节点端口模式）
  ip: "*"                         # 可选，服务绑定的 IP 地址，默认情况下为所有 IP 地址
  selector: "[]"                  # 必选，服务成员选择器，使用 JMESPath 来筛选配置清单
  backup: "[? pg_role == `primary`]"  # 可选，服务成员选择器（备份），也就是当默认选择器选中的实例都宕机后，服务才会由这里选中的实例成员来承载
  dest: default                   # 可选，目标端口，default|postgres|pgbouncer|<port_number>，默认为 'default'，Default的意思就是使用 pg_default_service_dest 的取值来最终决定
  check: /sync                    # 可选，健康检查 URL 路径，默认为 /，这里使用 Patroni API：/sync ，只有同步备库和主库才会返回 200 健康状态码 
  maxconn: 5000                   # 可选，允许的前端连接最大数，默认为5000
  balance: roundrobin             # 可选，haproxy 负载均衡算法（默认为 roundrobin，其他选项：leastconn）
  options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

请注意，本参数用于在集群层面添加额外的服务。如果您想在全局定义所有 PostgreSQL 数据库都要提供的服务，可以使用 pg_default_services 参数。

pg_hba_rules

参数名称： pg_hba_rules， 类型： hba[]， 层次：C

数据库集群/实例的客户端IP黑白名单规则。默认为：[] 空列表。

对象数组，每一个对象都代表一条规则， hba 规则对象的定义形式如下：

- title: allow intranet password access
  role: common
  rules:
    - host   all  all  10.0.0.0/8      md5
    - host   all  all  172.16.0.0/12   md5
    - host   all  all  192.168.0.0/16  md5
  • title： 规则的标题名称，会被渲染为 HBA 文件中的注释。
  • rules：规则数组，每个元素是一条标准的 HBA 规则字符串。
  • role：规则的应用范围，哪些实例角色会启用这条规则？
    • common：对于所有实例生效
    • primary, replica,offline： 只针对特定的角色 pg_role 实例生效。
    • 特例：role: 'offline' 的规则除了会应用在 pg_role : offline 的实例上，对于带有 pg_offline_query 标记的实例也生效。

除了上面这种原生 HBA 规则定义形式，Pigsty 还提供了另外一种更为简便的别名形式：

- addr: 'intra'    # world|intra|infra|admin|local|localhost|cluster|<cidr>
  auth: 'pwd'      # trust|pwd|ssl|cert|deny|<official auth method>
  user: 'all'      # all|${dbsu}|${repl}|${admin}|${monitor}|<user>|<group>
  db: 'all'        # all|replication|....
  rules: []        # raw hba string precedence over above all
  title: allow intranet password access

pg_default_hba_rules 与本参数基本类似，但它是用于定义全局的 HBA 规则，而本参数通常用于定制某个集群/实例的 HBA 规则。

pgb_hba_rules

参数名称： pgb_hba_rules， 类型： hba[]， 层次：C

Pgbouncer 业务HBA规则，默认值为： []， 空数组。

此参数与 pg_hba_rules 基本类似，都是 hba 规则对象的数组，区别在于本参数是为 Pgbouncer 准备的。

pgb_default_hba_rules 与本参数基本类似，但它是用于定义全局连接池 HBA 规则，而本参数通常用于定制某个连接池集群/实例的 HBA 规则。

pg_replication_username

参数名称： pg_replication_username， 类型： username， 层次：G

PostgreSQL 物理复制用户名，默认使用 replicator，不建议修改此参数。

pg_replication_password

参数名称： pg_replication_password， 类型： password， 层次：G

PostgreSQL 物理复制用户密码，默认值为：DBUser.Replicator。

警告：请在生产环境中修改此密码！

pg_admin_username

参数名称： pg_admin_username， 类型： username， 层次：G

PostgreSQL / Pgbouncer 管理员名称，默认为：dbuser_dba。

这是全局使用的数据库管理员，具有数据库的 Superuser 权限与连接池的流量管理权限，请务必控制使用范围。

pg_admin_password

参数名称： pg_admin_password， 类型： password， 层次：G

PostgreSQL / Pgbouncer 管理员密码，默认为： DBUser.DBA。

警告：请在生产环境中修改此密码！

pg_monitor_username

参数名称： pg_monitor_username， 类型： username， 层次：G

PostgreSQL/Pgbouncer 监控用户名，默认为：dbuser_monitor。

这是一个用于监控的数据库/连接池用户，不建议修改此用户名。

但如果您的现有数据库使用了不同的监控用户，可以在指定监控目标时使用此参数传入使用的监控用户名。

pg_monitor_password

参数名称： pg_monitor_password， 类型： password， 层次：G

PostgreSQL/Pgbouncer 监控用户使用的密码，默认为：DBUser.Monitor。

请尽可能不要在密码中使用 @:/ 这些容易与 URL 分隔符混淆的字符，减少不必要的麻烦。

警告：请在生产环境中修改此密码！

pg_dbsu_password

参数名称： pg_dbsu_password， 类型： password， 层次：G/C

PostgreSQL pg_dbsu 超级用户密码，默认是空字符串，即不为其设置密码。

我们不建议为 dbsu 配置密码登陆，这会增大攻击面。例外情况是：pg_mode = citus，这时候需要为每个分片集群的 dbsu 配置密码，以便在分片集群内部进行连接。

PG_INSTALL

本节负责安装 PostgreSQL 及其扩展。如果您希望安装不同大版本与扩展插件，修改 pg_version 与 pg_extensions 即可，不过请注意，并不是所有扩展都在所有大版本可用。

pg_dbsu: postgres                 # os 数据库超级用户名称，默认为 postgres，最好不要更改
pg_dbsu_uid: 26                   # os 数据库超级用户 uid 和 gid，默认为 26，适用于默认的 postgres 用户和组
pg_dbsu_sudo: limit               # 数据库超级用户 sudo 权限，可选 none,limit,all,nopass。默认为 limit
pg_dbsu_home: /var/lib/pgsql      # postgresql 主目录，默认为 `/var/lib/pgsql`
pg_dbsu_ssh_exchange: true        # 是否在相同的 pgsql 集群中交换 postgres 数据库超级用户的 ssh 密钥
pg_version: 16                    # 要安装的 postgres 主版本，默认为 15
pg_bin_dir: /usr/pgsql/bin        # postgres 二进制目录，默认为 `/usr/pgsql/bin`
pg_log_dir: /pg/log/postgres      # postgres 日志目录，默认为 `/pg/log/postgres`
pg_packages:                      # pg packages to be installed, alias can be used
  - postgresql
  - patroni pgbouncer pgbackrest pg_exporter pgbadger vip-manager wal2json pg_repack
pg_extensions:                    # pg extensions to be installed, alias can be used
  - postgis timescaledb pgvector

pg_dbsu

参数名称： pg_dbsu， 类型： username， 层次：C

PostgreSQL 使用的操作系统 dbsu 用户名， 默认为 postgres，改这个用户名是不太明智的。

不过在特定情况下，您可能会使用到不同于 postgres 的用户名，例如在安装配置 Greenplum / MatrixDB 时，需要使用 gpadmin / mxadmin 作为相应的操作系统超级用户。

pg_dbsu_uid

参数名称： pg_dbsu_uid， 类型： int， 层次：C

操作系统数据库超级用户的 uid 和 gid，26 是 PGDG RPM 默认的 postgres 用户 UID/GID。

对于 Debian/Ubuntu 系统，没有默认值，且 26 号用户经常被占用。因此Pigsty 在检测到安装环境为 Debian 系，且 uid 为 26 时，会自动使用替换的 pg_dbsu_uid = 543。

pg_dbsu_sudo

参数名称： pg_dbsu_sudo， 类型： enum， 层次：C

数据库超级用户的 sudo 权限，可以是 none、limit、all 或 nopass。默认为 limit

  • none: 无 Sudo 权限

  • limit: 有限的 sudo 权限，用于执行与数据库相关的组件的 systemctl 命令（默认选项）。

  • all: 完全的 sudo 权限，需要密码。

  • nopass: 不需要密码的完全 sudo 权限（不推荐）。

  • 默认值为 limit，只允许执行 sudo systemctl <start|stop|reload> <postgres|patroni|pgbouncer|...> 。

pg_dbsu_home

参数名称： pg_dbsu_home， 类型： path， 层次：C

postgresql 主目录，默认为 /var/lib/pgsql，与官方的 pgdg RPM 保持一致。

pg_dbsu_ssh_exchange

参数名称： pg_dbsu_ssh_exchange， 类型： bool， 层次：C

是否在同一 PostgreSQL 集群中交换操作系统 dbsu 的 ssh 密钥？

默认值为 true，意味着同一集群中的数据库超级用户可以互相 ssh 访问。

pg_version

参数名称： pg_version， 类型： enum， 层次：C

要安装的 postgres 主版本，默认为 16。

请注意，PostgreSQL 的物理流复制不能跨主要版本，因此最好不要在实例级别上配置此项。

您可以使用 pg_packages 和 pg_extensions 中的参数来为特定的 PG 大版本安装不同的软件包与扩展。

pg_bin_dir

参数名称： pg_bin_dir， 类型： path， 层次：C

PostgreSQL 二进制程序目录，默认为 /usr/pgsql/bin。

默认值是在安装过程中手动创建的软链接，指向安装的特定的 Postgres 版本目录。

例如 /usr/pgsql -> /usr/pgsql-15。在 Ubuntu/Debian 上则指向 /usr/lib/postgresql/15/bin。

更多详细信息，请查看 PGSQL 文件结构。

pg_log_dir

参数名称： pg_log_dir， 类型： path， 层次：C

PostgreSQL 日志目录，默认为：/pg/log/postgres，Promtail 会使用此变量收集 PostgreSQL 日志。

请注意，如果日志目录 pg_log_dir 以数据库目录 pg_data 作为前缀，则不会显式创建（数据库目录初始化时自动创建）。

pg_packages

参数名称： pg_packages， 类型： string[]， 层次：C

要安装的 PostgreSQL 软件包（rpm/deb），这是一个由软件包名组成的数组，每个元素都是逗号或空格分割的 PG 软件包名。

默认值为 PostgreSQL 内核，以及支持 PG RDS 的核心组件，以及两个重要的扩展插件 pg_repack 与 wal2json。

pg_packages:                      # pg packages to be installed, alias can be used
  - postgresql
  - patroni pgbouncer pgbackrest pg_exporter pgbadger vip-manager wal2json pg_repack

从 Pigsty v3 开始，您可以在本参数中使用roles/node_id/vars 中由 pg_package_map 指定的包别名。

使用包别名的好处是，您无需操心 PostgreSQL 相关软件包在不同系统平台上的包名，架构，以及大版本号，从而屏蔽了不同 OS 之间的区别：

定义在这里的软件包会首先经过 pg_package_map 的翻译，然后经过 PG 大版本号的替换，最后安装实际的 RPM/DEB 包。

您也可以直接指定最终安装的 RPM/DEB 包名称，包名中的 ${pg_version} 或 $v 版本号占位符将被替换为具体的大版本号 pg_version 。

pg_extensions

参数名称： pg_extensions， 类型： string[]， 层次：G/C

要安装的 PostgreSQL 扩展包（rpm/deb），这是一个由扩展包名组成的数组，每个元素都是逗号或空格分割的 PG 扩展包名。

本参数在形式上与 pg_packages 一致，但是通常用于指定需要安装的扩展插件，而且在这里指定的软件包会升级到可用的最新版本。

本参数的默认值为 PG 扩展生态最重要的三个扩展插件：postgis, timescaledb, pgvector。

pg_extensions:                    # pg extensions to be installed, alias can be used
  - postgis timescaledb pgvector  # 注意：在 EL7 中，postgis 应该使用 postgis33 代替

完整可用的扩展列表，已经在 Pigsty 默认生成的配置文件中给出，用户按需使用即可。例如，以下是 EL9 中可用的扩展插件列表：

pg_extensions: # extensions to be installed on this cluster
  - timescaledb periods temporal_tables emaj table_version pg_cron pg_later pg_background pg_timetable
  - postgis pgrouting pointcloud pg_h3 q3c ogr_fdw geoip #pg_geohash #mobilitydb
  - pgvector pgvectorscale pg_vectorize pg_similarity pg_tiktoken pgml #smlar
  - pg_search pg_bigm zhparser hunspell
  - hydra pg_analytics pg_lakehouse pg_duckdb duckdb_fdw pg_fkpart pg_partman plproxy #pg_strom citus
  - pg_hint_plan age hll rum pg_graphql pg_jsonschema jsquery index_advisor hypopg imgsmlr pg_ivm pgmq pgq #rdkit
  - pg_tle plv8 pllua plprql pldebugger plpgsql_check plprofiler plsh #pljava plr pgtap faker dbt2
  - prefix semver pgunit md5hash asn1oid roaringbitmap pgfaceting pgsphere pg_country pg_currency pgmp numeral pg_rational pguint ip4r timestamp9 chkpass #pg_uri #pgemailaddr #acl #debversion #pg_rrule
  - topn pg_gzip pg_http pg_net pg_html5_email_address pgsql_tweaks pg_extra_time pg_timeit count_distinct extra_window_functions first_last_agg tdigest aggs_for_arrays pg_arraymath pg_idkit pg_uuidv7 permuteseq pg_hashids
  - sequential_uuids pg_math pg_random pg_base36 pg_base62 floatvec pg_financial pgjwt pg_hashlib shacrypt cryptint pg_ecdsa pgpcre icu_ext envvar url_encode #pg_zstd #aggs_for_vecs #quantile #lower_quantile #pgqr #pg_protobuf
  - pg_repack pg_squeeze pg_dirtyread pgfincore pgdd ddlx pg_prioritize pg_checksums pg_readonly safeupdate pg_permissions pgautofailover pg_catcheck preprepare pgcozy pg_orphaned pg_crash pg_cheat_funcs pg_savior table_log pg_fio #pgpool pgagent
  - pg_profile pg_show_plans pg_stat_kcache pg_stat_monitor pg_qualstats pg_store_plans pg_track_settings pg_wait_sampling system_stats pg_meta pgnodemx pg_sqlog bgw_replstatus pgmeminfo toastinfo pagevis powa pg_top #pg_statviz #pgexporter_ext #pg_mon
  - passwordcheck supautils pgsodium pg_vault anonymizer pg_tde pgsmcrypto pgaudit pgauditlogtofile pg_auth_mon credcheck pgcryptokey pg_jobmon logerrors login_hook set_user pg_snakeoil pgextwlist pg_auditor noset #sslutils
  - wrappers multicorn odbc_fdw mysql_fdw tds_fdw sqlite_fdw pgbouncer_fdw mongo_fdw redis_fdw pg_redis_pubsub kafka_fdw hdfs_fdw firebird_fdw aws_s3 log_fdw #oracle_fdw #db2_fdw #jdbc_fdw
  - orafce pgtt session_variable pg_statement_rollback pg_dbms_metadata pg_dbms_lock pgmemcache #pg_dbms_job #wiltondb
  - pglogical pgl_ddl_deploy pg_failover_slots wal2json wal2mongo decoderbufs decoder_raw mimeo pgcopydb pgloader pg_fact_loader pg_bulkload pg_comparator pgimportdoc pgexportdoc #repmgr #slony
  - gis-stack rag-stack fdw-stack fts-stack etl-stack feat-stack olap-stack supa-stack stat-stack json-stack

完整列表请参考：roles/node_id/vars

PG_BOOTSTRAP

使用 Patroni 引导拉起 PostgreSQL 集群，并设置 1:1 对应的 Pgbouncer 连接池。

它还会使用 PG_PROVISION 中定义的默认角色、用户、权限、模式、扩展来初始化数据库集群

pg_safeguard: false               # prevent purging running postgres instance? false by default
pg_clean: true                    # purging existing postgres during pgsql init? true by default
pg_data: /pg/data                 # postgres data directory, `/pg/data` by default
pg_fs_main: /data                 # mountpoint/path for postgres main data, `/data` by default
pg_fs_bkup: /data/backups         # mountpoint/path for pg backup data, `/data/backup` by default
pg_storage_type: SSD              # storage type for pg main data, SSD,HDD, SSD by default
pg_dummy_filesize: 64MiB          # size of `/pg/dummy`, hold 64MB disk space for emergency use
pg_listen: '0.0.0.0'              # postgres/pgbouncer listen addresses, comma separated list
pg_port: 5432                     # postgres listen port, 5432 by default
pg_localhost: /var/run/postgresql # postgres unix socket dir for localhost connection
patroni_enabled: true             # if disabled, no postgres cluster will be created during init
patroni_mode: default             # patroni working mode: default,pause,remove
pg_namespace: /pg                 # top level key namespace in etcd, used by patroni & vip
patroni_port: 8008                # patroni listen port, 8008 by default
patroni_log_dir: /pg/log/patroni  # patroni log dir, `/pg/log/patroni` by default
patroni_ssl_enabled: false        # secure patroni RestAPI communications with SSL?
patroni_watchdog_mode: off        # patroni watchdog mode: automatic,required,off. off by default
patroni_username: postgres        # patroni restapi username, `postgres` by default
patroni_password: Patroni.API     # patroni restapi password, `Patroni.API` by default
pg_primary_db: postgres           # primary database name, used by citus,etc... ,postgres by default
pg_parameters: {}                 # extra parameters in postgresql.auto.conf
pg_files: []                      # extra files to be copied to postgres data directory (e.g. license)
pg_conf: oltp.yml                 # config template: oltp,olap,crit,tiny. `oltp.yml` by default
pg_max_conn: auto                 # postgres max connections, `auto` will use recommended value
pg_shared_buffer_ratio: 0.25      # postgres shared buffers ratio, 0.25 by default, 0.1~0.4
pg_rto: 30                        # recovery time objective in seconds,  `30s` by default
pg_rpo: 1048576                   # recovery point objective in bytes, `1MiB` at most by default
pg_libs: 'pg_stat_statements, auto_explain'  # preloaded libraries, `pg_stat_statements,auto_explain` by default
pg_delay: 0                       # replication apply delay for standby cluster leader
pg_checksum: false                # enable data checksum for postgres cluster?
pg_pwd_enc: scram-sha-256         # passwords encryption algorithm: md5,scram-sha-256
pg_encoding: UTF8                 # database cluster encoding, `UTF8` by default
pg_locale: C                      # database cluster local, `C` by default
pg_lc_collate: C                  # database cluster collate, `C` by default
pg_lc_ctype: en_US.UTF8           # database character type, `en_US.UTF8` by default
pgbouncer_enabled: true           # if disabled, pgbouncer will not be launched on pgsql host
pgbouncer_port: 6432              # pgbouncer listen port, 6432 by default
pgbouncer_log_dir: /pg/log/pgbouncer  # pgbouncer log dir, `/pg/log/pgbouncer` by default
pgbouncer_auth_query: false       # query postgres to retrieve unlisted business users?
pgbouncer_poolmode: transaction   # pooling mode: transaction,session,statement, transaction by default
pgbouncer_sslmode: disable        # pgbouncer client ssl mode, disable by default

pg_safeguard

参数名称： pg_safeguard， 类型： bool， 层次：G/C/A

是否防止清除正在运行的Postgres实例？默认为：false。

如果启用，pgsql.yml 和 pgsql-rm.yml 在检测到任何正在运行的postgres实例时将立即中止。

pg_clean

参数名称： pg_clean， 类型： bool， 层次：G/C/A

在 PostgreSQL 初始化期间清除现有的 PG 实例吗？默认为：true。

默认值为true，在 pgsql.yml 初始化期间它将清除现有的postgres实例，这使得playbook具有幂等性。

如果设置为 false，pgsql.yml 会在遇到正在运行的 PostgreSQL 实例时中止。而 pgsql-rm.yml 将不会删除 PostgreSQL 的数据目录（只会停止服务器）。

pg_data

参数名称： pg_data， 类型： path， 层次：C

Postgres 数据目录，默认为 /pg/data。

这是一个指向底层实际数据目录的符号链接，在多处被使用，请不要修改它。参阅 PGSQL文件结构 获取详细信息。

pg_fs_main

参数名称： pg_fs_main， 类型： path， 层次：C

PostgreSQL 主数据盘的挂载点/文件系统路径，默认为/data。

默认值：/data，它将被用作 PostgreSQL 主数据目录（/data/postgres）的父目录。

建议使用 NVME SSD 作为 PostgreSQL 主数据存储，Pigsty默认为SSD存储进行了优化，但是也支持HDD。

您可以更改pg_storage_type为HDD以针对HDD存储进行优化。

pg_fs_bkup

参数名称： pg_fs_bkup， 类型： path， 层次：C

PostgreSQL 备份数据盘的挂载点/文件系统路径，默认为/data/backup。

如果您使用的是默认的 pgbackrest_method = local，建议为备份存储使用一个单独的磁盘。

备份磁盘应足够大，以容纳所有的备份，至少足以容纳3个基础备份+2天的WAL归档。 通常容量不是什么大问题，因为您可以使用便宜且大的机械硬盘作为备份盘。

建议为备份存储使用一个单独的磁盘，否则 Pigsty 将回退到主数据磁盘，并占用主数据盘的容量与IO。

pg_storage_type

参数名称： pg_storage_type， 类型： enum， 层次：C

PostgreSQL 数据存储介质的类型：SSD或HDD，默认为SSD。

默认值：SSD，它会影响一些调优参数，如 random_page_cost 和 effective_io_concurrency 。

pg_dummy_filesize

参数名称： pg_dummy_filesize， 类型： size， 层次：C

/pg/dummy的大小，默认值为64MiB，用于紧急使用的64MB磁盘空间。

当磁盘已满时，删除占位符文件可以为紧急使用释放一些空间，建议生产使用至少8GiB。

pg_listen

参数名称： pg_listen， 类型： ip， 层次：C

PostgreSQL / Pgbouncer 的监听地址，默认为0.0.0.0（所有ipv4地址）。

您可以在此变量中使用占位符，例如：'${ip},${lo}'或'${ip},${vip},${lo}'：

  • ${ip}：转换为 inventory_hostname，它是配置清单中定义的首要内网IP地址。
  • ${vip}：如果启用了pg_vip_enabled，将使用pg_vip_address的主机部分。
  • ${lo}：将替换为127.0.0.1

对于高安全性要求的生产环境，建议限制监听的IP地址。

pg_port

参数名称： pg_port， 类型： port， 层次：C

PostgreSQL 服务器监听的端口，默认为 5432。

pg_localhost

参数名称： pg_localhost， 类型： path， 层次：C

本地主机连接 PostgreSQL 使用的 Unix套接字目录，默认值为/var/run/postgresql。

PostgreSQL 和 Pgbouncer 本地连接的Unix套接字目录，pg_exporter 和 patroni 都会优先使用 Unix 套接字访问 PostgreSQL。

pg_namespace

参数名称： pg_namespace， 类型： path， 层次：C

在 etcd 中使用的顶级命名空间，由 patroni 和 vip-manager 使用，默认值是：/pg，不建议更改。

patroni_enabled

参数名称： patroni_enabled， 类型： bool， 层次：C

是否启用 Patroni ？默认值为：true。

如果禁用，则在初始化期间不会创建Postgres集群。Pigsty将跳过拉起 patroni的任务，当试图向现有的postgres实例添加一些组件时，可以使用此参数。

patroni_mode

参数名称： patroni_mode， 类型： enum， 层次：C

Patroni 工作模式：default，pause，remove。默认值：default。

  • default：正常使用 Patroni 引导 PostgreSQL 集群
  • pause：与default相似，但在引导后进入维护模式
  • remove：使用Patroni初始化集群，然后删除Patroni并使用原始 PostgreSQL。

patroni_port

参数名称： patroni_port， 类型： port， 层次：C

patroni监听端口，默认为8008，不建议更改。

Patroni API服务器在此端口上监听健康检查和API请求。

patroni_log_dir

参数名称： patroni_log_dir， 类型： path， 层次：C

patroni日志目录，默认为/pg/log/patroni，由promtail收集。

patroni_ssl_enabled

参数名称： patroni_ssl_enabled， 类型： bool， 层次：G

使用SSL保护patroni RestAPI通信吗？默认值为false。

此参数是一个全局标志，只能在部署之前预先设置。因为如果为 patroni 启用了SSL，您将必须使用 HTTPS 而不是 HTTP 执行健康检查、获取指标，调用API。

patroni_watchdog_mode

参数名称： patroni_watchdog_mode， 类型： string， 层次：C

patroni看门狗模式：automatic，required，off，默认值为 off。

在主库故障的情况下，Patroni 可以使用看门狗 来强制关机旧主库节点以避免脑裂。

  • off：不使用看门狗。完全不进行 Fencing （默认行为）
  • automatic：如果内核启用了softdog模块并且看门狗属于dbsu，则启用 watchdog。
  • required：强制启用 watchdog，如果softdog不可用则拒绝启动 Patroni/PostgreSQL。

默认值为off，您不应该在 Infra节点 启用看门狗，数据一致性优先于可用性的关键系统，特别是与钱有关的业务集群可以考虑打开此选项。

请注意，如果您的所有访问流量都使用 HAproxy 健康检查服务接入，正常是不存在脑裂风险的。

patroni_username

参数名称： patroni_username， 类型： username， 层次：C

Patroni REST API 用户名，默认为postgres，与patroni_password 配对使用。

Patroni的危险 REST API （比如重启集群）由额外的用户名/密码保护，查看配置集群和Patroni RESTAPI以获取详细信息。

patroni_password

参数名称： patroni_password， 类型： password， 层次：C

Patroni REST API 密码，默认为Patroni.API。

警告：务必生产环境中修改此参数！

pg_primary_db

参数名称： pg_primary_db， 类型： string， 层次：C

指定集群中的主数据库名称，用于 citus 等业务数据库，默认为 postgres。

例如，在使用 Patroni 管理高可用的 Citus 集群时，您必须选择一个 “主数据库”。

此外，在这里指定的数据库名称，将在 PGSQL 模块安装完成后，显示在打印的连接串中。

pg_parameters

参数名称： pg_parameters， 类型： dict， 层次：G/C/I

可用于指定并管理 postgresql.auto.conf 中的配置参数。

当集群所有实例完成初始化后，pg_param 任务将会把本字典中的 key / value 键值对依次覆盖写入 /pg/data/postgresql.auto.conf 中。

注意：请不要手工修改该配置文件，或通过 ALTER SYSTEM 修改集群配置参数，修改会在下一次配置同步时被覆盖。

该变量的优先级大于 Patroni / DCS 中的集群配置（即优先级高于集群配置，由 Patroni edit-config 编辑的配置），因此通常可以在实例级别覆盖集群默认参数。

当您的集群成员有着不同的规格（不推荐的行为！）时，您可以通过本参数对每个实例的配置进行精细化管理。

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary , pg_parameters: { shared_buffers: '5GB' } }
    10.10.10.12: { pg_seq: 2, pg_role: replica , pg_parameters: { shared_buffers: '4GB' } }
    10.10.10.13: { pg_seq: 3, pg_role: replica , pg_parameters: { shared_buffers: '3GB' } }

请注意，一些 重要的集群参数（对主从库参数值有要求）是 Patroni 直接通过命令行参数管理的，具有最高优先级，无法通过此方式覆盖，对于这些参数，您必须使用 Patroni edit-config 进行管理与配置。

在主从上必须保持一致的 PostgreSQL 参数（不一致会导致从库无法启动！）：

  • wal_level
  • max_connections
  • max_locks_per_transaction
  • max_worker_processes
  • max_prepared_transactions
  • track_commit_timestamp

在主从上最好保持一致的参数（考虑到主从切换的可能性）：

  • listen_addresses
  • port
  • cluster_name
  • hot_standby
  • wal_log_hints
  • max_wal_senders
  • max_replication_slots
  • wal_keep_segments
  • wal_keep_size

您可以设置不存在的参数（例如来自扩展的 GUC，从而配置 ALTER SYSTEM 无法修改的“尚未存在”的参数），但将现有配置修改为非法值可能会导致 PostgreSQL 无法启动，请谨慎配置！

pg_files

参数名称： pg_files， 类型： path[]， 层次：C

用于指定需要拷贝至PGDATA目录的文件列表，默认为空数组：[]

在本参数中指定的文件将会被拷贝至 {{ pg_data }} 目录下，这主要用于下发特殊商业版本 PostgreSQL 内核要求的 License 文件。

目前仅有 PolarDB （Oracle兼容）内核需要许可证文件，例如，您可以将 license.lic 文件放置在 files/ 目录下，并在 pg_files 中指定：

pg_files: [ license.lic ]

pg_conf

参数名称： pg_conf， 类型： enum， 层次：C

配置模板：{oltp,olap,crit,tiny}.yml，默认为oltp.yml。

  • tiny.yml：为小节点、虚拟机、小型演示优化（1-8核，1-16GB）
  • oltp.yml：为OLTP工作负载和延迟敏感应用优化（4C8GB+）（默认模板）
  • olap.yml：为OLAP工作负载和吞吐量优化（4C8G+）
  • crit.yml：为数据一致性和关键应用优化（4C8G+）

默认值：oltp.yml，但是配置程序将在当前节点为小节点时将此值设置为 tiny.yml。

您可以拥有自己的模板，只需将其放在templates/<mode>.yml下，并将此值设置为模板名称即可使用。

pg_max_conn

参数名称： pg_max_conn， 类型： int， 层次：C

PostgreSQL 服务器最大连接数。你可以选择一个介于 50 到 5000 之间的值，或使用 auto 选择推荐值。

默认值为 auto，会根据 pg_conf 和 pg_default_service_dest 来设定最大连接数。

  • tiny: 100
  • olap: 200
  • oltp: 200 (pgbouncer) / 1000 (postgres)
    • pg_default_service_dest = pgbouncer : 200
    • pg_default_service_dest = postgres : 1000
  • crit: 200 (pgbouncer) / 1000 (postgres)
    • pg_default_service_dest = pgbouncer : 200
    • pg_default_service_dest = postgres : 1000

不建议将此值设定为超过 5000，否则你还需要手动增加 haproxy 服务的连接限制。

Pgbouncer 的事务池可以缓解过多的 OLTP 连接问题，因此默认情况下不建议设置很大的连接数。

对于 OLAP 场景， pg_default_service_dest 修改为 postgres 可以绕过连接池。

pg_shared_buffer_ratio

参数名称： pg_shared_buffer_ratio， 类型： float， 层次：C

Postgres 共享缓冲区内存比例，默认为 0.25，正常范围在 0.1~0.4 之间。

默认值：0.25，意味着节点内存的 25% 将被用作 PostgreSQL 的分片缓冲区。如果您想为 PostgreSQL 启用大页，那么此参数值应当适当小于 node_hugepage_ratio。

将此值设定为大于 0.4（40%）通常不是好主意，但在极端情况下可能有用。

注意，共享缓冲区只是 PostgreSQL 中共享内存的一部分，要计算总共享内存，使用 show shared_memory_size_in_huge_pages;。

pg_rto

参数名称： pg_rto， 类型： int， 层次：C

以秒为单位的恢复时间目标（RTO）。这将用于计算 Patroni 的 TTL 值，默认为 30 秒。

如果主实例在这么长时间内失踪，将触发新的领导者选举，此值并非越低越好，它涉及到利弊权衡：

减小这个值可以减少集群故障转移期间的不可用时间（无法写入）， 但会使集群对短期网络抖动更加敏感，从而增加误报触发故障转移的几率。

您需要根据网络状况和业务约束来配置这个值，在故障几率和故障影响之间做出权衡， 默认值是 30s，它将影响以下的 Patroni 参数：

# 获取领导者租约的 TTL（以秒为单位）。将其视为启动自动故障转移过程之前的时间长度。默认值：30
ttl: {{ pg_rto }}

# 循环将休眠的秒数。默认值：10，这是 patroni 检查循环间隔
loop_wait: {{ (pg_rto / 3)|round(0, 'ceil')|int }}

# DCS 和 PostgreSQL 操作重试的超时时间（以秒为单位）。比这短的 DCS 或网络问题不会导致 Patroni 降级领导。默认值：10
retry_timeout: {{ (pg_rto / 3)|round(0, 'ceil')|int }}

# 主实例在触发故障转移之前允许从故障中恢复的时间（以秒为单位），最大 RTO：2 倍循环等待 + primary_start_timeout
primary_start_timeout: {{ (pg_rto / 3)|round(0, 'ceil')|int }}

pg_rpo

参数名称： pg_rpo， 类型： int， 层次：C

以字节为单位的恢复点目标（RPO），默认值：1048576。

默认为 1MiB，这意味着在故障转移期间最多可以容忍 1MiB 的数据丢失。

当主节点宕机并且所有副本都滞后时，你必须做出一个艰难的选择，在可用性和一致性之间进行权衡：

  • 提升一个从库成为新的主库，并尽快将系统恢复服务，但要付出可接受的数据丢失代价（例如，少于 1MB）。
  • 等待主库重新上线（可能永远不会），或人工干预以避免任何数据丢失。

你可以使用 crit.yml conf 模板来确保在故障转移期间没有数据丢失，但这会牺牲一些性能。

pg_libs

参数名称： pg_libs， 类型： string， 层次：C

预加载的动态共享库，默认为 pg_stat_statements,auto_explain，这是两个 PostgreSQL 自带的扩展，强烈建议启用。

对于现有集群，您可以直接配置集群的 shared_preload_libraries 参数并应用生效。

如果您想使用 TimescaleDB 或 Citus 扩展，您需要将 timescaledb 或 citus 添加到此列表中。timescaledb 和 citus 应当放在这个列表的最前面，例如：

citus,timescaledb,pg_stat_statements,auto_explain

其他需要动态加载的扩展也可以添加到这个列表中，例如 pg_cron， pgml 等，通常 citus 和 timescaledb 有着最高的优先级，应该添加到列表的最前面。

pg_delay

参数名称： pg_delay， 类型： interval， 层次：I

延迟备库复制延迟，默认值：0。

如果此值被设置为一个正值，备用集群主库在应用 WAL 变更之前将被延迟这个时间。设置为 1h 意味着该集群中的数据将始终滞后原集群一个小时。

查看 延迟备用集群 以获取详细信息。

pg_checksum

参数名称： pg_checksum， 类型： bool， 层次：C

为 PostgreSQL 集群启用数据校验和吗？默认值是 false，不启用。

这个参数只能在 PGSQL 部署之前设置（但你可以稍后手动启用它）。

如果使用 pg_conf crit.yml 模板，无论此参数如何，都会始终启用数据校验和，以确保数据完整性。

pg_pwd_enc

参数名称： pg_pwd_enc， 类型： enum， 层次：C

密码加密算法：md5 或 scram-sha-256，默认值：scram-sha-256。

前者已经不再安全，如果你与旧客户端有兼容性问题，你可以将其设置为 md5。

pg_encoding

参数名称： pg_encoding， 类型： enum， 层次：C

数据库集群编码，默认为 UTF8。

不建议使用其他非 UTF8 系编码。

pg_locale

参数名称： pg_locale， 类型： enum， 层次：C

数据库集群编码，默认为 UTF8。

数据库集群本地化规则集，默认为 UTF8。

pg_lc_collate

参数名称： pg_lc_collate， 类型： enum， 层次：C

数据库集群本地化排序规则，默认为 C。

除非您知道自己在做什么，否则不建议修改集群级别的本地排序规则设置。

pg_lc_ctype

参数名称： pg_lc_ctype， 类型： enum， 层次：C

数据库字符集 CTYPE，默认为 en_US.UTF8。

pgbouncer_enabled

参数名称： pgbouncer_enabled， 类型： bool， 层次：C

默认值为 true，如果禁用，将不会在 PGSQL节点上配置连接池 Pgbouncer。

pgbouncer_port

参数名称： pgbouncer_port， 类型： port， 层次：C

Pgbouncer 监听端口，默认为 6432。

pgbouncer_log_dir

参数名称： pgbouncer_log_dir， 类型： path， 层次：C

Pgbouncer 日志目录，默认为 /pg/log/pgbouncer，日志代理 promtail 会根据此参数收集 Pgbouncer 日志。

pgbouncer_auth_query

参数名称： pgbouncer_auth_query， 类型： bool， 层次：C

是否允许 Pgbouncer 查询 PostgreSQL，以允许未显式列出的用户通过连接池访问 PostgreSQL？默认值是 false。

如果启用，pgbouncer 用户将使用 SELECT username, password FROM monitor.pgbouncer_auth($1) 对 postgres 数据库进行身份验证，否则，只有带有 pgbouncer: true 的业务用户才被允许连接到 Pgbouncer 连接池。

pgbouncer_poolmode

参数名称： pgbouncer_poolmode， 类型： enum， 层次：C

Pgbouncer 连接池池化模式：transaction,session,statement，默认为 transaction。

  • session：会话级池化，具有最佳的功能兼容性。
  • transaction：事务级池化，具有更好的性能（许多小连接），可能会破坏某些会话级特性，如NOTIFY/LISTEN 等…
  • statements：语句级池化，用于简单的只读查询。

如果您的应用出现功能兼容性问题，可以考虑修改此参数为 session。

pgbouncer_sslmode

参数名称： pgbouncer_sslmode， 类型： enum， 层次：C

Pgbouncer 客户端 ssl 模式，默认为 disable。

注意，启用 SSL 可能会对你的 pgbouncer 产生巨大的性能影响。

  • disable：如果客户端请求 TLS 则忽略（默认）
  • allow：如果客户端请求 TLS 则使用。如果没有则使用纯TCP。不验证客户端证书。
  • prefer：与 allow 相同。
  • require：客户端必须使用 TLS。如果没有则拒绝客户端连接。不验证客户端证书。
  • verify-ca：客户端必须使用有效的客户端证书的TLS。
  • verify-full：与 verify-ca 相同。

PG_PROVISION

如果说 PG_BOOTSTRAP 是创建一个新的集群，那么 PG_PROVISION 就是在集群中创建默认的对象，包括：

pg_provision: true                # 在引导后提供postgres集群
pg_init: pg-init                  # 集群模板的初始化脚本，默认为`pg-init`
pg_default_roles:                 # postgres集群中的默认角色和用户
  - { name: dbrole_readonly  ,login: false ,comment: role for global read-only access     }
  - { name: dbrole_offline   ,login: false ,comment: role for restricted read-only access }
  - { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment: role for global read-write access }
  - { name: dbrole_admin     ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment: role for object creation }
  - { name: postgres     ,superuser: true  ,comment: system superuser }
  - { name: replicator ,replication: true  ,roles: [pg_monitor, dbrole_readonly] ,comment: system replicator }
  - { name: dbuser_dba   ,superuser: true  ,roles: [dbrole_admin]  ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment: pgsql admin user }
  - { name: dbuser_monitor ,roles: [pg_monitor] ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }
pg_default_privileges:            # 管理员用户创建时的默认权限
  - GRANT USAGE      ON SCHEMAS   TO dbrole_readonly
  - GRANT SELECT     ON TABLES    TO dbrole_readonly
  - GRANT SELECT     ON SEQUENCES TO dbrole_readonly
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_readonly
  - GRANT USAGE      ON SCHEMAS   TO dbrole_offline
  - GRANT SELECT     ON TABLES    TO dbrole_offline
  - GRANT SELECT     ON SEQUENCES TO dbrole_offline
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_offline
  - GRANT INSERT     ON TABLES    TO dbrole_readwrite
  - GRANT UPDATE     ON TABLES    TO dbrole_readwrite
  - GRANT DELETE     ON TABLES    TO dbrole_readwrite
  - GRANT USAGE      ON SEQUENCES TO dbrole_readwrite
  - GRANT UPDATE     ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE   ON TABLES    TO dbrole_admin
  - GRANT REFERENCES ON TABLES    TO dbrole_admin
  - GRANT TRIGGER    ON TABLES    TO dbrole_admin
  - GRANT CREATE     ON SCHEMAS   TO dbrole_admin
pg_default_schemas: [ monitor ]   # 默认模式
pg_default_extensions:            # 默认扩展
  - { name: adminpack          ,schema: pg_catalog }
  - { name: pg_stat_statements ,schema: monitor }
  - { name: pgstattuple        ,schema: monitor }
  - { name: pg_buffercache     ,schema: monitor }
  - { name: pageinspect        ,schema: monitor }
  - { name: pg_prewarm         ,schema: monitor }
  - { name: pg_visibility      ,schema: monitor }
  - { name: pg_freespacemap    ,schema: monitor }
  - { name: postgres_fdw       ,schema: public  }
  - { name: file_fdw           ,schema: public  }
  - { name: btree_gist         ,schema: public  }
  - { name: btree_gin          ,schema: public  }
  - { name: pg_trgm            ,schema: public  }
  - { name: intagg             ,schema: public  }
  - { name: intarray           ,schema: public  }
  - { name: pg_repack }
pg_reload: true                   # HBA变化后是否重载配置？
pg_default_hba_rules:             # postgres 默认 HBA 规则集
  - {user: '${dbsu}'    ,db: all         ,addr: local     ,auth: ident ,title: 'dbsu access via local os user ident'  }
  - {user: '${dbsu}'    ,db: replication ,addr: local     ,auth: ident ,title: 'dbsu replication from local os ident' }
  - {user: '${repl}'    ,db: replication ,addr: localhost ,auth: pwd   ,title: 'replicator replication from localhost'}
  - {user: '${repl}'    ,db: replication ,addr: intra     ,auth: pwd   ,title: 'replicator replication from intranet' }
  - {user: '${repl}'    ,db: postgres    ,addr: intra     ,auth: pwd   ,title: 'replicator postgres db from intranet' }
  - {user: '${monitor}' ,db: all         ,addr: localhost ,auth: pwd   ,title: 'monitor from localhost with password' }
  - {user: '${monitor}' ,db: all         ,addr: infra     ,auth: pwd   ,title: 'monitor from infra host with password'}
  - {user: '${admin}'   ,db: all         ,addr: infra     ,auth: ssl   ,title: 'admin @ infra nodes with pwd & ssl'   }
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: ssl   ,title: 'admin @ everywhere with ssl & pwd'    }
  - {user: '+dbrole_readonly',db: all    ,addr: localhost ,auth: pwd   ,title: 'pgbouncer read/write via local socket'}
  - {user: '+dbrole_readonly',db: all    ,addr: intra     ,auth: pwd   ,title: 'read/write biz user via password'     }
  - {user: '+dbrole_offline' ,db: all    ,addr: intra     ,auth: pwd   ,title: 'allow etl offline tasks from intranet'}
pgb_default_hba_rules:            # pgbouncer 默认 HBA 规则集
  - {user: '${dbsu}'    ,db: pgbouncer   ,addr: local     ,auth: peer  ,title: 'dbsu local admin access with os ident'}
  - {user: 'all'        ,db: all         ,addr: localhost ,auth: pwd   ,title: 'allow all user local access with pwd' }
  - {user: '${monitor}' ,db: pgbouncer   ,addr: intra     ,auth: pwd   ,title: 'monitor access via intranet with pwd' }
  - {user: '${monitor}' ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other monitor access addr' }
  - {user: '${admin}'   ,db: all         ,addr: intra     ,auth: pwd   ,title: 'admin access via intranet with pwd'   }
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other admin access addr'   }
  - {user: 'all'        ,db: all         ,addr: intra     ,auth: pwd   ,title: 'allow all user intra access with pwd' }

pg_provision

参数名称： pg_provision， 类型： bool， 层次：C

在集群拉起后，完整本节定义的 PostgreSQL 集群置备工作。默认值为true。

如果禁用，不会置备 PostgreSQL 集群。对于一些特殊的 “PostgreSQL” 集群，比如 Greenplum，可以关闭此选项跳过置备阶段。

pg_init

参数名称： pg_init， 类型： string， 层次：G/C

用于初始化数据库模板的Shell脚本位置，默认为 pg-init，该脚本会被拷贝至/pg/bin/pg-init后执行。

该脚本位于 roles/pgsql/templates/pg-init

你可以在该脚本中添加自己的逻辑，或者提供一个新的脚本放置在 templates/ 目录下，并将 pg_init 设置为新的脚本名称。使用自定义脚本时请保留现有的初始化逻辑。

pg_default_roles

参数名称： pg_default_roles， 类型： role[]， 层次：G/C

Postgres 集群中的默认角色和用户。

Pigsty有一个内置的角色系统，请查看PGSQL访问控制：角色系统了解详情。

pg_default_roles:                 # postgres集群中的默认角色和用户
  - { name: dbrole_readonly  ,login: false ,comment: role for global read-only access     }
  - { name: dbrole_offline   ,login: false ,comment: role for restricted read-only access }
  - { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment: role for global read-write access }
  - { name: dbrole_admin     ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment: role for object creation }
  - { name: postgres     ,superuser: true  ,comment: system superuser }
  - { name: replicator ,replication: true  ,roles: [pg_monitor, dbrole_readonly] ,comment: system replicator }
  - { name: dbuser_dba   ,superuser: true  ,roles: [dbrole_admin]  ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment: pgsql admin user }
  - { name: dbuser_monitor ,roles: [pg_monitor] ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }

pg_default_privileges

参数名称： pg_default_privileges， 类型： string[]， 层次：G/C

每个数据库中的默认权限（DEFAULT PRIVILEGE）设置：

pg_default_privileges:            # 管理员用户创建时的默认权限
  - GRANT USAGE      ON SCHEMAS   TO dbrole_readonly
  - GRANT SELECT     ON TABLES    TO dbrole_readonly
  - GRANT SELECT     ON SEQUENCES TO dbrole_readonly
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_readonly
  - GRANT USAGE      ON SCHEMAS   TO dbrole_offline
  - GRANT SELECT     ON TABLES    TO dbrole_offline
  - GRANT SELECT     ON SEQUENCES TO dbrole_offline
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_offline
  - GRANT INSERT     ON TABLES    TO dbrole_readwrite
  - GRANT UPDATE     ON TABLES    TO dbrole_readwrite
  - GRANT DELETE     ON TABLES    TO dbrole_readwrite
  - GRANT USAGE      ON SEQUENCES TO dbrole_readwrite
  - GRANT UPDATE     ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE   ON TABLES    TO dbrole_admin
  - GRANT REFERENCES ON TABLES    TO dbrole_admin
  - GRANT TRIGGER    ON TABLES    TO dbrole_admin
  - GRANT CREATE     ON SCHEMAS   TO dbrole_admin

Pigsty 基于默认角色系统提供了相应的默认权限设置，请查看PGSQL访问控制：权限了解详情。

pg_default_schemas

参数名称： pg_default_schemas， 类型： string[]， 层次：G/C

要创建的默认模式，默认值为：[ monitor ]，这将在所有数据库上创建一个monitor模式，用于放置各种监控扩展、表、视图、函数。

pg_default_extensions

参数名称： pg_default_extensions， 类型： extension[]， 层次：G/C

要在所有数据库中默认创建启用的扩展列表，默认值：

pg_default_extensions: # default extensions to be created
  - { name: adminpack          ,schema: pg_catalog }
  - { name: pg_stat_statements ,schema: monitor }
  - { name: pgstattuple        ,schema: monitor }
  - { name: pg_buffercache     ,schema: monitor }
  - { name: pageinspect        ,schema: monitor }
  - { name: pg_prewarm         ,schema: monitor }
  - { name: pg_visibility      ,schema: monitor }
  - { name: pg_freespacemap    ,schema: monitor }
  - { name: postgres_fdw       ,schema: public  }
  - { name: file_fdw           ,schema: public  }
  - { name: btree_gist         ,schema: public  }
  - { name: btree_gin          ,schema: public  }
  - { name: pg_trgm            ,schema: public  }
  - { name: intagg             ,schema: public  }
  - { name: intarray           ,schema: public  }
  - { name: pg_repack }

唯一的三方扩展是 pg_repack，这对于数据库维护很重要，所有其他扩展都是内置的 PostgreSQL Contrib 扩展插件。

监控相关的扩展默认安装在 monitor 模式中，该模式由pg_default_schemas创建。

pg_reload

参数名称： pg_reload， 类型： bool， 层次：A

在hba更改后重新加载 PostgreSQL，默认值为true

当您想在应用HBA更改之前进行检查时，将其设置为false以禁用自动重新加载配置。

pg_default_hba_rules

参数名称： pg_default_hba_rules， 类型： hba[]， 层次：G/C

PostgreSQL 基于主机的认证规则，全局默认规则定义。默认值为：

pg_default_hba_rules:             # postgres default host-based authentication rules
  - {user: '${dbsu}'    ,db: all         ,addr: local     ,auth: ident ,title: 'dbsu access via local os user ident'  }
  - {user: '${dbsu}'    ,db: replication ,addr: local     ,auth: ident ,title: 'dbsu replication from local os ident' }
  - {user: '${repl}'    ,db: replication ,addr: localhost ,auth: pwd   ,title: 'replicator replication from localhost'}
  - {user: '${repl}'    ,db: replication ,addr: intra     ,auth: pwd   ,title: 'replicator replication from intranet' }
  - {user: '${repl}'    ,db: postgres    ,addr: intra     ,auth: pwd   ,title: 'replicator postgres db from intranet' }
  - {user: '${monitor}' ,db: all         ,addr: localhost ,auth: pwd   ,title: 'monitor from localhost with password' }
  - {user: '${monitor}' ,db: all         ,addr: infra     ,auth: pwd   ,title: 'monitor from infra host with password'}
  - {user: '${admin}'   ,db: all         ,addr: infra     ,auth: ssl   ,title: 'admin @ infra nodes with pwd & ssl'   }
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: ssl   ,title: 'admin @ everywhere with ssl & pwd'    }
  - {user: '+dbrole_readonly',db: all    ,addr: localhost ,auth: pwd   ,title: 'pgbouncer read/write via local socket'}
  - {user: '+dbrole_readonly',db: all    ,addr: intra     ,auth: pwd   ,title: 'read/write biz user via password'     }
  - {user: '+dbrole_offline' ,db: all    ,addr: intra     ,auth: pwd   ,title: 'allow etl offline tasks from intranet'}

默认值为常见场景提供了足够的安全级别，请查看PGSQL身份验证了解详情。

本参数为 HBA规则对象组成的数组，在形式上与 pg_hba_rules 完全一致。 建议在全局配置统一的 pg_default_hba_rules，针对特定集群使用 pg_hba_rules 进行额外定制。两个参数中的规则都会依次应用，后者优先级更高。

pgb_default_hba_rules

参数名称： pgb_default_hba_rules， 类型： hba[]， 层次：G/C

pgbouncer default host-based authentication rules, array or hba rule object.

default value provides a fair enough security level for common scenarios, check PGSQL Authentication for details.

pgb_default_hba_rules:            # pgbouncer default host-based authentication rules
  - {user: '${dbsu}'    ,db: pgbouncer   ,addr: local     ,auth: peer  ,title: 'dbsu local admin access with os ident'}
  - {user: 'all'        ,db: all         ,addr: localhost ,auth: pwd   ,title: 'allow all user local access with pwd' }
  - {user: '${monitor}' ,db: pgbouncer   ,addr: intra     ,auth: pwd   ,title: 'monitor access via intranet with pwd' }
  - {user: '${monitor}' ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other monitor access addr' }
  - {user: '${admin}'   ,db: all         ,addr: intra     ,auth: pwd   ,title: 'admin access via intranet with pwd'   }
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other admin access addr'   }
  - {user: 'all'        ,db: all         ,addr: intra     ,auth: pwd   ,title: 'allow all user intra access with pwd' }

默认的Pgbouncer HBA规则很简单：

  1. 允许从本地使用密码登陆
  2. 允许从内网网断使用密码登陆

用户可以按照自己的需求进行定制。

本参数在形式上与 pgb_hba_rules 完全一致，建议在全局配置统一的 pgb_default_hba_rules，针对特定集群使用 pgb_hba_rules 进行额外定制。两个参数中的规则都会依次应用，后者优先级更高。

PG_BACKUP

本节定义了用于 pgBackRest 的变量，它被用于 PGSQL 时间点恢复 PITR 。

查看 PGSQL 备份 & PITR 以获取详细信息。

pgbackrest_enabled: true          # 在 pgsql 主机上启用 pgBackRest 吗？
pgbackrest_clean: true            # 初始化时删除 pg 备份数据？
pgbackrest_log_dir: /pg/log/pgbackrest # pgbackrest 日志目录，默认为 `/pg/log/pgbackrest`
pgbackrest_method: local          # pgbackrest 仓库方法：local, minio, [用户定义...]
pgbackrest_repo:                  # pgbackrest 仓库：https://pgbackrest.org/configuration.html#section-repository
  local:                          # 默认使用本地 posix 文件系统的 pgbackrest 仓库
    path: /pg/backup              # 本地备份目录，默认为 `/pg/backup`
    retention_full_type: count    # 按计数保留完整备份
    retention_full: 2             # 使用本地文件系统仓库时，最多保留 3 个完整备份，至少保留 2 个
  minio:                          # pgbackrest 的可选 minio 仓库
    type: s3                      # minio 是与 s3 兼容的，所以使用 s3
    s3_endpoint: sss.pigsty       # minio 端点域名，默认为 `sss.pigsty`
    s3_region: us-east-1          # minio 区域，默认为 us-east-1，对 minio 无效
    s3_bucket: pgsql              # minio 桶名称，默认为 `pgsql`
    s3_key: pgbackrest            # pgbackrest 的 minio 用户访问密钥
    s3_key_secret: S3User.Backup  # pgbackrest 的 minio 用户秘密密钥
    s3_uri_style: path            # 对 minio 使用路径风格的 uri，而不是主机风格
    path: /pgbackrest             # minio 备份路径，默认为 `/pgbackrest`
    storage_port: 9000            # minio 端口，默认为 9000
    storage_ca_file: /etc/pki/ca.crt  # minio ca 文件路径，默认为 `/etc/pki/ca.crt`
    bundle: y                     # 将小文件打包成一个文件
    cipher_type: aes-256-cbc      # 为远程备份仓库启用 AES 加密
    cipher_pass: pgBackRest       # AES 加密密码，默认为 'pgBackRest'
    retention_full_type: time     # 在 minio 仓库上按时间保留完整备份
    retention_full: 14            # 保留过去 14 天的完整备份

pgbackrest_enabled

参数名称： pgbackrest_enabled， 类型： bool， 层次：C

是否在 PGSQL 节点上启用 pgBackRest？默认值为： true

在使用本地文件系统备份仓库（local）时，只有集群主库才会真正启用 pgbackrest。其他实例只会初始化一个空仓库。

pgbackrest_clean

参数名称： pgbackrest_clean， 类型： bool， 层次：C

初始化时删除 PostgreSQL 备份数据吗？默认值为 true。

pgbackrest_log_dir

参数名称： pgbackrest_log_dir， 类型： path， 层次：C

pgBackRest 日志目录，默认为 /pg/log/pgbackrest，promtail 日志代理会引用此参数收集日志。

pgbackrest_method

参数名称： pgbackrest_method， 类型： enum， 层次：C

pgBackRest 仓库方法：默认可选项为：local、minio 或其他用户定义的方法，默认为 local。

此参数用于确定用于 pgBackRest 的仓库，所有可用的仓库方法都在 pgbackrest_repo 中定义。

Pigsty 默认使用 local 备份仓库，这将在主实例的 /pg/backup 目录上创建一个备份仓库。底层存储路径由 pg_fs_bkup 指定。

pgbackrest_repo

参数名称： pgbackrest_repo， 类型： dict， 层次：G/C

pgBackRest 仓库文档：https://pgbackrest.org/configuration.html#section-repository

默认值包括两种仓库方法：local 和 minio，定义如下：

pgbackrest_repo:                  # pgbackrest 仓库：https://pgbackrest.org/configuration.html#section-repository
  local:                          # 默认使用本地 posix 文件系统的 pgbackrest 仓库
    path: /pg/backup              # 本地备份目录，默认为 `/pg/backup`
    retention_full_type: count    # 按计数保留完整备份
    retention_full: 2             # 使用本地文件系统仓库时，最多保留 3 个完整备份，至少保留 2 个
  minio:                          # pgbackrest 的可选 minio 仓库
    type: s3                      # minio 是与 s3 兼容的，所以使用 s3
    s3_endpoint: sss.pigsty       # minio 端点域名，默认为 `sss.pigsty`
    s3_region: us-east-1          # minio 区域，默认为 us-east-1，对 minio 无效
    s3_bucket: pgsql              # minio 桶名称，默认为 `pgsql`
    s3_key: pgbackrest            # pgbackrest 的 minio 用户访问密钥
    s3_key_secret: S3User.Backup  # pgbackrest 的 minio 用户秘密密钥
    s3_uri_style: path            # 对 minio 使用路径风格的 uri，而不是主机风格
    path: /pgbackrest             # minio 备份路径，默认为 `/pgbackrest`
    storage_port: 9000            # minio 端口，默认为 9000
    storage_ca_file: /etc/pki/ca.crt  # minio ca 文件路径，默认为 `/etc/pki/ca.crt`
    bundle: y                     # 将小文件打包成一个文件
    cipher_type: aes-256-cbc      # 为远程备份仓库启用 AES 加密
    cipher_pass: pgBackRest       # AES 加密密码，默认为 'pgBackRest'
    retention_full_type: time     # 在 minio 仓库上按时间保留完整备份
    retention_full: 14            # 保留过去 14 天的完整备份

您可以定义新的备份仓库，例如使用 AWS S3，GCP 或其他云供应商的 S3 兼容存储服务。

PG_SERVICE

本节介绍如何将PostgreSQL服务暴露给外部世界，包括：

  • 使用haproxy在不同的端口上暴露不同的PostgreSQL服务
  • 使用vip-manager将可选的L2 VIP绑定到主实例
  • 在基础设施节点上使用dnsmasq注册集群/实例DNS记录
pg_weight: 100          #实例 # 服务中的相对负载均衡权重，默认为100，范围0-255
pg_default_service_dest: pgbouncer # 如果svc.dest='default'，则此为默认服务目的地
pg_default_services:              # postgres默认服务定义
  - { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
  - { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
  - { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }
  - { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}
pg_vip_enabled: false             # 为pgsql主要实例启用l2 vip吗? 默认为false
pg_vip_address: 127.0.0.1/24      # `<ipv4>/<mask>`格式的vip地址，如果启用vip则需要
pg_vip_interface: eth0            # vip网络接口监听，默认为eth0
pg_dns_suffix: ''                 # pgsql dns后缀，默认为空
pg_dns_target: auto               # auto、primary、vip、none或特定的ip

pg_weight

参数名称： pg_weight， 类型： int， 层次：G

服务中的相对负载均衡权重，默认为100，范围0-255。

默认值： 100。您必须在实例变量中定义它，并重载服务以生效。

pg_service_provider

参数名称： pg_service_provider， 类型： string， 层次：G/C

专用的haproxy节点组名，或默认为本地节点的空字符串。

如果指定，PostgreSQL服务将注册到专用的haproxy节点组，而不是当下的 PGSQL 集群节点。

请记住为每个服务在专用的 haproxy 节点上分配唯一的端口！

例如，如果我们在3节点的 pg-test 集群上定义以下参数：

pg_service_provider: infra       # use load balancer on group `infra`
pg_default_services:             # alloc port 10001 and 10002 for pg-test primary/replica service  
  - { name: primary ,port: 10001 ,dest: postgres  ,check: /primary   ,selector: "[]" }
  - { name: replica ,port: 10002 ,dest: postgres  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }

pg_default_service_dest

参数名称： pg_default_service_dest， 类型： enum， 层次：G/C

当定义一个服务时，如果 svc.dest='default'，此参数将用作默认值。

默认值： pgbouncer，意味着5433主服务和5434副本服务将默认将流量路由到 pgbouncer。

如果您不想使用pgbouncer，将其设置为postgres。流量将直接路由到 postgres。

pg_default_services

参数名称： pg_default_services， 类型： service[]， 层次：G/C

postgres默认服务定义

默认值是四个默认服务定义，如PGSQL Service所述

pg_default_services:               # postgres default service definitions
  - { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
  - { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
  - { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }
  - { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}

pg_vip_enabled

参数名称： pg_vip_enabled， 类型： bool， 层次：C

为 PGSQL 集群启用 L2 VIP吗？默认值是false，表示不创建 L2 VIP。

启用 L2 VIP 后，会有一个 VIP 绑定在集群主实例节点上，由 vip-manager 管理，根据 etcd 中的数据进行判断。

L2 VIP只能在相同的L2网络中使用，这可能会对您的网络拓扑产生额外的限制。

pg_vip_address

参数名称： pg_vip_address， 类型： cidr4， 层次：C

如果启用vip，则需要<ipv4>/<mask>格式的vip地址。

默认值： 127.0.0.1/24。这个值由两部分组成：ipv4和mask，用/分隔。

pg_vip_interface

参数名称： pg_vip_interface， 类型： string， 层次：C/I

vip network interface to listen, eth0 by default.

L2 VIP 监听的网卡接口，默认为 eth0。

它应该是您节点的首要网卡名，即您在配置清单中使用的IP地址。

如果您的节点有多块名称不同的网卡，您可以在实例变量上进行覆盖：

pg-test:
    hosts:
        10.10.10.11: {pg_seq: 1, pg_role: replica ,pg_vip_interface: eth0 }
        10.10.10.12: {pg_seq: 2, pg_role: primary ,pg_vip_interface: eth1 }
        10.10.10.13: {pg_seq: 3, pg_role: replica ,pg_vip_interface: eth2 }
    vars:
      pg_vip_enabled: true          # 为这个集群启用L2 VIP，默认绑定到主实例
      pg_vip_address: 10.10.10.3/24 # L2网络CIDR: 10.10.10.0/24, vip地址: 10.10.10.3
      # pg_vip_interface: eth1      # 如果您的节点有统一的接口，您可以在这里定义它

pg_dns_suffix

参数名称： pg_dns_suffix， 类型： string， 层次：C

PostgreSQL DNS 名称后缀，默认为空字符串。

在默认情况下，PostgreQL 集群名会作为 DNS 域名注册到 Infra 节点的 dnsmasq 中对外提供解析。

您可以通过本参数指定一个域名后缀，这样会使用 {{ pg_cluster }}{{ pg_dns_suffix }} 作为集群 DNS 名称。

例如，如果您将 pg_dns_suffix 设置为 .db.vip.company.tld，那么 pg-test 的集群 DNS 名称将是 pg-test.db.vip.company.tld

pg_dns_target

参数名称： pg_dns_target， 类型： enum， 层次：C

Could be: auto, primary, vip, none, or an ad hoc ip address, which will be the target IP address of cluster DNS record.

default values: auto , which will bind to pg_vip_address if pg_vip_enabled, or fallback to cluster primary instance ip address.

  • vip: bind to pg_vip_address
  • primary: resolve to cluster primary instance ip address
  • auto: resolve to pg_vip_address if pg_vip_enabled, or fallback to cluster primary instance ip address.
  • none: do not bind to any ip address
  • <ipv4>: bind to the given IP address

可以是：auto、primary、vip、none或一个特定的IP地址，它将是集群DNS记录的解析目标IP地址。

默认值： auto，如果pg_vip_enabled，将绑定到pg_vip_address，否则会回退到集群主实例的 IP 地址。

  • vip：绑定到pg_vip_address
  • primary：解析为集群主实例IP地址
  • auto：如果 pg_vip_enabled，解析为 pg_vip_address，或回退到集群主实例ip地址。
  • none：不绑定到任何ip地址
  • <ipv4>：绑定到指定的IP地址

PG_EXPORTER

PG Exporter 用于监控 PostgreSQL 数据库与 Pgbouncer 连接池的状态。

pg_exporter_enabled: true              # 在 pgsql 主机上启用 pg_exporter 吗？
pg_exporter_config: pg_exporter.yml    # pg_exporter 配置文件名
pg_exporter_cache_ttls: '1,10,60,300'  # pg_exporter 收集器 ttl 阶段（秒），默认为 '1,10,60,300'
pg_exporter_port: 9630                 # pg_exporter 监听端口，默认为 9630
pg_exporter_params: 'sslmode=disable'  # pg_exporter dsn 的额外 url 参数
pg_exporter_url: ''                    # 如果指定，将覆盖自动生成的 pg dsn
pg_exporter_auto_discovery: true       # 启用自动数据库发现？默认启用
pg_exporter_exclude_database: 'template0,template1,postgres' # 在自动发现过程中不会被监控的数据库的 csv 列表
pg_exporter_include_database: ''       # 在自动发现过程中将被监控的数据库的 csv 列表
pg_exporter_connect_timeout: 200       # pg_exporter 连接超时（毫秒），默认为 200
pg_exporter_options: ''                # 覆盖 pg_exporter 的额外选项
pgbouncer_exporter_enabled: true       # 在 pgsql 主机上启用 pgbouncer_exporter 吗？
pgbouncer_exporter_port: 9631          # pgbouncer_exporter 监听端口，默认为 9631
pgbouncer_exporter_url: ''             # 如果指定，将覆盖自动生成的 pgbouncer dsn
pgbouncer_exporter_options: ''         # 覆盖 pgbouncer_exporter 的额外选项

pg_exporter_enabled

参数名称： pg_exporter_enabled， 类型： bool， 层次：C

是否在 PGSQL 节点上启用 pg_exporter？默认值为：true。

PG Exporter 用于监控 PostgreSQL 数据库实例，如果不想安装 pg_exporter 可以设置为 false。

pg_exporter_config

参数名称： pg_exporter_config， 类型： string， 层次：C

pg_exporter 配置文件名，PG Exporter 和 PGBouncer Exporter 都会使用这个配置文件。默认值：pg_exporter.yml。

如果你想使用自定义配置文件，你可以在这里定义它。你的自定义配置文件应当放置于 files/<name>.yml。

例如，当您希望监控一个远程的 PolarDB 数据库实例时，可以使用样例配置：files/polar_exporter.yml。

pg_exporter_cache_ttls

参数名称： pg_exporter_cache_ttls， 类型： string， 层次：C

pg_exporter 收集器 TTL 阶梯（秒），默认为 ‘1,10,60,300’

默认值：1,10,60,300，它将为不同的度量收集器使用不同的TTL值： 1s, 10s, 60s, 300s。

PG Exporter 内置了缓存机制，避免多个 Prometheus 重复抓取对数据库产生不当影响，所有指标收集器按 TTL 分为四类：

ttl_fast: "{{ pg_exporter_cache_ttls.split(',')[0]|int }}"         # critical queries
ttl_norm: "{{ pg_exporter_cache_ttls.split(',')[1]|int }}"         # common queries
ttl_slow: "{{ pg_exporter_cache_ttls.split(',')[2]|int }}"         # slow queries (e.g table size)
ttl_slowest: "{{ pg_exporter_cache_ttls.split(',')[3]|int }}"      # ver slow queries (e.g bloat)

例如，在默认配置下，存活类指标默认最多缓存 1s，大部分普通指标会缓存 10s（应当与 prometheus_scrape_interval 相同）。 少量变化缓慢的查询会有 60s 的TTL，极个别大开销监控查询会有 300s 的TTL。

pg_exporter_port

参数名称： pg_exporter_port， 类型： port， 层次：C

pg_exporter 监听端口号，默认值为：9631

pg_exporter_params

参数名称： pg_exporter_params， 类型： string， 层次：C

pg_exporter 所使用 DSN 中额外的 URL PATH 参数。

默认值：sslmode=disable，它将禁用用于监控连接的 SSL（因为默认使用本地 unix 套接字）。

pg_exporter_url

参数名称： pg_exporter_url， 类型： pgurl， 层次：C

如果指定了本参数，将会覆盖自动生成的 PostgreSQL DSN，使用指定的 DSN 连接 PostgreSQL 。默认值为空字符串。

如果没有指定此参数，PG Exporter 默认会使用以下的连接串访问 PostgreSQL ：

postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@{{ pg_host }}:{{ pg_port }}/postgres{% if pg_exporter_params != '' %}?{{ pg_exporter_params }}{% endif %}

当您想监控一个远程的 PostgreSQL 实例时，或者需要使用不同的监控用户/密码，配置选项时，可以使用这个参数。

pg_exporter_auto_discovery

参数名称： pg_exporter_auto_discovery， 类型： bool， 层次：C

启用自动数据库发现吗？ 默认启用：true。

PG Exporter 默认会连接到 DSN 中指定的数据库 （默认为管理数据库 postgres） 收集全局指标，如果您希望收集所有业务数据库的指标，可以开启此选项。 PG Exporter 会自动发现目标 PostgreSQL 实例中的所有数据库，并在这些数据库中收集 库级监控指标。

pg_exporter_exclude_database

参数名称： pg_exporter_exclude_database， 类型： string， 层次：C

如果启用了数据库自动发现（默认启用），在这个参数指定的列表中的数据库将不会被监控。 默认值为： template0,template1,postgres，即管理数据库 postgres 与模板数据库会被排除在自动监控的数据库之外。

作为例外，DSN 中指定的数据库不受此参数影响，例如，PG Exporter 如果连接的是 postgres 数据库，那么即使 postgres 在此列表中，也会被监控。

pg_exporter_include_database

参数名称： pg_exporter_include_database， 类型： string， 层次：C

如果启用了数据库自动发现（默认启用），在这个参数指定的列表中的数据库才会被监控。默认值为空字符串，即不启用此功能。

参数的形式是由逗号分隔的数据库名称列表，例如：db1,db2,db3。

此参数相对于 [pg_exporter_exclude_database] 有更高的优先级，相当于白名单模式。如果您只希望监控特定的数据库，可以使用此参数。

pg_exporter_connect_timeout

参数名称： pg_exporter_connect_timeout， 类型： int， 层次：C

pg_exporter 连接超时（毫秒），默认为 200 （单位毫秒）

当 PG Exporter 尝试连接到 PostgreSQL 数据库时，最多会等待多长时间？超过这个时间，PG Exporter 将会放弃连接并报错。

默认值 200毫秒 对于绝大多数场景（例如：同可用区监控）都是足够的，但是如果您监控的远程 PostgreSQL 位于另一个大洲，您可能需要增加此值以避免连接超时。

pg_exporter_options

参数名称： pg_exporter_options， 类型： arg， 层次：C

传给 PG Exporter 的命令行参数，默认值为："" 空字符串。

当使用空字符串时，会使用默认的命令参数：

{% if pg_exporter_port != '' %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pg_exporter_port }} {{ pg_exporter_options }}'
{% else %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pg_exporter_port }} --log.level=info'
{% endif %}

注意，请不要在本参数中覆盖 pg_exporter_port 的端口配置。

pgbouncer_exporter_enabled

参数名称： pgbouncer_exporter_enabled， 类型： bool， 层次：C

在 PGSQL 节点上，是否启用 pgbouncer_exporter ？默认值为：true。

pgbouncer_exporter_port

参数名称： pgbouncer_exporter_port， 类型： port， 层次：C

pgbouncer_exporter 监听端口号，默认值为：9631

pgbouncer_exporter_url

参数名称： pgbouncer_exporter_url， 类型： pgurl， 层次：C

如果指定了本参数，将会覆盖自动生成的 pgbouncer DSN，使用指定的 DSN 连接 pgbouncer。默认值为空字符串。

如果没有指定此参数，Pgbouncer Exporter 默认会使用以下的连接串访问 Pgbouncer：

postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@:{{ pgbouncer_port }}/pgbouncer?host={{ pg_localhost }}&sslmode=disable

当您想监控一个远程的 Pgbouncer 实例时，或者需要使用不同的监控用户/密码，配置选项时，可以使用这个参数。

pgbouncer_exporter_options

参数名称： pgbouncer_exporter_options， 类型： arg， 层次：C

传给 Pgbouncer Exporter 的命令行参数，默认值为："" 空字符串。

当使用空字符串时，会使用默认的命令参数：

{% if pgbouncer_exporter_options != '' %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pgbouncer_exporter_port }} {{ pgbouncer_exporter_options }}'
{% else %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pgbouncer_exporter_port }} --log.level=info'
{% endif %}

注意，请不要在本参数中覆盖 pgbouncer_exporter_port 的端口配置。


Last modified 2024-12-09: fix vrid typo (a53c723c)