PostgreSQL pg_hba.conf 完全解读
maiaimei 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
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
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
匹配过程:
local✅all(数据库)✅all(用户)✅- → trust(免密)
# 示例 2:远程 TCP 连接(需密码)
psql -h localhost -U biz_app_rw -d bizdb
1
匹配过程:
host✅127.0.0.1✅- → 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
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 安全访问的第一道关卡。理解其匹配逻辑与认证方式,是进行数据库安全配置的基础。
初学者建议从本地开发环境入手,逐步过渡到生产环境的精细化权限控制。