Teldrive

Teldrive 是一个基于 Go 构建的 Telegram 文件管理服务。它将 Telegram 作为底层文件存储与传输通道，提供后端服务、Web UI，以及围绕上传、索引、任务处理和会话管理的一整套能力。

Important

Teldrive 本质上是对你的 Telegram 账号能力的一层封装。使用时必须遵守 Telegram API 的速率限制和平台规则；滥用接口、超限调用或不当存储行为可能导致账号或频道受限，相关风险需要由使用者自行承担。

项目文档站点：https://teldrive-docs.pages.dev

项目概览

从仓库实现看，Teldrive 不是一个单纯的脚本工具，而是一个完整的服务端应用：

• Go 后端服务：应用入口位于 main.go，通过 cmd 下的命令启动服务。
• HTTP API + Web 界面：后端会启动 HTTP 服务，并通过 ui/ui.go 内嵌前端静态资源。
• Telegram 客户端封装：项目内部封装了 Telegram 会话、连接、限流和上传/流式处理逻辑。
• 任务与事件体系：包含队列、缓存、事件广播和数据库迁移等基础设施。

为什么使用 Teldrive

• 性能更好：核心后端使用 Go 实现，适合长时间运行的服务场景。
• 不仅仅是上传工具：除了文件管理，还提供 Web 界面、任务处理、配置体系和 API。
• 前后端打包清晰：前端资源通过构建流程拉取并嵌入二进制，部署形式相对直接。
• 适合自动化与集成：仓库内包含 API 生成、文档生成、数据库迁移和集成测试流程。

代码结构

以下目录是理解项目的关键入口：

• main.go：程序入口。
• cmd/：CLI 命令定义，例如运行服务、检查任务等。
• internal/app/：应用装配、HTTP 服务启动、生命周期管理。
• internal/config/：配置加载与校验，支持默认值、配置文件、环境变量和命令行参数。
• internal/tgc/：Telegram 客户端相关封装。
• internal/tgstorage/：Telegram 会话存储实现。
• internal/database/：数据库初始化与迁移。
• pkg/repositories/、pkg/services/：业务仓储与服务层。
• ui/：前端静态资源嵌入。
• tests/integration/：依赖真实 PostgreSQL 的集成测试。

环境要求

根据仓库中的 Taskfile.yml、CONTRIBUTING.md 和测试说明，常见开发依赖包括：

• Go
• Git
• Task
• PowerShell 或 Bash
• Docker / Docker Compose（运行集成测试时需要）
• Bun（生成 API 文档或本地运行文档站点时需要）

快速开始

1. 克隆仓库

git clone https://github.com/tgdrive/teldrive.git
cd teldrive

2. 安装依赖

task deps

3. 拉取前端资源

Teldrive 的前端资源来自独立发布产物，执行下面的命令会下载并解压到 ui/dist：

task ui

4. 构建服务

完整构建：

task

仅构建后端：

task server

5. 运行服务

task run

默认情况下，服务监听 8080 端口；如果端口被占用，应用会尝试向后寻找可用端口。

配置说明

项目的配置系统位于 internal/config/config.go，并提供了示例配置文件：

• config.sample.yml
• config.sample.toml

配置内容覆盖以下核心部分：

• server：HTTP 端口、读写超时、优雅关闭等。
• db：数据库连接串、连接池、预编译语句等。
• jwt：登录会话和鉴权密钥。
• redis / cache：缓存与 Redis 连接参数。
• queue / jobs / events：后台任务、同步作业和事件广播设置。
• tg：Telegram App ID、App Hash、代理、限流、上传、流式读取、会话存储等。

从示例配置可以看出，项目默认会使用 PostgreSQL 作为数据库，并且 Telegram 会话存储也支持 postgres、bolt、memory 等模式。

构建与开发命令

仓库使用 Taskfile.yml 统一管理开发任务，常用命令如下：

基础命令

task deps      # 下载并整理 Go 依赖
task ui        # 下载前端构建产物
task server    # 构建后端二进制
task run       # 直接运行服务
task           # 默认执行 ui + server

代码生成

task gen           # 执行 go generate ./...
task gen:jet       # 重新生成 Jet models
task gen:config    # 重新生成示例配置
task gen:docs      # 生成 CLI/OpenAPI 文档资源
task gen-api       # 在 typespec 下生成 API specs

文档与质量检查

task docs:dev      # 本地启动文档站点
task docs:build    # 构建文档站点
task lint          # 运行 golangci-lint

测试

运行全部 Go 测试

go test ./...

运行集成测试

集成测试依赖一个真实的 PostgreSQL 实例，并会自动应用 goose migrations。

先启动测试数据库：

docker compose -f tests/docker-compose.test.yml up -d

然后执行：

TEST_DATABASE_URL=postgres://teldrive_test:teldrive_test@localhost:55432/teldrive_test?sslmode=disable go test ./tests/integration/... -count=1

或者直接使用辅助命令：

./scripts/test-integration.sh
task test:integration

前端说明

前端不是直接在本仓库内维护源码，而是通过发布产物的方式集成。task ui 会从 teldrive-ui 的发布资源中下载压缩包，并将内容提取到 ui/dist，随后由 Go 的 embed 机制嵌入到最终程序中。

这意味着：

• 本仓库主要负责后端、集成逻辑和最终打包。
• 若要深入修改前端，通常还需要关注对应的前端仓库与发布流程。

使用建议

• 控制调用频率，避免触发 Telegram API 限制。
• 不要把 Telegram 当作无限制、无风险的“免费网盘”。
• 在生产使用前，先验证数据库、Redis、会话存储和代理配置是否符合你的环境。
• 若涉及大规模上传、同步或机器人协作，建议先在测试环境验证限流和任务参数。

贡献

欢迎参与贡献。开始之前请先阅读 CONTRIBUTING.md。

许可证

本项目仓库中包含 LICENSE 文件，使用前建议先阅读其具体条款。

捐赠

如果这个项目对你有帮助，欢迎通过 Paypal 支持作者。

Star History