telegram-upload：把 Telegram 当作个人云盘的上传下载工具
telegram-upload 是一个基于个人 Telegram 账号的命令行工具，支持上传和下载最大 4 GiB（免费用户 2 GiB）的文件，可把 Telegram 变成个人云存储；提供交互模式、大文件分片与合并、缩略图、下载成功后删除消息、caption 变量和代理等能力，使用 MIT 许可证，支持 pip3 安装与 Docker 运行。
社区作者 · zZz
它解决什么问题
telegram-upload 使用你的个人 Telegram 账号上传和下载文件，单文件最大可达 4 GiB（免费用户为 2 GiB），目标是把 Telegram 变成你的个人 ☁ 云盘。
项目起源与致谢：该项目由 Nekmo 及贡献者开发，基于 Telethon（作为 Telegram 客户端库）实现。配图 1 为项目 logo。
核心特性（来源 Features 列表）：
- 上传和下载多个文件（Premium 用户单文件最大 4 GiB）。
- 交互模式（--interactive），支持鼠标的终端向导。
- 为视频添加缩略图。
- 拆分（split）与合并（join）大文件。
- 成功后删除本地或远端文件（--delete-on-success）。
- 在 caption 消息中使用变量。
- 以及其他更多选项。
重要限制：不能使用 Bot token，因为 Bot 上传被限制在 50MB。必须使用个人账号的 api_id 与 api_hash。
配置与安全：凭证保存在 ~/.config/telegram-upload.json 和 ~/.config/telegram-upload.session，必须确保这些文件安全；可复制到其他机器用于认证，但建议每台机器单独创建 session 文件。
工具提供两个命令：telegram-upload（上传，默认上传到 Saved Messages）与 telegram-download（下载，默认从 Saved Messages 下载，直到最后一条文本消息为止）。配图 2 为演示动图。更多选项（自定义文件缩略图、设置带变量的 caption 消息、配置代理等）见官方文档。
— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。
安装 / 开始使用
环境准备：
- 准备一个 Telegram 账号，并在 my.telegram.org 申请 App 的 api_id 与 api_hash。
- 注意：本程序不能使用 Bot token（Bot 上传被限制在 50MB）。
步骤 3
Python 3.7-3.11 经过测试并受支持。
安装方式一（推荐，
pip3）：
$ sudo pip3 install -U telegram-upload 这是推荐安装方式，会始终安装最新的稳定版本。此外还有 Docker 等其他安装方式，更多信息见官方文档。
首次运行：
- 第一次使用 telegram-upload 时会要求输入 📱 电话号码、api_id 与 api_hash。
- 凭证会保存到 ~/.config/telegram-upload.json 与 ~/.config/telegram-upload.session。必须确保这两个文件的安全。你可以复制这些文件在其他机器上认证 telegram-upload，但建议为每台机器分别创建 session 文件。
基本使用步骤：
$ telegram-upload file1.mp4 file2.mkv
$ telegram-download
$ telegram-upload --interactive # 交互式上传 $ telegram-download --interactive # 交互式下载
$ telegram-upload --to telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg video.mkv
$ telegram-download --from username entity 的全部可用取值见官方文档。
- 上传文件（默认上传到 Saved Messages/收藏夹）：
- 下载文件（默认从 Saved Messages 下载，也可从 channel 下载；会下载所有文件直到最后一条文本消息）：
- 交互模式（--interactive，通过终端 🪄 向导选择会话与要下载或上传的文件，甚至支持鼠标），参见配图 2 的演示：
- 指定上传目标（默认使用个人 chat，可用 --to <entity> 定义目标）：
- 指定下载来源（使用 --from <entity> 参数从特定 chat 下载）：
$ telegram-upload --large-files split large-video.mkv 下载时可用以下命令把拆分文件重新合并： $ telegram-download --split-files join
- 拆分与合并大文件：如果上传的文件超过 Telegram 默认支持的最大值会报错，可启用 ✂ split 模式上传多个分片：
- 成功后删除：--delete-on-success 选项允许在下载完文件后 ❌ 删除 Telegram 消息，适合把待下载文件发送到收藏夹以避免重复下载，也可用于离家在外时把文件下载到自己的电脑。
- 更多选项：可自定义文件缩略图、设置 caption 消息（支持变量）、配置代理，详见官方文档。
Docker 运行（无需在系统中安装）：使用 Docker 时，用 upload 和 download 替代 telegram-upload 和 telegram-download：docker run -v <files_dir>:/files/ \-v <config_dir>:/config \ -it nekmo/telegram-upload:master \ <command> <args> 参数说明：
示例：
- <files_dir>：上传或下载目录。
- <config_dir>：用于存放 telegram-upload 配置的目录，会自动创建。
- <command>：upload 和 download。
- <args>：telegram-upload 和 telegram-download 的参数。
docker run -v /media/data/:/files/ \-v $PWD/config:/config \ -it nekmo/telegram-upload:master \ upload file_to_upload.txt
常见问题：
- 上传超过 Telegram 限制的文件会报错：改用 --large-files split 拆分上传，下载时用 --split-files join 合并。
- 无法使用 Bot token：Bot 上传被限制在 50MB，必须使用个人账号的 api_id 与 api_hash。
- 单文件大小上限：免费用户 2 GiB，Premium 用户 4 GiB。
- 凭证文件安全：~/.config/telegram-upload.json 与 ~/.config/telegram-upload.session 必须妥善保管，建议每台机器单独生成 session。
