跳到主要内容

诊断工具

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 进行深入调试。

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