Telegram（国内俗称 “纸飞机”）上有大量优质频道资源，tangyoha/telegram_media_downloader 是一款开源的 TG 媒体批量下载工具，支持自动增量下载、文件类型过滤、Web 管理界面等功能。本文基于飞牛 NAS（fnOS）环境，完整记录从配置到部署的全流程，以及过程中遇到的所有坑点与解决方案。

一、前置准备

1.1 获取 Telegram API 凭证

程序通过 Telegram 官方 API 连接账号，需要先申请 api_id 和 api_hash：

  1. 打开官方申请页面：https://my.telegram.org/apps

  2. 登录你的 Telegram 账号，按提示填写应用名称和描述

  3. 提交后即可获得 api_id（数字）和 api_hash（字符串），妥善保存

1.2 飞牛 NAS 开启 SSH 并登录

  1. 飞牛后台 → 设置 → 安全 → 开启 SSH 开关

  2. 使用终端工具（如 PowerShell、Xshell）连接 NAS，命令格式： 

    ssh 管理员账号@你的NAS内网IP

  3. 输入管理员密码登录，执行 sudo -i 切换到 root 权限

💡 踩坑提醒：fnOS 基于 Debian，SSH 服务名为 ssh，不是 sshd。如果修改配置后重启失败，使用 systemctl restart ssh 命令，不要用 sshd。

1.3 创建工作目录

选择你的存储池路径，创建项目目录和必要子目录 / 文件：

# 进入你的存储目录，示例路径请替换为自己的
cd /vol1/1000/raid10
mkdir -p tg_downloader/{sessions,log,temp,downloads}
cd tg_downloader

# 必须提前创建空文件，否则Docker会误建为同名目录
touch data.yaml

二、编写核心配置文件

在项目目录下创建 config.yaml，这是程序的核心配置，所有参数提前写好即可实现免交互启动。

2.1 最小可用配置模板

api_hash: 你申请的api_bash
api_id: 你申请的纸飞机id
chat:
- chat_id: -1004375565798
  last_read_message_id: 0
file_formats:
  audio:
  - all
  document:
  - all
  video:
  - all
file_path_prefix:
- chat_title
- media_datetime
media_types:
- audio
- photo
- video
- document
- voice
- video_note
# in linux please use /
# save_path: E:\github\telegram_media_downloader

2.2 关键注意事项

  • YAML 格式严格缩进，只能用空格，不能用 Tab

  • chat_id 可通过 网页版地址栏获取

三、首次登录：必须前台交互启动

3.1 为什么不能直接后台启动

程序首次运行需要输入验证码完成登录。如果直接后台启动容器，没有交互输入流，程序会瞬间读到 EOF 并报错退出，这也是很多人遇到 “容器启动就闪退” 的核心原因。

飞牛 Docker 面板的「查看日志」窗口是纯只读的，无法输入内容，必须通过 SSH 命令行操作。

3.2 前台交互式启动命令

在项目目录下执行：

docker run -it --rm \
  -v ./config.yaml:/app/config.yaml \
  -v ./data.yaml:/app/data.yaml \
  -v ./sessions:/app/sessions \
  -v ./log:/app/log \
  -v ./temp:/app/temp \
  -v ./downloads:/app/downloads \
  tangyoha/telegram_media_downloader:latest

3.3 登录操作步骤

  1. 命令执行后，程序会读取配置中的手机号，等待输入验证码

  2. 打开你的 TG 客户端（手机 / 网页版），查看官方发送的验证码

  3. 在终端输入验证码，回车

  4. 若账号开启了二步验证，再输入二步验证密码，回车

  5. 看到程序开始连接服务器、扫描频道，说明登录成功

  6. 按 Ctrl+C 停止容器即可。--rm 参数会自动删除临时容器，登录凭证已保存在本地 sessions 目录，不会丢失

四、Docker Compose 后台常驻部署

登录完成后，使用 Compose 配置后台常驻运行，后续直接在飞牛面板即可管理。

4.1 docker-compose.yml 配置

在项目目录下创建 docker-compose.yml：

services:
  telegram_media_downloader:
    image: tangyoha/telegram_media_downloader:latest
    container_name: tg_downloader
    restart: unless-stopped
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./data.yaml:/app/data.yaml
      - ./sessions:/app/sessions
      - ./log:/app/log
      - ./temp:/app/temp
      - ./downloads:/app/downloads
    ports:
      - "5000:5000"  # WebUI 端口
    environment:
      - TZ=Asia/Shanghai

4.2 启动与验证

# 后台启动
docker compose up -d

# 查看运行日志
docker compose logs -f

正常启动后，程序会自动扫描配置的频道，按规则增量下载文件。浏览器访问 http://你的NAS_IP:8000 可进入 Web 管理界面。

五、高频报错与解决方案

5.1 报错：Failed to restart sshd.service

原因：fnOS 基于 Debian，SSH 服务名是 ssh，不是 CentOS 系的 sshd。 解决：使用正确命令重启服务

systemctl restart ssh

5.2 报错：not a directory 挂载失败

完整报错：error mounting ... not a directory: unknown: Are you trying to mount a directory onto a file 原因：宿主机上 data.yaml / config.yaml 不存在，Docker 会自动创建同名目录，导致文件挂载类型不匹配。 解决：删除错误目录，重建为空文件

rm -rf data.yaml
touch data.yaml

5.3 报错：EOFError 容器启动就闪退

完整报错：EOFError: EOF when reading a line 原因：

  1. config.yaml 未填写手机号，程序进入交互输入模式

  2. 后台启动容器无输入流，程序读取不到输入直接崩溃 解决：

  3. 补全 config.yaml 中的 phone_number

  4. 按本文第三步，前台交互启动一次完成登录

5.4 飞牛 Docker 面板日志窗口无法输入

原因：面板的日志查看窗口是只读输出，不支持标准输入。 解决：所有需要交互的操作，统一通过 SSH 命令行执行。

六、补充说明

  1. 登录持久化：只要 sessions 目录不删除，容器重启、重建、升级镜像都无需重新登录。

  2. 自动增量下载：在配置中开启 daemon 模式，设置检查间隔，程序会定时轮询频道自动下载新内容。

  3. 文件管理：下载的文件保存在 downloads 目录，可通过飞牛的文件管理、SMB 共享直接访问。

  4. 安全提示：公网环境不建议暴露 WebUI 和 SSH 端口，建议仅内网使用。

七、总结

飞牛 NAS 部署 TG 下载器的核心坑点集中在「首次登录交互」和「文件挂载类型」上。只要遵循「先前台交互登录 → 再后台常驻运行」的流程，提前创建好挂载文件，就能顺利跑通服务。后续日常使用几乎无需维护，程序会自动按配置完成媒体下载。