Telegram Cloud Storage

核心用法

Telegram Cloud Storage (Teldrive Edition) 是一款将 Telegram 作为后端存储介质的高性能云存储解决方案。用户需先配置 PostgreSQL 17+ 数据库并安装 pgroonga 扩展以支持文件搜索，随后通过 Telegram 官方获取 API ID 与 Hash 完成身份认证。部署后，系统提供三类访问方式：Web 界面可视化操作、REST API 程序化调用，以及内置的 client.py AI 原生客户端供智能体直接操控文件。

文件管理采用 Telegram 群组/频道作为物理存储层，Teldrive 通过索引映射实现逻辑目录结构。上传文件会被分片存储至 Telegram 服务器，下载时通过多线程优化传输速度。Python 客户端支持列出目录、上传下载等基础操作，需配置 JWT Token 与会话哈希进行身份验证。

显著优点

• 零成本无限扩容：依托 Telegram 免费云存储，理论容量无上限
• 高性能架构：Go 语言编写，针对大文件传输与并发访问深度优化
• 三重交互界面：兼顾普通用户的 Web UI、开发者的 REST API、AI 系统的原生客户端
• AI-Native 设计：client.py 专为智能体场景设计，便于集成至自动化工作流

潜在缺点与局限性

• 依赖 Telegram 政策风险：违反 Telegram ToS 的自动化工具，存在账号封禁可能性
• 数据库运维门槛：要求独立维护 PostgreSQL 及 pgroonga 扩展，增加了部署复杂度
• 元数据单点故障：文件索引存储于本地数据库，若未备份则无法重建文件映射关系
• 无官方 SLA 保障：Telegram 服务中断或 API 变更将直接影响可用性

适合人群

• 技术爱好者与自托管用户，具备 Linux 服务器运维能力
• 需要大容量低成本存储的内容创作者、归档管理员
• 开发集成 Telegram 存储能力的 AI 应用或自动化脚本的工程师

常规风险

| 风险类型 | 说明 |

|---------|------|

| 账号安全 | Telegram API 滥用可能导致主账号受限或封禁 |

| 数据持久性 | Telegram 不保证文件永久留存，极端情况下可能丢失 |

| 隐私合规 | 敏感数据经第三方工具中转，需自行评估加密与合规需求 |

| 依赖链风险 | PostgreSQL、pgroonga、Teldrive 任一组件更新故障均会影响服务 |

核心用法

Telegram Cloud Storage 是一个基于 Teldrive 的 Skill 包装器，将 Telegram 的无限存储空间转化为个人云盘。用户通过本地部署的 Go 二进制服务获得完整的 Web UI 和 REST API，支持文件上传、下载、列表浏览和管理操作。

部署流程：配置 PostgreSQL 17+ 数据库并安装 pgroonga 扩展 → 运行 ./scripts/setup.sh 生成配置 → 启动服务 ./scripts/manage.sh start → 通过 python3 scripts/client.py 进行命令行操作。

Agent 集成：提供 client.py 客户端，支持 list/upload/download 命令，需配置 TELDRIVE_TOKEN 和 TELDRIVE_SESSION_HASH 环境变量。

---

显著优点

1. 存储成本归零：利用 Telegram 的免费云存储作为后端，理论容量无上限
2. 性能优异：核心引擎 Teldrive 使用 Go 编写，针对高速文件传输优化
3. 双模交互：同时提供现代化 Web 界面和完整的 REST API，兼顾人工操作与自动化集成
4. AI-Native 设计：内置 Python 客户端脚本，便于 LLM Agent 直接调用文件操作
5. 来源可信：依赖官方 GitHub Releases 分发，Teldrive 为知名开源项目（GitHub 2K+ Stars）

---

潜在缺点与局限性

| 方面 | 说明 |

|:---|:---|

| **安全风险突出** | 配置文件中**硬编码 Telegram API 凭证**（App ID/App Hash）和 **JWT Secret**，违反安全基线 |

| **明文 Token 存储** | JWT Token 以明文形式写入 `config/token.txt`，泄露即导致账户接管 |

| **供应链风险** | 二进制从网络下载，当前**无哈希校验**，存在篡改可能 |

| **基础设施依赖** | 强制要求 PostgreSQL 17+ 和 pgroonga 扩展，部署门槛较高 |

| **本地通信未加密** | API 默认使用 HTTP 而非 HTTPS，本地网络存在中间人风险 |

| **合规瑕疵** | 不符合 GDPR 数据最小化原则，硬编码密钥直接触发安全审计失败 |

---

适合人群

• 技术型用户：具备 Linux 服务器管理、数据库配置能力的开发者或运维人员
• 成本敏感场景：需要大容量冷存储且对数据隐私要求不极端严格的个人用户
• 自动化工作流：需要将文件操作集成到 CI/CD 或 Agent 工作流的开发者
• 不适合：企业级生产环境、处理敏感商业数据、或缺乏安全审计能力的团队

---

常规风险

| 风险等级 | 具体风险 | 缓解建议 |

|:---|:---|:---|

| 🔴 **严重** | 硬编码凭证可导致未授权 Telegram API 访问和 JWT 伪造 | 立即改用环境变量注入，从版本控制移除配置文件 |

| 🔴 **严重** | 明文 Token 文件权限不当可被任意进程读取 | 设置 `chmod 600`，考虑使用密钥管理服务 |

| 🟠 **高** | 二进制下载缺乏完整性验证 | 手动校验 GitHub Release 的 SHA256 签名 |

| 🟡 **中** | Telegram 账户可能因 API 滥用被限制 | 遵守 Telegram ToS，避免高频自动化操作 |

| 🟡 **中** | 依赖外部服务的持久可用性 | 建立本地备份机制，勿将 Telegram 作为唯一数据源 |

综合评估：该 Skill 功能价值明确，但安全实现存在根本性缺陷。建议在修复硬编码凭证问题后再投入生产使用，当前评级仅适合隔离环境测试或低敏感度场景。