在 PostgreSQL 中，客户端连接被拒绝并提示类似 FATAL: password authentication failed for user 的错误时，很多人的第一反应是密码记错了。但实际场景里，认证失败更多来自服务端认证配置、角色属性或连接方式不匹配。定位这类问题最快的方式不是反复重试密码，而是先查看数据库日志中的完整报错信息。不同认证方法报错文本不同，例如 peer authentication failed、ident authentication failed、no pg_hba.conf entry for host 等，每种都指向不同原因。
接下来需要确认客户端是通过 Unix socket 还是 TCP 连接。psql 默认在本地可能走 socket，而应用连接串使用 localhost 或 IP 时走 TCP。两者匹配的 pg_hba.conf 规则不一样，这也是很多本地命令行能登录但程序连接失败的原因。先定位连接类型，再检查对应规则，能避免大范围改动配置。
一、从错误日志定位认证失败类型
PostgreSQL 的认证失败信息会记录在数据库日志中，日志位置可以在 postgresql.conf 中通过 log_destination 和 logging_collector 参数查看。常见错误包括密码认证失败、peer 认证失败、ident 认证失败以及没有匹配的认证规则。密码认证失败通常说明 PostgreSQL 已经要求客户端提供密码，但密码与角色存储的密码不一致；peer 认证失败则是因为本地 socket 连接时操作系统用户与数据库角色不匹配，根本不会校验密码。
如果日志中出现 no pg_hba.conf entry for host，说明该客户端的 IP 地址、数据库名、用户名组合没有匹配到任何一条规则，PostgreSQL 默认执行拒绝策略。此时要检查 pg_hba.conf 中是否缺少对应网段的 host 规则，或者客户端的 IP 被 NAT 转换后不在允许范围内。还有一种情况是 IPv6 地址匹配问题：连接串写的是 localhost，但客户端优先解析成 ::1，而 pg_hba.conf 只配置了 127.0.0.1，导致规则匹配不到。
日志中如果看到 ident authentication failed，说明 PostgreSQL 尝试通过操作系统的 ident 服务确认客户端身份，但目标机器没有运行 ident 服务或返回了错误用户。这种认证方式在 Linux 本地 socket 中常见，如果数据库用户和系统用户不一致，就会失败。定位到具体错误类型后，再进入对应配置文件或角色属性中处理，成功率会高很多。
二、检查 pg_hba.conf 的规则顺序和认证方法
pg_hba.conf 是 PostgreSQL 客户端认证的核心文件，规则按照从上到下的顺序匹配，先匹配到的规则生效。因此即使文件中有允许的规则，如果前面有一条更宽泛但认证方法不合适的规则先匹配，也会导致认证失败。例如文件开头有 local all all peer，而应用使用本地 socket 连接，数据库用户与系统用户不一致，就会直接报 peer 认证失败，后面的密码规则不会被执行。
下面是一个常见的 pg_hba.conf 片段：
# TYPE DATABASE USER ADDRESS METHOD local all all peer host all all 127.0.0.1/32 scram-sha-256 host all all ::1/128 scram-sha-256
如果本地 socket 连接需要使用密码认证，可以把 local 行的 METHOD 从 peer 改成 scram-sha-256 或 md5。如果希望远程连接通过密码认证，需要确认 host 行存在，并且 ADDRESS 覆盖了客户端所在网段。修改时不要把规则顺序随意调整，否则可能导致某些连接突然被拒绝。修改后需要重载配置才能生效。
在 Windows 平台，PostgreSQL 数据目录默认位于 C:\Program Files\PostgreSQL\16\data，其中 pg_hba.conf 就在该目录下。编辑后如果无法保存，需要检查文件权限，某些情况下需要以管理员身份打开编辑器。文件中的注释行以 # 开头，不会影响认证行为。
三、排查角色状态、密码加密与过期时间
认证失败不一定是 pg_hba.conf 的问题，角色本身的状态也会影响登录。角色有 rolcanlogin 属性，如果为 false，即使密码正确也不能登录。角色还可以设置有效期 rolvaliduntil，超过该时间后认证会被拒绝。通过以下 SQL 可以查看角色的关键属性：
SELECT rolname, rolcanlogin, rolvaliduntil FROM pg_roles WHERE rolname = 'app_user';
如果 rolcanlogin 为 false，需要执行 ALTER ROLE app_user LOGIN; 开启登录权限。如果 rolvaliduntil 已经过期，可以执行 ALTER ROLE app_user VALID UNTIL 'infinity'; 清除过期时间。执行这些操作需要以超级用户身份登录数据库，本地管理员通常可以通过系统用户 postgres 直接登录。
另一个常见问题是密码加密方式不一致。PostgreSQL 10 之后默认使用 scram-sha-256，而旧版本或从旧版本升级上来的角色可能仍然使用 md5。如果 pg_hba.conf 中要求 scram-sha-256，但角色存储的是 md5 密码，认证会失败。此时可以重新设置密码，让 PostgreSQL 使用当前默认的加密方式：
ALTER ROLE app_user WITH PASSWORD 'new_password';
重新设置密码后，认证时就会按照 password_encryption 参数生成新的加密格式。如果应用不支持 scram-sha-256，可以临时在 pg_hba.conf 中把对应规则的 METHOD 改成 md5，但这不是长期推荐方案，因为 scram-sha-256 更安全。
四、修改后重载配置并验证连接
修改 pg_hba.conf 或 postgresql.conf 后，不需要重启整个数据库服务，只需要执行重载操作让配置生效。可以通过 SQL 命令 SELECT pg_reload_conf(); 完成，也可以使用系统命令 pg_ctl reload 或 Windows 服务管理器中的重载功能。重载成功后，日志中会出现配置已重载的记录。
SELECT pg_reload_conf();
重载后不要直接结束排查，应该使用目标客户端重新建立连接，确认问题是否解决。可以用 psql 命令指定主机、端口、用户和数据库进行测试。例如：
psql -h 127.0.0.1 -p 5432 -U app_user -d mydb
如果仍然失败，再回到日志中查看新的报错信息，确认是否切换到了另一种错误类型。例如原本是 peer 认证失败，修改后变成密码认证失败，说明已经进入密码校验环节，此时可以专注于角色密码问题。每一步只调整一个变量，才能快速收敛问题点。
最后还要检查 postgresql.conf 中的 listen_addresses 和 port 设置。如果客户端通过远程连接失败，但日志中没有任何连接记录，可能是服务根本没有监听目标地址。把 listen_addresses 改成 * 或具体的网卡 IP，再确认防火墙放行端口，才能让认证规则有机会匹配。
PostgreSQL认证失败pg_hba.conf密码认证修改时间：2026-09-24 07:21:25