WeChat Local Viewer：本地搜索与分析微信聊天记录
WeChat Local Viewer 用 FastAPI、Vue 和 SQLite FTS5 在本机浏览、搜索、导出微信聊天记录，并可选接入兼容 OpenAI 的 LLM。
WeChat Local Viewer：本地搜索与分析微信聊天记录
当微信聊天记录积累到数十万甚至上百万条消息时，系统自带的查看方式往往难以满足检索、归档和分析需求。ops120/wechat-local-viewer 提供了一个本地优先的解决方案：用户准备好自己的聊天数据库后，可以在浏览器中查看会话、浏览消息、执行全文搜索、导出数据，还能选择性地接入 LLM 生成总结或进行问答。
项目的一个重要边界是：它不是解密工具。仓库不包含密钥提取、数据库解密或绕过安全机制的代码。聊天数据必须由用户自行准备，并放入项目约定的目录中；查看器只负责解析和展示已经可读取的数据。
为什么值得关注
这个项目的核心价值不在于“把聊天记录显示出来”，而在于它把一套本地数据处理链路组织起来：
- 从用户提供的目录读取联系人、会话和消息数据库。
- 通过 ETL 流程将数据整理到中间 SQLite 数据库。
- 为消息建立 FTS5 全文索引。
- 通过 FastAPI 提供分页、搜索、统计和 LLM 接口。
- 使用 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 智能总结，全部本地运行，零外部依赖。