tgscope

Telegram OSINT、抓取与归档。
一款完全在您机器上运行、仅与 Telegram 通信的本地 Web 应用。

npm install
npm start

然后打开 **http://127.0.0.1:5173**。首次运行会引导您配置 API 凭据、通过二维码登录并加载您的会话列表。它只与 Telegram 这一个服务器通信。无需创建账户、没有遥测、也没有中间服务：您收集的数据都保存在您自己拥有的 SQLite 文件中。

是 telegram-scraper、telescope 和 Harrier 的继任者，基于 Telethon 1.44 构建。

功能介绍

收集

• 每个已登录账户下的每个频道、群组、论坛主题和聊天，都汇总在一棵可选择的树中，显示完整 -100 id、名称以及可见该对话的账户徽章
• 每个对话都由实际可读取它的账户进行收集，因此跨两个账户的选择会为每个账户分别启动一次运行
• 包含完整元数据的消息：浏览量、转发数、反应、编辑日期、相册、投票、地理位置、链接、回复链、帖子作者以及每条消息的转发来源
• 论坛群组按主题拆分——可以只收集单个主题，而非整个群组
• 媒体并行下载，并通过 SHA-256 和 Telegram 文件 id 去重，因此转发到五个频道的文件只存储一份
• 支持从每对话的水印处断点续传；连续模式按时间间隔重新检查
• 已保存的集合可一键重新运行所选内容

调查

• 查询手机号、@username、用户 id 或 t.me 链接
• 简介、标志位、作为隐私指示器的最后上线时间精度、共同群聊、个人频道
• Telegram 愿意透露的关于该账户的任何信息：注册月份、手机号所属国家、用户最近一次改名或更换头像的时间、自动删除计时器、受限转发时显示的名称。请注意，它通常什么都不会透露。这些字段附带在 Telegram 向陌生人发消息时显示的反诈骗面板上，而直接查询个人资料时它们会返回空值，因此请将它们视为额外收获，而非可规划的依据
• 商业账户确实能可靠地提供街道地址、坐标和时区
• 每一张可见的个人资料照片，均经过 SHA-256 和感知哈希处理，以图库形式展示
• 感知哈希跨账户匹配，因此同一张图片出现在另一个账户上时也能被识别出来
• 消息发送者在抓取时即被记录，因此浏览器中显示的名字即使对方没有用户名，也是一个可点击跳转到查询页面的有效链接；“同步成员”可为之前收集的内容填补这一信息
• 每次查询都会快照并做差异对比：用户名变更、显示名称变更、简介编辑、照片新增或移除、隐私设置变化

导出

环境要求

• Node.js 18+
• Python 3.12+
• 来自 my.telegram.org/apps 的 API 凭据

npm install 会在 server/.venv 下创建 Python 环境，并安装两侧的依赖。

文件存放位置

一个数据库保存所有内容，这正是实现跨对话搜索、共享用户表、媒体去重和转发图的基础。

媒体目录结构

文件按对话类型、对话、论坛主题、媒体类型分目录存放：

media/
├── channels/technews_-1002116176890/
│   ├── photos/00004711-8001-conference-slides.jpg
│   └── documents/00004802-8210-quarterly-report.pdf
├── groups/pythondev_-1001597139842/
│   ├── general/photos/…
│   └── help/voice/00000004-9004-voice.ogg
└── profiles/123456789/000-5544332211.jpg

目录名称由句柄加完整 id 组成，非 ASCII 标题会被音译，文件名采用补零方式，以便按时间顺序排序。

速率限制与账户安全

每次 Telegram 调用都经过每个账户独立的令牌桶调控器，并带有 FloodWait 退避机制；每一次分页读取——消息、对话、成员、个人资料照片——都会等待洪泛结束后继续，而不是让运行失败。三种配置文件：

更长的等待会在活动日志中公布并等待结束；同一读取操作连续十二次触发等待会放弃并报告。

支持多个账户。可在设置中将某个账户标记为 burner（一次性账户），手机号查询将自动在其上运行，因为这是唯一有风险的操作：

手机号查询会将该号码短暂导入为联系人，然后立即删除。如果号码主人已经保存了您的号码，他们可能会看到一条“已加入 Telegram”的通知。tgscope 每次都会先询问，并且个人资料卡片会记录使用的是哪个账户。

开发

npm test                    # 92 个后端测试和 42 个前端测试，无需网络
npm run build               # 客户端生产构建

后端是基于 Telethon 核心的 FastAPI，使用模拟的 Telethon 客户端进行测试：覆盖抓取器、导出器、媒体目录结构以及所有模式迁移。前端测试覆盖浏览器背后的纯逻辑、周期运算、直方图分桶、数字和时间戳格式化，并渲染每个屏幕两次，一次为空、一次已有数据。

scripts/demo/ 通过预置的假数据重新生成 docs/preview.gif。它需要 chromium 和 ffmpeg，不会触碰您真实的工作区，也不属于应用的一部分。

源码不含注释 —— 含义由命名和结构承载，并且有测试强制执行这一点。

法律声明

适用于研究、新闻和授权调查。它通过 Telethon 使用 Telegram 官方 API，只读取您的账户已经能看到的内容——不会绕过任何人的隐私设置。请勿将其用于骚扰或跟踪，遵守 Telegram 的服务条款，并注意适用于您的数据保护法律。

MIT 许可证。