Telegram Drive 是一个跨平台文件管理器，利用您的 Telegram 账户（特别是“已保存消息”和频道）作为个人云存储空间。它提供了类似桌面文件管理器的体验，包括上传、下载、文件夹、预览、流媒体、分享工具、本地 REST API 和可选的加密传输模式。应用基于 Tauri、Rust、React 和 TypeScript 构建。

1. 系统要求与前提

1.1 硬件与软件要求

  • 操作系统：Windows、macOS (Intel/Apple Silicon)、Linux，以及 Android (Beta)。
  • 网络：需要稳定的互联网连接以上传/下载文件。
  • Telegram 账户：您需要一个有效的 Telegram 账户。
  • Telegram API 凭证：您需要从 my.telegram.org 申请自己的 api_id 和 api_hash。

1.2 重要须知

  • 存储限制：受限于 Telegram 的账户、服务和每文件大小限制（应用当前限制单个文件约 2GB）。加密文件因额外开销，原始大小上限略低。
  • 数据安全：标准上传以明文形式发送到 Telegram。可选的 TDENC2 加密模式（Alpha）提供客户端加密，但未经独立安全审计，请先使用测试数据。

2. 安装方式

2.1 下载预编译安装包（推荐）

从项目的 GitHub Releases 页面 下载适用于您系统的最新版本：

  • macOS：下载 .pkg 或 .dmg 文件（区分 Intel 和 Apple Silicon）。
  • Windows：下载 .msi 安装程序。
  • Linux：下载 .AppImage 或对应包管理器的格式（如 .deb、.rpm）。
  • Android (Beta)：从 Release 页面下载 未签名的 APK (Telegram-Drive-v3.0.0-beta.apk)。由于未签名，您需要在 Android 设置中允许安装未知来源的应用。安装后首次启动需输入您的 api_id 和 api_hash。

2.2 从源码构建（面向开发者）

如果您希望从源码运行或贡献代码，请遵循以下步骤：

  1. 前提条件：

    • Node.js：20.19.0+（推荐 Node 20 LTS）或 22.12.0+。
    • Rust：最新稳定版（通过 rustup 安装）。
    • 系统依赖：根据 Tauri 文档安装对应平台的依赖（如 Linux 上的 libwebkit2gtk 等）。
    • Telegram API 凭证：从 my.telegram.org 获取。

  2. 克隆并安装：

    1
    2
    3
    4
    git clone https://github.com/caamer20/Telegram-Drive.git
    cd Telegram-Drive/app
    npm install
    npm run tauri dev   # 启动开发模式

  3. 构建生产包：

    1
    2
    cd app
    npm run tauri build

3. 核心功能与使用

3.1 首次启动与登录

  1. 启动应用后，输入您的 API ID 和 API Hash（首次使用）。
  2. 使用您的 Telegram 手机号登录，并通过接收的验证码或二维码完成认证。
  3. 如果启用了两步验证，还需输入云密码。

3.2 文件工作区与组织

  • 浏览模式：支持网格和列表视图，可调整卡片大小（50%-200%）。
  • 文件操作：支持上传、下载、重命名、移动、复制和删除（需 Telegram 支持）。
  • 拖放：支持从文件管理器拖放上传，以及应用内部的拖放整理。
  • 文件夹管理：创建、重命名、删除文件夹，支持可见性控制和本地自定义分组。
  • 远程 URL 上传：支持从 URL 直接上传文件，并显示进度、支持取消和断点续传（源服务器支持时）。
  • 传输队列：有持久的传输队列和集中式传输中心，管理上传/下载状态。

3.3 文件预览与播放

  • 图像/媒体：内联缩略图、懒加载、图像预览。
  • PDF 阅读器：内置 PDF 查看。
  • 音频/视频播放：内置音频播放器和视频流媒体支持，并支持转封装/转码（针对兼容的明文媒体）。
  • 归档文件：支持浏览和提取 ZIP、RAR、7z 格式的压缩包，并可提取回 Telegram Drive。

注意：这些查看器目前仅适用于标准的未加密文件。加密文件（TDENC2）当前不支持预览、流媒体和本地分享链接等功能。

3.4 分享与本地集成

  • 本地下载链接：为标准文件生成本地下载链接，可设置密码保护、过期时间。
  • Telegram 消息链接：为公共频道中的文件生成原生 Telegram 消息链接。
  • REST API：可选地启用本地 REST API（默认关闭），绑定到 127.0.0.1，支持文件/文件夹管理、批量操作等。需要 X-API-Key 头认证。
  • WebDAV 访问：可选地启用 WebDAV（默认关闭），提供只读或读写访问，受一次性链接保护。

3.5 主题与界面

  • 外观模式：支持默认、系统、浅色和深色模式。
  • 自定义主题：内置颜色预设，并提供自定义主题编辑器，可创建、编辑和激活用户主题。
  • 性能偏好：支持减少动画和调整界面性能。

4. 高级功能：加密模式 (Alpha)

从 2.0.0 版本开始，Telegram Drive 包含可选的客户端加密传输模式 TDENC2。

4.1 上传保护模式

您可以在上传时为文件选择保护级别：

  • 标准：普通的明文 Telegram 上传。
  • Vault：使用本地加密保险库中的密钥进行加密（需解锁保险库）。
  • 文件密码：为文件单独设置一个密码。
  • Vault + 文件密码：同时使用两种方式。

4.2 加密安全提示

  • 无法恢复：丢失保险库密码、文件密码或密钥将永久无法恢复加密数据。
  • 未经审计：加密功能未经独立安全审计，请勿用于敏感数据。
  • 功能限制：加密文件目前不支持应用内预览、流媒体、本地分享链接和 REST API 访问。

5. 常见问题排查

问题 可能原因 解决方案
首次启动提示“无效的 API ID/Hash” 输入的凭证有误或未在 my.telegram.org 创建应用 检查 API ID 和 Hash 是否完全正确。确保已创建应用并获取凭证。
登录时无法接收验证码 网络问题或 Telegram 服务限制 检查网络连接。如果使用代理，请正确配置 SOCKS5 或 HTTP 代理。
上传/下载速度慢或中断 网络不稳定或 Telegram 服务波动 检查网络。尝试调整应用设置中的带宽、超时和重试参数。
预览 PDF/视频失败 文件损坏、格式不支持或为加密文件 加密文件暂不支持预览。标准文件请确保格式常见且未损坏。
WebDAV/REST API 无法连接 服务未启用或端口被占用 在设置中启用相应服务，并检查配置的端口是否空闲，且仅绑定到本地 127.0.0.1。
Android APK 安装失败 系统安全策略或 SDK 版本限制 启用“安装未知应用”权限。如因 target SDK 被阻止，可尝试 ADB 安装命令：adb install --bypass-low-target-sdk-block Telegram-Drive.apk。

6. 总结

Telegram Drive 将 Telegram 强大的后台支持转化为一个灵活的个人云存储解决方案。

核心使用路径：

  1. 获取凭证：在 my.telegram.org 申请 api_id 和 api_hash。
  2. 下载安装：从 Releases 页面获取适合您系统的安装包。
  3. 登录配置：首次启动时输入凭证，登录您的 Telegram 账户。
  4. 开始使用：将文件拖入应用，创建文件夹，就像使用本地文件管理器一样。
  5. 高级功能：按需启用 REST API、WebDAV 或加密模式（Alpha，请谨慎使用）。

建议：

  • 安全第一：在充分理解加密模式的限制和风险（特别是无法恢复数据）之前，请仅对测试数据使用加密功能。
  • 备份重要文件：不要将 Telegram Drive 作为唯一的数据备份方案，请定期将重要文件备份到其他可靠的存储位置。
  • 探索功能：熟悉应用的设置选项，特别是网络代理、传输队列和主题自定义，以获得最佳体验。

项目地址：https://github.com/caamer20/Telegram-Drive