PostgreSQL 18 中文参考文档(未翻译部分保留英文)🌐 切换到英文原版 →

20.1. pg_hba.conf 配置文件 #

客户端认证策略由专用的配置文件统一控制,传统上命名为 pg_hba.conf 并存放于数据库集群的数据目录中(HBA 代表基于主机的访问认证 Host-Based Authentication)。默认文件在执行 initdb 初始化集群时自动生成。可以通过配置参数 hba_file 将其重定向至其他物理路径。

服务在启动时以及主进程收到 SIGHUP 信号时会重新加载 pg_hba.conf。在热重载生效之前,可以使用系统视图 pg_hba_file_rules 预先检查规则语法,视图中的 error 字段会清晰提示对应行存在的配置错误。

pg_hba.conf 采用基于行的记录格式,每行配置一条规则。以井号(#)开头的行为注释行。单条规则记录由空格或制表符分隔的若干字段组成:

# TYPE  DATABASE        USER            ADDRESS                 METHOD  [OPTIONS]
local   all             all                                     peer
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256
hostssl all             all             0.0.0.0/0               scram-sha-256

各个字段的详细语义如下:

连接类型(TYPE)

  • local:匹配通过本地 Unix 域套接字发起的进程间通信连接。

  • host:匹配通过 TCP/IP 网络发起的连接(无论是否加密)。

  • hostssl:强制仅匹配通过 SSL/TLS 加密通道发起的 TCP/IP 连接,明文连接将被直接拒止。

  • hostnossl:仅匹配未加密的明文 TCP/IP 连接。

  • hostgssenc:仅匹配基于 GSSAPI 协议完成强加密的 TCP/IP 连接。

目标数据库(DATABASE)

指定该规则适用的数据库名称。关键字 all 匹配集群内的所有普通数据库;sameuser 仅当请求连接的数据库名称与登录用户名相同时才匹配;replication 专门用于匹配物理流复制与备份连接;还可以指定以逗号分隔的多库清单。

登录用户(USER)

指定该规则适用的数据库角色名称。all 匹配所有用户;以加号(+)开头(如 +admin_group)表示匹配该角色群组内部的全部成员用户。

客户端网络地址(ADDRESS)

针对 TCP/IP 连接类型(host/hostssl),声明匹配的客户端 IP 地址段。可以使用标准的 CIDR 无类域间路由掩码记法(例如 192.168.1.0/24 或 10.0.0.1/32、IPv6 地址 ::1/128),或者使用关键字 samehost(匹配本机发起的任何网络连接)与 samenet(匹配与服务器处于同一直接物理子网的客户端)。

认证方法(METHOD)与附加选项(OPTIONS)

指定当前连接通过何种加密挑战与密码学机制校验身份。如果配置了多条可能匹配的规则,系统在收到客户端连接时,会严格自顶向下逐行顺序扫描 pg_hba.conf,一旦命中首条符合条件的规则便立即执行该认证,绝不回退继续匹配后续记录。因此,必须将范围更狭窄严格的特定规则置于文件上方,而将宽泛的兜底规则置于文件末尾。

Example 20.1. pg_hba.conf 记录示例

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     trust
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256
host    all             all             192.168.1.0/24          scram-sha-256