Telegram Search Lite

轻量级 Telegram 聊天记录搜索与导出工具。
Lightweight browser-only Telegram search.

在线使用 · GitHub Pages 部署 · Fork 部署

感谢linux.do社区为本项目赞助的ai资源。

项目简介

Telegram Search Lite 是一个纯浏览器模式的 Telegram 搜索工具，重点是：

• 直接在浏览器中登录 Telegram
• 使用官方 Data Export (Takeout) API 做聊天同步
• 按日期、按聊天做选择性同步
• 按日期浏览聊天记录
• 支持模糊搜索
• 支持跨群按用户筛选消息
• 搜索结果和同步消息保存在浏览器本地，后续可继续查询
• 可直接部署到 GitHub Pages

这个项目偏向轻量、直接、可自行部署，不依赖单独后端。

在线地址

• 线上地址：https://tg.fjh1997.top/
• 仓库地址：https://github.com/fjh1997/telegram-search-lite

核心功能

• 浏览器内登录：不需要单独服务端，Telegram 会话保存在浏览器本地
• 选择性同步：在聊天日期选择器里直接同步指定日期范围
• 本地搜索：同步后的消息会写入本地 IndexedDB 并建立搜索索引
• 按用户搜索：可以在多个群里筛选某个用户发过的消息
• 增量复用：已同步消息和按用户搜索结果都可以复用，不需要每次从零开始

跨群按用户筛选消息

项目里的“按用户筛选群聊发言”分成两种模式：

• 查本地：只查询已经同步到浏览器 IndexedDB 里的消息
• 查全部群组：在线遍历当前账号可访问的群聊，并实时返回该用户的发言

两种模式的区别：

• 查本地 不会再次请求 Telegram 历史消息，只是在本地数据库里按 senderId 建索引筛选，速度快，也没有额外 Telegram 风控压力
• 查全部群组 会直接调用 Telegram 的消息历史/消息搜索能力，在每个群里按发送者筛消息，然后把结果持续写回本地数据库，后续可继续本地搜索

当前项目里相关链路大致是：

• 会话同步优先使用官方 Data Export (Takeout) API，同步指定聊天和日期范围的消息
• 跨群在线按用户筛选使用的是普通消息检索链路，也就是 GramJS iterMessages(..., { fromUser })，底层会落到 Telegram 常规消息历史/搜索接口，而不是 Takeout 导出接口

关于封禁和风控风险：

• 查本地 基本没有额外账号风险，因为它不新增 Telegram 拉取请求
• 查全部群组 有一定风控风险，因为它会高频遍历多个群并读取消息历史
• 相比之下，Takeout 导出接口通常更稳定、限制更宽松，也更适合做批量同步
• 但在线按用户跨群筛选无法直接复用 Takeout 的那套“按发送者跨多个群实时筛选”能力，所以这里只能走常规消息接口

这意味着：

• 轻度使用通常问题不大
• 大量、频繁、连续地跨很多群在线筛选消息，理论上更容易触发 Telegram 的反滥用限制
• 本项目无法保证“绝对不会被限流或风控”，请按自己的账号风险承受能力使用

GitHub Pages 部署

本仓库已经内置 GitHub Pages 工作流：

• 工作流文件：.github/workflows/pages.yml
• 构建产物目录：dist/client
• 默认线上配置文件：public/telegram-api.example.json

默认情况下：

• 本地开发可使用 .env 或 .env.local
• GitHub Pages 会在没有构建环境变量时回退到 public/telegram-api.example.json

部署步骤：

1. 打开仓库 Settings
2. 进入 Pages
3. 在 Build and deployment 中选择 GitHub Actions
4. 推送到 main 分支，或者手动运行 Deploy GitHub Pages
5. 等待 Actions 完成后访问生成的站点地址

Fork 后如何部署

如果你要部署自己的版本：

1. Fork 本仓库
2. 在 fork 仓库中打开 Settings -> Pages
3. 选择 GitHub Actions
4. 如果你需要自己的 Telegram API 配置： 本地开发时修改 .env 或部署前替换 public/telegram-api.example.json
5. 推送到 main
6. GitHub Actions 会自动构建并发布

Fork 后通常可以通过下面地址访问：

https://<你的 GitHub 用户名>.github.io/<你的仓库名>/

本地开发

npm install
npm run dev

构建

npm run build

致谢

本项目的交互思路和部分产品方向参考了 telegram-search，在此感谢原项目。

• 原项目链接：https://github.com/groupultra/telegram-search

English

Telegram Search Lite is a lightweight, browser-only Telegram search project focused on local-first sync and self-hosted deployment.

Highlights:

• Telegram login directly in the browser
• Official Data Export (Takeout) API sync
• Selective sync by date and chat
• Date-based chat browsing
• Fuzzy full-text search
• Search messages by user across groups
• Local browser storage for synced data
• GitHub Pages friendly deployment

Cross-group search by sender has two modes:

• Local only: searches only messages that are already synced into IndexedDB in the browser
• All groups: scans accessible groups online and streams matched messages from the selected sender into the result list

How they work:

• Local only does not request Telegram message history again. It filters locally indexed messages by senderId, so it is fast and does not add Telegram-side abuse risk
• All groups uses Telegram's regular message retrieval/search path to scan each group by sender, and then stores matched results into the local database for future searches

API path used in this project:

• Chat sync prefers the official Data Export (Takeout) API for selective history sync
• Cross-group sender search uses the regular GramJS iterMessages(..., { fromUser }) path, which relies on Telegram's normal history/search interfaces instead of the Takeout export path

Risk note:

• Local only has essentially no extra account risk because it does not create additional Telegram history requests
• All groups does carry some anti-abuse / rate-limit risk, because it may scan many groups and read message history at a relatively high frequency
• The official Takeout export flow is usually more stable for bulk sync and generally has looser limits
• However, Telegram does not expose a Takeout-style real-time cross-group sender filter for this use case, so this feature has to use the regular message interfaces

In practice:

• light usage is usually fine
• heavy and repeated online scans across many groups are more likely to trigger Telegram anti-abuse systems
• this project cannot guarantee zero restriction risk; use it according to your own account risk tolerance

Live site:

• https://tg.fjh1997.top/

Thanks:

• Inspired by telegram-search: https://github.com/groupultra/telegram-search