永远雪山1. 先把这个报错拆开看：pgsql 到底在哪个环节连不上
先别被这串英文吓到。pgsql 的连接失败错误提示虽然长，但绝大多数 connection failed、port 5432 failed 的现象都可以归结到三个层面：网络层、服务配置层、认证层。很多新手第一眼看到“connection failed”就以为是服务挂了，接着开始查防火墙、重启服务，折腾半天才发现，服务端日志里明明写的是角色不存在，或者 IP 根本没被 pg_hba.conf 放行。
真正有价值的报错信息往往在冒号后面。比如标题里截断的这段，完整形态通常是：
text复制psql: error: connection to server at "localhost" (:1), port 5432 failed:
FATAL: role "postgres" does not exist
这串内容里，“localhost”“(:1)”“5432”都只是连接目标描述，告诉你客户端在往本机的 IPv6 回环地址 ::1 的 5432 端口发起连接。看到 FATAL: 开头的内容，说明 TCP 连接其实已经建立起来了，是 PostgreSQL 服务端返回了明确的错误信息。“role 'postgres' does not exist”才是真正的根因，和网络通不通、端口通不通没有任何关系。
经常有朋友拿着类似报错来问我，第一句话就是“我密码是不是错了”。不是。角色不存在跟密码错误是两码事。密码错误会提示 password authentication failed，而角色不存在说明服务端在做用户认证时，压根没找到这个登录名。所以排查时，我习惯先把问题分类：连接被拒、超时、SSL 中断属于网络/服务层；FATAL: 后面跟的认证相关消息属于认证层；客户端自己报一堆看不懂的网络请求错误，则往往要先看是不是驱动或环境变量问题。
1.1 FATAL 后面的内容才是数据库给你的“结论”
如果报错里出现了 FATAL:，就要把注意力从前半段挪到后半段。因为连接请求已经到达 PostgreSQL 服务端，数据库完成了 TCP 握手并开始处理认证请求，然后才拒绝了你。这种“能连上但被拒”的情况，排查思路和“根本连不上”完全不同。
常见几种 FATAL：
FATAL: role "postgres" does not exist
数据库里没有叫 postgres 的登录角色。要么用户名写错了，要么初始化数据目录时指定了其他超级用户名。FATAL: password authentication failed for user "xxx"
角色存在，但密码不匹配。重点是检查密码，并确认当前pg_hba.conf用的认证方式是scram-sha-256还是md5。FATAL: no pg_hba.conf entry for host "::1", user "postgres", database "postgres", no encryption
客户端的来源 IP 不在访问白名单里。你可能改了监听地址，却忘了给对应 IP 网段加一条 host 规则。FATAL: database "xxx" does not exist
这更常见，用户和端口都对，但连接的数据库名写错了。
所以第一步，永远是把服务端返回的 FATAL 完整抄下来，再决定下一步。别只看开头几十个英文字母就开始重启服务，那大概率白忙。
1.2 三层定位法：网络层、服务配置层、认证层
我自己排障时习惯不按“现象”走，而是按“阶段”走。连接失败可以理解为一次快递派送：快递员要先把包裹送到小区门口，再让门卫核对身份，最后确认收件人存在。对应到 PostgreSQL 上，就是网络层、服务层、认证层。
第一层，网络能不能到。如果报错是 Connection refused、No route to host、Operation timed out，那问题出在“小区门口”。先查服务有没有启动、端口有没有监听、防火墙有没有放行。
第二层，服务愿不愿意收。如果报错是 server closed the connection unexpectedly、SSL SYSCALL error，一般是 PostgreSQL 的服务配置、SSL 握手或客户端驱动协议出了问题。这一层容易被忽略，因为错误信息不直观，很多经验不足的人会误以为是网络问题。
第三层，身份和权限。只要报错里出现 FATAL:，就说明包裹已经递到门卫手里了。这时候看 pg_hba.conf、角色是否存在、密码是否错误。
三层定位法看着简单，但能避免大量无效操作。我最常见到的情况是：用户远程连不上，第一反应是改 PostgreSQL 密码，改完发现还是不行，最后才发现根本没改 listen_addresses，数据库压根没监听外部网卡。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 网络层最常见的两个坑：服务没监听与本地回环地址解析
如果你那边的报错是长这样的：
text复制connection to server at "localhost" (:1), port 5432 failed: Connection refused
这是最常见的网络层场景。端口 5432 上根本没有 PostgreSQL 在接收连接，连接请求被系统直接拒绝。首先要做的不是去改密码，也不是去翻应用配置，而是确认数据库进程本身有没有起来。
2.1 先确认 5432 端口上真的有 PostgreSQL 在听
Linux 环境下，最直观的是看端口监听状态。我一般两步走：
bash复制systemctl status postgresql
ss -lntp | grep 5432
systemctl status 看服务单元是否 running；ss -lntp 看 5432 端口到底被哪个进程占着。如果看到进程存在但没有输出，说明 PostgreSQL 没监听 TCP，或者监听的地址不是本机回环地址。
如果服务压根没起来，服务端日志里通常会有原因。Debian/Ubuntu 的日志路径一般在 /var/log/postgresql/postgresql-16-main.log，RedHat/CentOS 系一般在 /var/lib/pgsql/16/data/log/ 下。看日志时重点找几个关键词：could not bind、Address already in use、permissions on file。
其中 Address already in use 要特别提醒一句：5432 端口被其他进程占了。有可能是你自己手动起了第二个 PostgreSQL 实例，也可能是别的程序占用了端口。这时候即便服务再正常，应用也连不上你期望的那个实例。先看端口被谁占了，比你反复重启有效得多。
Windows 下的排查逻辑一样，用 netstat -ano | findstr 5432 查端口占用，再到任务管理器里核对 PID 对应的进程。很多 Windows 本机用户遇到的 Connection refused，其实是安装时只装了命令行工具，没把 PostgreSQL 注册成 Windows 服务，或者服务启动类型被改成了手动。
2.2 “localhost”不等于“127.0.0.1”，IPv6 的坑要认出来
这里必须单独说一个非常隐蔽的坑：报错里写着 localhost (:1)，很多人想当然以为它在连 127.0.0.1，其实不是。:1 是 IPv6 回环地址 ::1 的缩写。localhost 在现代操作系统里通常会同时解析为 IPv4 和 IPv6 两个地址，客户端优先尝试 IPv6，然后才回落 IPv4。
PostgreSQL 默认 listen_addresses = 'localhost'。这个配置项的含义在不同平台上有细微差别，但很多系统上，PostgreSQL 只会监听 127.0.0.1 和 ::1 中的一个。假设服务只监听了 IPv4 的 127.0.0.1，而你的客户端先尝试了 IPv6 的 ::1，就会出现 connection to server at "localhost" (:1), port 5432 failed。
在这种报错后面如果跟着 Connection refused，十有八九是 IPv6 回环地址没被监听。
遇到这种情况，最快验证方法是强制走 IPv4：
bash复制psql -h 127.0.0.1 -U postgres -d postgres
如果 -h 127.0.0.1 能连上，说明问题就是 IPv6。要根治可以改 postgresql.conf：
conf复制listen_addresses = '*'
改完需要重启 PostgreSQL，不是 reload。很多人改完 listen_addresses 后用 systemctl reload 重载配置，结果连接还是失败，以为配置没生效。原因是 listen_addresses 这个参数只在数据库启动时读取一次，reload 不会重新绑定端口。只有 pg_hba.conf 的改动支持热加载。这一点是我在所有 PostgreSQL 排障里最常提醒的一句话。
当然，listen_addresses = '*' 不是无脑改的。如果数据库部署在公网服务器上，这等于让 PostgreSQL 对所有网卡开放监听。更稳妥的做法是指定内网 IP：
conf复制listen_addresses = 'localhost,192.168.1.10'
改完执行 pg_ctl restart 或 systemctl restart postgresql，然后用 ss -lntp | grep 5432 确认监听地址已经包含你需要的 IP。
3. 认证层：postgres 角色不存在和 pg_hba.conf 的相爱相杀
到了这一层，报错通常会表现出更“友好”的样子——至少说明网络通了、服务活着：
text复制connection to server at "127.0.0.1", port 5432 failed: FATAL: role "postgres" does not exist
我见过太多人第一次遇到这个报错时，第一反应是“我是不是没写密码”，甚至有朋友重装了三次 PostgreSQL。其实问题跟密码没有关系，是数据库里压根没有 postgres 这个登录角色。
3.1 为什么数据库里会没有 postgres 这个角色
很多人默认认为 PostgreSQL 装好后一定有个叫 postgres 的超级用户。这个认知在多数发行版安装包下成立，但并非绝对。PostgreSQL 初始化数据目录时，默认会创建一个超级用户，名字跟“执行 initdb 命令的操作系统用户”一致。只有你用 postgres 这个系统用户去执行 initdb，初始超级用户才叫 postgres。
如果你用的是 Debian/Ubuntu 的 apt 包，安装时会自动创建 postgres 系统用户并完成 initdb，所以确实有一个 postgres 超级用户。但如果你是自己编译安装、用 zip 包解压，或者用容器镜像时指定了其他管理员用户名，初始化出来的超级用户可能叫 myadmin、pgadmin，就是没有 postgres。
另外还有一种常见场景：应用配置里写死了 Username=postgres，但数据库早就被初始化成另一个超级用户名。应用连进来时，PostgreSQL 先检查有没有名为 postgres 的角色，发现没有就直接返回 role "postgres" does not exist。这跟密码没关系，你把密码换成什么都不会改变结果。
如果你是 Linux apt 包安装，并且系统上创建了 postgres 系统用户，但远程连接时报角色不存在，可以先登录到本机，用系统用户进去看看：
bash复制sudo -u postgres psql -c "\du"
如果看到用户列表里的确有 postgres，那说明不是角色问题，而是你远程连错了实例，或者 pg_hba.conf 里把用户匹配到了其他角色。如果确实没有，用现有超级用户补建一个即可：
sql复制CREATE ROLE postgres LOGIN SUPERUSER;
ALTER ROLE postgres WITH PASSWORD '这里写一个强密码';
创建完之后尽量选一个与安装模式匹配的认证方式。新版 PostgreSQL 默认用 scram-sha-256，密码字段可以直接用 CREATE ROLE ... PASSWORD 设置。
如果没有任何可用的超级用户能登录，比如你连初始超级用户名都忘了，那只能用单用户模式或者临时把 pg_hba.conf 改成 trust 的方式找回。临时改 trust 的方法能救急，但操作要足够小心：先停服务、改配置、再启动、建完角色后立刻改回原来的认证方式。千万别长期把 trust 留在生产环境的配置里，那是裸奔。
3.2 pg_hba.conf 对错误形态的影响，以及修改后的重载问题
PostgreSQL 的客户端接入规则放在 pg_hba.conf 里。它的匹配顺序是从上往下，第一条匹配到的规则生效，后面的规则不再参与。很多诡异的“我能用 A 机器连上，B 机器就是连不上”问题，都是因为 pg_hba.conf 里前面有一条规则把流量拦住了。
不同错误形态对应不同规则问题：
no pg_hba.conf entry for host：说明没有任何一条规则匹配你的来源 IP，或者匹配到了reject规则。password authentication failed：匹配到了规则，但密码错误，或者服务端认证方法要求scram，你客户端还在发md5。role "xx" does not exist：规则放行了，但数据库里没有这个角色。
常见的本地开发配置长这样：
conf复制local all all peer
host all all 127.0.0.1/32 scram-sha-256
host all all ::1/128 scram-sha-256
host all all 192.168.1.0/24 scram-sha-256
第二、第三条覆盖了本机 IPv4 和 IPv6 回环；第四条是给局域网客户端用的。如果你只想让某个具体 IP 连接，就精确写 IP：
conf复制host all all 203.0.113.10/32 scram-sha-256
提示：
pg_hba.conf修改后不需要重启数据库，执行SELECT pg_reload_conf();或者systemctl reload postgresql就会生效。但对已经建立的连接没有影响，只会作用于新连接。
我见过很多人在改了 pg_hba.conf 后直接 restart 数据库，这也不是不行，但没必要。生产环境重启数据库会影响所有正在跑的业务，尤其是有长事务、连接池的场景。能 reload 解决的问题，不要升级到 restart。
另外要注意，pg_hba.conf 里的认证方法字段一定要和 postgresql.conf 里的 password_encryption 参数匹配。PostgreSQL 14 之后默认是 scram-sha-256，如果你为了兼容老客户端改成了 md5，两者不一致也会导致连接失败。服务端日志会提示类似 password authentication failed 或 unsupported frontend protocol，看到这类字眼时去检查这个参数。
这一层排完，绝大多数“连不上”的问题已经能解决。剩下的问题，大多出在客户端侧。
4. 客户端侧差异：psql、ADO.NET/Npgsql、DBeaver 的常见连接失败原因
有时候服务端配置没有任何问题，用命令行 psql 也能正常连，但换到程序或图形工具里就报错。遇到这种场景，要立刻把排查重点切换到客户端连接参数上。
不同的客户端工具对连接参数的解析方式不一样，对 SSL、超时、驱动版本的要求也不一样。下面拆开讲。
4.1 Npgsql / ADO.NET 连接串的错误写法与正确姿势
.NET 生态下连接 PostgreSQL 最常用的是 Npgsql 驱动，也就是 ADO.NET Provider。很多人写连接串时会下意识套 SQL Server 的格式，结果踩了不少坑。
先看一个常见的错误写法：
text复制Server=localhost;Database=postgres;UID=sa;PWD=123456;Trusted_Connection=true;
sa、Trusted_Connection 都是 SQL Server 的习惯，Npgsql 根本不认识。Npgsql 的典型连接串是：
text复制Host=127.0.0.1;Port=5432;Database=postgres;Username=postgres;Password=your_password;SSL Mode=Prefer;
里面几个容易搞混的点：
Host可以写成Server，两个都认，但别只写主机名不写端口。如果 PostgreSQL 跑在非默认端口，而连接串里漏了Port=5432之外的端口，就会连到默认端口去。Username是 PostgreSQL 角色名，不是 Windows 登录名。SSL Mode是 Npgsql 特有的写法，取值一般是Prefer、Require、Disable。如果测试环境没配 SSL 证书，可以先用Disable排除 SSL 干扰。
还有一个容易被忽视的场景：连接池。Npgsql 默认启用连接池，连接串里 Maximum Pool Size 默认是 100。如果应用里频繁创建连接却没正确释放，连接池耗尽后新增连接请求会一直等待，最终表现为超时。验证方法很简单，把连接串里的 Pooling=true 临时改成 Pooling=false 再跑一次。如果立刻能连上，就说明连接池配置或代码使用方式有问题，而不是数据库的问题。
连接串里如果出现 Timeout=15，这个 15 秒是“建立连接的超时时间”，不代表数据库查询超时。排在数据库前面的防火墙如果直接丢弃包，不在一定时间内返回结果，客户端会一直等到 Timeout 耗尽才报错，所以你会觉得应用“转圈圈转很久才报失败”。这通常是网络不通而不是数据库问题。
4.2 DBeaver 连接 pgsql 的检查点
DBeaver 是很多人日常查数据用的图形工具。它连接 PostgreSQL 的报错有时跟 psql 不一样，因为 DBeaver 走的是 JDBC 驱动，不是 libpq。
首次连接时，DBeaver 会自动下载 PostgreSQL JDBC 驱动。如果下载失败，测试连接会直接报驱动相关错误，甚至“Can't create driver instance”。这种问题跟你的数据库没关系，是 DBeaver 没法获取 jar 包。
我的建议是，宁可手动驱动。在 DBeaver 菜单里找到“数据库 -> 驱动管理器”，选中 PostgreSQL，点“编辑”，在“库”页签里手动添加本地的 postgresql-x.y.z.jar。这个 jar 可以从你 Maven 仓库或者项目依赖里直接复用。驱动版本不要太老，PostgreSQL 14 之后的 scram-sha-256 认证需要较新的 JDBC 驱动才完整支持。
DBeaver 连接设置页里需要填的字段不多：
- Host：不要填 localhost，直接填 127.0.0.1，避免 IPv6 坑。
- Port：5432。
- Database：postgres，或者你真实的业务库名。
- Username：postgres。
- Password：对应密码。
DBeaver 默认会对 SSL 做协商，如果你的服务端没有启用 SSL，但驱动属性里的 sslmode 被设成了 require，就会报证书或 SSL 错误。可以新建连接时在“驱动属性”里找到 sslmode，改为 disable 或 prefer 再试。
另外，DBeaver 连接远程 PostgreSQL 前，必须确保服务器 listen_addresses 包含了对外网卡地址，并且 pg_hba.conf 放行了你的来源 IP。很多人在本机用 DBeaver 连本机 PostgreSQL 没问题，一旦把 Host 改成远端服务器 IP 就连不上，原因通常是远端数据库没有监听外部地址。
提示：DBeaver 默认会保留历史连接和凭据。如果确认密码没变但连不上，先试“新建一个连接”，避免旧驱动缓存干扰。
4.3 报错 000000e / server closed connection：先怀疑 SSL 握手
PostgreSQL 客户端连接时有一套自己的协议流程。如果服务端配置了 SSL，postgresql.conf 里 ssl = on，而客户端的 SSL 库或驱动版本过旧，可能出现握手中断。错误信息往往不是标准 FATAL，而是：
text复制connection to server at "127.0.0.1", port 5432 failed: server closed the connection unexpectedly
有些 psql 或图形客户端会附带类似 000000e、SSL SYSCALL error: EOF detected 这样的代码。我在实际排查中看到这种错误，第一反应是关掉 SSL 试一次，而不是去查防火墙。
如果在 psql 命令里可以这样排除：
bash复制psql "host=127.0.0.1 port=5432 dbname=postgres user=postgres sslmode=disable"
如果关掉 SSL 后连接正常，说明问题出在 SSL 协商上。可以进一步检查服务器证书有效期、证书链是否完整、客户端系统时间是否偏差过大。系统时间不对是 SSL 握手失败的一个隐性因素，证书“还没生效