初始化 telegram-downloader 并接入群晖 CI/CD

2026-04-22 21:29:03 +08:00
commit cf40343c51
153 changed files with 33376 additions and 0 deletions
@@ -0,0 +1,339 @@
+# Telegram Media Downloader 配置指南
+
+> 本文档记录了在 macOS 上配置和运行 Telegram Media Downloader 的完整步骤。
+
+---
+
+## 目录
+
+- [环境要求](#环境要求)
+- [快速启动](#快速启动)
+- [详细配置步骤](#详细配置步骤)
+  - [1. 安装依赖](#1-安装依赖)
+  - [2. 获取 Telegram API 密钥](#2-获取-telegram-api-密钥)
+  - [3. 配置代理](#3-配置代理)
+  - [4. 修改 Web 端口](#4-修改-web-端口)
+  - [5. 首次登录认证](#5-首次登录认证)
+  - [6. 配置下载任务](#6-配置下载任务)
+  - [7. 配置 Bot（持续运行）](#7-配置-bot持续运行)
+- [配置文件说明](#配置文件说明)
+- [常用命令](#常用命令)
+- [常见问题](#常见问题)
+- [我的配置信息](#我的配置信息)
+
+---
+
+## 环境要求
+
+- **操作系统**: macOS / Linux / Windows
+- **Python**: 3.7 及以上
+- **代理软件**: Clash / V2Ray 等（国内必需）
+- **Telegram 账号**: 需要能正常登录
+
+---
+
+## 快速启动
+
+如果已经配置好，直接运行：
+
+```bash
+cd /Users/gaotu/WebstormProjects/telegram_media_downloader-master
+python3 media_downloader.py
+```
+
+访问 Web 界面：
+- **下载进度**: http://localhost:5001
+- **控制台**: http://localhost:5001/control
+
+---
+
+## 详细配置步骤
+
+### 1. 安装依赖
+
+```bash
+# 进入项目目录
+cd /Users/gaotu/WebstormProjects/telegram_media_downloader-master
+
+# 安装依赖（macOS/Linux）
+make install
+
+# 或者直接用 pip（Windows）
+pip3 install -r requirements.txt
+```
+
+### 2. 获取 Telegram API 密钥
+
+1. 访问 https://my.telegram.org/apps
+2. 使用 Telegram 账号登录,登录时需要注意，验证码不是发短信，是发送到软件里，需要到软件中的服务号查收。
+3. 填写表单创建新应用（Platform 选 Desktop）
+4. 获取 `api_id` 和 `api_hash`
+
+> ⚠️ 注意：如果提示 "too many tries"，需要等待 1-2 小时再试。
+
+### 3. 配置代理
+
+由于国内无法直连 Telegram，需要配置代理。
+
+编辑 `config.yaml`，添加代理配置：
+
+```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 端口，需要修改：
+
+```yaml
+web_host: 127.0.0.1
+web_port: 5001    # 改为其他端口
+```
+
+### 5. 首次登录认证
+
+运行程序：
+
+```bash
+python3 media_downloader.py
+```
+
+首次运行会要求输入：
+
+1. **手机号**：输入 Telegram 注册手机号（带国际区号，如 `+8615064240820`）
+2. **确认**：输入 `y` 确认
+3. **验证码**：查看 Telegram 客户端收到的验证码，输入
+
+登录成功后会生成 `media_downloader.session` 文件，后续无需重复登录。
+
+### 6. 配置下载任务
+
+编辑 `config.yaml` 中的 `chat` 部分：
+
+```yaml
+chat:
+- chat_id: happycat03              # 频道用户名或 ID
+  last_read_message_id: 0          # 从头开始下载设为 0
+  download_filter: message_date >= 2024-01-01 00:00:00  # 时间过滤
+```
+
+**获取频道 ID 的方法**：
+
+1. **使用用户名**：直接填写 `@` 后面的部分，如 `happycat03`
+2. **使用机器人**：发送频道链接给 [@username_to_id_bot](https://t.me/username_to_id_bot)
+3. **Web Telegram**：从 URL 中获取
+
+**时间过滤器示例**：
+
+```yaml
+# 下载 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**：
+
+1. 在 Telegram 中打开 [@BotFather](https://t.me/BotFather)
+2. 发送 `/newbot`
+3. 按提示设置名称和用户名（用户名必须以 `bot` 结尾）
+4. 获取 Bot Token
+
+**添加到配置**：
+
+```yaml
+bot_token: 你的Bot_Token
+```
+
+配置后：
+- 程序会持续运行
+- 可以通过机器人发送命令下载
+- Web 界面可以一直访问
+
+---
+
+## 配置文件说明
+
+完整的 `config.yaml` 示例：
+
+```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 英文
+```
+
+---
+
+## 常用命令
+
+```bash
+# 启动下载程序
+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）
+
+**原因**：代理未配置或代理软件未运行
+
+**解决**：
+1. 确保 Clash/V2Ray 正在运行
+2. 检查 `config.yaml` 中的代理端口是否正确
+
+### Q2: 端口 5000 被占用
+
+**原因**：macOS AirPlay Receiver 占用
+
+**解决**：修改 `web_port` 为其他端口（如 5001）
+
+### Q3: 程序下载完就退出
+
+**原因**：未配置 Bot Token
+
+**解决**：创建 Telegram Bot 并配置 `bot_token`
+
+### Q4: 大文件下载失败（Request timed out）
+
+**原因**：网络不稳定，大文件容易超时
+
+**解决**：
+1. 重新运行程序，会自动重试失败的文件
+2. 更换更稳定的代理节点
+
+### Q5: API 密钥申请被限制
+
+**原因**：尝试次数过多
+
+**解决**：等待 1-2 小时后重试，或更换网络/IP
+
+---
+
+## 我的配置信息
+
+> ⚠️ 以下是我的个人配置，请勿泄露给他人
+
+| 配置项 | 值 |
+|--------|-----|
+| api_id | `35804872` |
+| api_hash | `79872da654ba47a407ff758df43b342b` |
+| bot_token | `8304994550:AAHrfD8iZy-g7eMvd5j_nUCWAVzkfpn-STk` |
+| Bot 用户名 | [@ymxixibot](https://t.me/ymxixibot) |
+| 代理端口 | `7891`（Clash SOCKS5） |
+| Web 端口 | `5001` |
+| 保存路径 | `/Users/gaotu/Downloads/telegram_downloads` |
+
+---
+
+## Web 界面说明
+
+### 下载进度页面
+
+地址：http://localhost:5001
+
+- 查看正在下载的文件
+- 查看已完成的下载
+- 暂停/继续下载
+
+### 控制台页面（自定义）
+
+地址：http://localhost:5001/control
+
+- 输入频道链接
+- 设置下载时间范围
+- 查看当前配置
+- 查看下载状态
+
+---
+
+## 更新日志
+
+- **2026-01-10**: 初次配置，成功下载 184 个无损音乐文件
+- **2026-01-10**: 配置 Bot Token，实现程序持续运行
+- **2026-01-10**: 添加自定义 Web 控制台页面
+
+---
+
+*文档创建于 2026-01-10*