Ubuntu中PostgreSQL如何进行故障排查

Ubuntu 下 PostgreSQL 故障排查清单

一 快速定位与通用检查

• 确认服务与集群状态：使用命令查看服务是否运行、版本与集群名（Ubuntu 常见为“main”集群）。示例：sudo systemctl status postgresql；若使用传统集群管理，可用 pg_lsclusters 查看各版本/集群的运行状态。
• 查看服务日志：PostgreSQL 日志通常位于 /var/log/postgresql/，优先用 sudo tail -f /var/log/postgresql/postgresql-<version>-main.log 观察启动失败、认证错误等关键信息。
• 核对端口占用：确认 5432 端口未被其他进程占用，示例：sudo netstat -tulpen | grep 5432。
• 核对数据目录与权限：常见数据目录为 /var/lib/postgresql//main，确保目录存在且属主为运行 PostgreSQL 的系统用户（如 postgres），权限正确。
• 核对配置文件：主配置 postgresql.conf（常见路径 /etc/postgresql//main/），重点检查 listen_addresses、port；客户端认证 pg_hba.conf 用于来源网段、认证方式（如 md5、scram-sha-256）与数据库/用户的白名单控制。

二 常见故障与修复

• 无法本地连接 Unix 域套接字
  典型报错：psql: could not connect to server: No such file or directory ... /var/run/postgresql/.s.PGSQL.5432。
  处理步骤：
  1. 确认服务已启动；2) 检查套接字目录与文件是否存在（常见目录为 /var/run/postgresql/ 或 /tmp/）；3) 若套接字在不同目录，可在 postgresql.conf 的 unix_socket_directories 中统一目录，或创建符号链接（如 ln -s /tmp/.s.PGSQL.5432 /var/run/postgresql/.s.PGSQL.5432）；4) 重启服务并复测。
• 端口冲突导致启动失败
  现象：日志提示端口被占用或启动失败。
  处理步骤：用 netstat 找到占用 5432 的进程并停止/更换端口；或在 postgresql.conf 中将 port 改为未占用端口后重启。
• 数据目录不可访问或不存在
  现象：日志出现 “… is not accessible or does not exist”，或 systemd 报 Result: protocol。
  处理步骤：确认挂载点已就绪（如外置 HDD/SSD 或 NFS 已挂载），目录权限正确；若系统启动早于存储就绪，可为服务添加启动延迟（见下一节 WSL/外置盘场景）。
• 认证失败或 pg_hba.conf 配置错误
  现象：日志出现 “FATAL: could not load pg_hba.conf” 或客户端被拒绝。
  处理步骤：检查 pg_hba.conf 的语法与来源网段、认证方式；修改后执行 sudo systemctl restart postgresql 使配置生效。
• WSL 或权限异常
  现象：systemctl 报权限错误、或 psql 仍找不到套接字。
  处理步骤：在 WSL 中优先使用 sudo systemctl start postgresql 启动服务；若仍异常，检查 /var/run/postgresql 目录权限与套接字文件；必要时以 sudo -u postgres psql 本地连接验证。

三 场景化排查要点

• 外置硬盘或网络存储延迟挂载
  症状：系统重启后 PostgreSQL 立即启动但数据目录未就绪，出现 “not accessible or does not exist” 或 Result: protocol。
  解决思路：为集群服务添加启动前延迟，例如创建覆盖配置：
  sudo mkdir -p /etc/systemd/system/postgresql@15-main.service.d
sudo tee /etc/systemd/system/postgresql@15-main.service.d/override.conf <<'EOF'
[Service]
ExecStartPre=/bin/sleep 5
EOF
  然后 sudo systemctl daemon-reload && sudo systemctl restart postgresql@15-main，验证延迟后已正常启动。
• WSL 环境
  症状：systemctl 报权限拒绝或 psql 找不到套接字。
  解决思路：使用 sudo systemctl start postgresql 启动服务；若仍失败，检查目录权限与套接字；必要时以 sudo -u postgres psql 本地直连验证服务可用性。

四 性能类问题的排查路径

• 资源与负载：先用系统工具确认是否存在 CPU、内存/Swap、磁盘 I/O 瓶颈（如 top、htop、iostat、vmstat）。
• 慢查询与执行计划：
  1. 在 postgresql.conf 中开启慢查询日志，例如 log_min_duration_statement = 1000（记录超过 1 秒 的语句）；
  2. 使用 pg_stat_statements 找出最耗时/最频繁 SQL；
  3. 对问题 SQL 执行 EXPLAIN (ANALYZE, BUFFERS) 检查是否出现全表扫描、排序/哈希溢出到磁盘等。
• 锁与长事务：
  1. 查询阻塞关系与长事务，及时终止或优化；
  2. 避免长时间 “idle in transaction”，以免阻碍 VACUUM 清理与引起膨胀。
• 表膨胀与维护：对高频 UPDATE/DELETE 的表评估膨胀率，按需执行 VACUUM FULL/CLUSTER 或重建索引。

五 常用命令与配置路径速查

• 服务与集群：sudo systemctl status postgresql、sudo systemctl restart postgresql、pg_lsclusters
• 日志与端口：sudo tail -f /var/log/postgresql/postgresql-<version>-main.log、sudo netstat -tulpen | grep 5432
• 配置与目录：/etc/postgresql/<version>/main/postgresql.conf、/etc/postgresql/<version>/main/pg_hba.conf、/var/lib/postgresql/<version>/main
• 本地连接测试：sudo -u postgres psql -c "select version();"
• 套接字与目录：检查 /var/run/postgresql/ 与 /tmp/ 下的 .s.PGSQL.5432，必要时统一 unix_socket_directories 或创建符号链接