Skip to content

inchTodd/db-error-troubleshooting-skills / skills/pg-no-pg-hba-conf-entry

pg-no-pg-hba-conf-entry

Verified

排查 PostgreSQL 报错「no pg_hba.conf entry for host "%s", user "%s", database "%s", %s」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。

FileKindSize
SKILL.mdskill md7.5 KB
---
name: pg-no-pg-hba-conf-entry
description: "排查 PostgreSQL 报错「no pg_hba.conf entry for host \"%s\", user \"%s\", database \"%s\", %s」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。"
---

# PostgreSQL「no pg_hba.conf entry for host」:报错里的四个字段就是你要加的那行规则

> 原文与完整版:https://surinch.com/tools/postgresql-error/no-pg-hba-conf-entry(最后核对 2026-11-04)

## 一句话结论

服务器收到了连接,但 `pg_hba.conf` 里**没有一行同时匹配**报错里给出的来源地址、用户名、数据库和加密方式,于是直接拒绝,连密码都没问。照着报错补一行 `host 库 用户 来源/32 scram-sha-256`,放到合适的位置,`SELECT pg_reload_conf();` 即可。连接还没到这一步(端口不通、`listen_addresses` 没开)时报的是 connection refused 或超时,不是这条。

## 官方报错原文

```
no pg_hba.conf entry for host "%s", user "%s", database "%s", %s
```

出自 auth.c 的 ClientAuthentication(),SQLSTATE 28000。最后一个 `%s` 是加密状态:`no encryption`、`SSL encryption` 或 `GSS encryption`。复制连接的报错是 `no pg_hba.conf entry for replication connection from host ...`。

## 关键事实

| 项 | 内容 |
|---|---|
| SQLSTATE | `28000`(invalid_authorization_specification) |
| 匹配规则 | 按文件顺序逐行比对,用第一条匹配的规则;后面的不再看,也不会“失败后试下一条” |
| 何时生效 | 启动时和收到 SIGHUP 时读取;改完要 reload |
| 复制连接 | `database` 字段要写 `replication`,`all` 不匹配复制连接 |
| 检查工具 | `pg_hba_file_rules` 视图的 `error` 列(PG10 起) |

## 把报错拆成规则的四列

这条报错的好处是它把缺的规则直接告诉你了。以 `no pg_hba.conf entry for host "10.0.1.25", user "app", database "appdb", no encryption` 为例:

| 报错里的字段 | 对应 pg_hba.conf 的列 | 本例要写 |
|---|---|---|
| `host "10.0.1.25"` | ADDRESS(服务器看到的来源 IP) | `10.0.1.25/32`,或网段 `10.0.1.0/24` |
| `user "app"` | USER | `app`(或 `all`) |
| `database "appdb"` | DATABASE | `appdb`(或 `all`) |
| `no encryption` / `SSL encryption` / `GSS encryption` | TYPE | `host` 匹配任何 TCP;`hostssl` 只匹配 SSL;`hostnossl` 只匹配非 SSL |

```text
# TYPE  DATABASE  USER  ADDRESS        METHOD
host    appdb     app   10.0.1.0/24    scram-sha-256
```

> 来源地址按报错里的值写。经过 NAT、负载均衡、Docker 网络或 Kubernetes 时,服务器看到的往往是网关或节点地址,不是应用所在机器的 IP。


## 报错写着 no encryption:可能是只配了 hostssl

如果规则文件里给这个来源写的是 `hostssl`,而客户端没用 SSL 连接,报错末尾就是 `no encryption`,看起来像“明明配了却说没有”。反过来,写了 `hostnossl` 而客户端用 SSL 连,也会不匹配。

| 报错末尾 | 客户端实际 | 能匹配的 TYPE |
|---|---|---|
| `no encryption` | 没用 SSL | `host`、`hostnossl` |
| `SSL encryption` | 用了 SSL | `host`、`hostssl` |
| `GSS encryption` | 用了 GSSAPI 加密 | `host`、`hostgssenc` |

要求加密时,让客户端加 `sslmode=require`(或更严格的 `verify-full`),不要为了消除报错把 `hostssl` 改回 `host`。


## 加了规则还报错:多半是顺序或 reload

1. **没 reload**:`pg_hba.conf` 只在启动和 SIGHUP 时读取。执行 `SELECT pg_reload_conf();`,或 `pg_ctl reload`。
2. **改错了文件**:用 `SHOW hba_file;` 看服务器实际用的路径。Debian/Ubuntu 一般在 `/etc/postgresql/<版本>/main/`,源码或 RPM 安装常在数据目录里,以查询结果为准。
3. **前面有一条 reject 先匹配了**:规则按顺序比对,第一条匹配的生效;前面的 `host all all 0.0.0.0/0 reject` 会挡住后面的放行规则。
4. **新行有语法错误**:有错的行会被跳过,`pg_hba_file_rules` 的 `error` 列会写原因。
5. **复制连接**:`pg_basebackup` 或备库报的是 `replication connection`,DATABASE 列要写 `replication`。

```sql
SHOW hba_file;
SHOW ident_file;
SELECT line_number, type, database, user_name, address, netmask, auth_method, error
FROM pg_hba_file_rules
ORDER BY line_number;
```

```sql
-- 改完 pg_hba.conf 后,先看有没有语法错误(error 列非空即有问题)
SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;
-- 没有错误再重新加载(不需要重启)
SELECT pg_reload_conf();
```


## PG14–18 差异与升级提醒

- 报错格式在 PG13、14、18 的源码里相同,本页的判断方法适用于这些版本。
- 服务器日志里配套的 DETAIL:PG16 起写 `Connection matched file "..." line N`,PG15 及以前写 `Connection matched pg_hba.conf line N`(只在规则匹配但认证失败时出现)。
- PG14 起 `password_encryption` 默认是 `scram-sha-256`。从 PG13 或更早升级、并沿用旧的 `pg_hba.conf` 时,记得一起核对认证方式,见 [PG14 停更升级体检](https://surinch.com/tools/db-migration-check/pg-upgrade)。

## 常见问题

**no pg_hba.conf entry for host 是什么意思?**

服务器收到了连接,但 pg_hba.conf 里没有一行同时匹配报错里的来源地址、用户名、数据库和加密方式,所以在验证密码之前就拒绝了。SQLSTATE 是 28000。

**怎么允许远程连接 PostgreSQL?**

两步:postgresql.conf 的 listen_addresses 要包含服务器网卡地址(改它需要重启),pg_hba.conf 加一行 host 库 用户 来源网段 scram-sha-256 再 reload。只改 pg_hba.conf 而没监听远程地址,客户端会是连接被拒或超时。

**改了 pg_hba.conf 要重启吗?**

不用重启,执行 SELECT pg_reload_conf() 或 pg_ctl reload 即可。listen_addresses 才需要重启。

**报错末尾的 no encryption 是什么?**

表示这次连接没有用 SSL 或 GSS 加密。如果你的规则写的是 hostssl,就不会匹配;让客户端用 sslmode=require 连接,或确认规则类型。

**0.0.0.0/0 可以吗?**

它表示所有 IPv4 来源都能尝试登录,只适合在前面已有防火墙或安全组限制时临时使用。按报错里的来源地址写到 /32 或具体网段更稳妥。

## 给 agent 的使用守则

- 先让用户贴出完整报错和执行的命令,按上面的顺序做只读检查,再给修改建议。
- 不要求用户提供密码、连接串里的凭证或生产数据;需要时让用户自己在本机执行命令并贴结果(可先打码)。
- 改配置(pg_hba.conf、my.cnf、授权语句)前先说明影响并让用户确认;本 skill 不承诺任何修复效果。

## 来源

- [PostgreSQL 源码 REL_18_STABLE:src/backend/libpq/auth.c(auth_failed)](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/libpq/auth.c)
- [PostgreSQL 18 文档 20.1:The pg_hba.conf File](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)
- [PostgreSQL 18 文档:pg_hba_file_rules 视图](https://www.postgresql.org/docs/current/view-pg-hba-file-rules.html)
- [PostgreSQL 18 文档 20.16:Authentication Problems](https://www.postgresql.org/docs/current/client-authentication-problems.html)
- [PostgreSQL 14 文档 20.3:password_encryption(默认 scram-sha-256)](https://www.postgresql.org/docs/14/runtime-config-connection.html)

完整图文版和相关报错:https://surinch.com/tools/postgresql-error/no-pg-hba-conf-entry
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall