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:

text
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 会按文件顺序逐条检查规则。连接命中第一条规则后,就使用该规则指定的方法认证;如果认证失败,服务器不会“继续尝试下一条更宽松的规则”。

pg_hba.conf 从上到下匹配并在首条命中规则处停止

因此,较具体的允许规则应放在较宽泛的拒绝规则之前。如果把 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。先在数据库中执行重新加载,再检查解析结果:

sql
SELECT pg_reload_conf();

SELECT type, database, user_name, address, auth_method, error
FROM pg_hba_file_rules
WHERE error IS NOT NULL;

预期输出:

text
 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 就不再是一组零散配置,而是一套可预测的访问控制规则。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

理解 pg_hba.conf

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通