乐悠厨房如果你在终端里看到这么一行 pgsql 报错，大概率会和我第一次遇到时一样，先愣一下：
text复制connection to server at "1", port 5432 failed "postgres" P
这个报错看起来非常奇怪——主机名是个孤零零的 1，后面还拖着半截 postgres 和 P，像是被什么东西从中间硬生生剪断了。实际上，它通常是完整报错在日志或终端里被截断、换行折叠之后留下的残片。把它还原出来，最常见的完整形态长这样：
text复制psql: error: connection to server at "localhost" (::1), port 5432 failed:
FATAL: password authentication failed for user "postgres"
这个报错能出现在 psql 命令行、DBeaver、Navicat、Java JDBC、.NET 的 Npgsql（也就是 ADO.NET 场景）、Python 的 psycopg2，以及任何走 TCP 5432 端口的 PostgreSQL 客户端上。它并不是某个平台特有的问题，Linux、macOS、Windows 上装完 PostgreSQL 后都容易碰到。文章后面我会按实际排查顺序把这类问题拆开讲。刚装完 pgsql 连不上的新手可以直接照着做，被生产环境 5432 折腾过的老手也能拿这套检查清单快速定位。
1. 拿到 pgsql connection failed 报错，先别急着背命令
1.1 一段连接报错信息里到底藏了哪些关键线索
PostgreSQL 客户端报连接失败时，不是随便给你一句话，而是把“目标主机、端口、连接阶段、失败原因”压缩到了一行里。拿这个经典报错拆开看：
text复制connection to server at "localhost" (::1), port 5432 failed: FATAL: password authentication failed for user "postgres"
逐段解读：
connection to server at "localhost" (::1)：客户端要连的主机是localhost，(::1)表示系统把localhost解析成了 IPv6 回环地址::1。你可以把它理解成快递员拿到了地址，但发现写的是“本市环路一号”，他得先确认这个门牌到底存不存在。port 5432：端口是 PostgreSQL 默认端口。绝大多数报错都停在这个数字上，说明问题不在端口号本身。FATAL:：这是 PostgreSQL 服务端返回的致命错误标记，注意它和前面“TCP 连不上”是不同的阶段。FATAL出现时，至少说明你的数据包已经到达了 PostgreSQL 进程。password authentication failed for user "postgres"：这才是真正的病因——用户postgres的密码认证没通过。这是最常见的失败原因，占了这类报错的一大半。
如果是连接服务端本身失败，后半段往往会是 Connection refused、Connection timed out、No route to host，或者 server does not support SSL。所以收到报错的第一件事不是去改防火墙，而是先看后半段到底写的什么。
1.2 为什么日志会截断成 “1” 和 “postgres P” 这种碎片
你看到的标题里 at "1" 并不代表真的有台主机叫 1，而是完整信息 at "localhost" (::1) 在展示或复制时被截断了。这类截断经常出现在三种场景里：
- 终端宽度不够，psql 或 IDE 把长错误信息换行，复制的时候只复制了半行；
- CI/CD 日志、容器日志平台按行存储长文本，自动把中间内容折叠了；
- 某些客户端库对错误信息做了长度限制，只把首尾拼给你。
同理，结尾的 "postgres" P 是 "postgres" 后面紧跟着 password... 的开头字母。遇到这种残缺信息，我建议先去拿完整报错，别猜。命令行下可以把 psql 的错误输出重定向到文件再看：
bash复制psql -h localhost -p 5432 -U postgres -d postgres 2>&1 | tee /tmp/pg_conn_error.log
如果能在服务端看日志，直接翻 PostgreSQL 日志是最准确的，因为服务端记录的是原始完整信息，不经过客户端裁剪。
1.3 先建立排查框架：网络层失败 vs 认证层失败
我把常见的 PostgreSQL 连接失败分成两大类，对应的处理方式完全相反，混淆了会白折腾：
| 报错关键字 | 所处阶段 | 典型原因 |
|---|---|---|
Connection refused |
TCP 连接层 | 服务没启动、端口没监听、防火墙拦截 |
Connection timed out |
TCP 连接层 | 网络不通、安全组未放行、远端地址错误 |
No route to host |
TCP 连接层 | 路由不可达、主机不存在 |
server does not support SSL |
SSL 协商层 | 客户端强制要求 SSL，服务端未开启 |
FATAL: password authentication failed |
PostgreSQL 认证层 | 密码错误、pg_hba.conf 认证方式不匹配 |
FATAL: role "postgres" does not exist |
PostgreSQL 角色层 | 用户不存在或集群 superuser 不叫 postgres |
FATAL: database "xxx" does not exist |
PostgreSQL 数据库层 | 库名拼写错误 |
只要看到 FATAL:，就证明 TCP 已经通了，往后要查的是 PostgreSQL 自己的用户、密码、权限和库。如果看到 Connection refused，那就先别折腾密码，去查服务进程和监听端口。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。