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 构建。

收集	跨多个账户收集频道、群组和论坛主题，支持媒体、去重和断点续传
调查	通过手机号、@username、id 或 t.me 链接查询个人资料、所有历史照片，以及与上次相比的差异
导出	十种格式，从纯 CSV 到带哈希的证据包
运行环境	Node 18+、Python 3.12+、SQLite。一个数据库，一个文件夹，无服务

功能说明

收集

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

调查

• 查询手机号、@username、用户 id 或 t.me 链接
• 简介、标记、作为隐私指标的最近上线精度、共同聊天、个人频道
• Telegram 主动提供的关于该账户的任何信息：注册月份、手机号所属国家、此人上次改名或更换照片的时间、其自动删除计时器、受限转发中显示的名称。请注意，它通常不会主动提供任何这些信息。这些字段会随 Telegram 在陌生人给你发消息时显示的反诈骗面板一同出现，而直接查询个人资料时则返回空值，因此请将它们视为额外收获，而非可依赖的内容
• 商业账户确实会可靠地提供街道地址、坐标和时区
• 每一张可见的个人资料照片，均以 SHA-256 和感知哈希进行哈希，并以画廊形式展示
• 感知哈希会跨账户匹配，因此第二份资料上的同一张图片会被发现
• 消息发送者在抓取时即被记录，因此浏览器中的名字即使此人没有用户名，也是指向查询的有效链接；“同步成员”会为之前收集的任何内容补全此项
• 每次查询都会生成快照并进行差异对比：用户名变更、显示名称变更、简介编辑、照片增删、隐私变更

导出

格式	你将获得
csv	每个对话一个文件
json / jsonl	完整元数据；JSONL 逐行流式输出
xlsx	包含消息、媒体、参与者和反应的工作表
html	独立报告：统计、活动、顶级发送者、转发来源、可搜索表格
markdown	与报告相同的文本版本
gexf / edges	用于 Gephi 和 Maltego 的转发图
sqlite	仅包含所选对话的独立数据库
bundle	包含数据、媒体、SHA-256 哈希清单和收集日志的 ZIP

环境要求

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

npm install 会在 server/.venv 下创建 Python 环境并安装前后端。

文件位置

内容	位置
配置	~/.config/tgscope/config.json（权限 600）
数据库	~/.local/share/tgscope/tgscope.db（WAL、FTS5）
媒体	~/.local/share/tgscope/media/
导出	~/.local/share/tgscope/exports/<timestamp>-<label>/

一个数据库容纳所有内容，这正是跨对话搜索、共享用户表、媒体去重和转发图谱得以实现的原因。

媒体布局

文件按对话类型、对话、论坛主题、媒体类型依次归档：

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

目录名由 handle 与完整 id 组合而成，非 ASCII 标题会进行音译，文件名会补零以便按时间顺序排序。

速率限制与账号安全

每次 Telegram 调用都会经过按账号划分的调控器，其带有令牌桶和 FloodWait 退避机制；每次分页读取——消息、对话、成员、头像——都会等待洪泛限制结束并恢复，而不是让本次运行失败。共有三种配置：

配置	媒体工作线程	请求间隔	静默吸收的等待时长
stealth	1	1.6 秒	最长 180 秒
balanced	4	0.35 秒	最长 90 秒
fast	8	无	最长 45 秒

更长的等待会在活动日志中公布并等待结束；若单次读取连续出现十二次，则放弃并报告。

支持多账号。在设置中将一个账号标记为 burner，手机号查询便会自动在该账号上运行，因为这是唯一有风险的操作：

手机号查询会临时将该号码作为联系人导入，随后再将其删除。如果对方已保存你的号码，他们可能会看到“已加入 Telegram”的通知。tgscope 每次都会先询问，并且个人资料卡片会记录使用了哪个账号。

开发

npm test                    # 92 backend and 42 frontend tests, no network needed
npm run build               # production bundle of the client

后端基于 Telethon 核心之上构建 FastAPI，并针对一个模拟的 Telethon 客户端进行了测试：包括抓取器、导出器、媒体布局以及每一次 schema 迁移。前端测试覆盖浏览器背后的纯逻辑、周期运算、直方图分桶以及数字和时间戳格式化，并且对每个界面渲染两次，一次为空状态，一次为填充状态。

scripts/demo/ 会从预置的模拟数据重新生成 docs/preview.gif。它需要 chromium 和 ffmpeg，不会触碰你真实工作区中的任何内容，也不属于应用的一部分。

源码中不包含任何注释 —— 命名和结构承载含义，并且有测试对此进行强制约束。

法律

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

MIT 许可。