跳到主要内容

诊断工具

Elftia 内置了一套完整的诊断工具，帮助你排查问题、收集日志、管理缓存和优化数据库。所有诊断功能位于 设置 → 系统 页面。

诊断信息导出​

Export Diagnostics​

收集 Elftia 运行时的完整诊断信息，打包为一个可分享的文件。

操作步骤：

  1. 打开 设置 → 系统。
  2. 在「Diagnostics & Caches」区域，点击 Export Diagnostics 按钮。
  3. 系统开始收集信息（按钮显示为 Collecting...）。
  4. 收集完成后，选择保存位置。

导出的信息包含：

内容说明
应用版本Elftia 版本号、Electron 版本
操作系统OS 类型、版本、架构
运行时环境Node.js 版本、内存使用、CPU 信息
提供商配置已配置的提供商列表和状态（不含 API Key）
MCP 服务器已配置的 MCP 服务器列表和连接状态
应用设置当前的应用配置（脱敏处理）
运行日志最近的应用运行日志
数据库状态数据库大小、表统计
信息

导出的诊断信息经过脱敏处理，不会包含 API Key、密码等敏感信息。你可以安全地将诊断文件分享给技术支持或社区。

导出格式选项​

诊断信息支持多种导出格式：

格式说明推荐场景
JSON单个 JSON 文件快速分享、在线查看
ZIP完整的诊断包包含日志文件等完整信息，用于详细排查

Copy Diagnostics Log​

将诊断日志直接复制到剪贴板，方便快速粘贴到聊天或问题反馈中。

  1. 点击 Copy diagnostics log 按钮。
  2. 日志内容被复制到剪贴板。
  3. 粘贴到需要的位置。

查看诊断日志​

在 Export Diagnostics 或 Copy Diagnostics Log 操作后，诊断结果会显示在页面下方的日志区域中，以绿色等宽字体显示。你可以直接在页面上查看和审阅诊断信息。

缓存管理​

Clear Caches​

清除 Elftia 的本地缓存数据，包括模型列表缓存、搜索缓存等。

操作步骤：

  1. 点击 Clear Caches 按钮（红色危险按钮）。
  2. 等待清理完成（按钮显示为 Clearing...）。
  3. 清理完成后，页面会显示清理结果。

清除的内容：

  • 模型列表缓存（下次使用时会重新获取）
  • 网页搜索结果缓存
  • 文件搜索索引缓存
  • 缩略图缓存
  • API Key 池的运行时缓存

不会清除的内容：

  • 对话记录
  • 用户设置
  • API Key 和提供商配置
  • MCP 服务器配置
  • 主题设置
提示

如果遇到模型列表不更新、缓存数据过时等问题，清除缓存通常可以解决。清除后不会影响你的数据和配置。

Prune Attachments​

清理未关联到任何消息的孤立附件文件，释放磁盘空间。

操作步骤：

  1. 点击 Prune attachments 按钮。
  2. 系统扫描所有附件文件，识别未被任何消息引用的孤立文件。
  3. 安全删除孤立文件。
  4. 显示清理结果（删除的文件数量和释放的空间）。
信息

此操作只清理确认未被引用的附件文件，不会影响正常对话中的附件。

数据库维护​

数据库大小​

页面上会显示当前 SQLite 数据库文件的大小。随着对话记录增多，数据库会逐渐增大。

VACUUM 优化​

SQLite 在删除数据后不会自动回收磁盘空间。VACUUM 操作会重建数据库文件，释放已删除数据占用的空间。

操作步骤：

  1. 在数据库维护区域，点击 VACUUM 按钮。
  2. 等待操作完成（按钮显示为进行中状态）。
  3. 完成后显示优化结果和新的数据库大小。

注意事项：

  • VACUUM 操作会临时创建数据库的副本，需要确保磁盘有足够的空间（约为数据库大小的 2 倍）。
  • 操作过程中应避免关闭应用。
  • 大型数据库的 VACUUM 可能需要几秒到几十秒。

推荐频率：

  • 日常使用：每月执行一次即可。
  • 大量删除对话后：建议立即执行。
  • 数据库异常大：可能有已删除但未回收的空间，执行 VACUUM 可以显著缩小。

资源清理​

孤立资源清理​

显示可以安全清理的孤立资源文件的数量和总大小，并提供一键清理功能。

操作步骤：

  1. 查看「可清理数量」和「可清理大小」。
  2. 点击 清理资源 按钮执行清理。
  3. 清理完成后显示结果。

环境检测​

位于 设置 → 通用 → 环境。

环境检测会扫描系统中的开发工具安装状态：

工具检测内容显示信息
Node.jsnode --version版本号、安装路径
Gitgit --version版本号、安装路径
ripgreprg --version版本号、安装路径
uvuv --version版本号、安装路径
uvxuvx --version版本号、安装路径

每个工具旁边有状态标识：

  • 绿色圆点（已安装）：显示版本号和安装路径。
  • 红色圆点（未安装）：如果支持自动安装，会显示「安装」按钮。

自动安装​

部分工具支持直接在 Elftia 中一键安装：

  1. 在未安装的工具旁边，点击 安装 按钮。
  2. 按钮变为「Installing...」，显示安装进度。
  3. 安装完成后状态自动更新。

目前支持自动安装的工具：ripgrep、uv、uvx。

Node.js 和 Git 需要从各自的官方网站手动下载安装。

开发者模式诊断​

启用开发者模式后（设置 → 关于 中连续点击版本号），可以获得额外的诊断能力：

DevTools​

开发者模式下，可以在 设置 → 关于 中打开/关闭 Electron DevTools：

  • Console：查看应用的 JavaScript 日志输出，包含详细的错误信息和调试日志。
  • Network：查看所有网络请求，包括 LLM API 调用的详细请求和响应。
  • Elements：检查 DOM 结构，定位界面问题。

使用 DevTools 调试​

  1. 启用开发者模式。
  2. 在关于页面点击 Open DevTools 按钮。
  3. DevTools 窗口打开后，切换到 Console 标签页。
  4. 观察日志输出，错误信息通常以红色显示。
  5. 对于网络问题，切换到 Network 标签页，查看失败的请求。
提示

当你向社区或技术支持反馈问题时，除了诊断导出文件，DevTools Console 中的错误日志也是非常有价值的排查信息。可以右键点击 Console 中的日志，选择「Save as」保存完整日志。

其他诊断功能​

附件指标​

在系统标签页中可以查看附件相关的统计信息：

  • 总附件数量
  • 附件占用的磁盘空间
  • 孤立附件的数量和大小

缓存指标​

查看各种缓存的大小和命中率：

  • 文件搜索缓存
  • 模型列表缓存
  • 缩略图缓存
  • 文件树缓存

运行时预算​

查看资源使用的运行时预算概览，帮助了解应用的资源消耗情况。

数据库分页指标​

查看数据库分页查询的性能指标，用于诊断数据库相关的性能问题。

诊断排查流程​

遇到问题时，推荐按以下流程排查：

  1. 收集信息：点击 Export Diagnostics 导出诊断信息。
  2. 查看日志：在诊断日志中搜索错误信息。
  3. 检查环境：确认环境工具的安装状态。
  4. 清理缓存：执行 Clear Caches 清除可能过时的缓存。
  5. 优化数据库：执行 VACUUM 优化数据库。
  6. 重启应用：重启 Elftia 测试问题是否解决。
  7. 启用 DevTools：如果以上步骤未能解决，启用开发者模式使用 DevTools 进行深入调试。

如果通过诊断工具发现了具体的错误信息，请参阅 常见问题 或 连接错误 查找对应的解决方案。