PostgreSQL / 系统课时
理解 pg_hba.conf
理解 pg_hba.conf
pg_hba.conf 决定客户端连接到 PostgreSQL 时,哪一类连接可以进入认证、使用什么认证方法,以及不允许的连接如何被拒绝。关键不是“写对一条规则”,而是理解它会从上到下匹配,并在第一条命中规则处停止。
学习目标
- 读懂
pg_hba.conf中连接类型、数据库、用户、地址和认证方法 - 理解“第一条匹配即生效”的顺序规则,以及认证失败不会继续向下匹配
- 能修改规则、重新加载配置并检查规则是否存在解析错误
一条规则到底匹配什么
TCP/IP 连接最常见的记录格式可以概括为 TYPE DATABASE USER ADDRESS METHOD。其中 host 表示 TCP/IP,hostssl 只匹配使用 SSL/TLS 的 TCP/IP;local 用于 Unix-domain socket,因此没有地址字段。
DATABASE 和 USER 可以写具体名称,也可以使用 all 等匹配方式;ADDRESS 通常使用 CIDR,例如 10.20.30.0/24;METHOD 决定认证方式。新部署中通常优先使用 scram-sha-256,而不是把数据库密码直接暴露给网络或依赖过宽的信任规则。
下面是一个片段示例,假设只允许 10.20.30.0/24 网段中的 app_user 通过 TLS 访问 appdb:
local all postgres peer
hostssl appdb app_user 10.20.30.0/24 scram-sha-256
host all all 0.0.0.0/0 reject
host all all ::/0 reject这段配置的生效行为是:本机 postgres 用户可通过 Unix socket 使用 peer;目标网段中的应用连接只有在数据库名、用户名、来源地址和 SSL 条件都匹配时,才会进入 SCRAM 密码认证;其他 IPv4/IPv6 TCP 连接被拒绝。
匹配顺序为什么比规则数量更重要
PostgreSQL 会按文件顺序逐条检查规则。连接命中第一条规则后,就使用该规则指定的方法认证;如果认证失败,服务器不会“继续尝试下一条更宽松的规则”。

因此,较具体的允许规则应放在较宽泛的拒绝规则之前。如果把 host all all 0.0.0.0/0 reject 放到最前面,后面的 IPv4 允许规则将永远无法命中。反过来,如果先放一个过宽的允许规则,后续的精细拒绝也可能失去作用。
让地址范围保持最小
CIDR 同时描述网络地址和掩码长度。10.20.30.0/24 只覆盖一个较小网段,而 0.0.0.0/0 覆盖所有 IPv4 地址。安全配置应尽量写业务实际需要的来源网段,而不是先放开全部地址再依赖密码兜底。
hostssl 还增加了传输层条件:只有 SSL/TLS 连接才匹配。若客户端未启用 SSL,它会继续寻找后续可匹配的 host 或 hostnossl 规则,因此文件顺序仍然重要。
修改后如何验证
pg_hba.conf 的大多数修改只需重新加载配置,不需要重启 PostgreSQL。先在数据库中执行重新加载,再检查解析结果:
SELECT pg_reload_conf();
SELECT type, database, user_name, address, auth_method, error
FROM pg_hba_file_rules
WHERE error IS NOT NULL;预期输出:
pg_reload_conf
----------------
t
(1 row)
type | database | user_name | address | auth_method | error
------+----------+-----------+---------+-------------+-------
(0 rows)如果第二条查询出现记录,说明至少有一条 HBA 配置无法被正确解析,应先修复错误再测试客户端连接。实际规则命中还要结合连接的数据库、用户、来源地址和 SSL 状态判断,不能只看“文件已经加载”。
排查认证失败时先找第一条命中规则
遇到“密码明明正确却无法连接”时,不要先反复改密码。先确认客户端使用的是 Unix socket 还是 TCP/IP、目标数据库和用户、客户端 IP,以及是否启用了 SSL,然后按 pg_hba.conf 从上到下寻找第一条完整匹配的规则。
只要掌握“按顺序检查、首条命中、认证失败不回退”这三个原则,pg_hba.conf 就不再是一组零散配置,而是一套可预测的访问控制规则。