PostgreSQL连接失败排查：从报错原文到PGHOST环境变量陷阱

先说个结论：看到connection failed这种报错，第一反应不应该是跑去翻防火墙，而是先把报错原文一个字一个字读清楚。标题里这个报错很有意思，connection to server at "1", port 5432 failed，后面还跟了一个孤零零的P。这个P大概率是复制报错时被截断了，但更值得注意的，是那个被引号框起来的1——PostgreSQL 客户端想要连一台名字叫1的机器，而这样的机器在绝大多数环境里都不存在。

很多人栽在这一步，问题根本不在 pgsql 服务本身，而在连接参数。这篇文章我就围绕这行典型的 PostgreSQL 连接失败报错，把"报错怎么拆解、排错按什么顺序、真实案例怎么复盘、平时怎么避免"完整过一遍。无论你是刚装完 pgsql 还连不上，还是被这种报错折腾过几次的老手，应该都能从里面找到能直接用的东西。

1. 报错原文拆解：被引号圈住的"1"才是核心线索

1.1 connection to server at "..."：这是哪一层的失败？

PostgreSQL 客户端的连接过程大致分四步：解析主机名或 IP、建立 TCP 连接、完成 SSL/TLS 协商（如果启用）、发送启动报文给数据库做身份认证。

connection to server at "1", port 5432 failed这一步发生在最前面的"解析主机名 + 建立 TCP"阶段。也就是说，客户端可能连对方的 IP 都没摸到，更没到"密码对不对"那一层。

有个点很容易被忽略：server at "1"里面的1，并不是什么固定参数，而是客户端实际尝试去连接的目标主机名。它可以是 IP，也可以是域名，还可以是一个被你写错的环境变量值。报错里出现1，基本只可能是三种情况之一：

• 连接串里 host 字段写成了1，比如psql -h 1 -U postgres -d postgres
• 环境变量PGHOST被设置成了1
• 程序代码里把某个编号变量当主机名拼进了连接串

记住这个思路：报错里出现的每一个值，都是客户端真实想用的值。你不需要猜服务端有什么问题，先盯住客户端到底在连谁。

1.2 port 5432：默认端口为什么会出现在报错里

5432 是 PostgreSQL 的默认端口。看到port 5432很多人会下意识以为"端口是不是被占用了？防火墙是不是没放行？"——先别急着下结论。

port 5432 failed只是陈述了一个事实：客户端试图连目标的 5432 端口，但失败了。至于失败原因是"对端没监听""网络不通""被防火墙丢弃"，还是"对端监听了别的位置"，报错本身没有说。所以这一段的正确用法是：确认一下你的服务端到底在监听哪个端口。有时候你把端口改成了 5433，但客户端连接串还写着 5432，那当然是port 5432 failed。

查看端口监听我一般用这几条命令：

# Linux ss -lntp | grep 5432 # Windows netstat -ano | findstr 5432

如果输出里能看到 PostgreSQL 进程在0.0.0.0:5432或127.0.0.1:5432上监听，说明端口这层没问题，问题在别处。如果什么都没输出，说明服务端根本没在这个端口上监听。

1.3 failed "postgres"和尾部那个孤零零的"P"

标题里failed "postgres" P明显是一个被截断的报错。完整的报错尾部大概长这样：

connection to server at "1", port 5432 failed: FATAL: password authentication failed for user "postgres"

或者：

FATAL: database "postgres" does not exist

这里有个很实用的经验：复制报错必须整段复制，最好连带时间戳和上下文一起复制。我见过太多人把报错尾部截掉，然后在论坛上问"为什么连接失败"，下面的人只能从残缺信息里猜。FATAL之后的描述才是真正的病根，比如：

• password authentication failed for user "postgres"：TCP 通了，密码不对。
• database "postgres" does not exist：TCP 通了，认证也可能过了，但连的库不存在。
• no pg_hba.conf entry for host "192.168.1.10", user "postgres", database "postgres"：TCP 通了，但认证规则没匹配上。

所以看报错要养成习惯：先看connection to server at ... failed之后那一段FATAL或DETAIL，那里通常才是真正的答案。

1.4 引号、中文引号与手动转写误差

标题里出现的"1"用的是中文引号“1”，这个细节值得说一句。真实的 psql 报错里，主机名两侧是英文引号。中文引号只有一种来源：报错从网页、聊天记录、截图转写出来的时候被人为重新敲过一遍。

这种"二道转写"非常容易引入误差。比如有人会把1看成l，或者把0（数字零）看成O，把-h参数漏掉。排查这类连接问题的时候，一定以终端里复现的原始输出为准，不要以聊天软件里的转写文本为准。这不是矫情，是排错的基本纪律。

2. 我建议的排错顺序：进程、监听、网络、认证、密码

很多新手一看到connection failed就先去重置密码，这是最浪费时间的一种做法。我的习惯是严格按层级来，从下往上、从内到外，每层都用命令验证完再进下一层。顺序是这样的：进程有没有起 → 端口在不在监听 → 网络通不通 → 认证规则拦没拦 → 密码对不对。

2.1 第一层确认：数据库进程有没有在跑

这一步最简单，但也最容易被忽略。服务的状态直接决定了后面所有层的判断。

Linux 下：

systemctl status postgresql

或者看进程：

ps aux | grep postgres

Windows 下到服务管理器（Win+R 输入services.msc）里看postgresql-x64-16之类的服务是否处于"正在运行"。

macOS 下用 Homebrew 装的话：

brew services list

还有一条所有平台通用的命令，pg_isready，专门用来探测 PostgreSQL 是否在某个端口就绪：

pg_isready -h 127.0.0.1 -p 5432

如果输出accepting connections，说明服务端进程活着并且接受了连接请求，问题在更高层；如果输出no response，说明进程可能没跑。

2.2 第二层确认：端口在不在监听，监听在哪块网卡

进程起来不代表端口就对了。PostgreSQL 默认配置里listen_addresses往往是'localhost'，意思是只监听本机回环地址。这样的配置下，本机用127.0.0.1可以连，局域网里的其他机器就连不上。

看监听地址还是用前面那两条命令。这里重点解释一下监听地址的区别：

• 127.0.0.1:5432：只让本机通过回环地址连接，外部访问一律连不上。
• 0.0.0.0:5432：监听所有 IPv4 网卡，只要防火墙允许，局域网内的机器都能连。
• ::5432：监听 IPv6，也要注意。

如果你想允许远程连接，需要改postgresql.conf里的listen_addresses：

listen_addresses = '*' # 监听所有网卡，或者写具体的IP，如 '192.168.1.10'

注意：改这个参数后必须重启 PostgreSQL，reload 不生效。这个坑后面还会细说。

2.3 第三层确认：从客户端所在的网络能不能摸到这个端口

这一层是在测网络路径，而不是在测 PostgreSQL。我用telnet测 TCP 端口连通性：

telnet 192.168.1.10 5432

如果连接被拒绝（Connection refused），说明端口没在听或者防火墙把端口挡了。如果卡住不动直到超时，说明网络路径上有丢包或被防火墙静默丢弃，这种情况最隐蔽。

Windows 上 PowerShell 可以用：

Test-NetConnection 192.168.1.10 -Port 5432

判断标准很简单：在客户端机器上能telnet 通服务器的 5432，才轮到怀疑认证和密码；telnet 都不通，问题在进程、监听或防火墙/安全组。别在密码上折腾半天，最后发现是云服务器安全组没放行 5432。

2.4 第四层确认：pg_hba.conf的认证规则拦没拦你

TCP 能通之后，PostgreSQL 会按pg_hba.conf里的规则逐条匹配客户端的 IP、数据库名、用户名和连接方式。规则是自上而下第一条匹配者生效。常见的默认规则长这样：

# TYPE DATABASE USER ADDRESS METHOD host all all 127.0.0.1/32 scram-sha-256 host all all ::1/128 scram-sha-256

这意味着默认情况下，只允许本机回环地址用scram-sha-256认证方式连接。如果你用内网 IP192.168.1.50访问，会直接被打回，报错通常是：

FATAL: no pg_hba.conf entry for host "192.168.1.50", user "postgres", database "postgres", SSL off

想要允许局域网访问，需要在文件里加一行，比如：

host all all 192.168.1.0/24 scram-sha-256

改完pg_hba.conf不需要重启，reload 即可：

systemctl reload postgresql

或者在 psql 里执行：

SELECT pg_reload_conf();

2.5 第五层确认：密码和连接串参数

前面四层都通了才轮到密码。PostgreSQL 的密码认证失败报错非常明确，就是password authentication failed for user "postgres"。这种情况重置密码用：

su - postgres -c "psql -c \"ALTER USER postgres PASSWORD '你的新密码';\""

Windows 下可能需要先切到 postgres 用户再执行，或者用 GUI 工具连上去改。

密码的坑也很典型：刚装完 PostgreSQL 时，postgres用户的密码可能不是你以为的那个。Windows 安装器会让你设置密码，Linux 用initdb初始化的集群默认走 peer 认证，本地postgres系统用户可以直接免密登录，但 TCP 连接就不一定了。所以"密码不对"很多时候不是改密码的问题，而是认证方式和密码压根没对齐。

3. 现场复盘：当PGHOST被设成"1"之后

这一节我完整复盘一次真实的排障过程，从头到尾走一遍当时的思路。这种"看到什么 → 想到什么 → 验证什么"的链路，比直接给答案更有参考价值。

3.1 故障现象：部署脚本半夜报错

当时是凌晨一点多，运维群里甩过来一条报错截图，内容跟标题几乎一模一样：

psql: error: connection to server at "1", port 5432 failed: FATAL: password authentication failed for user "postgres"

部署脚本是定时任务跑的，每天都往 PostgreSQL 里同步数据，前一天还是好的，今天突然就失败了。报错里的FATAL: password authentication failed让人第一时间想到"密码过期了？被人改了？"——但实际上connection to server at "1"这个诡异的主机名才是真正的异常信号。

3.2 第一直觉错在哪：我先去查了服务端

我当时第一反应也是去查服务端：进程正常、端口正常、防火墙正常、日志里干干净净，没有任何来自"1"这个主机的连接记录。查了一圈发现数据库本身一切健康，报错却还在。

回头看 varchar 的这个主机名1，才意识到问题根本不在服务端，而在客户端。如果服务端日志里压根没有对应的连接尝试记录，那多半是请求根本没到达数据库。这是一个非常关键的判断依据：服务端日志是排错的照妖镜，日志里没有你这条连接，就别再盯着服务端看了。

3.3 复现一次，让报错自己说话

为了复现，我直接手动执行了脚本里的连接命令，结果报错和线上完全一致。接下来用psql -E模式跑连接，把连接参数打出来：

psql -E "host=1 port=5432 dbname=postgres user=postgres"

然后检查客户端环境变量：

env | grep -i pg

输出结果让我愣了一下：

PGHOST=1

原来环境变量PGHOST被设置成了1。PostgreSQL 的 libpq 库里，PGHOST环境变量优先级非常高，连接串里不写host=时，它会自动读取PGHOST。所以 psql 看起来是在连一个叫1的主机，实际是环境变量在作怪。

3.4 根因确认：环境变量把机器编号当成主机名了

再往前翻，发现是部署脚本里有一行把配置文件的机器编号读出来导出成了PGHOST，原本应该是从配置里取数据库主机地址，结果因为解析逻辑写错，读到了配置里某行的第一个字段——而那个字段刚好是1（机器分区编号）。

修复很简单，把脚本里的导出逻辑改成读取真正的主机名，然后清掉旧环境变量：

unset PGHOST

再用psql连接，一切恢复正常。

3.5 复盘结论：报错的提示都在原文里

这个案例里最有意思的一点是：报错从一开始就写得很清楚——server at "1"。但我和同事都先被password authentication failed带跑了，下意识去检查密码和服务端，浪费了大概二十分钟。

教训有三条：

1. 报错里的每个字段都值得先读完，尤其是server at "..."这个位置。它告诉你的是"客户端实际在连谁"。
2. 服务端日志没有对应记录时，问题基本在客户端或网络路径。
3. 环境变量在连接过程中的优先级很高，排查时要主动检查PGHOST、PGPORT、PGUSER这类变量。

从那以后我再遇到connection to server at "..."报错，第一件事就是打印客户端环境变量。

4. 排障时容易踩的隐藏坑：六个检查点

除了核心的排错链路，还有几个"不做功课绝对会踩"的坑，这里单独整理出来。每个坑我都见过至少三次以上，写出来帮你直接绕开。

4.1 Linux下psql不经过5432端口（socket优先）

在 Linux 上执行psql -U postgres -d postgres时，如果没有显式指定-h，libpq 默认走的是 Unix domain socket，而不是 TCP 5432。socket 连接走的认证规则在pg_hba.conf里是local开头的行，根本不会触发host系列的 TCP 规则。

这就导致一种迷惑现象：本机能连，把-h 127.0.0.1加上反而报错。原因往往是 socket 认证用的是peer，TCP 认证走的是scram-sha-256，两边的要求不一样。判断一个连接到底走没走 TCP，看命令里有没有-h就行。建议统一用-h 127.0.0.1这种方式验证，能避开 socket 和 TCP 的混乱。

4.2 本机能连、换了机器就报错，多半在listen_addresses

很多人用 DBeaver 在本机连 PostgreSQL 没问题，部署到服务器上从程序连就报Connection refused。原因几乎都是listen_addresses默认只监听 localhost。

这个参数修改后必须重启实例，不是 reload 就能生效的。重启命令：

systemctl restart postgresql

Windows 服务方式安装的话，直接在服务管理器里重启服务。改完以后再用ss -lntp确认监听地址是不是变成了0.0.0.0:5432或你的内网 IP。

4.3 pg_hba.conf改完不重启，但要reload

pg_hba.conf和postgresql.conf的重载机制不一样。前者改完执行SELECT pg_reload_conf();或systemctl reload postgresql就能生效；后者改完通常需要重启才能完全生效，尤其是listen_addresses、port这类启动时读取的参数。

最稳妥的做法是：改postgresql.conf后重启，改pg_hba.conf后 reload。如果不确定改的是哪个文件，直接重启也不会有什么坏处，只是生产环境注意业务中断窗口。

4.4 IPv6规则没配：localhost和127.0.0.1的差异

localhost在现代系统里可能解析成::1（IPv6），也可能解析成127.0.0.1（IPv4）。很多人的pg_hba.conf里配了127.0.0.1/32的规则，却没配::1/128，结果用psql -h localhost连的时候，连接走到了 IPv6 的::1，被认证规则直接拒绝。

表现就是-h 127.0.0.1能连，-h localhost连不上。解决方法是把两条规则都加上：

host all all 127.0.0.1/32 scram-sha-256 host all all ::1/128 scram-sha-256

4.5 连接串里把变量名当值用了

这个坑在程序代码里特别常见。比如有人写：

conn = psycopg2.connect( host=host_id, # 变量名叫 host_id，实际值是1 port=5432, dbname=db_name, user=db_user )

如果host_id这个变量的含义是"机器分组编号"，它的值就可能是1。传到 libpq 里，客户端就真的去连一个叫1的主机。这类问题从代码审查阶段就能发现，但往往要等部署环境里出现connection to server at "1"这类诡异报错才会暴露。

排查技巧：把程序实际拼接出来的连接串原样打印出来看一眼。一步到位。

4.6 多实例与端口占用

同一台机器上可能同时跑着多个 PostgreSQL 实例，比如一个系统自带的旧版本和一个手动安装的新版本，还可能有 Docker 容器占着 5432 端口。你用psql连接的可能是 A 实例，但 B 实例把端口占了，就会出现"服务看起来活着但连不上"的奇怪现象。

检查方法还是ss -lntp | grep 5432，看监听进程到底是哪个二进制。如果有两个实例，建议把不同实例放到不同端口，避免互相打架。

5. 把排错动作化成一个固定套路

5.1 每次连接必带的调试开关

psql有几个参数对排查非常实用：

psql -h 127.0.0.1 -p 5432 -U postgres -d postgres -E

• -E：回显内部执行的 SQL 查询，能看到 psql 自己跑了什么。
• -v ON_ERROR_STOP=1：遇到错误立即停止，不会带歪后续输出。
• -w：永远不提示输入密码，配合PGPASSWORD环境变量做自动化脚本很方便。

另外，给psql加-d用 URI 格式连接会让参数更一目了然：

psql "postgresql://postgres:密码@127.0.0.1:5432/postgres?sslmode=disable"

这种格式里 host、port、dbname、user 全在一个字符串里，报错时一眼就能看出哪段写错了。

5.2 日志里能读到什么

PostgreSQL 服务端日志是排错的下半场。默认情况下，连接失败这种事件不一定都会写日志，尤其是没到认证阶段就断掉的连接。所以要在配置文件里打开连接相关的日志参数：

log_connections = on log_disconnections = on log_line_prefix = '%m [%p] %q%u@%d '

log_line_prefix里的%u是用户名，%d是数据库名，%p是进程号。打开日志后，每当有人尝试连接，都会在日志里留下记录。如果日志里完全没有对应 IP 的连接记录，那结论非常明确：请求没到数据库。

日志位置一般在：

• Linux（Debian/Ubuntu 系）：/var/log/postgresql/
• Linux（RHEL 系）：/var/lib/pgsql/数据目录/log/
• Windows 安装包：C:\Program Files\PostgreSQL\版本号\data\log\

5.3 快速诊断速查表

下面这张表是我这些年总结出来的，丢在书签里随时查。你看到报错文本，直接对号入座：

报错文本特征	大概率原因	下一步动作
connection to server at "xxx", port 5432 failed: Connection refused	服务没起、端口不监听，或防火墙直接拒绝	查进程、查ss -lntp
connection to server at "xxx", port 5432 failed: No route to host	网络路由不通、跨网段、安全组未放行	查防火墙、路由、云安全组
connection to server at "xxx", port 5432 failed: timeout expired	网络丢包、被安全策略静默丢弃	用telnet/Test-NetConnection测连通性
FATAL: password authentication failed for user "xxx"	TCP 通了，密码或认证方式不对	重置密码、检查认证方式
FATAL: no pg_hba.conf entry for host "xxx"	TCP 通了，pg_hba.conf没匹配当前客户端 IP	改pg_hba.conf，reload
FATAL: database "xxx" does not exist	TCP 通了，认证过了，但连的数据库不存在	确认库名
server at "1"这类诡异主机名	客户端环境变量PGHOST或连接串写错	检查env、连接串、文档变量赋值

5.4 一个最省事的固定套路

我自己的习惯是，遇到连接报错先做三件事，五分钟内基本能定位：

1. 客户端这边打印环境变量：env | grep -i pg，同时打印连接串原文。
2. 服务端这边开日志：确认log_connections=on，然后看日志里有没有来自客户端 IP 的尝试记录。
3. 两边对照：如果日志有记录，看FATAL给的拒绝原因；如果日志没有记录，直接往网络和客户端参数方向查，别在数据库服务上浪费时间。

这三个动作做完，问题的层级基本上就锁死了。剩下就是按层级打开对应配置修。

最后再分享一个小技巧：别小看pg_isready这一步。它最常见的用法是确认服务存活，但它其实也接受-h -p -d -U这些参数，可以直接指定客户端视角的探测目标。用它对同一套参数反复探测，能直观感受到"换了一个主机名，结果从 accepting 变成 no response"的差异。这个差异本身就是最好的教材——报错里的"1"不是玄学，它就是你的连接参数被环境变量或者连接串污染后，数据库在提醒你去检查客户端自己。