Pigsty v4.5.0 配置参数详解

Pigsty v4.5.0 配置参数详解：按 Infra/Node/PGSQL/Monitor/Backup 五大类逐项实测 pigsty.yml 与 postgresql.conf 核心参数，含默认值、context 分级（user/sighup/postmaster）、pig patroni set 修改命令与重载/重启验证回显，附 16GB OLTP 生产配置模板。

PigstyPigstyPostgreSQL数据库AnsibleGrafana2026/10/25

Pigsty v4.5.0 配置参数详解

目标：把 Pigsty v4.5.0 的核心配置项讲清楚——它们写在哪、默认值是什么、改了之后怎么生效、如何验证。本篇基于 Debian 13 + PostgreSQL 18.6 实测，每类参数都给出「修改命令 → 生效方式 → 验证回显」的完整闭环（2026-10-25）。

一、环境信息

  • Pigsty 版本：v4.5.0
  • PostgreSQL 版本：18.6
  • pig CLI 版本：1.8.0
  • 操作系统：Debian 13 (trixie)，x86_64
  • 配置文件位置：/root/pigsty/pigsty.yml（Pigsty 清单）、/pg/data/postgresql.conf（PG 运行时配置）
  • PG 调优模板：oltp.yml
  • 节点调优模式：oltp

二、前置条件

  • Pigsty 已部署完成（PostgreSQL、Patroni、Grafana、VictoriaMetrics 均运行中）。
  • 具备 root 权限或可执行 pig 命令。
  • 了解 Ansible inventory 的基本结构（all.children.<group>.hosts 与 all.vars）。

三、参数查看与修改方式

3.1 查看配置

Pigsty 的全部声明式配置集中在 /root/pigsty/pigsty.yml。查看当前生效的 PostgreSQL 参数：

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -U dbuser_dba -d postgres -c "SELECT name, setting, unit, context FROM pg_settings WHERE name IN ('shared_buffers','work_mem','effective_cache_size','max_connections','checkpoint_timeout','wal_level') ORDER BY name;"

回显：

         name         | setting | unit |  context
----------------------+---------+------+------------
 checkpoint_timeout   | 900     | s    | sighup
 effective_cache_size | 2302208 | 8kB  | user
 max_connections      | 500     |      | postmaster
 shared_buffers       | 767488  | 8kB  | postmaster
 wal_level            | logical |      | postmaster
 work_mem             | 65536   | kB   | user

3.2 修改配置的三种生效方式

PostgreSQL 参数按 context 分为三类，改法不同：

context含义生效方式
user用户会话级改后即时生效，无需重载
superuser超级用户级需 pg_reload_conf() 或 SIGHUP 重载
sighup配置文件级需重载
postmaster启动级需重启 PostgreSQL

💡 技术拓展：PostgreSQL 参数 context 不止上述四种，完整分级还有 internal（编译期定，不可改）、backend（后端启动时定）。日常运维最常碰的是 user（会话级，如 work_mem）、sighup（配置级，如 checkpoint_timeout）、postmaster（重启级，如 shared_buffers、max_connections）。用 SHOW 或 pg_settings.context 字段可查每个参数的分级。

3.3 通过 pig patroni set 修改（推荐）

Pigsty 用 Patroni 管理 PostgreSQL，改参数统一走 pig patroni set KEY=VALUE，Patroni 会自动判断是否需要重载/重启：

echo y | pig patroni set work_mem=32MB

回显：

-    work_mem: 64MB
+    work_mem: 32MB
   remove_data_directory_on_rewind_failure: true
   use_pg_rewind: true
   use_slots: true
Apply these changes? [y/N]: Configuration changed
If the change was applied, verify with:
$ pig pt list

验证：

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -U dbuser_dba -d postgres -c "SHOW work_mem;"

回显：

 work_mem
----------
 32MB
(1 row)

work_mem 是 user context，改后即时生效，无需重载。

3.4 修改需重载的参数（sighup / superuser）

以 log_statement（superuser context）为例：

echo y | pig patroni set log_statement=all

Patroni 会自动触发重载。验证：

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -U dbuser_dba -d postgres -c "SHOW log_statement;"

回显：

 log_statement
---------------
 all
(1 row)

若需手动重载：

pig patroni reload pgsql

3.5 修改需重启的参数（postmaster）

以 max_connections 为例，它是 postmaster context，需重启 PostgreSQL：

echo y | pig patroni set max_connections=800

Patroni 会执行滚动重启（单节点即直接重启）。验证：

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -U dbuser_dba -d postgres -c "SHOW max_connections;"

回显：

 max_connections
-----------------
 800
(1 row)

⚠️ 重启 PostgreSQL 会短暂中断连接，生产环境应在维护窗口操作，或通过 Patroni 滚动切换主从避免中断。

四、参数总览

Pigsty 配置按层级分为：基础设施（Infra）、节点（Node）、数据库（PGSQL）、监控（Monitor）、备份（Backup）五大类。

大类关键配置项位置
Infraregion、admin_ip、infra_portal、proxy_envall.vars
Nodenodename、node_tune、node_ntp_enabled、node_dns_methodall.vars
PGSQLpg_version、pg_conf、pg_extensions、pg_users、pg_databases、pg_hba_rulesall.vars
Monitorgrafana_admin_password、pg_monitor_passwordall.vars
Backuppg_crontab、minio_*all.vars

五、核心参数分类详解

5.1 基础设施参数

region

  • 默认值：china
  • 说明：上游镜像源区域，可选 default、china、europe。决定部署时从哪个镜像源拉取包。
  • 修改：编辑 pigsty.yml 后 ./deploy.yml 重新收敛。

admin_ip

  • 默认值：127.0.0.1（单节点）
  • 说明：管理节点 IP，Ansible 与 Grafana 数据源注册用。多节点集群需改为管理节点真实 IP。
  • 修改：编辑 pigsty.yml 后重新部署。

infra_portal

  • 默认值：{ home: { domain: i.pigsty } }
  • 说明：Web 门户的域名配置。Nginx 会根据 i.pigsty 这个域名路由到 Pigsty 首页。
  • 修改：可改为自己的域名，如 { home: { domain: pigsty.example.com } }。

proxy_env

  • 默认值：仅 no_proxy，http_proxy/https_proxy 被注释。
  • 说明：部署期间下载包使用的代理。内网环境需填写代理地址。
  • 示例：
proxy_env:
  http_proxy: http://192.168.1.62:7897
  https_proxy: http://192.168.1.62:7897
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16"

5.2 节点参数

nodename

  • 默认值：pigsty
  • 说明：节点主机名，用于 Grafana 面板与监控标识。
  • 修改：编辑 pigsty.yml 后重新部署。

node_tune

  • 默认值：oltp
  • 说明：节点调优模式，可选 oltp、olap、tiny、crit。决定内核参数（sysctl）与磁盘调度策略。
  • 修改：改后重新部署，会重新应用 sysctl 参数。

💡 技术拓展：Pigsty 的节点调优模式对应不同业务负载——

模式目标负载关键调整
oltp在线事务处理高并发、低延迟，IO 调度 deadline
olap在线分析处理大查询、高吞吐，IO 调度 none
tiny微型/边缘低资源占用，限制后台进程
crit关键业务最保守参数，优先数据安全

本文单节点演示采用默认 oltp。

node_ntp_enabled

  • 默认值：false（单节点）
  • 说明：是否启用 NTP 时间同步。生产多节点集群建议设为 true，避免时钟漂移导致复制异常。

5.3 数据库参数

pg_version

  • 默认值：18
  • 说明：PostgreSQL 主版本号，支持 14、15、16、17、18。
  • 修改：改后重新部署会安装对应版本。注意：已部署后改版本需做迁移，不能直接覆盖。

pg_conf

  • 默认值：oltp.yml
  • 说明：PostgreSQL 调优模板，可选 oltp.yml、olap.yml、tiny.yml、crit.yml。决定 shared_buffers、work_mem、effective_cache_size 等核心参数。
  • 当前生效值（oltp 模板）：
参数值context
shared_buffers6GB (767488×8kB)postmaster
work_mem64MBuser
effective_cache_size约 17.6GBuser
maintenance_work_mem约 1.5GBuser
max_connections500postmaster
checkpoint_timeout15minsighup
max_wal_size92GBsighup

pg_extensions

  • 默认值：[pg18-main, pg18-time, pg18-gis, pg18-rag, pg18-fts, pg18-feat, pg18-lang, pg18-type, pg18-util, pg18-func, pg18-admin, pg18-stat, pg18-sec, pg18-fdw, pg18-sim, pg18-etl]
  • 说明：预装扩展组列表。每组对应一类扩展（如 pg18-gis 是地理空间、pg18-rag 是向量/AI）。
  • 修改：从列表中移除某个组即不装该类扩展；改后重新部署。

⚠️ Pigsty v4.5.0 的 pg18-olap 组内含冲突包（pg-duckdb 与 duckdb-fdw），APT 安装会失败。如需 OLAP 扩展，建议从列表移除 pg18-olap，部署后按需单独安装。

pg_users

  • 默认值：
pg_users:
  - { name: dbuser_meta, password: <随机>, pgbouncer: true, roles: [dbrole_admin], comment: pigsty admin user }
  - { name: dbuser_view, password: <随机>, pgbouncer: true, roles: [dbrole_readonly], comment: read-only viewer }
  • 说明：声明式创建的数据库用户。pgbouncer: true 表示同时在 pgBouncer 中创建连接池用户。
  • 修改：增删用户后重新部署，Ansible 会幂等地创建/删除。

pg_databases

  • 默认值：
pg_databases:
  - { name: meta, baseline: cmdb.sql, comment: pigsty meta database, schemas: [pigsty], extensions: [postgis, timescaledb, vector] }
  • 说明：声明式创建的数据库。baseline 是初始化 SQL，extensions 是需启用的扩展。
  • 修改：增删数据库后重新部署。

pg_hba_rules

  • 默认值：
pg_hba_rules:
  - { user: all, db: all, addr: intra, auth: pwd, order: 800 }
  - { user: all, db: all, addr: world, auth: pwd, order: 900 }
  • 说明：客户端认证规则。addr: intra 表示内网地址段，addr: world 表示所有地址。auth: pwd 表示密码认证。
  • 修改：改后重新部署，会重写 pg_hba.conf 并重载。

pg_libs

  • 默认值：'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'
  • 说明：shared_preload_libraries 的值，需在 PG 启动时加载的扩展。
  • 修改：改后需重启 PostgreSQL（postmaster context）。

pg_crontab

  • 默认值：[ '00 01 * * * /pg/bin/pg-backup full' ]
  • 说明：postgres 用户的定时任务。默认每天凌晨 1 点执行全量备份。
  • 修改：编辑后重新部署，会更新 crontab。

5.4 监控参数

grafana_admin_password

  • 默认值：./configure -g 随机生成
  • 说明：Grafana 管理员密码。
  • 修改：编辑 pigsty.yml 后重新部署，或在 Grafana 界面直接改。

pg_monitor_password

  • 默认值：随机生成
  • 说明：dbuser_monitor 用户密码，pg_exporter 用它连 PG 采集指标。
  • 修改：需同步改 pigsty.yml 与 pg_exporter 配置，重新部署。

5.5 备份参数

minio_secret_key / minio_access_key

  • 默认值：随机生成 / S3User.Backup
  • 说明：对象存储（MinIO/S3）的访问密钥，pgBackRest 用它把备份推到对象存储。
  • 修改：编辑 pigsty.yml 后重新部署。

六、生产配置模板

以下是一份 16GB 内存、NVMe SSD、OLTP 场景的推荐配置片段（摘自 pigsty.yml 的 all.vars）：

all:
  vars:
    version: v4.5.0
    admin_ip: 10.0.0.1              # 管理节点真实 IP
    region: china
    pg_version: 18
    pg_conf: oltp.yml              # OLTP 调优模板
    pg_extensions: [pg18-main, pg18-time, pg18-gis, pg18-rag, pg18-stat, pg18-sec]
    node_tune: oltp
    node_ntp_enabled: true         # 生产开启时间同步
    pg_crontab:
      - '00 01 * * * /pg/bin/pg-backup full'   # 每日全量
      - '*/15 * * * * /pg/bin/pg-backup incr'  # 每 15 分钟增量
    pg_hba_rules:
      - { user: all, db: all, addr: intra, auth: scram-sha-256, order: 800 }
      - { user: all, db: all, addr: world, auth: scram-sha-256, order: 900 }

💡 说明：生产环境建议把 auth 从 pwd 改为 scram-sha-256 增强安全性；备份策略根据 RPO 要求调整增量频率。

七、配置修改完整流程示例

以「把 work_mem 从 64MB 改为 32MB 并验证」为例：

步骤 1：查看当前值

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -U dbuser_dba -d postgres -c "SHOW work_mem;"

回显：

 work_mem
----------
 64MB
(1 row)

步骤 2：修改参数

echo y | pig patroni set work_mem=32MB

步骤 3：验证生效

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -U dbuser_dba -d postgres -c "SHOW work_mem;"

回显：

 work_mem
----------
 32MB
(1 row)

步骤 4：持久化到 pigsty.yml（可选）

pig patroni set 只改运行时配置，若需持久化（重启部署后不丢失），需同步编辑 pigsty.yml 中对应参数，再 ./deploy.yml 收敛。

八、常见问题

8.1 pig patroni set 卡在 Apply these changes? [y/N]:

原因：pig patroni set 默认需要人工确认。

解决：管道传入确认：echo y | pig patroni set work_mem=32MB。

8.2 改了参数但 SHOW 还是旧值

排查：

  1. 确认参数 context：SELECT name, context FROM pg_settings WHERE name = '...';
  2. 若 context 是 sighup/superuser，手动重载：pig patroni reload pgsql
  3. 若 context 是 postmaster，需重启：pig patroni restart pgsql
  4. 检查是否改对了集群名：pig patroni list 查看集群名（默认 pgsql）

8.3 修改 pigsty.yml 后重新部署，PG 参数没变化

原因：pigsty.yml 中声明的 PG 参数通过 Patroni 配置管理，若 Patroni 中已有运行时覆盖值，./deploy.yml 不会强制覆盖。

解决：先 pig patroni edit-config 删除运行时覆盖，再重新部署；或直接用 pig patroni set 修改。

8.4 如何查看所有已修改的参数

PGPASSWORD=<pg_admin_password> psql -h 127.0.0.1 -U dbuser_dba -d postgres -c "SELECT name, setting FROM pg_settings WHERE source <> 'default' ORDER BY name;"

该命令列出所有非默认值的参数，便于核对改动。

九、参考链接