telegram_media_downloader 部署教程

摘要：记录一下telegram_media_downloader部署教程，一个非常好用的下载飞机文件的工具。

一、准备工作

获取 api_id 和 api_hash

打开 my.telegram.org/apps，使用 Telegram 账号登录；
按页面提示创建应用；
记录生成的 api_id（数字）和 api_hash。

创建 Telegram 机器人

在 Telegram 中打开 @BotFather；
发送 /newbot，按提示设置机器人名称和用户名；
保存生成的 bot_token。

二、安装程序

cd /tg_download
git clone https://github.com/tangyoha/telegram_media_downloader.git
cd telegram_media_downloader
apt install -y python3-venv
python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt

三、修改配置文件

修改配置文件如下（将你的api_id、你的api_hash、你的bot_token、你的文件保存目录、你的web界面密码替换成你自己的配置）：

api_id: 你的api_id
api_hash: "你的api_hash"
bot_token: "你的bot_token"

# 不自动扫描任何频道，只处理转发或机器人命令
chat: []

# 下载所有支持的媒体
media_types:
  - audio
  - document
  - photo
  - video
  - voice
  - video_note
  - animation

file_formats:
  audio:
    - all
  document:
    - all
  video:
    - all

# 最终下载目录，使用绝对路径
save_path: /filedownload

# 按频道名称、年月分类
file_path_prefix:
  - chat_title
  - media_datetime

date_format: '%Y_%m'

# 文件名：消息 ID + 原始文件名
file_name_prefix:
  - message_id
  - file_name

file_name_prefix_split: ' - '

# 下载并发
max_download_task: 2

# Web 管理界面：仅监听本机，避免直接暴露到公网
web_host: 127.0.0.1
web_port: 5000
web_login_secret: "你的web界面密码"

# 仅允许登录账号操作机器人
# 留空时，已登录的 Telegram 账号仍可以操作机器人
allowed_user_ids: []

language: ZH

hide_file_name: false
enable_download_txt: false

# 不启用网盘上传
upload_drive:
  enable_upload_file: false

四、首次运行并登录 Telegram

这一步需要先在前台完成，不能直接跳到 systemd 后台启动。 首次运行通常要输入手机号（手机号要加国际代码，比如中国号码前面+86）、Telegram 验证码；如果启用了两步验证，还可能需要输入密码。

cd /tg_download/telegram_media_downloader
source .venv/bin/activate
# 注意如果运行后命令行卡死，可以考虑换个ssh工具
python media_downloader.py

按终端提示完成登录，确认程序能够正常启动后，按 Ctrl+C 停止。

五、配置 systemd 开机自启

然后运行下面命令配置linux服务、开启启动。注意/tg_download/telegram_media_downloader需要自行替换为你的项目根目录。

tee /etc/systemd/system/tg-media-downloader.service > /dev/null <<EOF
[Unit]
Description=Telegram Media Downloader
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/tg_download/telegram_media_downloader
ExecStart=/tg_download/telegram_media_downloader/.venv/bin/python -u /tg_download/telegram_media_downloader/media_downloader.py

Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

加载并启动服务：

# 重新加载服务配置
sudo systemctl daemon-reload

# 设置开机自启，并立即启动
sudo systemctl enable --now tg-media-downloader

# 查看服务运行状态
sudo systemctl status tg-media-downloader

# 查看实时日志（按 Ctrl+C 退出查看）
sudo journalctl -u tg-media-downloader -f

如果状态显示为 active (running)，说明服务已经在后台运行。

六、下载目录结构优化

安装上面的配置，配置过后下载的目录结构ru'x：

/filedownload/
├── download_dirs/
│   ├── Channel_A/
│   │   ├── 2026_09/
│   │   │   └── 视频A.mp4
│   │   └── 2026_10/
│   │       ├── 视频B.mp4
│   │       └── 图片A.jpg
│   └── Channel_B/
│       └── 2026_10/
│           └── 文件A.pdf
└── download_temp/
    └── 下载中的临时文件

当将频道消息转发给机器人。源码默认读取机器人收到的消息所属聊天，而不是原始频道，因此仅使用上述配置，不能保证下载的文件被存放到 Channel_A/2026_10/ 这样的原始频道目录。优化方法如下：

找到media_downloader.py文件将代码

dirname = validate_title(f"{chat_id}")
if message.chat and message.chat.title:
    dirname = validate_title(f"{message.chat.title}")
if message.date:
    datetime_dir_name = message.date.strftime(app.date_format)
else:
    datetime_dir_name = "0"

替换成

# 优先使用转发消息的原始频道名称
source_chat = getattr(message, "forward_from_chat", None)

dirname = validate_title(f"{chat_id}")

if source_chat and getattr(source_chat, "title", None):
    dirname = validate_title(source_chat.title)
elif message.chat and message.chat.title:
    dirname = validate_title(message.chat.title

# 优先使用原消息的发布时间
source_date = (
    getattr(message, "forward_date", None)
    or message.date
)

if source_date:
    datetime_dir_name = source_date.strftime(app.date_format)
else:
    datetime_dir_name = "0"

然后使用systemctl restart tg-media-downloader重启即可。

七、通过机器人下载文件

打开刚才使用 BotFather 创建的机器人，先发送 /start 或 /help 查看可用命令。

常见使用方式有：

转发媒体：将有权限转发的图片、视频或文件发送给机器人；
发送消息链接：将可访问的 Telegram 消息链接发送给机器人，例如 https://t.me/example_channel/123；
使用 /download 命令：按机器人帮助信息和项目文档，指定需要下载的聊天或消息范围。

八、常用维护命令

# 查看服务状态
sudo systemctl status tg-media-downloader

# 重启服务（修改 config.yaml 后可执行）
sudo systemctl restart tg-media-downloader

# 停止服务
sudo systemctl stop tg-media-downloader

# 启动服务
sudo systemctl start tg-media-downloader

# 查看最近 100 行日志
sudo journalctl -u tg-media-downloader -n 100 --no-pager

# 关闭开机自启
sudo systemctl disable tg-media-downloader

后续更新程序时，建议先备份 config.yaml、data.yaml 及 sessions/ 等重要文件，再停服务、更新代码与依赖、重新启动。更新前注意查看项目是否有配置变更。

文章目录

keepnight