yuming
7.3 KiB
7.3 KiB
Telegram Media Downloader 配置指南
本文档记录了在 macOS 上配置和运行 Telegram Media Downloader 的完整步骤。
目录
环境要求
- 操作系统: macOS / Linux / Windows
- Python: 3.7 及以上
- 代理软件: Clash / V2Ray 等（国内必需）
- Telegram 账号: 需要能正常登录
快速启动
如果已经配置好，直接运行：
cd /Users/gaotu/WebstormProjects/telegram_media_downloader-master
python3 media_downloader.py
访问 Web 界面：
详细配置步骤
1. 安装依赖
# 进入项目目录
cd /Users/gaotu/WebstormProjects/telegram_media_downloader-master
# 安装依赖（macOS/Linux）
make install
# 或者直接用 pip（Windows）
pip3 install -r requirements.txt
2. 获取 Telegram API 密钥
- 访问 https://my.telegram.org/apps
- 使用 Telegram 账号登录,登录时需要注意，验证码不是发短信，是发送到软件里，需要到软件中的服务号查收。
- 填写表单创建新应用（Platform 选 Desktop）
- 获取
api_id和api_hash
⚠️ 注意：如果提示 "too many tries"，需要等待 1-2 小时再试。
3. 配置代理
由于国内无法直连 Telegram，需要配置代理。
编辑 config.yaml，添加代理配置：
# Clash 代理配置
proxy:
scheme: socks5
hostname: 127.0.0.1
port: 7891 # Clash SOCKS5 端口，根据实际情况修改
常见代理端口：
| 代理软件 | HTTP 端口 | SOCKS5 端口 |
|---|---|---|
| Clash | 7890 | 7891 |
| V2Ray | 10809 | 10808 |
| Shadowsocks | - | 1080 |
4. 修改 Web 端口
macOS 的 AirPlay Receiver 默认占用 5000 端口，需要修改：
web_host: 127.0.0.1
web_port: 5001 # 改为其他端口
5. 首次登录认证
运行程序：
python3 media_downloader.py
首次运行会要求输入：
- 手机号：输入 Telegram 注册手机号（带国际区号，如
+8615064240820） - 确认：输入
y确认 - 验证码：查看 Telegram 客户端收到的验证码，输入
登录成功后会生成 media_downloader.session 文件，后续无需重复登录。
6. 配置下载任务
编辑 config.yaml 中的 chat 部分：
chat:
- chat_id: happycat03 # 频道用户名或 ID
last_read_message_id: 0 # 从头开始下载设为 0
download_filter: message_date >= 2024-01-01 00:00:00 # 时间过滤
获取频道 ID 的方法：
- 使用用户名：直接填写
@后面的部分，如happycat03 - 使用机器人：发送频道链接给 @username_to_id_bot
- Web Telegram：从 URL 中获取
时间过滤器示例：
# 下载 2024 年以后的
download_filter: message_date >= 2024-01-01 00:00:00
# 下载指定时间段
download_filter: message_date >= 2024-01-01 00:00:00 and message_date <= 2024-06-30 23:59:59
# 不设置过滤器（下载全部）
# 删除 download_filter 行即可
7. 配置 Bot（持续运行）
默认情况下，程序下载完成后会自动退出。配置 Bot 后程序会持续运行。
创建 Bot：
- 在 Telegram 中打开 @BotFather
- 发送
/newbot - 按提示设置名称和用户名（用户名必须以
bot结尾） - 获取 Bot Token
添加到配置：
bot_token: 你的Bot_Token
配置后：
- 程序会持续运行
- 可以通过机器人发送命令下载
- Web 界面可以一直访问
配置文件说明
完整的 config.yaml 示例：
# Telegram API 密钥
api_hash: your_api_hash
api_id: your_api_id
# Bot Token（可选，配置后程序持续运行）
bot_token: your_bot_token
# 下载任务配置
chat:
- chat_id: channel_username # 频道用户名或 ID
last_read_message_id: 0 # 上次读取位置，0 表示从头开始
download_filter: message_date >= 2024-01-01 00:00:00 # 时间过滤
# 下载的媒体类型
media_types:
- audio
- photo
- video
- document
- voice
- video_note
# 文件格式过滤
file_formats:
audio:
- all
document:
- all
video:
- all
# 保存路径
save_path: /Users/gaotu/Downloads/telegram_downloads
# 文件路径前缀（子目录结构）
file_path_prefix:
- chat_title # 频道名称
- media_datetime # 媒体日期
# Web 界面配置
web_host: 127.0.0.1
web_port: 5001
# 代理配置
proxy:
scheme: socks5
hostname: 127.0.0.1
port: 7891
# 语言
language: ZH # ZH 中文, EN 英文
常用命令
# 启动下载程序
python3 media_downloader.py
# 停止程序
Ctrl + C
# 后台运行（可选）
nohup python3 media_downloader.py > download.log 2>&1 &
# 查看后台进程
ps aux | grep media_downloader
# 停止后台进程
pkill -f media_downloader
常见问题
Q1: 连接超时（Connection timed out）
原因：代理未配置或代理软件未运行
解决：
- 确保 Clash/V2Ray 正在运行
- 检查
config.yaml中的代理端口是否正确
Q2: 端口 5000 被占用
原因：macOS AirPlay Receiver 占用
解决：修改 web_port 为其他端口（如 5001）
Q3: 程序下载完就退出
原因：未配置 Bot Token
解决：创建 Telegram Bot 并配置 bot_token
Q4: 大文件下载失败（Request timed out）
原因：网络不稳定，大文件容易超时
解决：
- 重新运行程序，会自动重试失败的文件
- 更换更稳定的代理节点
Q5: API 密钥申请被限制
原因：尝试次数过多
解决：等待 1-2 小时后重试，或更换网络/IP
我的配置信息
⚠️ 以下是我的个人配置，请勿泄露给他人
| 配置项 | 值 |
|---|---|
| api_id | 35804872 |
| api_hash | 79872da654ba47a407ff758df43b342b |
| bot_token | 8304994550:AAHrfD8iZy-g7eMvd5j_nUCWAVzkfpn-STk |
| Bot 用户名 | @ymxixibot |
| 代理端口 | 7891（Clash SOCKS5） |
| Web 端口 | 5001 |
| 保存路径 | /Users/gaotu/Downloads/telegram_downloads |
Web 界面说明
下载进度页面
- 查看正在下载的文件
- 查看已完成的下载
- 暂停/继续下载
控制台页面（自定义）
地址：http://localhost:5001/control
- 输入频道链接
- 设置下载时间范围
- 查看当前配置
- 查看下载状态
更新日志
- 2026-01-10: 初次配置，成功下载 184 个无损音乐文件
- 2026-01-10: 配置 Bot Token，实现程序持续运行
- 2026-01-10: 添加自定义 Web 控制台页面
文档创建于 2026-01-10