TeleGrabber 是一个 Telegram 机器人，用于自动保存接收到的图片、视频和 GIF 动画。当你的机器人收到图片、视频、GIF、图册或媒体文件时，它会自动下载并保存这些内容到本地文件系统。
- 自动下载并保存 Telegram 消息中的图片、视频和 GIF 动画
- 混合下载模式：默认使用标准 Bot API (仅限 20MB 以内)，配置 User API 后自动解锁大文件下载能力，彻底绕过 20MB 限制
- SQLite 数据库：持久化存储所有媒体元数据，支持全局去重与跨会话追踪
- 极速并发：小文件 (<20MB) 多线程并发下载，大文件使用串行接力
- 自动检测并保存正确的媒体格式（jpg、png、gif、webp、mp4、avi 等）
- 实时状态更新：进度条精确到百分比 (⬇️85%)
- 智能去重与安全删除：自动跳过库中已存在的资源；“删除”操作仅撤销本次下载，绝不触及历史存量数据
- Web 管理后台：内置基于 FastAPI 的可视化管理终端，支持大图/视频预览、媒体组聚合展示与远程一键删除
- 统一存储库 (Unified Library)：取消复杂的日期分层，防止散乱，方便管理和搜索
- 内置重试机制和代理支持，适应不同网络环境
telegrabber/
│
├── main.py # 主程序入口
├── bot.py # 机器人核心功能
├── user_api.py # MTProto (User API) 下载引擎
├── web_backend.py # Web 后端服务 (FastAPI)
├── static/ # Web 前端静态资源 (HTML/CSS/JS)
├── config.py # 配置管理
├── utils.py # 数据库与工具函数
├── requirements.txt # 依赖列表
├── env.example # 环境变量模板
├── telegrabber.db # SQLite 数据库 (自动生成)
└── downloads/ # 媒体文件保存目录
- 克隆此仓库：
git clone https://github.com/yourusername/telegrabber.git
cd telegrabber- 安装依赖：
pip install -r requirements.txt- 创建配置文件：
# 复制配置模板
cp env.example .env
# 编辑配置文件，填入你的Telegram机器人令牌
nano .env # 或者使用你喜欢的文本编辑器TeleGrabber 也支持使用 Docker 进行部署，这是最简单、最推荐的部署方式：
- 克隆此仓库：
git clone https://github.com/yourusername/telegrabber.git
cd telegrabber- 创建并配置 .env 文件：
# 复制配置模板
cp env.example .env
# 编辑配置文件
nano .env- 使用 Docker Compose 启动服务：
docker-compose up -d- 查看日志：
docker-compose logs -f- 停止服务：
docker-compose downDocker 部署的优点：
- 无需手动安装 Python 和依赖
- 环境隔离，不会影响系统环境
- 自动重启服务
- 数据持久化存储在宿主机的 downloads 目录
注意：首次部署会自动构建镜像，这可能需要几分钟。下载的媒体文件将保存在宿主机的 downloads 目录中。
- 在 Telegram 中搜索 @BotFather
- 发送命令
/newbot并按照提示创建一个新机器人 - 完成后，BotFather 会提供一个令牌（格式类似
123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ） - 将此令牌复制到
.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 中指定的其他目录），按照用户名/日期的层级结构组织。
当用户发送多张图片或视频（媒体组/相册）时：
- 机器人会先发送状态消息：
- 如果是第一个媒体组，显示"正在收集媒体组内容，请稍候..."
- 如果已有其他媒体组在处理或排队中，显示"媒体组已加入队列，请稍候..."
- 系统会在后台收集所有属于同一媒体组的图片和视频（默认等待 2 秒钟）
- 收集完成后，会在原始状态消息上更新处理进度（例如"正在保存媒体组：1/10"）
- 所有媒体保存完毕后，会显示完成状态和用时
这种机制确保了：
- 用户界面整洁，不会因每张图片都发送单独消息而造成刷屏
- 用户能够清楚地知道媒体组是立即处理还是已加入队列等待处理
- 用户能够看到实时进度，了解处理状态
- 相册中的所有图片都能被正确识别并保存
在通过机器人下载媒体组（相册）时，TeleGrabber 提供了一套便捷的交互按钮，方便您对任务进行即时控制：
- ♻️ 重新下载本次：安全重试模式。仅清理并重新下载本次任务产生的新文件，不会影响库中已存在的重复资源。
- 🔥 强制重下全部：全量强制模式。彻底从数据库和磁盘中抹除该媒体组的所有历史记录（含存量重复项），然后进行真正的全量重新下载。
- ❌ 重试失败项：如果下载过程中部分文件因网络原因报错，点击此按钮将仅重试那些失败的项目。
- 🔄 刷新状态：实时同步最新的处理进度，支持在删除后通过按钮快速恢复下载。
- 🗑️ 删除本次内容：一键撤销。仅从本地磁盘和数据库中移除本次下载的物理文件和元数据，确保存量数据的安全性。
TeleGrabber 现在自带一个功能强大的 Web 管理终端，随机器人同步启动。
- Premium UI：现代深色系毛玻璃设计，支持自适应布局，自带专属 Robot Favicon 图标。
- 媒体组聚合：自动按
media_group_id进行分组展示，并提取代表性标题。 - 智能排序：组内媒体按文件名自然排序（1, 2, ..., 10），符合人类预览习惯。
- 播放与删除：直接在浏览器内预览图片、播放视频（支持强效停音逻辑），一键同步删除磁盘文件及数据库记录。
- 一键追溯：预览页提供原始 Telegram 来源链接，支持一键跳转回原始频道/聊天。
默认访问地址：http://localhost:5000 (或服务器 IP:5000)
如需修改 Web 服务端口，可以在 .env 文件中设置：
WEB_PORT=5000 # 默认 5000在.env文件中可设置以下选项：
# 必填：Telegram 机器人令牌
TELEGRAM_BOT_TOKEN=your_token_here
# 选填：MTProto (User API) 凭据 (用于下载 > 20MB 文件)
# 获取地址：https://my.telegram.org
API_ID=your_api_id
API_HASH=your_api_hash
# 可选：代理设置
PROXY_URL=http://127.0.0.1:8123
# 可选：保存目录（默认为 ./downloads）
SAVE_DIR=./downloads
# 可选：允许使用机器人的用户列表
ALLOWED_USERS=your_username,123456789
TeleGrabber 支持限制只有特定用户才能使用机器人的功能，这对于在个人服务器上部署的实例特别有用。
- 在
.env文件中添加ALLOWED_USERS环境变量 - 填入允许使用的 Telegram 用户名或用户 ID，多个用户用逗号分隔
- 用户 ID 可以通过与@userinfobot对话获取
示例：
ALLOWED_USERS=john_doe,jane_smith,123456789
- 当非授权用户尝试使用机器人时，会收到访问受限的提示信息
- 提示信息中会包含项目的 GitHub 地址，引导用户部署自己的实例
- 所有授权验证失败的尝试都会在日志中记录
如果ALLOWED_USERS环境变量为空或未设置，机器人将允许所有用户使用。
/start- 启动机器人并收到欢迎消息/help- 获取帮助信息
如果你想调整媒体组收集的等待时间（默认为 2 秒），可以在bot.py中修改：
# 修改这个值可以调整收集媒体组的等待时间（秒）
MEDIA_GROUP_COLLECT_TIME = 2- 增加这个值可以确保在慢速网络下收集完整媒体组
- 减少这个值可以加快处理速度，但可能在某些情况下漏掉图片
TeleGrabber 使用智能的文件夹组织方式保存媒体文件：
downloads/
│
├── telegrabber.db # 全局统一数据库 (记录所有已下载项)
│
├── 频道名称/ # 来自频道的媒体 (自动去重)
│ ├── metadata.csv # 来源特定的元数据备份
│ └── [媒体文件]
│
├── 群组名称/ # 来自群组的媒体
│ ├── metadata.csv
│ └── [媒体文件]
│
└── users/ # 来自个人或私聊的媒体
└── 用户名/
├── metadata.csv
└── [媒体文件]
这种组织方式的主要优势：
- 所有用户来源的媒体统一保存在
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 发送)
重要提示：
- 小文件 (<20MB)：通过标准 Bot API 下载，速度极快且无需额外配置。
- 大文件 (>=20MB)：系统自动切换至 MTProto (User API) 协议。
- 初次启动：若配置了
API_ID，首次运行需要在终端输入手机号和验证码以完成登录。登录后的 session 文件将加密存储在本地。
所有媒体文件的详细信息都保存在 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 文件。