AIBit-探索开源项目 AIBit-探索开源项目

WeChat Local Viewer：本地搜索与分析微信聊天记录

WeChat Local Viewer 使用 FastAPI、Vue 和 SQLite FTS5 在本机浏览、搜索、导出微信聊天记录，并可选择性接入兼容 OpenAI 的 LLM。

WeChat Local Viewer：本地搜索与分析微信聊天记录

当微信聊天记录积累到数十万甚至上百万条消息时，系统自带的查看方式往往难以满足检索、归档和分析需求。ops120/wechat-local-viewer 提供了一个本地优先的解决方案：用户准备好自己的聊天数据库后，可以在浏览器中查看会话、浏览消息、执行全文搜索、导出数据，还能选择性地接入 LLM 生成总结或进行问答。

项目的一个重要边界是：它不是解密工具。仓库不包含密钥提取、数据库解密或绕过安全机制的代码。聊天数据必须由用户自行准备，并放入项目约定的目录中；查看器只负责解析和展示已经可读取的数据。

为什么值得关注

这个项目的核心价值不在于“把聊天记录显示出来”，而在于它把一套本地数据处理链路组织起来：

  1. 从用户提供的目录读取联系人、会话和消息数据库。
  2. 通过 ETL 流程将数据整理到中间 SQLite 数据库。
  3. 为消息建立 FTS5 全文索引。
  4. 通过 FastAPI 提供分页、搜索、统计和 LLM 接口。
  5. 使用 Vue 前端完成会话浏览、消息上下文查看和导出操作。

这种架构避免了前端直接读取大量原始数据库，也让增量刷新、索引重建和查询优化变得更容易。项目实测导入过 64 万条消息，消息浏览仍保持流畅；全文搜索基于 SQLite FTS5，目标是实现秒级、通常 1 秒内返回结果。

主要功能

  • 会话列表：按最后消息时间倒序展示单聊、群聊和公众号会话。
  • 消息浏览：按时间正序渲染消息，并支持分页和消息上下文。
  • 全文搜索：使用 SQLite FTS5 搜索消息内容，并提供搜索建议。
  • 多格式导出：将本地记录整理为便于保存和进一步处理的导出数据。
  • LLM 总结与问答：通过 OpenAI 兼容协议接入 DeepSeek、OpenAI、硅基流动、Ollama 等服务。
  • 本地优先：除用户主动配置的 LLM 服务外，不依赖外部 HTTP 服务。
  • 增量处理：ETL 会根据数据指纹判断执行全量处理、增量更新还是直接跳过。

环境要求

项目面向 Windows 10/11，运行环境包括：

  • Python 3.10 或更高版本
  • Node.js ^22.19.0 或 >=24.0.0
  • Windows 10/11

默认情况下，后端监听 18787，前端开发服务器监听 15713。项目特意避开了 Windows 上容易产生问题的 8765，也避开了容易冲突的 Vite 默认端口 5173。

准备数据目录

将已经准备好的聊天数据放在项目根目录下，项目会自动识别 decrypted/ 或 .decrypted/，二选一即可：

wechat-local-viewer/
├── decrypted/
│   ├── contact/      # 联系人数据
│   ├── session/      # 会话数据
│   ├── message/      # 消息数据库，例如 message_*.db
│   └── hardlink/     # 图片索引，可选
└── start.bat

hardlink/ 是可选目录，通常用于图片索引。即使没有完整媒体文件，文本消息和已经还原的部分图片仍然可以正常查看。

一键启动

在 Windows 中，最简单的方式是双击项目根目录下的 start.bat。脚本会检查端口是否被占用，并在启动后自动打开：

http://127.0.0.1:18787/

后端会直接托管已经构建好的前端产物，因此生产使用不需要额外启动前端开发服务器。

如果需要修改端口，可以在启动前设置环境变量：

set WCVIEWER_PORT=28888
set WCVIEWER_FRONT_PORT=25813
start.bat

端口检测很实用：相比服务启动后才暴露绑定错误，脚本可以提前给出清晰提示，尤其适合 Windows 上同时运行多个本地开发服务的场景。

手动启动与开发模式

后端使用 FastAPI 和 Uvicorn：

cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 18787

前端使用 Vue 和 Vite：

cd frontend
npm install
npm run dev

构建生产版本：

npm run build

构建完成后，后端会自动托管 frontend/dist。在网络受限或希望提高 npm 安装稳定性时，项目文档建议使用镜像并限制并发：

npm config set registry https://registry.npmmirror.com
npm config set maxsockets 4
npm config set audit false
npm install

ETL 与缓存数据库

项目不会让每次页面请求都直接扫描原始微信数据库，而是通过 backend/app/etl.py 将源数据转换到运行时数据库：

.cache/app.db
├── sessions
├── contacts
├── messages
└── FTS5 索引

ETL 过程大致包括：

  • parse_sessions：解析会话并写入 sessions 表。
  • parse_contacts：解析联系人并写入 contacts 表。
  • parse_messages：读取 message_*.db 等文件，写入 messages 表并建立全文索引。
  • _update_session_stats：聚合会话统计信息。

数据指纹用于判断是否需要重新处理。没有变化时可以跳过；有新增或变化时执行增量刷新；必要时也可以通过管理接口强制执行 ETL。这种设计对于几十万条消息尤其重要，因为每次打开应用都进行完整导入会显著拖慢启动过程。

运行时还会生成以下目录，这些目录不属于源码仓库：

.cache/   # 中间数据库 app.db
.export/  # 导出产物
.tmp/     # 日志和临时文件

它们已经通过 .gitignore 排除，不应提交到版本库。

API 设计

后端提供了相对清晰的 REST API，便于调试或扩展其他客户端：

端点 方法 用途
/api/sessions GET 获取按 last_time 倒序排列的会话
/api/sessions/{username} GET 获取单个会话详情
/api/messages?session=X GET 分页获取消息
/api/messages/{id} GET 获取单条消息
/api/messages/{id}/context GET 获取消息上下文
/api/search?q=X GET 使用 FTS5 执行全文搜索
/api/search/suggest?q=X GET 获取搜索建议
/api/admin/etl POST 触发 ETL，可传递 {"force": true}
/api/admin/status GET 查看 ETL 状态
/api/admin/logs GET 查看日志尾部
/api/admin/rebuild-fts POST 重建全文索引
/api/admin/stats/daily GET 获取每日统计
/api/llm/config GET / POST 读取或保存 LLM 配置
/api/llm/chat POST 通过 SSE 返回流式问答结果
/media/... GET 提供已经还原的媒体文件

其中 /api/llm/chat 使用 SSE 流式输出，因此界面可以在模型生成过程中逐步显示内容，而不必等待完整响应。

可选的 LLM 集成

LLM 并不是查看器的必要依赖。用户可以在页面右上角的“设置”中填写 OpenAI 兼容服务：

DeepSeek:   https://api.deepseek.com/v1
OpenAI:     https://api.openai.com/v1
Ollama:     http://localhost:11434/v1
硅基流动:    https://api.siliconflow.cn/v1

常见模型示例包括：

deepseek-chat
gpt-4o-mini
qwen2.5:7b

配置项包括 Base URL、API Key 和 Model。API key 只保存在浏览器 localStorage 中，并会随每次问答请求发送给后端；也可以通过环境变量提供后备默认值：

set LLM_BASE_URL=https://api.deepseek.com/v1
set LLM_API_KEY=your-api-key
set LLM_MODEL=deepseek-chat

未配置 LLM 时，基础的会话浏览、搜索和导出仍然可用。点击总结功能时，界面会明确提示尚未配置，而不是静默失败。

需要注意的是，“本地运行”并不等于 LLM 请求也完全本地运行。只要使用 DeepSeek、OpenAI 或其他远程兼容服务，发送给该服务的内容就会离开本机。若希望保持更强的数据边界，可以使用本机运行的 Ollama，并将 Base URL 设置为 http://localhost:11434/v1。

隐私与安全边界

项目在设计上强调本地优先：

  • 除用户配置的 LLM base_url 外，不执行外部 HTTP 请求。
  • 静态 /media/ 路由不会列出目录。
  • LLM API key 仅保存在浏览器 localStorage。
  • 原始数据、缓存数据库、导出文件和临时日志都保留在本机。

不过，聊天记录本身通常包含敏感个人信息。使用远程 LLM 时，应先确认服务商的数据保留和训练政策，并考虑只发送必要的会话片段。对于高敏感数据，本地模型通常比远程 API 更合适。

性能与验证

项目给出的性能预算包括：

  • 启动到首屏：数秒级，基于 64 万消息库，但文档未给出精确实测时间。
  • 打开会话：首屏加载 30 条消息，依赖索引查询，表现良好。
  • 全文搜索：使用 FTS5，目标为秒级返回。
  • LLM 流式首字：主要取决于模型服务和网络延迟，未提供固定实测值。

部署或排查问题时，可以先检查前端目录结构：

cd <仓库根目录>
tree /F frontend

如果前端依赖尚未安装，则进入 frontend 执行安装；如果搜索结果异常，可以调用 /api/admin/rebuild-fts 重建索引；如果 ETL 状态不明确，则查看 /api/admin/status 和 /api/admin/logs。

适合哪些场景

WeChat Local Viewer 适合需要长期保存、检索或研究个人聊天资料的开发者和高级用户，例如：

  • 从大量历史消息中查找某个关键词或决定。
  • 按会话浏览长期项目讨论。
  • 将聊天记录导出用于个人归档。
  • 使用本地或兼容 OpenAI 的模型总结长对话。
  • 在不上传完整数据库的前提下构建本地检索工具。

项目采用 MIT License，主要代码由 Python、Vue 和 TypeScript 组成，语言占比约为 Python 64.8%、Vue 24.2%、TypeScript 7.7%、Batchfile 2.4%、JavaScript 0.5% 和 HTML/CSS 各 0.2%。截至页面信息记录，仓库拥有 143 个 stars、94 个 forks，尚未发布正式 Release。

总的来说，这个项目把“读取本地聊天数据库”提升为一套可扩展的本地应用：SQLite FTS5 解决检索问题，ETL 和缓存解决规模问题，FastAPI 与 Vue 提供清晰的应用边界，而可选的 LLM 集成则为总结和问答提供了扩展能力。最重要的是，用户可以在不依赖云端服务的情况下完成核心浏览与搜索工作，并根据自己的隐私需求决定是否启用模型能力。

Source

ops120/wechat-local-viewer: 微信本地聊天记录查看器 — 会话浏览/全文搜索/多格式导出/可选 LLM 智能总结，全部本地运行，零外部依赖。