database Troubleshooting
PostgreSQL connection refused 排查方法
psql 连接 PostgreSQL 报 could not connect to server: Connection refused 时，先确认服务是否 running、5432 是否监听、postgresql.conf 的 listen_addresses 是否绑定到目标 IP，再逐层排查防火墙、安全组和 Docker 端口映射，pg_hba.conf 只影响后续认证。
connection refused 表示 TCP 连接被拒绝，优先检查 PostgreSQL 是否启动、listen_addresses、端口监听和网络路径。pg_hba.conf 通常影响的是认证阶段，不是拒绝连接阶段。
Scenario
这篇文章解决什么问题
适用于 psql 或应用连接 PostgreSQL 报 could not connect to server: Connection refused 的场景。排查核心是区分服务未启动、监听地址不对、端口不对还是网络路径不通，pg_hba.conf 在这个阶段不是主要原因。
Symptoms
典型现象
- psql 报 could not connect to server: Connection refused，Is the server running on that host and accepting TCP/IP connections?
- systemctl status postgresql 显示 active 但 ss -lntp 找不到 5432 端口。
- 本机 psql -h 127.0.0.1 能连，但用内网 IP 或容器名连不上。
- Docker 容器内 psql 连宿主机 PostgreSQL 失败。
Before Debugging
排查前先确认
- 先区分连接、认证、锁、慢查询、连接池、内存或持久化问题。
- 记录数据库端时间、应用实例数、连接池大小和报错 SQL。
- 任何 kill/调参前先确认是否影响正在执行的业务事务。
Root Causes
常见根因分层
连接池与数据库容量失配
实例数乘以每个实例连接池上限，可能远超数据库 max_connections；连接泄漏和慢查询会进一步放大问题。
- 统计来源用户和主机
- 查看 Sleep 与活跃连接比例
- 核对应用连接池配置
事务、锁和慢查询堆积
锁等待、长事务、缺索引更新和慢 SQL 会拖住连接，最终表现成连接数耗尽或接口超时。
- 查 processlist / innodb_trx
- 看 deadlock 和 lock waits
- 定位 blocking session
缓存或内存策略失控
Redis 大 key、无 TTL、noeviction、MySQL buffer/临时表配置都可能让系统进入持续抖动。
- 先看内存水位和策略
- 找大 key/慢查询
- 评估数据模型是否合理
Diagnosis Path
分步诊断流程
1. 固定现场，避免追着变化状态跑
先记录故障时间、影响入口、完整错误和最近一次变更。PostgreSQL connection refused 排查方法 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。
- 截图或保存完整错误文本
- 记录请求域名/IP/端口/namespace/服务名
- 标出最近发布、配置、证书、镜像或依赖变更
systemctl status postgresql --no-pager
ss -lntp | grep 54322. 在故障发生的同一位置复现
很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。
- 从报错服务所在机器执行测试
- 必要时加 Host、SNI、namespace 或代理参数
- 把成功路径和失败路径的输出并排比较
ss -lntp | grep 5432
psql -h 127.0.0.1 -p 5432 -U postgres -c "select 1"
sudo tail -n 100 /var/log/postgresql/postgresql-*.log3. 读取服务端证据，而不是只看客户端提示
客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。
- 确认 PostgreSQL 服务是否运行，端口是否监听。
- 区分连接 127.0.0.1、内网 IP、容器名和公网 IP 的不同路径。
- 检查 postgresql.conf 的 listen_addresses 和 port。
psql -h 127.0.0.1 -p 5432 -U postgres -c "select 1"
sudo tail -n 100 /var/log/postgresql/postgresql-*.log
docker ps --format "table {{.Names}} {{.Ports}}"4. 做最小修复并立即回归验证
每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。
- 检查 postgresql.conf 的 listen_addresses 和 port。
- 远程访问时检查防火墙、安全组、Docker -p 映射和网络策略。
- 如果已经连上但认证失败，再检查 pg_hba.conf 和用户密码。
sudo tail -n 100 /var/log/postgresql/postgresql-*.log
docker ps --format "table {{.Names}} {{.Ports}}"Commands
排查命令与使用意图
命令 1
用于确认服务当前运行状态、退出码和最近日志。重点看 Active 行和 Main PID。
systemctl status postgresql --no-pager命令 2
用于确认端口监听状态和连接关系。重点看 LISTEN 行的地址是 127.0.0.1 还是 0.0.0.0，以及 ESTAB 连接数。
ss -lntp | grep 5432命令 3
用于验证 PostgreSQL 连接和查询状态。重点看连接数、锁等待和日志中的 FATAL/ERROR 记录。
psql -h 127.0.0.1 -p 5432 -U postgres -c "select 1"命令 4
用于读取日志或配置文件内容。重点看时间戳附近的 ERROR、FATAL、refused、timeout 等关键词。
sudo tail -n 100 /var/log/postgresql/postgresql-*.log命令 5
用于确认容器运行状态、端口映射和网络配置。inspect 能看到 HostConfig.PortBindings 和 NetworkSettings 等关键字段。
docker ps --format "table {{.Names}} {{.Ports}}"Risk Notes
容易踩坑的地方
- listen_addresses = 'localhost' 只监听 127.0.0.1，远程连接全部被拒绝，改为 '*' 需配合 pg_hba.conf 和防火墙。
- Docker 中 PostgreSQL 镜像默认监听 5432，但如果用 docker run -p 127.0.0.1:5432:5432 则外部不可达。
- pg_hba.conf 的 reject 规则和 Connection refused 是不同层面的问题，前者是认证拒绝后者是 TCP 连不上。
Verification
修复后怎么确认
- 原始故障现象已经消失，且使用同一入口重新测试 PostgreSQL connection refused 能稳定成功。
- 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
- 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。
Prevention
后续预防
- 生产环境把 listen_addresses 设为内网 IP，配合 pg_hba.conf 限制来源 IP 段，不要用 0.0.0.0。
- Docker 部署用 docker-compose 自定义网络让应用容器用服务名连接，避免端口映射。
- 监控 PostgreSQL 连接数和拒绝连接日志，配置 max_connections 和连接池（如 PgBouncer）。
常见问题
connection refused 和 password authentication failed 区别是什么？
前者 TCP 连接还没建立，多数是服务/端口/网络问题；后者已经连到 PostgreSQL，是账号密码或 pg_hba 规则问题。
PostgreSQL 默认能远程访问吗？
多数发行版默认只监听本机，需要显式调整 listen_addresses、pg_hba.conf 和防火墙。
Long-tail SEO
你可能正在搜索这些报错
下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。
- Postgres connection refused
- psql could not connect to server
- PostgreSQL 5432 连接被拒绝
- postgresql listen_addresses 配置
- pg_hba.conf 连接失败
- Postgres Docker 端口不通
- connection to server failed refused
- PostgreSQL 防火墙 连接失败
Need More Help
这个问题还没完全解决？
把你的报错、环境和已经尝试过的步骤发给我，后续会优先补充到排障手册。