WeChat Local Viewer 详细部署教程

1. 部署前必读：项目定位与合规边界

WeChat Local Viewer 是一款微信本地聊天记录查看器，提供会话浏览、全文搜索、多格式导出和可选的 LLM 智能总结功能，全部本地运行 。

⚠️ 最重要的前提说明：
本项目只提供查看界面，不提供任何解密工具。 仓库中不含密钥提取、数据库解密等任何工具与代码。聊天数据需由用户自行准备后导入目录 。

这意味着：如果你还没有已解密的微信数据库文件，本工具无法直接使用。数据准备环节需由你自行完成，本文不涉及解密方法。

实测环境：微信版本 4.1.13.12（Windows）。

2. 环境要求

依赖 版本要求 说明
操作系统 Windows 10/11 官方仅支持 Windows
Python 3.10+ 后端运行环境
Node.js `^22.19.0

📌 Node 版本约束：项目对 Node 版本有明确要求（^22.19.0 || >=24.0.0）。版本不符可能导致前端依赖安装失败 。

3. 第一步：准备数据目录

这是最关键的前置步骤。将你自行准备的聊天数据放到项目根目录，支持两种命名（二选一，工具自动识别）：

text

1
2
3
4
5
6
7
wechat-local-viewer/
├── decrypted/          （或 .decrypted/）
│   ├── contact/        # 联系人数据
│   ├── session/        # 会话数据
│   ├── message/        # 消息数据（message_*.db）
│   └── hardlink/       # 图片索引（hardlink.db，可选）
└── start.bat

各子目录作用：

目录 内容 是否必需
contact/ 联系人数据 必需
session/ 会话数据 必需
message/ 消息数据（message_*.db 等） 必需
hardlink/ 图片文件索引（hardlink.db） 可选

⚠️ 重要提醒：以下目录均已通过 .gitignore 排除，不要提交到版本库 ：

  • decrypted/ 或 .decrypted/ —— 微信聊天数据（用户提供）
  • .cache/ —— 中间层数据库 app.db（ETL 自动创建）
  • .export/ —— 导出产物
  • .tmp/ —— 日志等临时文件

4. 第二步：一键启动（推荐）

4.1 操作流程

  1. 确认数据已按第 3 节放入 decrypted/ 目录。
  2. 双击 start.bat。
  3. 浏览器自动打开 http://127.0.0.1:18787/（后端直接托管前端构建产物）。

4.2 默认端口

端口 用途 说明
18787 后端 FastAPI 避开 8765 等 Windows 保留端口
15713 前端 Vite dev 避开 5173 易冲突端口

💡 端口设计巧思：项目刻意避开了 Windows 保留端口区间，减少”端口被系统占用但查不出原因”的困扰 。

4.3 自定义端口

1
2
3
set WCVIEWER_PORT=28888
set WCVIEWER_FRONT_PORT=25813
start.bat

✅ 端口冲突检测：start.bat 启动前会自动检测端口占用，被占用会报错并给出提示，而非静默失败 。

5. 第三步：手动启动（开发/调试场景）

若需自定义配置或参与开发，可手动分别启动前后端。

5.1 启动后端

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

📌 pip 源建议：项目约束中明确要求 pip 使用清华源，可加速依赖安装 。

5.2 启动前端（开发模式）

1
2
3
cd frontend
npm install
npm run dev

生产模式：

1
npm run build

构建产物到 dist/，后端会自动托管。

5.3 前端依赖安装优化（网络受限时）

如果 npm install 缓慢或失败，按官方验证步骤优化：

1
2
3
4
5
cd frontend
npm config set registry https://registry.npmmirror.com
npm config set maxsockets 4
npm config set audit false
npm install

💡 maxsockets 4 降低并发连接数，在部分网络环境下反而更稳定；audit false 跳过安全审计，加快安装。

6. 系统架构理解

理解数据流有助于排查问题：

text

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
数据源（用户提供 decrypted/）
        │
        │ ① ETL (etl.py)
        │   指纹判断：全量 / 增量 / 跳过
        │   parse_sessions   → sessions 表
        │   parse_contacts   → contacts 表
        │   parse_messages   → messages 表 (+FTS5 索引)
        │   _update_session_stats 聚合统计
        ▼
.cache/app.db  (中间层查询库)
   sessions / contacts / messages + FTS
        │
        │ ② API (FastAPI :18787)
        ▼
frontend (Vue, 已构建至 dist)
   会话列表 / 消息浏览 / 搜索 / 导出

关键理解：

  • ETL 是智能的：通过”指纹判断”决定执行全量、增量还是跳过。首次导入为全量，后续数据有更新时走增量，无变化则跳过 。
  • 中间层数据库：.cache/app.db 是查询加速层，原始数据仍在 decrypted/ 中。

7. 配置 LLM 智能总结（可选）

LLM 功能完全可选，未配置时点”总结”会给出明确提示 。

7.1 配置方式一：页面设置（推荐）

打开页面右上角「设置」，填入：

字段 说明 示例
Base URL OpenAI 兼容服务地址 见下表
API Key 对应服务的密钥 —
Model 模型名 见下表

常用服务配置：

服务 Base URL 示例 Model
DeepSeek https://api.deepseek.com/v1 deepseek-chat
OpenAI https://api.openai.com/v1 gpt-4o-mini
Ollama（本地） http://localhost:11434/v1 qwen2.5:7b
硅基流动 https://api.siliconflow.cn/v1 —

7.2 配置方式二：环境变量（后备默认值）

1
2
3
set LLM_BASE_URL=https://api.deepseek.com/v1
set LLM_API_KEY=你的key
set LLM_MODEL=deepseek-chat

7.3 安全说明

🔒 API Key 存储机制：API key 仅存储在浏览器 localStorage，随每次问答请求发给后端。它不会被写入服务器配置文件或日志 。

8. 数据刷新（增量更新）

当微信产生新消息、你重新准备了数据后，无需重新全量导入。项目提供了 refresh.bat 增量刷新脚本 。

💡 ETL 的指纹判断机制会识别数据变化：有更新走增量，无变化直接跳过，避免重复计算 。

9. API 端点参考（供集成/调试）

端点 方法 说明
/api/sessions GET 会话列表（按 last_time 倒序）
/api/sessions/{username} GET 单会话详情
/api/messages?session=X GET 消息分页
/api/messages/{id}/context GET 消息上下文
/api/search?q=X GET 全文搜索（FTS5）
/api/search/suggest?q=X GET 搜索建议
/api/admin/etl POST 触发 ETL（{force:bool}）
/api/admin/status GET ETL 状态
/api/admin/rebuild-fts POST 重建 FTS 索引
/api/llm/chat POST LLM 流式问答（SSE）
/media/... GET 媒体静态文件（仅已还原图片可用）

10. 性能预期

项目 表现 备注
启动 → 首屏 数秒 64 万消息库，未实测计时
打开会话（首屏 30 条） 索引查询，表现良好 未实测计时
全文搜索 FTS5 索引，秒级返回 未实测计时
LLM 流式首字 取决于模型服务 —

📌 实测数据：已实测导入 64 万条消息，浏览流畅 。全文搜索基于 FTS5 索引，1 秒内返回结果 。

11. 安全特性

特性 说明
零外发 除 LLM base_url 外无任何 outbound HTTP
静态目录保护 /media/ 不列目录
密钥本地化 LLM API key 仅存浏览器 localStorage

12. 部署检查清单

  • □

    Windows 10/11 系统

  • □

    Python 3.10+ 已安装

  • □

    Node.js 版本符合 ^22.19.0 || >=24.0.0

  • □

    已自行准备聊天数据，放入 decrypted/ 或 .decrypted/

  • □

    数据含 contact/、session/、message/ 子目录

  • □

    start.bat 能正常启动，端口 18787 未被占用

  • □

    浏览器能访问 http://127.0.0.1:18787/

  • □

    （可选）LLM 配置正确，能正常总结

13. 常见问题排查

问题 可能原因 解决方案
启动报端口冲突 18787 或 15713 被占用 按 start.bat 提示，或用 WCVIEWER_PORT 自定义
npm install 失败 Node 版本不符或网络慢 检查 Node 版本；设置 npmmirror 源和 maxsockets 4
页面无数据 数据目录结构不对 检查 decrypted/ 下是否有 contact/、session/、message/
图片不显示 未提供 hardlink/ 或图片未还原 /media/ 仅对已还原的部分图片可用
LLM 总结无响应 未配置或配置错误 检查设置页的 Base URL、Key、Model
数据更新后不刷新 ETL 判断为无变化 使用 refresh.bat 或通过 /api/admin/etl 手动触发

14. 项目定位与边界说明

这个工具能做什么：

  • ✅ 浏览会话列表、消息记录
  • ✅ 全文搜索、导出多种格式
  • ✅ 可选的 LLM 智能总结
  • ✅ 全部本地运行，数据不外发

这个工具不做什么：

  • ❌ 不提供任何解密工具（密钥提取、数据库解密均不含）
  • ❌ 不自动定位微信数据目录
  • ❌ 不处理数据准备工作

⚠️ 合规提醒：本项目基于 MIT License 开源 。请确保你处理的数据为你本人合法拥有，遵守相关法律法规和平台服务条款。项目本身不存储、不传输你的聊天数据。

核心要点：部署本身很简单（双击 start.bat 即可），难点在于数据准备——你需要自行获得已解密的微信数据并按指定目录结构放置。这是项目的设计边界，不是缺陷。