telegram-downloader/MY_SETUP_GUIDE.md

# 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*