Debian 上 PostgreSQL 故障排查步骤
一 快速定位与通用检查
- 查看服务状态与版本：使用命令 sudo systemctl status postgresql 确认实例是否运行；如需确认具体版本与集群名，可执行 pg_lsclusters。
- 查看日志：Debian 上默认日志目录为 /var/log/postgresql/，实时跟踪主日志：tail -f /var/log/postgresql/postgresql--main.log。
- 核对关键配置：主配置 /etc/postgresql//main/postgresql.conf，客户端认证 /etc/postgresql//main/pg_hba.conf；修改后执行 sudo systemctl reload postgresql 使配置生效（重启仅在必要时使用）。
- 直连数据库做连通性验证：本地可用 sudo -u postgres psql，远程可用 psql -h -p -U -d ；若启用 SSL，可用 openssl s_client -connect : 验证握手与证书。
- 资源与表空间：用 top/htop/vmstat/iostat 检查 CPU/内存/磁盘 I/O；在库内用 \db 或查询 pg_tablespaces 查看表空间使用是否异常。
二 常见故障场景与处理
| 症状 |
快速检查 |
处理要点 |
| 无法连接数据库 |
服务是否运行；端口 5432 是否放行；日志是否有 FATAL/拒绝信息 |
启动服务：sudo systemctl start postgresql；放行防火墙：sudo ufw allow 5432/tcp；必要时在 postgresql.conf 设置 listen_addresses = ‘*’，在 pg_hba.conf 增加条目如 host all all 0.0.0.0/0 md5，然后 reload/restart |
| 认证失败 |
pg_hba.conf 的认证方式是否匹配；用户密码是否正确 |
本地以 sudo -u postgres psql 登录后执行 ALTER USER postgres WITH PASSWORD ‘new_password’；调整 pg_hba.conf 的 METHOD（如 md5/scram-sha-256）并 reload |
| 查询很慢 |
当前活跃会话与锁：SELECT * FROM pg_stat_activity; |
用 EXPLAIN (ANALYZE, BUFFERS) 定位瓶颈；创建合适索引；执行 ANALYZE 更新统计信息 |
| 磁盘空间耗尽 |
df -h；WAL 是否堆积 |
检查归档是否正常；清理过期 WAL：pg_archivecleanup /pgdata/pgwal <WAL文件名>；核查复制槽：SELECT * FROM pg_replication_slots; 必要时 SELECT pg_drop_replication_slot(‘slot_name’); |
| 复制/备库延迟或中断 |
主备日志、复制槽、网络 |
核对 primary_conninfo、WAL 保留与传输方式；清理无效复制槽；确保网络稳定与带宽充足 |
| 异常重启或疑似内存问题 |
内核日志 dmesg；OOM 杀手；实例日志 |
降低会话/工作内存（如 work_mem）、连接数；检查是否有连接泄漏；必要时增加系统内存或优化查询/索引 |
以上处理要点涉及的命令与路径为 Debian 上的常见位置与用法，具体版本与目录名以实际环境为准。
三 性能与日志分析进阶
- 启用并查询语句级统计：在 postgresql.conf 设置 shared_preload_libraries = ‘pg_stat_statements’，重启后在库内执行 CREATE EXTENSION IF NOT EXISTS pg_stat_statements;，通过 SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 20; 找出最耗时的 SQL。
- 深度分析执行计划：对慢 SQL 使用 EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)，关注 Seq Scan/Index Scan、Rows、Actual Loops、Buffers Hit/Miss、Sort/Hash 成本，据此增加或改写索引、改写 SQL、调整 work_mem/join_collapse_limit 等参数。
- 日志可视化与长期监控：用 pgBadger 分析 /var/log/postgresql/ 生成 HTML 报告；结合 Prometheus + Grafana 或 Zabbix/Nagios 做指标与告警（连接数、复制延迟、检查点、WAL、慢查询等）。
四 数据安全与恢复建议
- 权限与目录：确保数据目录与日志目录权限正确，数据目录通常为 0700，属主为 postgres:postgres。
- 常规维护：定期执行 VACUUM（防膨胀）与 ANALYZE（更新统计），对大表可分区、按需 VACUUM FULL/CLUSTER。
- 备份与恢复：例行逻辑备份 pg_dump -U -d -f backup.sql；时间点恢复或迁移用 pg_basebackup/WAL 归档；若仅有逻辑备份，使用 psql -f backup.sql 恢复。
- 变更前快照：调整参数或升级前，先记录关键配置与 pg_dumpall --globals-only，必要时对数据目录做快照，以便快速回滚。
