klivak/tg-harvest

# TG Harvest [](https://github.com/klivak/tg-harvest/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](LICENSE) [](https://github.com/klivak/tg-harvest/releases) 通过 MTProto API 的 Telegram 数据采集器。可从您有权访问的任何频道、群组、机器人或私人聊天中提取消息、媒体元数据、反应、浏览量、转发量 —— 包括禁用复制的受限频道。 ### 什么是 TG Harvest？ TG Harvest 是一个开源 Python 工具，用于**下载和导出 Telegram 频道数据**。它直接连接到 Telegram 的 MTProto API（官方应用使用的同一协议），让您能够访问网页抓取工具和机器人无法获取的数据 —— 包括带有复制限制的频道、私人群组和机器人对话。 与 Telegram 内置导出功能（仅适用于个人聊天）不同，TG Harvest 可以**导出您作为成员加入的任何频道或群组** —— 包含完整的消息文本、反应、浏览量、转发量、媒体元数据等。 ### 适用人群 - **营销人员 & SMM 运营经理** —— 导出频道帖子进行内容分析，追踪互动指标，对比竞争对手频道 - **研究人员 & 数据记者** —— 收集 Telegram 数据进行分析，监测公共舆论，归档新闻频道 - **OSINT 分析师** —— 从公共和私人频道提取数据用于调查 - **社区管理员** —— 备份群组对话，分析成员活动，追踪讨论趋势 - **开发者 & 数据科学家** —— 结构化 JSON/CSV 导出，用于构建数据集、训练模型或输入分析管道 - **任何需要 Telegram 备份的人** —— 将您自己的频道、群组或机器人对话导出为 JSON、CSV、Excel 或 HTML ### 核心功能 - 将 Telegram 频道、群组、机器人和私人聊天导出为 **JSON、CSV、Excel (.xlsx) 或 HTML** - 访问 Telegram 禁用复制的**受限频道** —— TG Harvest 在协议层面工作 - **多频道队列** —— 在一次会话中解析多个频道，每个保存到单独的文件夹 - **增量解析** —— 仅获取自上次运行以来的新消息（无重复） - **Web UI** —— 带有交互式图表、搜索和分析功能 —— 无需编程 - **CLI** —— 用于自动化和脚本编写 ## 快速开始 ### 步骤 0 — 安装 Python 您需要 Python 3.11 或更高版本。检查是否已安装： ``` python --version ``` 如果显示 `Python 3.11` 或更高版本，就可以了。如果没有，请从 [python.org/downloads](https://www.python.org/downloads/) 下载 Python 并安装。**在 Windows 上，安装过程中请勾选 "Add Python to PATH"。** ### 步骤 1 — 下载并安装 TG Harvest 打开终端并依次运行以下命令： ``` git clone https://github.com/klivak/tg-harvest.git cd tg-harvest python -m venv .venv ``` 激活虚拟环境： - **Windows:** `.venv\Scripts\activate` - **Mac/Linux:** `source .venv/bin/activate` 然后安装： ``` pip install -e . ``` ### 步骤 2 — 获取 Telegram API 密钥 1. 在浏览器中访问 [my.telegram.org/apps](https://my.telegram.org/apps) 2. 使用您的手机号码登录（与您的 Telegram 账户关联的号码） 3. 点击 **API development tools** 4. 填写任意应用标题（例如 `tg-harvest`）和简称（例如 `harvest`） 5. 您将看到 **App api_id**（数字）和 **App api_hash**（长字符串）—— 复制它们 ### 步骤 3 — 配置 ``` cp .env.example .env ``` 使用任何文本编辑器打开 `.env` 文件并填入您的值： ``` TG_API_ID=12345678 TG_API_HASH=your_api_hash_here TG_PHONE=+380123456789 ``` ### 步骤 4 — 登录 Telegram ``` tg-harvest auth login ``` Telegram 将向您的 Telegram 应用发送验证码。在提示时输入它。如果您启用了 2FA，也需要输入密码。**这只需要做一次** —— 会话将保存在本地。 ### 步骤 5 — 开始使用！ ``` # Web UI — 推荐（所有功能集于一处） tg-harvest web # opens at http://localhost:8777 # 或直接使用 CLI tg-harvest channels list # list your channels, groups, bots tg-harvest parse @channel # parse a public channel tg-harvest parse @some_bot # parse a bot conversation tg-harvest parse -1001234567890 # parse a private channel by numeric ID tg-harvest search "keyword" # search parsed data ``` ## 功能特性 - **完整的 MTProto 访问** —— 在协议层面工作，绕过 UI 限制（禁用复制的频道） - **频道、群组、机器人 & 私人聊天** —— 解析您有权访问的任何对话，包括机器人对话和一对一聊天 - **私人 & 受限频道** —— 甚至可以解析禁用复制限制的频道 - **丰富的数据提取** —— 消息、媒体、反应、浏览量、转发量、回复、实体 - **Web UI** —— Streamlit 界面，支持 EN/UK 语言切换、每页帮助指南、解析、搜索和分析 - **消息搜索** —— 在解析的数据中进行带过滤器的全文搜索 - **增量解析** —— 仅获取自上次解析以来的新消息 - **分析** —— 消息活动图表、热门帖子、反应分布 - **多频道队列** —— 在一次会话中解析多个频道（`tg-harvest parse @ch1 @ch2 @ch3`），每个保存到单独的带日期戳的文件夹 - **灵活的过滤** —— 按日期范围、消息限制 - **多种导出格式** —— JSON、CSV、Excel (.xlsx)、HTML 报告，或一次全部导出 - **文件分割** —— 将大型导出分割为多个部分（2–20 个文件） - **HTML 报告** —— 自包含的单文件 HTML，支持暗色/亮色主题、可排序表格、可点击的消息 URL - **重新导出** —— 将已解析的 JSON 转换为 CSV/XLSX/HTML，无需重新连接到 Telegram（`tg-harvest export`） - **文件管理器** —— 从 Web UI 浏览、删除和重新导出解析的文件 - **字段选择** —— 选择要导出的列（id、text、date、views、url 等） - **直接消息链接** —— 每条消息都包含一个 Telegram URL，以便快速导航 - **美观的 CLI** —— 进度条、彩色输出、汇总表 - **速率限制** —— 遵守 Telegram API 限制，自动处理 FloodWait 错误 - **CI/CD** —— GitHub Actions、ruff linting、pre-commit hooks ## 私人 & 受限频道 TG Harvest 可以从 Telegram UI 禁用复制的频道和群组中提取数据。这是因为该应用程序直接通过 **MTProto 协议** 通信 —— 与官方 Telegram 应用使用的协议相同。复制限制仅影响 UI，而不影响底层 API。 **要求：** - 您的 Telegram 账户必须是频道或群组的**成员** - 您必须通过 `tg-harvest auth login` 进行身份验证 **如何访问私人频道：** 1. 运行 `tg-harvest channels list` 或在 Web UI 中打开 **Channels** 页面 2. 找到该频道 —— 私人频道不显示用户名，只显示数字 ID 3. 复制数字 ID（例如 `-1001234567890`） 4. 使用它进行解析：`tg-harvest parse -1001234567890` **TG Harvest 可以从受限频道提取的内容：** - 完整的消息文本 - 媒体元数据（文件名、类型、大小 —— 而非文件本身） - 反应、浏览量、转发量 - 帖子作者、发送者信息 - 编辑历史、置顶状态 **无法做到的：** - 访问您不是成员的频道 - 检索已删除的消息 - 下载自毁消息 ## 使用方法 ### 身份验证 ``` # 登录（交互式：手机验证码 + 可选 2FA） tg-harvest auth login # 检查认证状态 tg-harvest auth status # 登出 tg-harvest auth logout ``` ### 列出频道、群组 & 机器人 ``` # 显示所有可访问的频道、群组、Bots 和私聊 tg-harvest channels list # 限制扫描的对话框数量 tg-harvest channels list -l 200 ``` ### 解析消息 ``` # 通过用户名解析公开频道 tg-harvest parse @channel_name # 解析 Bot 对话 tg-harvest parse @bot_username # 通过数字 ID 解析私有频道 tg-harvest parse -1001234567890 # 按日期范围解析 tg-harvest parse @channel -f 2024-01-01 -t 2024-12-31 # 限制消息数量 tg-harvest parse @channel --limit 5000 # 增量模式 — 仅解析自上次运行以来的新消息 tg-harvest parse @channel -i # 导出为 CSV tg-harvest parse @channel --format csv # 导出为 Excel (.xlsx) tg-harvest parse @channel --format xlsx # 导出为 HTML 报告 tg-harvest parse @channel --format html # 一次性导出为所有格式 (JSON + CSV + XLSX + HTML) tg-harvest parse @channel --format all # 仅导出选定字段 tg-harvest parse @channel --fields id,text,date,views # 自定义输出目录 tg-harvest parse @channel -o ./my_data # 下载媒体文件（照片、视频、文档） tg-harvest parse @channel --download-media # 下载带大小限制的媒体文件 (MB) tg-harvest parse @channel --download-media --max-media-size 100 # 将发送者 ID 解析为用户名和名称 tg-harvest parse @channel --enrich-senders # 获取完整回复线程（额外的 API 调用） tg-harvest parse @channel --fetch-replies # 多频道队列 — 在一个会话中解析多个频道 tg-harvest parse @channel1 @channel2 @channel3 # 带选项的多频道解析 tg-harvest parse @news @politics @tech --format all --limit 1000 # 将输出拆分为多个部分（适用于大型导出） tg-harvest parse @channel --split-parts 5 # 详细模式（调试日志） tg-harvest -v parse @channel ``` ### 搜索消息 ``` # 搜索所有已解析数据 tg-harvest search "keyword" # 按媒体类型筛选 tg-harvest search "photo" --media-type photo # 按最低浏览量筛选 tg-harvest search "news" --min-views 1000 # 仅显示带有 Reactions 的消息 tg-harvest search "announcement" --has-reactions # 日期范围筛选 tg-harvest search "update" --from-date 2024-01-01 --to-date 2024-06-30 # 限制结果数量 tg-harvest search "crypto" -n 100 ``` ### 重新导出 ``` # 将已解析的 JSON 重新导出为 CSV（无需 Telegram 连接） tg-harvest export output/channel_20240615.json --format csv # 重新导出为 HTML 报告 tg-harvest export output/channel_20240615.json --format html # 重新导出目录中的所有 JSON 文件 tg-harvest export output/ --format all # 包含字段选择 tg-harvest export output/ --format xlsx --fields id,text,date,views,url ``` ### Web UI ``` # 启动 Streamlit Web 界面（端口 8777） tg-harvest web # 自定义端口 tg-harvest web -p 9000 ``` Web UI 提供： - **认证状态** —— 获取 API 凭证的分步指南、检查会话、查看配置 - **频道** —— 浏览所有可访问的频道、群组、机器人和私人聊天；显示类型和数字 ID 以便复制 - **解析** —— 按用户名或数字 ID 解析任何对话、日期选择器、增量模式、进度条、下载按钮 - **搜索** —— 带过滤器的全文搜索（媒体类型、浏览量、反应、日期范围、频道） - **分析** —— 交互式图表：每日/每周/每月消息数、每小时活动、按浏览量/反应/转发排名的热门帖子、媒体分布、反应分布、互动率、词频 - **文件** —— 文件管理器，用于浏览、删除和重新导出解析的输出文件 - **语言切换** —— English / Українська（侧边栏） 每个页面都有一个可折叠的 **Tips / Підказки** 部分，其中包含使用提示。 #### Web UI 分步工作流程 1. **认证状态** —— 验证您的 Telegram 会话是否处于活动状态（侧边栏中的绿色指示器） 2. **频道** —— 点击 "Load channels" 获取您的对话列表 3. **解析** —— 从下拉列表中选择一个频道（从步骤 2 加载），选择日期范围/限制预设，点击 "Parse" 4. **搜索 / 分析 / 文件** —— 探索解析的数据 ## 输出格式 ### JSON 包含所有字段的完整结构化数据： ``` { "channel": { "id": 1234567890, "title": "Channel Name", "username": "channel_name", "members_count": 15000 }, "messages": [ { "id": 1, "date": "2024-01-15T12:00:00+00:00", "text": "Message text", "views": 5432, "forwards": 12, "reactions": { "total": 150, "reactions": [ {"emoji": "👍", "count": 100}, {"emoji": "❤️", "count": 50} ] } } ], "total_messages": 1, "parsed_at": "2024-06-01T10:00:00+00:00" } ``` ### CSV / Excel 扁平表格格式。可直接在 Excel 或 Google Sheets 中打开。 ## 项目结构 ``` src/tg_harvest/ config/ Settings, constants models/ Pydantic data models client/ Telegram session, rate limiter parsers/ Message/media/channel parsing exporters/ JSON, CSV, Excel, HTML export (with field selection) storage/ Incremental parsing state search/ Search engine analytics/ Statistics and analytics cli/ Click CLI commands web/ Streamlit web UI locales/ Translation files (en.json, uk.json) utils/ Logging, date helpers ``` ## 可选设置 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `TG_SESSION_NAME` | `tg_harvest` | 会话文件名 | | `TG_FLOOD_SLEEP_THRESHOLD` | `60` | FloodWait 错误的自动休眠时间（秒） | | `TG_REQUEST_DELAY` | `1.0` | API 请求之间的延迟（秒） | | `TG_OUTPUT_DIR` | `./output` | 默认输出目录 | | `TG_WEB_PORT` | `8777` | Streamlit Web UI 端口 | ## 安全性 ### 凭证存储 - API 密钥（`TG_API_ID`、`TG_API_HASH`、`TG_PHONE`）从 `.env` 加载，该文件已被 **gitignore** —— 永远不会被提交 - Telegram 会话文件（`sessions/*.session`）已被 **gitignore** —— 包含认证令牌，在共享系统上请使用文件系统权限（`chmod 600 sessions/`）进行保护 - 解析的数据（`output/`）已被 **gitignore** - 电话号码在所有 UI 输出中都会被掩码处理（`+380***4567`） - 2FA 密码输入使用 `getpass` —— 不会回显到终端 ### 输入处理 - 搜索查询在使用前会进行正则转义（`re.escape`） - 输出目录会针对 `..` 路径遍历进行验证 - 所有数据模型在使用前都通过 Pydantic v2 进行验证 ### Web UI - 消息文本通过 `st.dataframe()` 显示 —— 不作为 markdown 渲染（无 XSS） - 翻译字符串是静态文件 —— 从不受用户控制 - **不设计用于公共互联网暴露** —— 如果暴露，请在本地运行或使用带有身份验证的反向代理 ### 负责任地使用 TG Harvest 仅访问您作为 Telegram 成员已经可以看到的数据。它不会绕过访问控制 —— 仅绕过 UI 复制限制。在收集数据时，请遵守 Telegram 的服务条款和适用法律。 ## 开发 ``` # 安装开发依赖 pip install -e ".[dev]" # 运行测试 pytest -v # Lint ruff check src/ tests/ # 格式化 ruff format src/ tests/ # 设置 pre-commit hooks pre-commit install ``` ## 许可证 MIT ☕ 如果这个项目对您有帮助，请 [请我喝杯咖啡](https://ko-fi.com/klivak)

标签：API客户端, ESC4, JSON导出, Kubernetes, MTProto, OSINT, Python, Telegram, Web界面, 即时通讯, 命令控制, 数据导出, 数据泄露, 数据采集, 无后门, 漏洞探测, 用户行为分析, 社会媒体监控, 竞争情报, 聊天记录备份, 舆情分析, 隐私数据获取