🚀 Telegram Downloader 部署教程

使用 Docker 部署 Telegram 文件下载机器人，支持将 Telegram 文件保存到 NAS 或 Linux 服务器。

📋 目录

✨ 功能简介

Telegram Downloader 是一个基于 Docker 的 Telegram 机器人，可以将 Telegram 中的文件自动下载到 NAS 或 Linux 服务器。

主要功能：

功能 说明
📥 自动下载 支持视频、图片、文档等所有格式
📦 大文件支持 支持下载较大的 Telegram 文件
⚡ 并发下载 支持多文件同时下载
📁 自动保存 按原文件名保存到指定目录
🔧 易于部署 使用 Docker 快速部署

🔧 前期准备

系统要求

  • ✅ NAS 或 Linux 服务器
  • ✅ 已安装 Docker 和 Docker Compose
  • ✅ 足够的磁盘空间

检查 Docker 环境

1
2
3
4
5
# 检查 Docker 版本
docker --version

# 检查 Docker Compose 版本
docker compose version

🔑 获取配置信息

在部署之前，你需要获取以下 4 个关键信息：

1️⃣ 获取 API_ID 和 API_HASH

步骤：

  1. 访问 https://my.telegram.org/apps
  2. 输入你的 Telegram 手机号（带国家代码，如 +8613800138000）
  3. 输入收到的验证码登录
  4. 点击 Create New Application
  5. 填写应用信息：
  • App title：Telegram Downloader
  • Short name：telegram_downloader
  • Platform：选择任意
  1. 点击 Create Application
  2. 复制并保存以下信息：
  • api_id（数字，如：555343476）
  • api_hash（32 位字符串，如：555806aa32934346aade8556bdf3cc）

⚠️ 重要提示：

配置项 格式 示例
API_ID 纯数字 55534776
API_HASH 32 位字母数字 555806aa3434aade8556bdf3cc

2️⃣ 创建 Telegram Bot 并获取 BOT_TOKEN

步骤：

  1. 在 Telegram 中搜索 @BotFather
  2. 点击进入对话，发送 /start
  3. 创建新机器人，发送 /newbot
  4. 按提示设置机器人名称（如：Telegram Downloader Bot）
  5. 设置机器人用户名（必须以 bot 结尾，如：tg_downloader_bot）
  6. BotFather 会返回类似这样的信息：
1
2
3
4
5
6
Done! Congratulations on your new bot.

Please use this token to access the HTTP API:
554321098:AAHxvsE-55a29l34347xyz-55CD1234EFGH

Keep your token secure and store it safely.
  1. 复制并保存 BOT_TOKEN

⚠️ 重要提示：

  • ✅ 正确格式：5554321098:AAHxvsE-q834344F（英文冒号）
  • ❌ 错误格式：55521098：AAHxvsE-q8Fa23434O4F（中文冒号）

验证 Token 是否有效：

注意：BOT_TOKEN 属于敏感信息。只建议在可信设备和网络环境中验证，验证后不要将链接截图或分享给他人。

在浏览器中访问：

1
https://api.telegram.org/bot<TOKEN>/getMe

返回 ok: true 即为有效。

3️⃣ 获取你的 Telegram 用户 ID

方法 1：使用 @userinfobot

  1. 在 Telegram 中搜索 @userinfobot
  2. 发送 /start
  3. Bot 会回复你的信息，包括 Id（数字）

方法 2：使用 @myidbot

  1. 在 Telegram 中搜索 @myidbot
  2. 发送 /start
  3. Bot 会回复你的 Your User ID

示例： 555505234986

🚀 快速部署

步骤 1：创建项目目录

1
2
3
4
5
# 创建项目目录
mkdir -p /app/data/files

# 进入目录
cd /app/data/files

步骤 2：创建 docker-compose.yml 文件

创建文件 docker-compose.yml，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
version: '3.8'

services:
  telegram-downloader:
    image: jsavargas/telegram-downloader:latest
    container_name: telegram-downloader
    restart: unless-stopped

    # 环境变量配置
    environment:
      # ============ 必填项 ============
      # Telegram API 凭证
      - API_ID=你的API_ID
      - API_HASH=你的API_HASH

      # 机器人 Token（冒号必须是英文冒号）
      - BOT_TOKEN=你的Bot_Token

      # 授权用户 ID
      - AUTHORIZED_USER_ID=你的用户ID

      # ============ 可选项 ============
      # 时区设置
      - TZ=Asia/Shanghai

      # 最大并发下载数（1-4，推荐 3）
      - MAX_CONCURRENT_TASKS=3

      # 文件权限（适配 NAS 用户，通常为 1000）
      - PUID=1000
      - PGID=1000

    # 存储卷映射
    volumes:
      # 配置文件存储
      - ./config:/config

      # 下载文件存储（核心目录）
      - ./downloads:/download

      # 监控目录（用于 torrent 等自动处理）
      - ./watch:/watch

    # 网络配置（不需要端口映射）
    ports: []

    # 资源限制（可选）
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M

替换占位符：

占位符 替换为 示例
你的API_ID API_ID 55522776
你的API_HASH API_HASH 555806aa3293434aade8556bdf3cc
你的Bot_Token BOT_TOKEN 5554341098:A3434q8Fa29lL4O4F
你的用户ID 用户 ID 555543434986

步骤 3：创建必要的目录

1
2
3
4
5
6
7
8
# 创建配置目录
mkdir -p config

# 创建下载目录
mkdir -p downloads

# 创建监控目录
mkdir -p watch

步骤 4：启动容器

1
2
3
4
5
# 启动容器
docker compose up -d

# 查看容器状态
docker ps | grep telegram-downloader

步骤 5：查看启动日志

1
2
# 查看容器日志
docker logs -f telegram-downloader

✅ 成功启动的日志示例：

1
2
3
4
Starting Telegram Downloader Bot...
Bot is ready!
Authorized user ID: 55505234986
Waiting for messages...

❌ 如果出现错误：

错误信息 解决方法
ApiIdInvalid API_ID 或 API_HASH 错误，重新获取
AccessTokenInvalid BOT_TOKEN 错误，检查格式（是否为英文冒号）

✅ 验证部署

1. 验证容器状态

1
docker ps | grep telegram-downloader

预期输出：

1
abc123def456  jsavargas/telegram-downloader:latest  "python3 /app/downloa…"  10 seconds ago  Up 5 seconds  telegram-downloader

2. 验证挂载点

1
docker inspect telegram-downloader --format='{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'

预期输出：

1
2
3
/app/data/files/config -> /config
/app/data/files/downloads -> /download
/app/data/files/watch -> /watch

3. 在 Telegram 中测试机器人

  1. 在 Telegram 中找到你创建的机器人
  2. 向机器人发送 /start
  3. 机器人应该回复欢迎信息

4. 测试下载功能

  1. 在 Telegram 中向机器人发送一个下载链接
  2. 或转发一个文件给机器人
  3. 等待下载完成

5. 检查下载文件

1
2
3
4
5
# 进入下载目录
cd /app/data/files/downloads

# 查看下载的文件
ls -lh

📖 使用指南

基本使用

向机器人发送消息：

  • 发送 Telegram 消息链接 → 自动下载
  • 发送 Telegram 文件 → 自动保存
  • 发送 Telegram 视频链接 → 自动下载

支持的文件格式：

类型 格式示例
🎬 视频 MP4, AVI, MKV 等
🖼️ 图片 JPG, PNG, GIF 等
📄 文档 PDF, DOC, XLS 等
📦 压缩包 ZIP, RAR 等
🎵 音频 MP3, FLAC 等

下载文件位置

路径类型 路径
NAS 实际路径 /app/data/files/downloads
容器内路径 /download

查看下载进度

方法 1：查看容器日志

1
docker logs -f telegram-downloader

方法 2：进入容器查看

1
2
3
4
5
6
7
8
# 进入容器
docker exec -it telegram-downloader sh

# 查看下载目录
ls -lh /download

# 退出容器
exit

管理下载文件

1
2
3
4
5
6
7
8
# 查看文件列表
ls -lh /app/data/files/downloads

# 查看文件大小
du -sh /app/data/files/downloads

# 查找最新下载的文件
ls -lt /app/data/files/downloads | head -10

🛠️ 常见问题

问题 1：容器无法启动

错误信息：

1
Conflict. The container name "/telegram-downloader" is already in use

解决方案：

1
2
3
4
docker stop telegram-downloader
docker rm telegram-downloader
docker network rm tgbot_default 2>/dev/null || true
docker compose up -d

问题 2：API_ID 或 API_HASH 无效

错误信息：

1
ApiIdInvalid: The api_id/api_hash combination is invalid

解决方案：

  1. 重新获取 API_ID 和 API_HASH
  2. 确认复制完整且正确
  3. 更新 docker-compose.yml
  4. 重启容器：
    1
    2
    docker compose down
    docker compose up -d

问题 3：BOT_TOKEN 无效

错误信息：

1
AccessTokenInvalid: The bot access token is invalid

解决方案：

检查项 正确 错误
冒号类型 : (英文) ： (中文)
格式 数字:字母 其他格式
  1. 重新从 @BotFather 获取 Token
  2. 确认冒号是英文冒号 :
  3. 验证 Token：
    1
    https://api.telegram.org/bot<TOKEN>/getMe
  4. 更新 docker-compose.yml
  5. 重启容器

问题 4：机器人不响应消息

排查步骤：

1
2
3
4
5
6
7
8
9
10
# 1. 检查容器状态
docker ps | grep telegram-downloader

# 2. 查看容器日志
docker logs -f telegram-downloader

# 3. 验证配置
docker exec telegram-downloader cat /config/config.py

# 4. 确认授权用户 ID 是否正确

问题 5：路径重复问题

错误信息：

1
本地路径：/vol1/1000/tg_bigfile_bot/vol1/1000/tg_bigfile_bot/downloads...

解决方案：

1
2
3
4
5
cd /app/data/files
docker stop telegram-downloader
docker rm telegram-downloader
docker network rm tgbot_default 2>/dev/null || true
docker compose up -d

⚙️ 高级配置

修改下载目录

编辑 docker-compose.yml：

1
2
volumes:
  - /你的新路径:/download

例如：

1
2
volumes:
  - /vol1/1000/MyDownloads:/download

重启容器：

1
2
docker compose down
docker compose up -d

多用户配置

修改 AUTHORIZED_USER_ID：

1
- AUTHORIZED_USER_ID=5534986,1255567890,955543210

多个用户 ID 使用英文逗号分隔。

调整并发下载数

修改 MAX_CONCURRENT_TASKS：

值 适用场景
1-2 网络较慢
3 默认值，适合大多数情况
4 网络较快 
1
- MAX_CONCURRENT_TASKS=3

修改文件权限

根据你的 NAS 用户 ID 设置：

1
2
- PUID=1000
- PGID=1000

📝 维护命令

常用命令速查表

操作 命令
启动容器 docker compose up -d
停止容器 docker compose stop
重启容器 docker compose restart
查看日志 docker logs -f telegram-downloader
进入容器 docker exec -it telegram-downloader sh
删除容器 docker compose down
更新镜像 docker compose pull && docker compose up -d

📊 配置总结

关键配置一览

配置项 说明 示例
API_ID Telegram API ID 5552776
API_HASH Telegram API Hash 555a806aa32910a806aade8556bdf3cc
BOT_TOKEN Bot Token 555521098:AAHxvsE-q8Fa29lL4O4F
AUTHORIZED_USER_ID 授权用户 ID 555234986
TZ 时区 Asia/Shanghai
MAX_CONCURRENT_TASKS 最大并发下载数 3
PUID/PGID 文件权限 1000/1000

文件/目录结构

1
2
3
4
5
/app/data/files/
├── docker-compose.yml          # 容器配置文件
├── config/                     # 机器人配置
├── downloads/                  # 下载文件存储 ⭐
└── watch/                      # Torrent 监控

💡 提示与注意事项

✅ 最佳实践

  1. 定期清理下载目录，避免磁盘空间不足。
  2. 设置合理的并发数，避免网络拥堵。
  3. 定期查看日志，及时发现异常。
  4. 备份配置文件，便于后续迁移。

⚠️ 注意事项

  1. 妥善保管 API 凭证，不要泄露。
  2. BOT_TOKEN 是敏感信息，不要提交到公开仓库或分享给他人。
  3. 确保磁盘空间充足，避免下载失败。
  4. 定期更新镜像，获取最新功能和修复。

🎉 结语

至此，Telegram Downloader 已经部署完成。

现在你可以：

  • ✅ 通过 Telegram 下载文件
  • ✅ 在 NAS 上管理下载的文件
  • ✅ 自动化文件下载和管理

祝你使用愉快！

如有问题，欢迎在评论区交流！

📌 相关链接