PostgreSQL · 错误码速查
PostgreSQL「Peer authentication failed」：操作系统用户名和数据库用户名对不上，换对用户或改走密码认证
这条报错说明连接命中了 pg_hba.conf 里一条 local ... peer 规则：peer 方式会从内核取当前操作系统用户名，要求它和你要登录的数据库用户名一致。用 Linux 用户 ubuntu 执行 psql -U postgres 就会失败。最快的改法是 sudo -u postgres psql；应用要用密码登录时，改走 TCP（-h 127.0.0.1）或把那条 local 规则改成 scram-sha-256。
官方原文
Peer authentication failed for user "%s"出自 PostgreSQL 源码 auth.c 的 auth_failed()，错误码 ERRCODE_INVALID_AUTHORIZATION_SPECIFICATION（SQLSTATE 28000）。客户端看到的完整形式一般是 psql: error: connection to server on socket "..." failed: FATAL: Peer authentication failed for user "postgres"。
出处：PostgreSQL 源码 REL_18_STABLE：src/backend/libpq/auth.c（auth_failed） 最后核对：
| SQLSTATE | 28000（invalid_authorization_specification） | 出处 |
|---|---|---|
| 只发生在 | local 连接（Unix 域套接字）；peer 不支持 TCP | 出处 |
| 比对的是 | 内核报告的客户端操作系统用户名 vs 请求的数据库用户名（可用 map= 做映射） | 出处 |
| 常见来源 | Debian/Ubuntu 的 pg_createcluster 默认把本地连接设为 peer | 出处 |
| 服务器日志额外信息 | Connection matched ... line N: "..."，指出命中的是哪一行 | 出处 |
为什么本机连接会走 peer
psql 不写 -h 时默认走 Unix 域套接字，对应 pg_hba.conf 里 local 开头的规则。Debian / Ubuntu 用 pg_createcluster 建的集群，默认就把本地连接设成 peer。典型规则长这样：
# TYPE DATABASE USER ADDRESS METHOD
local all postgres peer
local all all peer
host all all 127.0.0.1/32 scram-sha-256peer 的规则很简单：内核告诉服务器“连过来的是操作系统用户 X”，服务器只允许 X 登录同名的数据库用户。所以下面三种情况都会报这条错：
| 你执行的 | 操作系统用户 | 请求的数据库用户 | 结果 |
|---|---|---|---|
psql -U postgres | ubuntu | postgres | 失败：名字不一致 |
sudo psql -U postgres | root | postgres | 失败：sudo 后是 root |
应用用 localhost 以外的方式连套接字，用户名 app | www-data | app | 失败：服务进程用户不是 app |
sudo -u postgres psql | postgres | postgres | 成功 |
三种改法，按场景选
| 场景 | 做法 | 要不要改配置 |
|---|---|---|
| DBA 在服务器上做管理 | sudo -u postgres psql，以 postgres 系统用户执行 | 不用 |
| 应用或脚本要用密码登录 | 连接串写 -h 127.0.0.1（或 localhost），改走 host 规则，用密码认证 | 通常不用；确认 host 行是 scram-sha-256 / md5 |
| 坚持用套接字 + 密码 | 把对应 local 行的 peer 改成 scram-sha-256，并给数据库用户设好密码 | 要，改完 reload |
| 固定的系统用户映射到另一个数据库用户 | pg_ident.conf 写映射，local 行加 map=名称 | 要，改完 reload |
# 1) 管理员：切到 postgres 系统用户
sudo -u postgres psql
# 2) 应用：改走 TCP，使用密码认证
psql -h 127.0.0.1 -U app -d appdb改走 TCP 后如果变成 password authentication failed，说明 peer 这一步已经过了，接下来查密码，见 password authentication failed。
用 pg_ident.conf 做用户名映射
官方的 User Name Maps 允许“这个操作系统用户可以以那个数据库用户登录”。例如允许系统用户 deploy 以数据库用户 app 登录：
# pg_ident.conf
# MAPNAME SYSTEM-USERNAME PG-USERNAME
appmap deploy app
# pg_hba.conf（这行要放在 local all all peer 之前）
local appdb app peer map=appmappg_hba.conf按顺序匹配、命中第一条就停，所以带map=的这行必须放在通用的local all all peer前面。pg_ident.conf同样只在启动和 SIGHUP 时读取，改完执行SELECT pg_reload_conf();。- PG15 起可以用
pg_ident_file_mappings视图检查映射是否解析成功；PG14 及以前没有这个视图，只能看服务器日志。
改 pg_hba.conf 的安全步骤（PG10 及以上）
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;-- 改完 pg_hba.conf 后，先看有没有语法错误（error 列非空即有问题）
SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;
-- 没有错误再重新加载（不需要重启）
SELECT pg_reload_conf();pg_hba_file_rules 显示的是文件当前内容，不是服务器已加载的内容，所以可以在 reload 之前先检查。PG16 起服务器日志里的 Connection matched 会带上文件名，PG15 及以前只写行号。
常见问题
Peer authentication failed for user "postgres" 怎么解决？
用 sudo -u postgres psql 以 postgres 系统用户执行。peer 方式要求操作系统用户名和数据库用户名一致，用别的系统用户执行 psql -U postgres 就会失败。
为什么 sudo psql -U postgres 也不行？
sudo 之后当前用户是 root，不是 postgres，peer 比对的是 root 和 postgres，所以仍然失败。要写 sudo -u postgres。
应用连本机 PostgreSQL 报 peer 错误怎么办？
把连接串的主机写成 127.0.0.1 或 localhost，让连接走 TCP 和 host 规则，用密码认证。peer 只用于 Unix 套接字连接。
把 peer 改成 trust 可以吗？
trust 表示不验证身份，任何能连上套接字的系统用户都能以任意数据库用户登录，不建议在有多个系统用户的服务器上使用。需要密码登录就改成 scram-sha-256。
改了 pg_hba.conf 为什么没生效？
pg_hba.conf 只在启动和收到 SIGHUP 时读取，改完要执行 SELECT pg_reload_conf() 或 pg_ctl reload。另外规则按顺序匹配，前面已有一条匹配的 peer 行时，后面的改动不会被用到。
免费 · 留邮箱领检查单
PostgreSQL 14 停更升级检查单（Excel 可直接打开）
- PG14 2026-11-12 停更，升 17 / 18 前后 19 项检查：只读预检、--check、回滚、补统计、回归
- 每项写清怎么查、通过标准、不处理会怎样（附测试库实测数字）
- 配合站上的只读预检 SQL 使用，每个业务库各跑一次
下一步
价格以对应页面当前标价为准。
出处（最后核对 2026-11-04）
- PostgreSQL 源码 REL_18_STABLE：src/backend/libpq/auth.c（auth_failed）
- PostgreSQL 18 文档 20.9：Peer Authentication
- PostgreSQL 18 文档 20.2：User Name Maps（pg_ident.conf）
- PostgreSQL 18 文档 20.1：The pg_hba.conf File
- PostgreSQL 18 文档：pg_hba_file_rules 视图
- Debian postgresql-common：pg_createcluster(1) 手册
本页摘录并解读上面列出的官方文档，不是官方页面；官方文档更新后以官方为准。本页内容都来自官方文档，没有我们自己的测试结果。