Debian 上 PostgreSQL 连接问题的排查与修复
一 快速自检
- 确认服务是否运行：sudo systemctl status postgresql；若未运行，执行 sudo systemctl start postgresql。
- 本地套接字连接测试：psql -U postgres -h localhost -p 5432；若提示“Unix 域套接字不存在”，见第四部分的套接字路径问题。
- 远程连接测试：psql -U 用户名 -h 服务器IP -p 5432 -d 数据库名；不通时继续下一步。
- 端口监听与连通性：ss -lntp | grep 5432 或 netstat -nltp | grep 5432；从客户端执行 nc -vz 服务器IP 5432 或 telnet 服务器IP 5432。
- 防火墙放行：sudo ufw allow 5432/tcp（如使用 UFW）；如使用 iptables，放行对应端口/策略。
- 查看日志定位：tail -f /var/log/postgresql/postgresql-*-main.log，优先看 FATAL/ERROR 行。
二 常见原因与修复对照表
| 症状 |
可能原因 |
修复要点 |
| psql: could not connect to server: No such file or directory（套接字路径） |
客户端与服务器 Unix 套接字目录不一致（Debian 常用 /var/run/postgresql/，第三方包可能用 /tmp） |
使用 psql -h localhost 走 TCP；或设置 PGHOST=/tmp；或创建软链 ln -s /tmp/.s.PGSQL.5432 /var/run/postgresql/.s.PGSQL.5432 |
| 服务未启动 |
未安装/未启动/启动失败 |
sudo apt install postgresql postgresql-contrib；sudo systemctl start postgresql；查看日志排错 |
| 仅本地可连，远程超时 |
listen_addresses 仅 127.0.0.1 或未放行 5432 |
postgresql.conf 中设 listen_addresses=‘*’；pg_hba.conf 增加 host all all 0.0.0.0/0 md5；重启；防火墙放行 5432/tcp |
| 密码错误或认证失败 |
用户口令错误、pg_hba 方法不匹配 |
本地切换到 postgres：sudo -u postgres psql；执行 ALTER USER postgres WITH PASSWORD ‘新密码’；在 pg_hba.conf 为对应网段使用 md5/peer/scram-sha-256 并重启 |
| SSL/TLS 握手失败 |
证书缺失/路径错误/客户端未启用 SSL |
postgresql.conf 中设 ssl=on，配置 ssl_cert_file/ssl_key_file；客户端连接串加 --ssl 或 sslmode=require |
| 云服务器端口未放行 |
云平台安全组未开放 5432 |
在云控制台安全组放行入站 TCP 5432；本机防火墙同样放行 |
三 远程访问配置步骤
- 修改 postgresql.conf（路径随版本变化，如 /etc/postgresql/13/main/postgresql.conf）：
- listen_addresses = ‘*’
- port = 5432
- 修改 pg_hba.conf（追加规则，建议按网段细化，生产环境避免 0.0.0.0/0）：
- host all all 0.0.0.0/0 md5（示例，允许所有 IPv4 以密码方式连接）
- 应用并重启：sudo systemctl restart postgresql（或先 sudo systemctl reload postgresql 使配置生效）。
- 防火墙与云安全组：
- UFW：sudo ufw allow 5432/tcp
- 云厂商安全组：入站放行 TCP 5432 到数据库实例
四 套接字与本地连接问题
- 出现“Unix 域套接字不存在”时，优先用 TCP 方式连接：psql -U postgres -h localhost -p 5432。
- 若必须使用套接字，统一套接字目录：
- 查看服务器套接字：ss -lp --protocol=unix | grep postgres
- 设置环境变量：export PGHOST=/tmp（或实际目录）
- 或创建软链：sudo ln -s /tmp/.s.PGSQL.5432 /var/run/postgresql/.s.PGSQL.5432
- 第三方/自编译 PostgreSQL 与 Debian 打包的套接字目录不一致是常见根因，上述任一方式均可解决。
五 日志与进阶排查
- 查看数据库日志：tail -f /var/log/postgresql/postgresql--main.log，关注 FATAL/ERROR、认证拒绝、SSL 错误等行。
- 查看系统日志：tail -f /var/log/syslog；或使用 journalctl -u postgresql 查看服务单元日志。
- 连接与活动会话：
- 当前连接与查询：SELECT * FROM pg_stat_activity;
- 终止阻塞会话：SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE …;（谨慎操作）
- SSL 连接诊断：openssl s_client -connect 主机:端口；客户端连接串增加 --ssl 或 sslmode=require 验证。
