PostgreSQL pg_hba.conf 完全解读

2026/11/15 PostgreSQL

前置说明:pg_hba.conf 是 PostgreSQL 的客户端认证配置文件,全称 PostgreSQL Host-Based Authentication Configuration。

它决定了:谁能连、从哪里连、连哪个库、用什么方式认证。

本文从简单到专业,帮助你快速读懂并正确配置它。


# 一、如何查看 pg_hba.conf

# 1️⃣ 查看文件路径

连接到 PostgreSQL 后执行:

SHOW hba_file;
1

返回结果类似:

/var/lib/postgresql/data/pg_hba.conf
1

该路径即为当前实例实际加载的配置文件位置。


# 2️⃣ 查看当前已生效的规则(推荐)

SELECT line_number,
       type,
       database,
       user_name,
       address,
       auth_method
FROM pg_hba_file_rules
ORDER BY line_number;
1
2
3
4
5
6
7
8

✅ 优点:

  • 直接反映 PostgreSQL 实际加载的规则
  • 可快速定位“为何未提示输入密码”等问题

# 二、pg_hba.conf 基础语法

pg_hba.conf 文件中每一行代表一条连接规则,格式如下:

TYPE  DATABASE  USER  ADDRESS  METHOD  [OPTIONS]
1

# 字段含义对照表

字段 含义 常见值
TYPE 连接类型 local(Unix socket) host(TCP/IP)
DATABASE 允许连接的数据库 all, postgres, 具体库名
USER 允许连接的用户 all, postgres, 具体用户名
ADDRESS 来源 IP 或网段 127.0.0.1/32, 0.0.0.0/0, ::1/128
METHOD 认证方式 trust, md5, scram-sha-256, peer

⚠️ 注意:规则匹配遵循自上而下、首次命中即生效原则。


# 三、典型默认配置示例与解读

以下是常见的默认配置内容(适用于本地开发、Docker 等环境):

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# 本地 Socket 免密:允许通过本地 Unix socket 连接,匹配所有数据库、所有用户,无需密码(trust)。常见于容器内或服务器本机直接执行 psql 时免密登录。
local   all             all                                     trust

# IPv4 本地 TCP 免密:允许通过 TCP/IP 从 127.0.0.1(本机)连接,匹配所有库、所有用户,无需密码(trust)。对应 psql -h localhost 的本机连接场景。
host    all             all             127.0.0.1/32            trust

# IPv6 本地 TCP 免密:允许通过 TCP/IP 从 ::1(IPv6 本机回环)连接,匹配所有库、所有用户,无需密码(trust)。
host    all             all             ::1/128                 trust

# 本地复制免密:允许本地 Unix socket 进行数据库复制(replication)操作,匹配所有用户,无需密码(trust)。
local   replication     all                                     trust

# IPv4 复制免密:允许从 127.0.0.1 通过 TCP 进行复制连接,所有用户,无需密码(trust)。
host    replication     all             127.0.0.1/32            trust

# IPv6 复制免密:允许从 ::1 通过 TCP 进行复制连接,所有用户,无需密码(trust)。
host    replication     all             ::1/128                 trust

# 外部远程需密:允许所有 TCP/IP 来源(包括外部网络),匹配所有库、所有用户,必须使用密码认证(scram-sha-256,PostgreSQL 10+ 推荐的强加密方式)。这是保障外部访问安全的核心规则。
host all all all scram-sha-256
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

核心总结:

该配置体现了典型的**“本地全免密、远程强密码”**策略。前 6 条规则保障了本地(容器内)运维与复制的便捷性;最后一条 host all all all scram-sha-256 作为兜底规则,确保任何外部远程连接都必须提供强密码,防止未授权访问。


# 四、如何判断某连接会匹配哪条规则

PostgreSQL 按从上到下第一条匹配的规则生效。

# 示例 1:本地连接(免密)

psql -U postgres
1

匹配过程:

  1. local ✅
  2. all(数据库)✅
  3. all(用户)✅
  4. → trust(免密)

# 示例 2:远程 TCP 连接(需密码)

psql -h localhost -U biz_app_rw -d bizdb
1

匹配过程:

  1. host ✅
  2. 127.0.0.1 ✅
  3. → scram-sha-256(要求密码)

# 五、查看特定用户的认证规则

如需确认某个用户或某类用户的认证方式,可执行:

SELECT *
FROM pg_hba_file_rules
WHERE user_name IN ('postgres', 'biz_app_rw', 'all')
ORDER BY line_number;
1
2
3
4

# 六、修改配置后如何生效

编辑 pg_hba.conf 文件后,需重新加载配置:

SELECT pg_reload_conf();
1

随后重新建立连接进行测试,以验证规则是否按预期生效。


# 七、核心要点速查表

场景 操作
快速确认规则 SELECT * FROM pg_hba_file_rules;
查看文件路径 SHOW hba_file;
修改配置 编辑 pg_hba.conf
使配置生效 SELECT pg_reload_conf();

总结:pg_hba.conf 是 PostgreSQL 安全访问的第一道关卡。

理解其匹配逻辑与认证方式,是进行数据库安全配置的基础。

初学者建议从本地开发环境入手,逐步过渡到生产环境的精细化权限控制。