TeleGrabber

TeleGrabber 是一个 Telegram 机器人，用于自动保存接收到的图片、视频和 GIF 动画。当你的机器人收到图片、视频、GIF、图册或媒体文件时，它会自动下载并保存这些内容到本地文件系统。

功能特点

• 自动下载并保存 Telegram 消息中的图片、视频和 GIF 动画
• 支持单张图片、单个视频、GIF 动画和多媒体组（相册，包括混合图片和视频）
• 支持作为文件发送的图片
• 自动检测并保存正确的媒体格式（jpg、png、gif、webp、mp4、avi 等）
• 实时状态更新和处理进度提示
• 按照用户名、日期和来源智能组织文件夹
• 智能分类转发来源（频道、群组、机器人和用户）
• 简洁文件名与 CSV 元数据分离，方便管理
• 内置重试机制和代理支持，适应不同网络环境
• 优化的媒体组处理，避免重复消息

项目结构

telegrabber/
│
├── main.py          # 主程序入口
├── bot.py           # 机器人核心功能
├── config.py        # 配置管理
├── utils.py         # 工具函数
├── requirements.txt # 依赖列表
├── env.example      # 环境变量模板
└── README.md        # 项目说明

安装方法

标准安装

1. 克隆此仓库：

git clone https://github.com/yourusername/telegrabber.git
cd telegrabber

2. 安装依赖：

pip install -r requirements.txt

3. 创建配置文件：

# 复制配置模板
cp env.example .env

# 编辑配置文件，填入你的Telegram机器人令牌
nano .env  # 或者使用你喜欢的文本编辑器

Docker 部署

TeleGrabber 也支持使用 Docker 进行部署，这是最简单、最推荐的部署方式：

1. 克隆此仓库：

git clone https://github.com/yourusername/telegrabber.git
cd telegrabber

2. 创建并配置 .env 文件：

# 复制配置模板
cp env.example .env

# 编辑配置文件
nano .env

3. 使用 Docker Compose 启动服务：

docker-compose up -d

4. 查看日志：

docker-compose logs -f

5. 停止服务：

docker-compose down

Docker 部署的优点：

• 无需手动安装 Python 和依赖
• 环境隔离，不会影响系统环境
• 自动重启服务
• 数据持久化存储在宿主机的 downloads 目录

注意：首次部署会自动构建镜像，这可能需要几分钟。下载的媒体文件将保存在宿主机的 downloads 目录中。

如何获取 Telegram 机器人令牌

1. 在 Telegram 中搜索 @BotFather
2. 发送命令 /newbot 并按照提示创建一个新机器人
3. 完成后，BotFather 会提供一个令牌（格式类似 123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ）
4. 将此令牌复制到 .env 文件中的 TELEGRAM_BOT_TOKEN= 后面

网络问题解决方案

如果你在中国大陆或其他网络受限区域，可能无法直接连接到 Telegram API。你可以通过在.env文件中设置代理来解决:

# 使用SOCKS5代理
PROXY_URL=socks5h://127.0.0.1:1080

# 或者使用HTTP代理
# PROXY_URL=http://127.0.0.1:8124

你需要确保已安装代理支持:

pip install pysocks

使用方法

运行机器人：

python main.py

机器人启动后，你可以向它发送以下内容：

• 单张图片：机器人将下载并保存，并回复确认消息
• 单个视频：机器人将下载并保存，并回复确认消息
• GIF 动画：机器人将下载并保存，并回复确认消息
• 多媒体组（相册）：机器人将显示收集状态，然后保存所有图片和视频
• 图片文件：机器人会检查文件类型，只保存图片文件

所有媒体文件将保存在 downloads 目录下（或你在 .env 中指定的其他目录），按照用户名/日期的层级结构组织。

媒体组处理机制

当用户发送多张图片或视频（媒体组/相册）时：

1. 机器人会先发送状态消息：
   • 如果是第一个媒体组，显示"正在收集媒体组内容，请稍候..."
   • 如果已有其他媒体组在处理或排队中，显示"媒体组已加入队列，请稍候..."
2. 系统会在后台收集所有属于同一媒体组的图片和视频（默认等待 2 秒钟）
3. 收集完成后，会在原始状态消息上更新处理进度（例如"正在保存媒体组：1/10"）
4. 所有媒体保存完毕后，会显示完成状态和用时

这种机制确保了：

• 用户界面整洁，不会因每张图片都发送单独消息而造成刷屏
• 用户能够清楚地知道媒体组是立即处理还是已加入队列等待处理
• 用户能够看到实时进度，了解处理状态
• 相册中的所有图片都能被正确识别并保存

配置选项

在.env文件中可设置以下选项：

# 必填：Telegram机器人令牌
TELEGRAM_BOT_TOKEN=your_token_here

# 可选：代理设置（如需要）
PROXY_URL=http://127.0.0.1:8124

# 可选：保存目录（默认为 ./downloads）
SAVE_DIR=./my_images

# 可选：日志级别（默认为 INFO）
LOG_LEVEL=INFO

# 可选：允许使用机器人的用户列表（用逗号分隔的用户名或用户ID）
# 如果设置此项，只有列表中的用户可以使用机器人
# 如果为空或不设置，则允许所有用户使用
ALLOWED_USERS=your_username,123456789

用户访问限制

TeleGrabber 支持限制只有特定用户才能使用机器人的功能，这对于在个人服务器上部署的实例特别有用。

设置方法：

1. 在.env文件中添加ALLOWED_USERS环境变量
2. 填入允许使用的 Telegram 用户名或用户 ID，多个用户用逗号分隔
3. 用户 ID 可以通过与@userinfobot对话获取

示例：

ALLOWED_USERS=john_doe,jane_smith,123456789

行为说明：

• 当非授权用户尝试使用机器人时，会收到访问受限的提示信息
• 提示信息中会包含项目的 GitHub 地址，引导用户部署自己的实例
• 所有授权验证失败的尝试都会在日志中记录

如果ALLOWED_USERS环境变量为空或未设置，机器人将允许所有用户使用。

命令

• /start - 启动机器人并收到欢迎消息
• /help - 获取帮助信息

高级配置

如果你想调整媒体组收集的等待时间（默认为 2 秒），可以在bot.py中修改：

# 修改这个值可以调整收集媒体组的等待时间（秒）
MEDIA_GROUP_COLLECT_TIME = 2

• 增加这个值可以确保在慢速网络下收集完整媒体组
• 减少这个值可以加快处理速度，但可能在某些情况下漏掉图片

文件夹组织结构

TeleGrabber 使用智能的文件夹组织方式保存媒体文件：

downloads/
│
└── 用户名/
    │
    └── 2023-06-15/              # 日期文件夹
        │
        ├── metadata.csv         # 当日所有媒体的元数据
        │
        ├── 频道名称/            # 来自频道的媒体
        │   └── [媒体文件]
        │
        ├── 群组名称/            # 来自群组的媒体
        │   └── [媒体文件]
        │
        ├── 机器人名称/          # 来自机器人的媒体
        │   └── [媒体文件]
        │
        └── users/               # 来自个人用户的媒体
            │
            ├── 用户名1/
            │   └── [媒体文件]
            │
            └── 用户名2/
                └── [媒体文件]

这种组织方式的主要优势：

• 所有用户来源的媒体统一保存在 users 目录下，避免散乱
• 频道、群组、机器人的媒体直接位于日期目录下，便于快速访问
• 元数据 CSV 文件保存在日期目录下，而非用户目录下，避免积累过多文件
• 根据媒体来源类型自动选择最优的保存位置

视频格式支持

TeleGrabber 支持多种常见的视频格式，包括：

• MP4 (.mp4)
• WebM (.webm)
• QuickTime (.mov)
• AVI (.avi)

系统会自动检测视频的实际格式，如果无法确定，将默认使用 .mp4 扩展名。

文件命名规则

TeleGrabber 使用优化的文件命名方案，保持文件名可追踪性，同时保存完整元数据信息：

• 媒体组图片/视频：{完整媒体组ID}_{时间戳}{扩展名} 例如：13991698976443269_1686834561723.jpg 或 .mp4 等
• 单张图片：single_{时间戳}{扩展名} 例如：single_1686834561723.jpg 或 .webp 等
• 单个视频：single_{时间戳}{扩展名} 例如：single_1686834561723.mp4 或 .avi 等
• GIF 动画：single_{时间戳}.gif 例如：single_1686834561723.gif
• 文档类图片：doc_{时间戳}{扩展名} 例如：doc_1686834561723.png 或 .gif 等

时间戳为毫秒级数字格式（13 位数字），如1686834561723，代表精确到毫秒的 UNIX 时间戳，确保在短时间内连续保存的媒体文件也能有唯一文件名。

系统会自动检测每个媒体文件的实际格式，并使用正确的文件扩展名（如 .jpg、.png、.gif、.webp、.mp4、.avi 等）。

支持的媒体类型

TeleGrabber 支持以下类型的媒体：

图片格式

• JPEG (.jpg)
• PNG (.png)
• GIF (静态, .gif)
• WebP (.webp)
• BMP (.bmp)
• 其他常见图片格式

视频格式

• MP4 (.mp4)
• WebM (.webm)
• QuickTime (.mov)
• AVI (.avi)

动画格式

• GIF 动画 (.gif)
• 基于 MP4 的动画 (Telegram 有时将 GIF 作为无声 MP4 发送)

注意：由于 Telegram Bot API 的限制，机器人只能下载 20MB 以下的媒体文件。超过此限制的文件将无法下载并会收到错误提示。

元数据管理

所有媒体文件的详细信息都保存在 CSV 文件中，包括：

• 文件名
• 保存时间
• Telegram 文件 ID
• Telegram 文件唯一 ID
• 媒体组 ID (如适用)
• 媒体类型 (photo、video 或 animation)
• 来源名称 (频道名、用户名等)
• 来源 ID (频道 ID、用户 ID 等)
• 来源链接 (t.me 格式的链接)
• 来源类型 (channel、group、bot、user、private_user 等)

CSV 文件名为 metadata.csv，存储在对应日期的目录下：{用户名}/{日期}/metadata.csv

这种设计有以下优势：

• 保存完整的追踪信息
• 每日单独的 CSV 文件，便于查询和管理
• 支持按来源类型筛选和组织媒体
• 保存可点击的来源链接，方便回溯原始内容
• 可以根据来源 ID 和链接确定精确的媒体来源

许可证

本项目采用 MIT 许可证。详细信息请参阅 LICENSE 文件。