qq-chat-exporter
QQ 聊天记录导出工具，支持 HTML/JSON 多格式导出，完整保留媒体资源
QQChatExporter (QCE) 是一个基于 NapCat 框架开发的专业 QQ 聊天记录导出工具。它旨在提供稳定、高效的本地化数据备份方案，支持将群聊或好友的对话记录完整导出为 HTML、JSON 等多种格式，并完美保留图片、视频等媒体资源。
本手册旨在帮助用户从零开始掌握 QCE 的使用方法，涵盖基础操作、高级功能配置以及针对特定场景的最佳实践教程。
目录
一、使用文档
1. 快速开始
简介
QCE 解决了 QQ 聊天记录难以本地化保存和管理的问题。通过直接与 NapCat 框架交互，它能够读取并导出用户的聊天数据，支持多种标准文件格式，确保数据的可移植性和永久性。
安装与启动
-
下载与解压：前往 GitHub Releases 页面 下载适用于您操作系统的最新版本压缩包（如
NapCat-QCE-Windows-x64.zip），完整解压到任意目录。整包已包含插件、依赖和前端资源，无需额外安装。 -
选择启动模式：
完整模式（需要登录 QQ，支持导出新记录）：
- Windows：双击运行
launcher-user.bat - Linux：将文件解压到 QQ 安装目录（
/opt/QQ）后运行./launcher-user.sh - 根据控制台提示，使用手机 QQ 扫描二维码完成登录
- 访问
http://localhost:40653/qce-v4-tool，输入控制台显示的访问令牌 (Access Token) 完成验证
独立模式（无需登录 QQ，仅浏览已导出文件）：
- Windows：双击运行
start-standalone.bat - Linux：运行
./start-standalone.sh - 访问
http://localhost:40653/qce-v4-tool即可直接使用，无需 Token - 适用于：查看历史导出文件、使用资源画廊浏览图片、在没有 QQ 的设备上查看备份
- Windows：双击运行
注：macOS 平台因兼容性问题暂不支持，开发中。
界面概览
QCE 的界面设计遵循简洁高效的原则，主要分为以下功能区：
- 概览 (Overview)：监控系统状态。显示 WebSocket 连接状态、QQ 在线状态以及任务统计。
- 会话 (Sessions)：数据源管理。列出所有加载的群组和好友，是发起导出任务的主要入口。
- 任务 (Tasks)：任务队列。显示正在进行或已完成的任务，支持实时查看进度和下载文件。
- 定时 (Scheduled)：自动化管理。用于配置周期性的自动备份计划。
- 聊天记录 (History)：文件归档。集中管理已导出的文件，支持在线预览 HTML/JSON 内容，提供资源画廊模式浏览图片。
- 表情包 (Stickers)：表情管理。用于查看和导出账号收藏的表情包。
2. 基础功能
导出聊天记录
这是 QCE 最核心的功能，支持导出任意群组或好友的记录。
- 进入 会话 页面。
- 若列表为空，点击右上角的 刷新列表 按钮同步最新数据。
- 在列表中找到目标会话，点击右侧的 导出 按钮。
- 在弹出的配置窗口中设置参数，确认后点击 创建任务。任务将进入后台队列执行。
导出格式选择
QCE 提供多种格式以适应不同场景：
- HTML (推荐)：生成网页文件。高度还原移动端聊天界面，支持气泡对话、图片显示和头像展示。适合人工阅读。
- JSON：生成结构化数据文件。保留完整元数据（发送者ID、时间戳、消息类型等）。适合开发者进行二次处理或数据分析。
- TXT：生成纯文本文件。仅保留文字，图片和表情转换为占位符。体积最小，适合快速检索。
- Excel：生成表格文件。消息按行排列，便于筛选和统计。
导出范围设置
通过过滤条件提高导出效率：
- 时间范围：指定 开始时间 和 结束时间。留空则默认导出所有历史记录。
- 关键词过滤：仅保留包含特定关键词的消息。
- 排除用户：输入特定的 QQ 号，该用户的消息将被剔除（适用于过滤机器人消息）。
资源处理
QCE 对多媒体资源提供了灵活的处理方式：
- 默认行为：自动下载聊天记录中的图片、视频、语音和文件。
- 文件结构：以 HTML 为例，导出结果包含一个
.html文件和一个同名的resources文件夹
- 注意：移动或分享时，必须同时移动 HTML 文件和资源文件夹，否则图片无法显示。
- 也可以勾选导出为ZIP压缩包，将HTML文件和资源文件打包为ZIP格式。
- 快速导出：勾选 快速导出（跳过资源下载） 后，系统仅导出文本数据，不再下载媒体文件。这能显著缩短导出时间。
3. 高级功能
批量导出
针对需要备份大量会话的场景：
- 操作：在 会话 页面点击 批量导出，勾选多个会话或点击 全选。
- 配置：点击 导出选中 后，设置统一的参数（如格式、时间范围）。系统会将任务加入队列依次执行。
定时导出任务
实现数据的自动化备份：
- 创建：在 定时 页面点击 新建定时任务。
- 调度策略：
- 预设：支持每天、每周、每月执行。
- 自定义 (Cron)：支持输入 Cron 表达式进行精确控制（如
0 9 * * *表示每天 9:00）。
- 增量备份：建议将时间范围设置为 昨天 或 上周，每次仅导出新增内容。
- 管理：支持查看每次执行的历史记录，或点击 执行 手动触发任务。
流式导出（针对超大群聊）
针对数十万至上百万条消息的超大群聊，普通导出可能导致内存溢出（OOM）。流式导出采用"边读边写"策略解决此问题。
- 启用：在导出配置窗口的 高级选项 中勾选 流式导出。
*
- 格式区别：
- HTML 模式：生成 流式 ZIP。包含分块的 HTML 片段和资源文件，解压后通过
index.html浏览。 - JSON 模式：生成 流式 JSONL。每一行为一个独立的 JSON 对象，适合大数据工具逐行处理。
- HTML 模式：生成 流式 ZIP。包含分块的 HTML 片段和资源文件，解压后通过
资源合并
将定时任务产生的碎片化文件整合成完整文件：
- 操作：在 定时 页面点击 合并备份。
- 选项：
- 消息去重：自动剔除重复消息。
- 删除源文件：合并成功后清理原始碎片文件。
表情包导出
支持导出账号内的表情资源：
- 类型：包括收藏表情、市场表情包和系统表情包。
- 操作：在 表情包 页面，可选择导出单个表情包，或点击 导出所有 批量下载账号下所有表情资源。
二、教程文档
教程 1：备份重要聊天记录
场景描述：将与某个人或群组的珍贵聊天记录永久保存在本地，不受平台漫游时间限制，并可随时查看。
操作步骤：
- 定位会话：打开 QCE 会话 页面，通过搜索框快速找到目标好友或群组。
- 配置参数：
- 点击 导出。
- 格式：选择 HTML，以获得最佳的阅读体验。
- 时间范围：若需备份全部，留空即可；若只需特定时间段，设置起止时间。
- 资源：保持默认设置，确保图片视频被下载。
- 执行与查看：
- 点击 创建任务，等待任务完成。
- 在 任务 页面点击 打开文件位置。
- 双击生成的
.html文件即可在浏览器中查看。
- 分享提示：若需分享给他人，请务必将
.html文件和同名的资源文件夹打包压缩，否则接收方无法看到图片。
教程 2：定期自动备份群聊
场景描述：针对活跃群聊建立自动化的增量备份机制，防止消息过多导致手动备份困难。
操作步骤：
- 建立任务：
- 进入 定时 页面，点击 新建定时任务，选择目标群聊。
- 调度：选择 每天，执行时间设为凌晨（如
03:00）。 - 策略：将导出范围设置为 昨天。这样系统每天仅导出过去 24 小时的新增消息，速度快且占用低。
- 运行维护：保存并启用任务。系统将自动生成按日期命名的文件（如
群名_2024-01-01.html）。 - 定期合并：
- 每隔一段时间（如月底），点击 定时 页面的 合并备份。
- 勾选该群组下的所有碎片文件，启用 消息去重。
- 执行合并，生成一份完整的月度备份文件。
教程 3：导出超大群聊（百万消息级别）
场景描述：导出拥有数百万条消息的老群，普通导出方式容易导致软件卡死或崩溃。
操作步骤：
- 启用流式模式：
- 在导出向导中选择目标群聊。
- 展开 高级选项，勾选 流式导出（超大消息量专用）。
- 选择格式：
- 若用于阅读，选择 HTML（系统将生成流式 ZIP）。
- 若用于数据分析，选择 JSON（系统将生成 JSONL）。
- 查看结果：
- 导出完成后，解压生成的 ZIP 包。
- 打开文件夹内的
index.html。页面采用动态加载技术，滚动时按需加载数据，即使是百万级消息也能流畅浏览。
教程 4：批量备份所有群聊/好友
场景描述：在更换设备或重装系统前，对账号内所有社交数据进行全量备份。
操作步骤：
- 进入批量模式：在 会话 页面点击右上角的 批量导出。
- 选择对象：
- 点击 全选。
- 建议：若会话数量极多（>500），建议分批次操作（先全选群组，再全选好友），以便更好地管理任务队列。
- 统一配置：
- 点击 导出选中。
- 设置 时间范围 为 全部。
- 注意：全量备份且包含媒体文件会占用大量磁盘空间，请提前确认磁盘容量。
- 执行：确认后，QCE 会将任务加入队列并串行执行。你可以将浏览器最小化，留意右上角的通知中心查看完成情况。
开发者资源
如需查阅 API 接口文档或深入了解项目架构，请访问自动生成的技术文档：
https://deepwiki.com/shuakami/qq-chat-exporter/11-api-reference