HBA 认证
Pigsty 中基于主机的身份认证 HBA（Host-Based Authentication）配置详解。
HBA（Host-Based Authentication）控制“谁可以从哪里、以什么方式连接到数据库”。Pigsty 通过
pg_default_hba_rules与pg_hba_rules让 HBA 规则也能以配置形式管理。
Pigsty 会在初始化时渲染 /pg/data/pg_hba.conf 与 /etc/pgbouncer/pg_hba.conf，其中：
pg_default_hba_rules：全局默认规则，通常位于all.vars。pg_hba_rules：集群/业务级追加规则，在all.children.<cls>.vars或主机vars中覆盖。pgb_default_hba_rules/pgb_hba_rules：连接池 pgbouncer 的 HBA 规则。- 规则支持按实例角色生效（
role: primary/replica/offline/common），Pigsty 会根据实例的pg_role自动筛选。
写法：原始形式与别名形式
每条规则由 title、role 和 rules/别名字段组成：
pg_hba_rules:
- title: allow intranet password access # 注释
role: common # 作用在哪类实例？
rules: # 原始 HBA 文本
- host all all 10.0.0.0/8 md5
- host all all 172.16.0.0/12 md5
为了简化常见配置，可以使用别名形式：
- title: allow grafana view access
role: primary
user: dbuser_view # user/all/${dbsu}/+group
db: meta # all/replication/指定库
addr: infra # world/intra/infra/admin/local/localhost/cluster/<cidr>
auth: ssl # trust/pwd/md5/scram/ssl/ssl-md5/ssl-sha/peer/cert/deny
addr：支持别名（world/intra/infra/admin/local/localhost/cluster）或10.0.0.0/24形式的网络。auth：pwd会根据pg_pwd_enc自动使用md5或scram-sha-256；ssl/ssl-md5/ssl-sha会强制要求 SSL。user：可以是单个用户名、${admin}等内置变量，或+dbrole_readonly这样的角色组。db：指定数据库名称或all/replication。role：common（所有实例）、primary、replica、offline。- 若同时指定
rules与别名字段，以rules为准。
Pigsty 提供的变量占位符：${dbsu}、${admin}、${monitor}、${repl} 等，会在渲染时替换为当前参数值。
常见配置示例
1. 只允许内网密码访问业务库
pg_hba_rules:
- { title: 'intra readwrite access', role: common,
user: '+dbrole_readwrite', db: all, addr: intra, auth: pwd }
效果：所有业务读写角色可以从内网网段（默认
10/8,172.16/12,192.168/16，可通过node_firewall_intranet调整）使用密码访问任意数据库。
2. 离线实例只给离线角色
pg_hba_rules:
- { title: 'offline replica dedicated network', role: offline,
user: '+dbrole_offline', db: all, addr: 172.20.0.0/16, auth: ssl-sha }
效果：仅
pg_role: offline或pg_offline_query: true的实例会增添该规则，要求离线角色从指定网段以 SSL + SCRAM 连接。
3. 管理员强制使用客户端证书
pg_hba_rules:
- title: 'admin cert access'
role: common
user: '${admin}'
db: all
addr: world
auth: cert
效果：管理员角色必须携带客户端证书才能从任意来源连接，可搭配
ssl_cafile与patroni_watchdog_mode构建更严格的访问链。
4. pgbouncer 单独控制
pgb_hba_rules:
- { title: 'app via pgbouncer', role: common,
user: '+dbrole_readwrite', db: all, addr: world, auth: ssl }
效果：pgbouncer 的 HBA 会允许来自任意网段的业务应用接入连接池，但必须在 TLS 隧道下并使用密码认证。
刷新 HBA
修改规则后需要让 PostgreSQL/pgbouncer 重新加载配置：
bin/pgsql-hba <cls> # 重新生成并 reload 集群的 pg_hba.conf
bin/pgsql-hba <cls> ip1 ip2... # 只针对特定实例执行
上述命令内部等价于：
./pgsql.yml -l <cls> -e pg_reload=true -t pg_hba,pg_reload
./pgsql.yml -l <cls> -e pg_reload=true -t pgbouncer_hba,pgbouncer_reload
建议在新增/下线实例、切换主从或修改角色访问范围后立即执行刷新。
默认规则参考
Pigsty 内置的 pg_default_hba_rules 能覆盖绝大多数场景：
pg_default_hba_rules:
- {user: '${dbsu}', db: all, addr: local, auth: ident, title: 'dbsu via local ident' }
- {user: '${dbsu}', db: replication, addr: local, auth: ident, title: 'dbsu local replication'}
- {user: '${repl}', db: replication, addr: localhost, auth: pwd, title: 'replication from localhost'}
- {user: '${repl}', db: replication, addr: intra, auth: pwd, title: 'replication from intranet' }
- {user: '${monitor}', db: all, addr: localhost, auth: pwd, title: 'monitor local password' }
- {user: '${monitor}', db: all, addr: infra, auth: pwd, title: 'monitor infra password' }
- {user: '${admin}', db: all, addr: infra, auth: ssl, title: 'admin infra ssl+pwd' }
- {user: '${admin}', db: all, addr: world, auth: ssl, title: 'admin world ssl+pwd' }
- {user: '+dbrole_readonly',db: all, addr: localhost, auth: pwd, title: 'pgbouncer local access' }
- {user: '+dbrole_readonly',db: all, addr: intra, auth: pwd, title: 'biz users via intranet' }
- {user: '+dbrole_offline', db: all, addr: intra, auth: pwd, title: 'offline jobs via intranet'}
pgbouncer 默认规则也已经封装常见需求：
pgb_default_hba_rules:
- {user: '${dbsu}', db: pgbouncer, addr: local, auth: peer, title: 'dbsu local admin'}
- {user: 'all', db: all, addr: localhost, auth: pwd, title: 'local clients'}
- {user: '${monitor}',db: all, addr: world, auth: deny, title: 'block monitor world'}
- {user: '${admin}', db: all, addr: intra, auth: pwd, title: 'admin via infra'}
- {user: 'all', db: all, addr: intra, auth: pwd, title: 'business via intranet'}
直接在
pg_hba_rules/pgb_hba_rules中增删条目即可实现差异化访问控制，无需手工编辑pg_hba.conf。