Dxx-OTG/TGArchive

# 🗄️ TGArchive — Telegram 群组 OSINT 工具包    ## 📸 截图

🖼️ 点击展开 — 截图和完整的演示视频

**机器人** — 无需命令：只需一次 `/start`，之后所有操作都是可点击的卡片，并原地编辑。 | `/start` 中心 | 实体卡片 | |:---:|:---:| |  |  | | 抓取菜单 | 数据菜单 | 抓取完成 | |:---:|:---:|:---:| |  |  |  | **CLI** — 机器人的终端镜像：相同的数据库，相同的命令。 | 命令 (`help`) | 实时抓取 | |:---:|:---:| |  |  | **启动器和后端** | `TGArchive.bat` 菜单 | 机器人控制台 — CSV → DB 导入 | |:---:|:---:| |  |  |

🎥 观看完整演示 — 机器人的快速概览

▶️ [直接打开视频](https://github.com/user-attachments/assets/8cedb2c1-7ac1-4a11-89e8-6adf45b110ed)

## ⚠️ 注意事项（请先阅读） - **私人机器人。** 它仅回复 `ADMIN_USER_IDS` 中列出的 Telegram ID/用户名；所有其他发送者都会被自动拒绝，包括在 `/start` 时。 - **抓取涉及真实的个人数据**（用户名、用户 ID，有时包括消息）。遵守 [Telegram 的服务条款](https://telegram.org/tos) 和适用的隐私法律（例如欧盟的 GDPR）是运行者的责任。 - **机密信息保留在本地。** `.env`（token、凭证）和 `*.session` 文件（已认证的 Telegram 登录）已被 [.gitignore](.gitignore) 排除，不属于代码库的一部分。被跟踪的模板是 [`.env.example`](.env.example)。 - `Blacklist.py` 在**任何地方**隐藏特定的人/群组/频道——每个列表、搜索、计数（包括统计和各群组的计数）、链接和收藏，无论是在机器人还是在 CLI 中，就像它们不存在一样。 ## 📑 目录 **[📸 截图](#-screenshots)** **安装与运行** 1. [前置条件](#-prerequisites) 2. [依赖项](#-dependencies) 3. [安装说明](#-setup) 4. [`.env` 配置](#-env-configuration) 5. [菜单](#-menu) 6. [迁移到另一台电脑](#-transfer-to-another-pc) **工作原理** 7. [功能与使用方法](#-what-it-does-and-how-to-use-it) 8. [项目结构](#-project-structure) **参考** 9. [建议](#-recommendations) 10. [Telegram 频率限制 (FloodWait)](#-telegram-rate-limits-floodwait) 11. [疑难解答](#-troubleshooting) 12. [许可证](#-license) ## 🔧 前置条件 | 要求 | 说明 | |---|---| | **Windows 10 / 11** | 自动化脚本为 `.bat` + PowerShell。 | | **Python 3.10+** | 必须在 `PATH` 中。使用 `python --version` 检查。[下载](https://www.python.org/downloads/)（勾选*"将 Python 添加到 PATH"*）。`TGArchive.bat` 会自动检查此项，并告诉你它是否缺失或版本过旧。 | | **Git** | 用于克隆代码库。[下载](https://git-scm.com/download/win)。 | | **winget** | 用于自动安装 PostgreSQL。在保持最新状态的 Windows 10/11 上已预装（即“应用安装程序”）。 | | **一个 Telegram 账户** | 用于创建机器人和验证抓取。 | | **Bot token** | 来自 [@BotFather](https://t.me/BotFather)：`/newbot`。 | | **API ID + API Hash** | 来自 [my.telegram.org](https://my.telegram.org) → *API development tools*（具体步骤见[`.env` 配置](#-env-configuration)）。 | ## 📦 依赖项 Python 包（在 [`requirements.txt`](requirements.txt) 中，首次运行时自动安装到虚拟环境中）： ``` Telethon>=1.43 # scraping (user account) aiogram>=3.13 # Telegram bot asyncpg>=0.30 # async PostgreSQL driver python-dotenv>=1.0 # reads the .env file watchfiles>=0.21 # instant CSV-folder change detection for the bot's import watcher ``` 另外还有 **PostgreSQL 17**（由 **Setup Database** 安装）。 ## 🚀 安装说明 所有操作均通过 **`TGArchive.bat`** 这个单一入口进行。它会检测缺失的内容并引导你完成每一个步骤——创建 `.env`、填写内容、安装数据库——然后在一切准备就绪后显示完整菜单。 ### 1. 克隆 ``` git clone https://github.com/Dxx-OTG/TGArchive.git cd TGArchive TGArchive.bat ``` ### 2. 运行 `TGArchive.bat` 双击 **`TGArchive.bat`**（或如上所示从终端运行它）并按照屏幕上的菜单操作： 1. 首次运行时，它会从模板创建 `.env` 并在文本编辑器中打开它（记事本，如果记事本不可用则使用备用编辑器）。填写 `BOT_TOKEN`、`TG_API_ID`、`TG_API_HASH` 和 `ADMIN_USER_IDS`（见[`.env` 配置](#-env-configuration)）。 2. 然后它会提供 **Setup Database** 选项，该选项会安装 PostgreSQL 17，创建 `scraper` 数据库，应用 `db\migrations\` 中的 schema，并将 `DATABASE_URL_*` 行写入 `.env`。在需要时，它会自动以管理员身份重新运行。它总是会清楚地说明它检测到的状态（未安装 PostgreSQL / 已安装并正常工作 / 已安装但无法连接），而不是默默地猜测。它只会创建一个**空**的 schema——你抓取的数据存在于 `output\` CSV 文件中，并在你首次启动机器人或 CLI 时（重新）导入到数据库中，因此重置永远不会丢失任何东西。 3. 数据库准备好后，如果 Telegram 抓取账户尚未认证，菜单会对此进行标记。选择 **🔑 Telegram Login** 直接从菜单登录（手机号码 + OTP，如果启用的话还包括 2FA 密码）——无需打开 CLI——这样在机器人的中心/卡片中也能进行抓取。（CLI 也会在你第一次运行抓取时让你登录。） 4. 当 `.env`、数据库和 Telethon 登录都准备好后，将显示完整菜单——选择 **Start The Bot**。 无需手动启动 `scripts\` 中的任何脚本：`TGArchive.bat` 会在执行适当的检查后运行它们。该菜单在系统 Python 上运行（仅使用标准库），因此它永远不会占用 `.venv`，并且在显示完整菜单之前，它会探测数据库（不仅仅是检查“端口是否打开”），从而能够区分“未设置”、“无法连接”、“凭证错误”和“schema 缺失/损坏”，并为每种情况提供各自的解释。 ## 🔐 `.env` 配置 | 变量 | 值 | |---|---| | `BOT_TOKEN` | [@BotFather](https://t.me/BotFather) 在执行 `/newbot` 后返回的 token。 | | `TG_API_ID` | 来自 [my.telegram.org](https://my.telegram.org) 的数字 `api_id`。 | | `TG_API_HASH` | 来自 [my.telegram.org](https://my.telegram.org) 的 `api_hash`。 | | `TG_SESSION_NAME` | Telethon session 文件名。保持原样（例如 `telegram_session`）。 | | `ADMIN_USER_IDS` | **谁可以使用该机器人。** 接受用户名（带或不带 `@`）**或**数字 ID，可混合使用，以逗号分隔。例如 `@johndoe` 或 `123456789` 或 `@johndoe,987654321`。 | | `DATABASE_URL_BOT` | 由 **Setup Database** 写入——请勿手动编辑。 | | `DATABASE_URL_COLLECTOR` | 由 **Setup Database** 写入——请勿手动编辑。 | ## 📋 菜单 **`TGArchive.bat`** 是唯一的入口点。它的菜单包括： - 🤖 **Start The Bot** — 在单独的窗口中运行机器人；在使用期间该窗口保持打开。 - 🛠️ **CLI** — 机器人的终端镜像：在同一个数据库上执行相同的命令（搜索、浏览、统计、导出、删除、收藏、抓取）。 - 🔑 **Telegram Login / Switch Account** — 直接从菜单验证抓取账户（手机 + OTP，以及 2FA），无需打开 CLI。如果账户已登录，同一选项会提供**切换账户**功能：它会登出旧账户，删除其 `.session` 文件，并登录新账户。标签会根据状态发生变化（登出时显示 Login，登录时显示 Switch）。 - 🗄️ **Setup Database** — 安装或修复数据库（在准备好之前会一直显示）。 - 📦 **Prepare Transfer To New PC** — 将文件夹打包以供另一台机器使用。 - 🧹 **Clean Logs/History** — 清除本地 `log\` 文件，并分别清除（在每个操作前都有独立的 y/n 确认）两个缓存：可达性检查结果和 24 小时内解析的链接身份（重新打开的卡片）。不会触碰任何已抓取的数据。分页/card token 保留在内存中，并在重启机器人时重置。 - ⚙️ **Open `.env` in a text editor** — 直接编辑配置（记事本，不可用时自动回退到备用编辑器）。 ## 🔄 迁移到另一台电脑 在保留存档的同时移动已安装好的程序： **在旧 PC 上：** 1. *TGArchive.bat* → **Prepare Transfer To New PC**。这将清除 `.env` 中的 `DATABASE_URL_*` 行，并删除 `.venv`、`__pycache__` 文件夹和本地 `log\*.log` 文件。你抓取的数据以 `output\` CSV 文件的形式转移——没有数据库转储。（如果打开了机器人/抓取窗口，请先关闭它们，以免 `.venv` 被锁定。） 2. 将整个文件夹复制到新 PC。它包含 `.env` 和 `.session`，这些都是机密文件——请通过可信的渠道进行传输。 **在新 PC 上：** 3. 运行 **`TGArchive.bat`**。它会为这台机器重建 `.venv`（virtualenv 不能在 PC 之间移动），然后运行 Setup Database，创建一个空的 `scraper` 数据库。启动机器人：它会在首次启动时将你的 `output\` CSV 导入到全新的数据库中，从而重建完整的存档。 ## 📖 功能与使用方法 TGArchive 用于存档和搜索 Telegram 群组和频道的**成员、消息发送者和共享链接**。你可以通过无需命令的 **Telegram 机器人**（主要方式）或等效的**终端 CLI** 来驱动它——两者都在同一个存档上工作。 ### 准备就绪 1. **登录一次**（如果你还没有）：菜单中的 **🔑 Telegram Login 会登录抓取账户（手机 + OTP，如果启用的话还包括 2FA），保存在 `.session` 文件中——或者直接运行任何 CLI 抓取，它会在那时提示你。机器人本身从不要求提供手机号码。 2. **收集。** 通过机器人：`/start` → 🤖 Scrape，或者粘贴一个群组/频道并使用其卡片。通过 CLI：`scrapemembers` / `scrapemessages` / `scrapelinks [limit]`。目标可以是公开的 `@username`/`t.me` 链接，或者是该账户已加入的私有 `t.me/+…` 邀请链接。 3. **探索。** 浏览、搜索、收藏、检查和导出——从机器人的中心或 CLI 的命令进行。两者读取的是同一个数据库，因此结果总是一致的。 ### 机器人（无需命令） **`/start` 是唯一的命令**——其他所有操作都在它打开的菜单中进行，或者通过粘贴一个引用来完成。有两种方式： - **`/start` → 菜单中心。** 六个部分，全部**原地**导航（同一条消息被编辑，没有新消息）： - **🤖 Scrape** — 群组的成员、消息发送者或共享链接（选择要读取多少条消息；重新抓取会合并，保留旧数据）。 - **🔎 Search** — **用户**、**机器人**、**群组**、**频道**或**链接**（输入名称、`@username`、ID 或 t.me 链接的任意部分）。 - **🗂 Browse** — 你收集的所有内容，按类别分类（群组、频道、用户、机器人、链接），并显示成员/链接计数。 - **📊 Data** — **Stats**；**Check**（可达性：Check All + Check Links）；**Export All**（压缩包）；**Delete All**。 - **⭐ Favorites** — 你保存的实体。 - **ℹ️ Help** — 应用内指南，支持**英文或意大利文**（一键切换语言），并带有指向此完整指南的链接。 - **粘贴一个 `@username` / `t.me` 链接**（或转发一条频道帖子）→ 该实体的**操作卡片**：抓取、检查、收藏、查看成员/链接、导出、删除，或者**将其添加到存档而不进行抓取**。私有群组的邀请链接也会打开其卡片（收藏/检查/添加甚至在抓取账户加入之前就可以工作；只有 Scrape 需要它成为成员）。 **一切都是卡片。** 在任何列表中（搜索结果、成员、群组的链接、收藏、统计）点击任何名称或链接，都会在同一条消息中打开该实体的卡片——只有卡片自身的标题会外链到 Telegram。列表进行分页（◀ / ▶）并按字母顺序排序（没有用户名的用户排在最后）。 ### CLI（终端镜像） 在**相同的数据库和逻辑**上机器人的纯文本镜像——终端没有按钮，所以它使用键入的命令：`searchusers`/`searchbots`/`searchgroups`/`searchchannels`/`searchlinks`、`users`、`bots`、`groups`、`channels`、`members`、`links`、`stats`、`export`、`delete`、`favorites`、`check [all|links|prune]`、`scrape*`、`card`。在这里粘贴一个引用也会打开其卡片。 ### 需要了解的信息 - **抓取是累加的** — 重新抓取一个群组只会添加新成员/链接，永远不会删除已有的内容。只有指向真实用户/频道/群组的链接会被保留，并且链接源可以是频道，而不仅仅是群组。 - **不抓取直接添加** 将群组/频道/用户/机器人作为占位符放入存档，你可以将其收藏和检查。 - **机器人**会自动与用户区分开来（机器人的 `@username` 以 *bot* 结尾）。 - **可达性检查** 将实体标记为 ✅ 可达 / ❌ 已离开或被封禁 / ⚠️ 未验证，并且可以丢弃无效的实体。它经过节奏控制并缓存 24 小时，以对 Telegram 保持温和——见 [FloodWait](#-telegram-rate-limits-floodwait)。 - **你的数据就是 `output\` 文件夹**（CSV 文件）。数据库只是每次启动时从中重建的快速索引——可随时丢弃——因此 `output\` 才是真正的存档：**请自行备份**。机器人和 CLI 不能同时运行（它们共享一个 Telegram 账户），因此在打开另一个之前请先关闭当前一个。 ## 📁 项目结构 ``` . ├── TGArchive.bat # single entry point (the menu) ├── .env.example # config template (copy to .env) ├── Blacklist.py # people/groups/channels to hide everywhere ├── requirements.txt ├── bot/ # Telegram bot (aiogram), private (admin-only gate) │ ├── main.py # startup, middlewares, polling │ ├── card.py, card_view.py # the entity "action card": logic + rendering │ ├── csv_watcher.py # imports the CSVs into the DB, live (watchfiles) │ ├── telethon_client.py # the shared scraping client, bot side │ ├── i18n.py # all user-facing strings (incl. the EN/IT in-app help) │ ├── middlewares/ # admin-only gate, rate limit │ └── modules/ # routers (start hub, card, check, admin) + helpers (search, groups, stats, scrape) ├── CLI/ # terminal mirror of the bot (same DB, same logic) │ ├── Menu.py # REPL: connects DB + Telethon, syncs CSVs, dispatches commands │ ├── commands.py # command handlers (reuse db.queries; plain-text rendering) │ └── Scrape.py, Messages.py, ExtractLinks.py # the three scrapers ├── collectors/ # shared backend: Telethon client + lock, login, entity resolve, │ # reachability check, CSV -> DB import, pacing/throttle ├── db/ # PostgreSQL: pool, queries, blacklist, cleanup │ └── migrations/ # 0001_init.sql (the full schema) └── scripts/ # .bat + PowerShell: setup DB, transfer, login, clean logs, menu └── _bootstrap_venv.bat # shared venv/dependency bootstrap, called by every script that needs it ``` ## 💡 建议 - **保护好抓取账户。** 所有实时操作（解析链接、检查、抓取）均由 `telegram.session` 中的那一个账户完成。繁重或突发的使用可能会导致其**被 Telegram 频率限制或受到限制**——请参阅下文的 [FloodWait](#-telegram-rate-limits-floodwait)。如果你要进行大量抓取/检查，请使用一个**专用（备用）账户**，而不是你的个人账户。 - **不要发送垃圾信息。** 避免连续粘贴几十个全新的链接，不要一次强制对大型存档进行全面重新检查——**请分批检查**（先 Check，然后稍后 ⏭ 跳过最近的）。机器人已经自动控制了节奏并限制了每次运行的数量，但保持克制能让你远离限制。 - **如果 Telegram 对你进行了频率限制（FloodWait）：** 只需等待机器人显示的时间然后重试——这是一个临时的冷却期，不会丢失任何东西。备用账户可以立即绕过它（它的冷却期是分开的）；要让机器人变得更温和，可以在 `collectors/throttle.py` 中提高节奏控制的值。 - **搜索/浏览/统计是免费的。** 它们只读取数据库——没有 Telegram 调用，因此即使在账户处于 FloodWait 冷却期间也可以随意使用它们。 - **一次只运行一个任务。** 机器人和 CLI 共享同一个账户/session，并且有一个锁会阻止它们一起运行——在使用另一个之前先关闭当前一个。 - **重新抓取是累加的** — 它只会添加新的成员/链接，永远不会删除你已经拥有的内容。以后再次抓取同一个群组以进行补充。 - **使用 `Blacklist.py` 隐藏人员/群组** — 列出的条目会从每个列表、搜索、计数、链接和收藏中消失（在启动时读取，因此编辑后需要重启）。 - **`output\` 是你的存档——请自行备份。** 数据库是可随时丢弃的（每次启动时从 `output\` 重建），因此没有数据库备份：`output\` 中的 CSV 文件（以及 `.env`/`.session`）是唯一无法重新生成的内容。如果数据对你很重要，请定期将该文件夹复制到安全的地方，并在迁移到另一台 PC 之前使用 **Prepare Transfer**。 ## ⏳ Telegram 频率限制 (FloodWait) **这是什么。** `telegram.session` 中的那一个账户执行所有实时操作（解析粘贴的链接、检查可达性、抓取）。当它过快地发出过多调用时——尤其是**实体解析**（`ResolveUsername` / `CheckChatInvite`，这是 Telegram 限制最严格的操作）——Telegram 会回复“等待 N 秒”：这就是 *FloodWait*。这是一个临时的、针对账户的冷却期，旨在让你放慢速度——**不是封禁，也不会丢失任何东西。** **这里触发它的原因。** 主要是在大型存档上进行**Check**（每个目标都是一次解析，连续数百个从未见过的实体正是 Telegram 会进行限流的情况）以及快速粘贴许多全新的链接。单次抓取没问题——这主要是有节奏地读取一个聊天。 **你会看到什么。** 机器人会告诉你等待时间，例如*"⏳ Telegram 正在对该账户进行限流 (FloodWait) — 请在大约 1 小时 15 分钟后重试。"* 遇到此情况的检查会提前停止并**保存部分结果**。只需等待它结束，然后重试——请参阅上文的[建议](#-recommendations)了解如何避免它。 ## 🩹 疑难解答 | 症状 | 原因 / 修复方法 | |---|---| | `BOT_TOKEN missing in .env` | 未创建或未填写 `.env`。请参阅[配置](#-env-configuration)。 | | 机器人不回复 `/start` | 发送者的 ID/用户名不在 `ADMIN_USER_IDS` 中。控制台会打印出发送者的 ID。 | | `Conflict: terminated by other getUpdates request` | 同一个机器人（相同的 `BOT_TOKEN`）已经在其他地方运行。请关闭另一个实例。 | | 数据库损坏 / 凭证丢失 | 从菜单运行 **Setup Database**。它会**在不重新安装 PostgreSQL** 的情况下修复/重置 `scraper` 数据库：如果 `.env` 中仍有可用凭证，它会重复使用它们，否则会就地恢复访问权限。这也是从多个此文件夹副本运行 Setup Database 的典型后果 - PostgreSQL 是一个共享服务，因此只有最新副本的 `.env` 保持有效。 | | 菜单或机器人控制台提示数据库"可达，但凭证无效" | 同上解决方法（Setup Database）。菜单在您尝试启动机器人之前就会检查真实凭证；如果您绕过它并直接运行 `start_bot.bat`，机器人自身的启动检查会以相同的消息捕获相同的问题。 | | 菜单或机器人控制台提示数据库"schema 缺失或损坏" | 连接和凭证正常，但预期的表不存在 - 请运行 **Setup Database** 以重新应用 schema（它会将其重新创建为空；您的 `output\` CSV 会在下次启动时重新导入，因此不会丢失数据）。在菜单和机器人自身的启动中都存在相同的检查。 | | Setup Database 提示"found a different installation"并停止 | 此 PC 上已安装了非 17 版本的 PostgreSQL（Windows 服务名称不同）- 此项目仅管理 PostgreSQL 17。请手动卸载另一个版本（设置 > 应用），然后再次运行 Setup Database。 | | 安装过程中提示 `winget not available` | 从 Microsoft Store 安装"应用安装程序"，然后再次运行 Setup Database。 | | 更改了 `Blacklist.py` / `.env` 但没有任何变化 | 两者仅在启动时读取：请重新启动机器人（或 CLI）。 | | 抓取回复"Scraping unavailable" | Telethon session 尚未经过验证：从菜单运行 **🔑 Telegram Login**（手机 + OTP）— 或者打开 **CLI** 并运行一次任何抓取命令 — 然后重新启动机器人。 | | "another TGArchive process is already connected" | 预期行为，不是 bug：CLI 和机器人共享一个 `.session` 文件，自动锁阻止它们同时运行。在使用另一个之前先关闭当前一个。 | | CLI 提示"DATABASE_URL_BOT is missing" / "schema missing or broken" | CLI 使用与机器人相同的数据库。请先运行 **Setup Database**，然后重新打开 CLI。 | ## 📜 许可证 [PolyForm Noncommercial 1.0.0](LICENSE)。仅供个人、教育和研究使用 - **未授权用于商业用途或转售**。按“原样”提供，不提供任何形式的保证；合法使用并遵守所有适用法律和服务条款是用户的责任。

标签：AI合规, ESC4, OSINT, PostgreSQL, Python, Telegram机器人, 命令控制, 数据采集, 无后门, 测试用例, 逆向工具