一个基于 Python (Telethon + Flask) 和网页界面的 Telegram 媒体文件（图片、视频、文档等）自动解析与下载工具。提供类似苹果风格的精致 UI，支持多图相册解析、文件名自定义修改、下载进度实时展示等功能。
- 一键解析: 粘贴 Telegram 消息链接，自动解析出该消息内包含的所有媒体文件。
- 相册支持: 完美支持解析 Telegram 的相册（多图/多视频），自动编号，避免文件名冲突。
- 重命名功能:
- 支持内联修改（直接点击文件名修改）。
- 支持超长文本弹窗修改（点击“详细”按钮修改）。
- 后台异步下载: 解析后一键推送到后台下载，不阻塞页面，支持断点续传机制，实时显示下载速度和进度。
- 精美 UI: 采用 Tailwind CSS 打造的苹果风格响应式界面，支持深色/浅色模式一键切换。
- 持久化登录: 基于 Telethon 的
session文件，一次登录，长久有效。
在开始部署之前，您需要准备以下信息：
- Telegram API ID 和 API HASH:
- 访问 https://my.telegram.org/
- 登录您的 Telegram 账号。
- 点击
API development tools。 - 随意填写
App title和Short name，创建一个应用。 - 创建成功后，您将获得
api_id和api_hash。请妥善保存。
使用 Docker 部署是最简单且不会污染宿主机环境的方式。
将本项目的所有代码下载到您的服务器或本地电脑上，并进入项目目录。
编辑 docker-compose.yml 里的 environment，填入您刚刚获取的 API 信息，以及配置您的 Web 访问账号密码。
在项目根目录下（包含 Dockerfile 的目录），运行以下命令构建镜像：
docker build -t tg-auto-downloader .在项目根目录创建 docker-compose.yml，内容如下：
services: # Compose 的服务列表（一个服务对应一个容器）
tg-downloader: # 服务名（可自定义）
image: tg-auto-downloader:latest # 使用已构建好的镜像名:标签（和 docker build -t 的名字保持一致）
container_name: tg-downloader # 固定容器名（可选；不写时 Docker 会自动生成）
ports: # 端口映射：宿主机端口:容器端口
- "7979:7979" # 浏览器访问宿主机 7979，会转发到容器内 Flask 的 7979
environment: # 环境变量（程序通过 os.getenv(...) 读取）
API_ID: "YOUR_API_ID" # Telegram 的 api_id（数字），来自 https://my.telegram.org/
API_HASH: "YOUR_API_HASH" # Telegram 的 api_hash（字符串），来自 https://my.telegram.org/
SESSION_FILE: "/data/session.session" # Telethon 会话文件保存路径（放到 /data 以便持久化）
DOWNLOAD_DIR: "downloads" # 下载目录名（容器内最终路径为 /app/downloads）
PORT: "7979" # Flask 监听端口（容器内）
DEBUG_MOCK_MODE: "false" # true=不连 Telegram、返回 Mock 数据；false=真实解析/下载
WEB_USERNAME: "admin" # Web Basic Auth 用户名（建议改掉）
WEB_PASSWORD: "change_me" # Web Basic Auth 密码（强烈建议改成强密码；不要用默认值）
volumes: # 挂载（持久化/映射文件）
- ./downloads:/app/downloads # 把下载文件映射到宿主机 ./downloads，方便直接取走文件
- tg_downloader_data:/data # 命名卷（Docker 管理）：用于持久化 session 等数据（不会出现在项目目录）
stdin_open: true # 保持 STDIN 打开，配合首次登录的交互输入（手机号/验证码）
tty: true # 分配 TTY，提升交互体验（docker compose up 前台运行时更直观）
restart: unless-stopped # 异常退出/重启后自动拉起，手动 stop 则不再自动启动
volumes: # 命名卷声明
tg_downloader_data: # 卷名（和上面 volumes 里引用的名字一致）首次启动建议以前台方式运行（需要交互式输入手机号/验证码）：
docker compose up注意查看终端输出：
- 终端会提示
Please enter your phone (or bot token):。 - 输入您注册 Telegram 的手机号（带国际区号，如
+8613800138000）。 - 接着终端会提示输入验证码。请打开您手机上的 Telegram App，查看官方账号发送给您的登录验证码并输入。
- （如果开启了二次验证两步验证），可能还需要输入您的两步验证密码。
- 看到
Telegram Client Started Successfully!说明登录成功。
第一次登录成功后，登录会话会保存在 Docker 的命名卷 tg_downloader_data 中，您可以按 Ctrl+C 停止前台运行。
以后每次只需以后台模式运行即可：
docker compose up -d如果您不想使用 Docker，也可以直接在本地运行。
确保您的电脑上安装了 Python 3.10 或以上版本。
在项目根目录下打开终端，运行：
pip install -r requirements.txt同样，在 .env 文件中填入您的 API_ID 和 API_HASH。
在终端中运行：
python main.py与 Docker 部署类似，第一次运行时会在终端提示您输入手机号和验证码，请根据提示完成登录授权。
- 打开网页:
在浏览器中访问
http://127.0.0.1:7979(如果部署在服务器上，将127.0.0.1替换为服务器 IP)。 - 解析链接:
在 Telegram 中找到您想要下载的图片或视频，长按或右键复制消息链接 (如
https://t.me/c/123456789/123)。 将其粘贴到网页的输入框中，点击“解析”。 - 修改文件名: 解析出列表后，您可以点击卡片上的原始文件名或消息内容名进行修改。如果名字太长，可以点击旁边的“详细”按钮呼出大弹窗修改。
- 开始下载: 勾选需要下载的媒体，点击“开始下载选中项”。
- 查看进度: 点击顶部的“已下载任务”标签，可以实时查看当前的下载进度和速度。
Q: 为什么解析链接一直提示“无法获取消息，可能无权访问或链接错误”？ A: 请确保您登录的 Telegram 账号已经加入了该群组或频道。如果这是一个私密频道，且您的账号不在里面，是无法解析出内容的。
Q: 为什么解析出来有些文件叫 media_xxx.jpg？
A: 这是因为该条消息（或相册组）本身没有附带任何文字说明（Caption），所以系统只能以其消息 ID 作为默认名称。您可以手动点击修改它。
Q: 任务列表里点击“清理记录”会删除文件吗？
A: 不会。清理记录只是清除了数据库中的下载历史显示，您下载到本地 downloads 文件夹里的文件依然安全存在。
Q: 如何重新登录其他账号？ A: 停止服务并删除命名卷后再启动即可（会清空登录会话）：
docker compose down -v
docker compose upQ: 首次启动没出现“输入手机号/验证码”的提示，或输入后一直连接失败怎么办？ A: 这通常是网络不稳定导致 Telethon 在进入交互登录前就断线了。可以按下面顺序尝试：
- 确保以前台方式启动（需要交互输入）：
docker compose up- 如果你之前在首次登录时按过
Ctrl+C或流程卡住，先重启容器再试一次：
docker compose down
docker compose up- 如果容器已经在跑但终端没进入交互输入界面，可以进入容器手动触发一次（经验做法）：
docker exec -it tg-downloader sh
python main.py如果一次没弹出提示，可在容器内多执行几次 python main.py（网络恢复后会继续进入登录流程）。若出现端口占用提示，先退出容器并用 docker compose down / docker compose up 重启再试。