erfanghorbanee/Telegram-File-Downloader
GitHub: erfanghorbanee/Telegram-File-Downloader
从 Telegram 频道、群组、私聊中批量下载并按类型过滤文件的 Python 命令行工具。
Stars: 31 | Forks: 6
# Telegram-File-Downloader
[](https://www.python.org/)
[](https://github.com/astral-sh/ruff)
一个用于从 Telegram 实体（频道、群组、聊天或收藏夹）下载文件的 Python 脚本。它支持按文件类型（例如图片、PDF）进行过滤。
## 目录
- [Telegram-File-Downloader](#telegram-file-downloader)
- [目录](#table-of-contents)
- [功能](#features)
- [前置条件](#prerequisites)
- [获取 Telegram API 凭证的步骤](#steps-to-get-telegram-api-credentials)
- [设置 .env 文件](#setting-up-the-env-file)
- [用法](#usage)
- [列出所有可访问的对话框](#list-all-accessible-dialogs)
- [下载文件](#download-files)
- [安全说明](#security-notes)
- [常见问题](#faq)
- [什么是 Telegram Entity？](#what-is-a-telegram-entity)
- [如何找到私有频道或群组的 ID？](#how-do-i-find-the-id-of-a-private-channel-or-group)
- [我可以使用 Bot Token 代替手机号码吗？](#can-i-use-a-bot-token-instead-of-my-phone-number)
- [支持哪些文件格式？](#what-file-formats-are-supported)
- [贡献](#contributing)
## 功能
- 从频道、群组、私聊或收藏夹下载文件。
- 按文件类型（例如图片、PDF、视频）过滤下载。
- 将文件保存到指定目录。
- 列出你有权访问的所有频道、群组和聊天。
- 通过环境变量轻松设置，实现安全的凭证管理。
## 前置条件
1. 你的系统上已安装 Python 3.12 或更高版本。
2. 已安装 `telethon` 库。你可以使用以下命令安装所有必需的库：
pip3 install -r requirements.txt
3. 一个 Telegram 账号或 Bot Token。
### 获取 Telegram API 凭证的步骤
要使用此脚本，你需要从 Telegram 获取 **API ID** 和 **API Hash**。请按照以下步骤操作：
1. 打开浏览器并访问 [Telegram 的 My Apps 页面](https://my.telegram.org/apps)。
2. 使用你的 Telegram 账号凭证登录。
3. 点击 **Create New Application**。
4. 填写所需详细信息。
5. 创建应用程序后，你将看到你的 **API ID** 和 **API Hash**。复制这些值。
### 设置 .env 文件
为了安全地存储你的凭证：
1. 在项目目录中，创建一个名为 `.env` 的文件。
2. 在文件中添加以下行：
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
将 `your_api_id` 和 `your_api_hash` 替换为从 Telegram 获取的实际值。
## 用法
### 列出所有可访问的对话框
要查看你有权访问的所有频道、群组和聊天：
```
python main.py --list
```
这将显示一个包含以下内容的表格：
- **ID**：实体的数字标识符
- **Type**：实体的类型（Channel (public/private)、User、Chat 等）
- **Name**：显示名称
- **Username**：公开用户名（如果有）
### 下载文件
**基本语法：**
```
python main.py --format --output --limit
```
**示例：**
```
# 从公开频道下载
python main.py @channel_name --format images --output ./downloads --limit 100
# 从 Saved Messages 下载
python main.py me --format videos --output ./downloads --limit 100
# 使用 ID 从私有频道、私有群组或用户聊天下载
python main.py -1001234567891 --format images --output ./downloads --limit 100
# 下载特定文件类型 (pdf)
python main.py @channel_name --format pdf --output ./downloads --limit 0
# 下载所有媒体类型（无过滤）
python main.py @channel_name --output ./downloads --limit 0
```
**参数：**
- ``：要下载内容的实体。可以是：
- 公开频道用户名：`@channel_name` 或 `channel_name`
- 实体 ID：`-1001234567891`（使用 `--list` 查找 ID）
- 收藏夹：`me` 或 `self`
- `--format` 或 `-f`：按文件类型类别或特定扩展名过滤。
- **类别：** `images`、`documents`、`videos`、`audios`、`archives`
- **特定扩展名：** `pdf`、`jpg`、`png`、`mp4`、`zip` 等。
- 如果省略，则下载所有媒体类型。
- `--output` 或 `-o`：保存下载文件的目录。默认为当前目录。
- `--limit` 或 `-l`：要获取的最大消息数量。使用 `0` 获取**所有消息**。默认为 100。
**注意：** 你可以在代码的 `FILE_CATEGORIES` 字典中自定义每个类别支持的扩展名。
**注意：** `--limit` 参数指定要检查的消息数量，而不是要下载的文件数量。例如，`--format pdf --limit 10` 将检查最近的 10 条消息，并下载其中找到的所有 PDF。
## 安全说明
- 避免分享 .env 文件。
- 避免分享 `session_name.session` 文件，因为它包含加密数据，可能被滥用以访问你的账号。
## 常见问题
### 什么是 Telegram Entity？
Telethon 库广泛使用了“entities”的概念。Entity 指的是 API 在响应某些方法（例如 GetUsersRequest）时可能返回的任何 User、Chat 或 Channel 对象。
**了解更多：** [Telethon Entities 文档](https://docs.telethon.dev/en/stable/concepts/entities.html)
### 如何找到私有频道或群组的 ID？
使用 `--list` 命令查看所有可访问的对话框及其 ID：
```
python main.py --list
```
**注意：** 你必须是频道/群组的成员或与用户存在聊天记录才能下载文件。
### 我可以使用 Bot Token 代替手机号码吗？
不可以。Telegram Bot 拥有受限的 API 访问权限，无法使用此脚本所需的方法 (`iter_messages`) 从频道检索消息历史记录。你必须使用用户账号（手机号码认证）才能使此脚本正常工作。
### 支持哪些文件格式？
你可以按类别或特定扩展名进行过滤：
**类别：** `images`、`documents`、`videos`、`audios`、`archives`
**特定扩展名：** `pdf`、`jpg`、`png`、`mp4`、`mp3`、`zip` 等。
## 贡献
如果你有建议或发现问题，请提交 issue 或 pull request。欢迎所有贡献。
标签：BeEF, PDF下载, Python, Telegram, Telethon, 二进制发布, 即时通讯, 图片下载, 媒体过滤, 开源工具, 数字取证, 数据归档, 数据获取, 文件下载, 无后门, 爬虫, 群组管理, 自动化脚本, 视频下载, 资源采集, 逆向工具, 频道监控