常见问题与故障排除

欢迎阅读 HarborDB 故障排除指南。这份全面的资源可帮助您快速识别和解决使用 HarborDB 和 PostgreSQL 时遇到的最常见问题。无论您遇到连接问题、性能缓慢还是界面问题，都能在此找到逐步解决方案。

如何使用本指南

1. 从以下类别中识别您的问题
2. 按顺序遵循故障排除步骤
3. 尝试解决方案直到问题解决
4. 如果仍未解决，使用"联系支持"部分

快速参考：常见问题

| 问题 | 可能原因 | 快速解决方案 | | --------------------------- | ------------------------------------- | ----------------------------------------- | | 无法连接到 PostgreSQL | 服务器未运行、防火墙阻止 | 启动 PostgreSQL、检查防火墙设置 | | 查询性能缓慢 | 缺失索引、大型数据集 | 添加索引、使用 LIMIT、优化查询 | | 高内存使用率 | 打开标签页过多、大型结果集 | 关闭未使用的标签页、启用流式模式 | | 导出失败 | 权限问题、磁盘已满 | 检查文件权限、释放磁盘空间 | | 界面感觉迟缓 | 系统资源限制 | 关闭其他应用、重启 HarborDB |

连接问题

"无法连接到 PostgreSQL 服务器"

症状：

• 连接超时错误
• "连接被拒绝"消息
• 测试连接时无限加载

逐步故障排除：

1. 检查 PostgreSQL 服务器状态：

   # 在终端中，检查 PostgreSQL 是否正在运行
   pg_isready -h localhost -p 5432
   

   • 如果未运行：brew services start postgresql（Homebrew）或通过系统偏好设置启动

2. 验证连接详细信息：

   • 主机名：本地使用 localhost，远程使用正确的 IP/主机名
   • 端口：默认是 5432，确认您的 PostgreSQL 端口
   • 数据库名：连接前必须存在
   • 用户名/密码：区分大小写，检查凭据

3. 检查防火墙设置：

   • 系统设置 → 安全性与隐私 → 防火墙
   • 确保允许 PostgreSQL 端口（5432）
   • 尝试暂时禁用防火墙进行测试

4. 测试网络连接性：

   # 对于远程服务器
   ping 您的服务器地址
   telnet 您的服务器地址 5432
   

常见解决方案：

• ✅ 启动 PostgreSQL 服务
• ✅ 正确的主机名/IP 地址
• ✅ 打开防火墙端口 5432
• ✅ 使用正确的凭据

"密码认证失败"

原因：

• 用户名或密码不正确
• PostgreSQL 认证方法不匹配
• 用户缺少数据库权限

解决方案：

1. 重置 PostgreSQL 密码：

   -- 以超级用户身份连接（通过命令行）
   ALTER USER 用户名 WITH PASSWORD '新密码';
   

2. 检查认证方法：

   • 查看 pg_hba.conf 文件
   • 常见方法：md5、scram-sha-256、trust
   • 如果需要，更新方法，重启 PostgreSQL

3. 验证用户权限：

   -- 列出用户和权限
   \du
   
   -- 列出数据库和访问权限
   \l
   

SSL/TLS 连接错误

连接到远程服务器时：

1. 检查 SSL 要求：

   • 服务器可能需要特定的 SSL 模式
   • 可能需要导入证书

2. 在 HarborDB 中尝试不同的 SSL 模式：

   • 从 prefer 开始
   • 然后尝试 require
   • 最后 verify-full（需要证书）

3. 如果使用 verify-full 则导入证书：

   • 从服务器管理员获取证书
   • 导入到 macOS 钥匙串访问
   • 授予 HarborDB 对证书的访问权限

性能问题

查询执行缓慢

诊断步骤：

1. 使用 EXPLAIN 进行分析：

   • 点击 HarborDB 中的"解释"按钮（⚡）
   • 查找"Seq Scan"（全表扫描）- 通常较慢
   • 查找"Index Scan" - 通常更快

2. 检查缺失的索引：

   -- 查找没有索引的频繁筛选列
   SELECT schemaname, tablename, attname
   FROM pg_stats
   WHERE schemaname NOT LIKE 'pg_%'
     AND n_distinct > 100
     AND attname NOT IN (
       SELECT column_name
       FROM information_schema.columns
       WHERE table_schema = schemaname
         AND table_name = tablename
     );
   

3. 添加适当的索引：

   -- 单列索引
   CREATE INDEX idx_table_column ON 表名(列名);
   
   -- 常见查询模式的多列索引
   CREATE INDEX idx_table_col1_col2 ON 表名(列1, 列2);
   

快速性能修复：

• 为探索性查询添加 LIMIT 子句
• 仅选择需要的列（不要使用 SELECT *）
• 在 WHERE 子句中使用索引列
• 避免在 WHERE 子句中使用阻止索引使用的函数

高内存使用率

症状：

• HarborDB 使用过多 RAM（检查活动监视器）
• 系统变得迟缓
• "内存不足"错误

解决方案：

1. 减少查询缓存大小：

   • 偏好设置 → 性能 → 查询缓存
   • 如果内存受限，从默认 256MB 减少到 128MB

2. 启用流式模式：

   • 偏好设置 → 性能 → 流式结果
   • 对结果 > 10,000 行启用
   • 减少大型数据集的内存使用

3. 管理打开的标签页：

   • 关闭未使用的查询标签页
   • HarborDB 将结果集按标签页保留在内存中
   • 常规工作：最多 5-10 个标签页

4. 重启 HarborDB：

   • 在大量使用期间每天退出并重启
   • 清除累积的内存使用

应用程序感觉迟缓

快速修复：

1. 关闭其他应用程序：

   • 特别是资源密集型应用（Chrome 带多个标签页、Docker 等）
   • 检查活动监视器的内存压力

2. 减少 UI 动画：

   • 偏好设置 → 外观 → 禁用动画
   • 在旧硬件上体验更流畅

3. 简化界面：

   • 折叠未使用的侧边栏部分
   • 使用更简单的颜色主题
   • 对非常大的查询禁用语法高亮

导出和文件问题

导出失败或创建空文件

常见原因和解决方案：

1. 权限问题：

   # 检查文件夹权限
   ls -la ~/Desktop/
   
   # 尝试不同的保存位置
   # 使用文稿文件夹而不是桌面
   

2. 磁盘空间问题：

   # 检查可用磁盘空间
   df -h
   
   # 需要至少 2 倍导出大小的可用空间
   

3. 文件格式问题：

   • CSV：尝试不同的分隔符（逗号、分号、制表符）
   • CSV：添加文本限定符（字段周围加引号）
   • JSON：尝试"美观"和"紧凑"两种格式

4. 大型导出优化：

   • 分块导出
   • 对大型数据集使用 CSV 而不是 JSON
   • 在导出设置中启用压缩

"文件未找到"或导出文件丢失

1. 检查默认保存位置：

   • 偏好设置 → 导出 → 默认保存位置
   • 更改为经常访问的文件夹

2. 搜索文件：

   # 搜索最近的 CSV/JSON 文件
   find ~ -name "*.csv" -mtime -1
   find ~ -name "*.json" -mtime -1
   

3. 检查废纸篓：

   • 导出文件可能被意外删除
   • 如果找到，从废纸篓恢复

界面和显示问题

主题未正确应用

macOS 深色/浅色模式问题：

1. 检查系统设置：

   • 系统设置 → 外观
   • 确保选择"自动"或所需主题

2. 重启 HarborDB：

   • 完全退出（⌘ + Q）
   • 重新打开以应用系统主题

3. 在 HarborDB 中强制主题：

   • 偏好设置 → 外观 → 主题
   • 选择"浅色"、"深色"或"系统"

功能或菜单缺失

1. 更新 HarborDB：

   • 检查更新（HarborDB → 检查更新）
   • App Store → 更新标签页

2. 重置界面布局：

   • 窗口 → 重置布局
   • 恢复默认面板排列

3. 检查功能可用性：

   • 某些功能需要特定的 PostgreSQL 版本
   • 在功能文档中验证兼容性

文本显示问题

字体大小/可读性问题：

1. 调整编辑器字体大小：

   • 偏好设置 → 编辑器 → 字体大小
   • 增加以提高可读性

2. 使用 macOS 缩放：

   • 系统设置 → 辅助功能 → 缩放
   • 启用以进行临时放大

3. 高对比度模式：

   • 系统设置 → 辅助功能 → 显示器
   • 增加对比度以提高可见性

macOS 特定问题

"应用程序已损坏"错误

打开 HarborDB 时：

# 移除隔离属性
sudo xattr -cr /Applications/HarborDB.app

# 重新打开 HarborDB
open /Applications/HarborDB.app

Gatekeeper 警告

对于直接下载（非 App Store）：

1. 系统设置 → 隐私与安全
2. 滚动到"安全性"部分
3. 点击 HarborDB 警告旁边的"仍要打开"
4. 确认打开

Touch ID/钥匙串访问问题

"HarborDB 想要使用您的密码"错误：

1. 重置钥匙串权限：

   • 打开钥匙串访问应用
   • 搜索"HarborDB"
   • 删除现有条目
   • 在 HarborDB 中重新添加连接

2. 修复钥匙串：

   • 钥匙串访问 → 文件 → 钥匙串急救
   • 对"登录"钥匙串运行修复

与 macOS 版本的兼容性

最低要求： macOS 12.0（Monterey） 推荐： macOS 13.0（Ventura）或更高版本

检查兼容性：

# 检查 macOS 版本
sw_vers

# 检查架构（Apple Silicon 与 Intel）
uname -m

数据库特定问题

"关系不存在"

查询表时：

1. 检查模式：

   -- 列出当前模式中的所有表
   \dt
   
   -- 列出所有模式中的表
   SELECT schemaname, tablename
   FROM pg_tables
   WHERE tablename LIKE '%您的表%';
   

2. 使用限定名称：

   -- 而不是：SELECT * FROM users;
   -- 使用模式限定：
   SELECT * FROM public.users;
   SELECT * FROM auth.users;
   

3. 设置默认模式：

   • 在 HarborDB 中编辑连接
   • 将"默认模式"设置为常用模式

数据库对象权限错误

权限被拒绝用于关系

1. 检查您的权限：

   -- 以超级用户或表所有者身份连接
   SELECT grantee, privilege_type
   FROM information_schema.role_table_grants
   WHERE table_name = '您的表';
   

2. 请求权限：

   -- 示例：授予 SELECT 权限
   GRANT SELECT ON 表名 TO 您的用户名;
   

大型数据集处理

"内存不足"或极其缓慢：

1. 使用服务器端分页：

   -- 而不是：SELECT * FROM 大型表;
   -- 使用：
   SELECT * FROM 大型表 LIMIT 1000 OFFSET 0;
   -- 然后为后续页面增加 OFFSET
   

2. 在 HarborDB 中启用流式传输：

   • 偏好设置 → 性能 → 流式模式
   • 设置阈值（例如，10,000 行）

3. 对频繁的复杂查询使用物化视图

网络和远程连接问题

远程连接缓慢

优化提示：

1. 启用压缩：

   • 连接设置 → 高级 → 压缩
   • 减少数据传输大小

2. 使用 SSH 隧道：

   • 比直接连接更安全
   • 可以提高受限网络上的性能

3. 安排繁重查询：

   • 在非高峰时段运行
   • 使用 HarborDB 的查询调度功能

间歇性连接断开

1. 增加超时设置：

   • 连接设置 → 超时
   • 从 30 秒增加到 60 秒

2. 启用保持连接：

   • 连接设置 → 保持连接
   • 维持空闲连接

3. 检查网络稳定性：

   # 测试网络稳定性
   ping -c 100 您的服务器地址
   # 查找丢包
   

联系支持前

要收集的信息

如果在故障排除后问题仍然存在，请收集以下信息：

1. 系统信息：

   • macOS 版本（Apple 菜单 → 关于本机）
   • HarborDB 版本（HarborDB → 关于 HarborDB）
   • PostgreSQL 版本（SELECT version();）

2. 错误详细信息：

   • 确切的错误消息（如果可能请截图）
   • 重现问题的步骤
   • 问题开始的时间

3. 配置详细信息：

   • 连接设置（不带密码）
   • 导致问题的查询（如果适用）
   • 导出设置（如果与导出相关）

HarborDB 中的诊断工具

1. 生成诊断报告：

   • 帮助 → 创建诊断报告
   • 包括日志、配置、系统信息

2. 查看应用程序日志：

   • 帮助 → 显示日志
   • 筛选错误和警告消息

3. Console.app 用于系统日志：

   • 打开 Console.app
   • 搜索"HarborDB"
   • 查找崩溃报告

快速自检

联系支持前，请验证：

• [ ] macOS 是最新版本
• [ ] HarborDB 是最新版本
• [ ] PostgreSQL 服务器正在运行
• [ ] 网络连接稳定
• [ ] 有足够的可用磁盘空间
• [ ] 用户具有必要的权限

联系支持

如果您已尝试所有故障排除步骤但问题仍然存在：

1. 邮件支持： support@harbordb.com

2. 在邮件中包含：

   • 诊断报告（来自帮助菜单）
   • 错误消息的截图
   • 重现问题的步骤
   • 您已尝试的故障排除步骤

3. 预期响应时间：

   • 初始响应：24-48 小时内
   • 工作时间：周一至周五，美国东部时间上午 9 点至下午 5 点
   • 紧急问题：将邮件标记为"紧急"

预防措施

定期维护

每周：

• 重启 HarborDB 以清除内存
• 清除临时导出文件
• 备份重要的连接设置

每月：

• 更新 HarborDB 和 PostgreSQL
• 审查和优化慢查询
• 清理未使用的连接

避免问题的最佳实践

1. 连接管理：

   • 使用有意义的连接名称
   • 定期测试连接
   • 移除未使用的连接

2. 查询开发：

   • 探索时始终使用 LIMIT
   • 运行大型查询前使用 EXPLAIN 测试
   • 保存复杂查询以供重用

3. 系统维护：

   • 保持 macOS 更新
   • 定期 Time Machine 备份
   • 监控磁盘空间

其他资源

• HarborDB 常见问题解答 - 常见问题答案
• 入门指南 - 安装和设置
• 性能优化 - 高级调优
• macOS 安全指南 - 安全最佳实践

---

安全是共同责任。通过理解并正确使用 HarborDB 的 macOS 安全功能，您可以构建强大的防御，防止数据泄露和未经授权的访问。请记住：良好的安全实践会成为保护您数据的日常习惯。

最后更新：{{current_date}}