TG-Vault 部署教程：Telegram 全自动转存 + 私有云存储系统

优化版 | 2026年7月
基于 hicocos/tg-vault 整理，适配最新版本，补充踩坑经验与进阶玩法

什么是 TG-Vault

TG-Vault 是一个开源的 Telegram 文件转存 + 私有云存储系统。它可以：

🚀 自动保存 Telegram 频道/群组的媒体文件到你的私有云
🤖 Bot 交互：通过 Telegram Bot 发文件、下视频、管理任务
☁️ 多存储源：支持本地、OneDrive、Google Drive、阿里云 OSS、S3（含 Cloudflare R2）、WebDAV
📥 链接下载：集成 yt-dlp，发链接就能下载视频/音频
🔒 安全可靠：TOTP 双因子认证、密钥加密、权限控制
🖥️ Web 管理：浏览器里浏览、预览、管理所有文件

一句话总结：把 Telegram 变成你的私人网盘。

功能对比：Bot 模式 vs 账号级模式

TG-Vault 有两种工作模式，能力存在差异：

功能	仅 Bot 模式	Bot + 账号级下载器
私聊发文件给 Bot 转存	✅	✅
任务管理 / 存储统计 / 删除文件	✅	✅
/ytdlp 下载视频链接	✅	✅
频道/群组按日期批量抓取	❌	✅
频道/群组按标签批量抓取	❌	✅
频道订阅自动同步新消息	❌	✅
超大文件（>2GB）稳定下载	⚠️ 可能失败	✅ 更稳定

新手建议：先部署 Bot 基础模式，确认能用后再加账号级下载器。

部署前置要求

硬件最低要求

CPU: 1 核
内存: 1GB（推荐 2GB+）
磁盘: 20GB + 根据存储量扩容
系统: Debian 11/12 或 Ubuntu 20.04/22.04/24.04

软件要求

Docker Engine 26+ & Docker Compose v2
宿主机安装 Nginx（用于 HTTPS 反代）
两个域名（推荐，也可以单域名不同路径）

域名准备

用途	示例域名	代理端口
Web 前端	cloud.yourdomain.com	→ 127.0.0.1:47832
API 后端	api.yourdomain.com	→ 127.0.0.1:51947

Step 1：安装 Docker

curl -fsSL https://get.docker.com | bash
systemctl enable --now docker
docker --version
docker compose version

Step 2：克隆项目 & 配置环境变量

git clone https://github.com/hicocos/tg-vault.git
cd tg-vault
cp .env.example .env
nano .env

必填变量

# 数据库密码
DB_PASSWORD=$(openssl rand -hex 32)

# 域名
VITE_API_URL=https://api.yourdomain.com
CORS_ORIGIN=https://cloud.yourdomain.com
DOMAIN=cloud.yourdomain.com

# 安全
COOKIE_SECURE=true
TRUST_PROXY=loopback

# Telegram Bot
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890

# 用户白名单（推荐设置）
TELEGRAM_ALLOWED_USER_IDS=你的Telegram用户ID

# 下载并发调优
TELEGRAM_DOWNLOAD_WORKERS=4
TELEGRAM_FILE_DOWNLOAD_CONCURRENCY=2

⚠️ 修改 VITE_API_URL 后必须重新构建前端镜像，它会打包进静态文件。

Step 3：构建 & 启动

# 让 .env 变量生效
set -a && source .env && set +a

# 构建前端（传入 API 地址）
docker build --build-arg VITE_API_URL="${VITE_API_URL}" -t tg-vault-frontend:latest ./frontend

# 构建后端
docker build -t tg-vault-backend:latest ./backend

# 启动
docker compose up -d

# 检查状态
docker compose ps
curl -fsS http://127.0.0.1:51947/livez
curl -fsS http://127.0.0.1:51947/readyz

Step 4：Nginx 反向代理 & HTTPS

创建 Nginx 配置：

# 前端
server {
    listen 80;
    server_name cloud.yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:47832;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# API（注意大文件上传限制）
server {
    listen 80;
    server_name api.yourdomain.com;
    client_max_body_size 10G;
    location / {
        proxy_pass http://127.0.0.1:51947;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

启用 & 签发证书：

ln -s /etc/nginx/sites-available/tg-vault /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d cloud.yourdomain.com -d api.yourdomain.com

Step 5：初始化 Web 管理后台

浏览器访问 https://cloud.yourdomain.com
首次访问会进入初始化页面，创建：管理员密码（至少 8 位）和 Bot PIN 码（4 位数字）
登录后进入文件管理主界面

Step 6：配置 Telegram Bot

获取 Bot Token

Telegram 搜索 @BotFather，发送 /newbot，按提示创建机器人。

获取 API ID & Hash

访问 my.telegram.org 登录 → API Development Tools → 创建应用。

获取你的 User ID

Telegram 搜索 @userinfobot，发送 /start 获取数字 ID。

验证

docker compose up -d --build
# 在 Telegram 私聊你的 Bot，发送 /start，输入 4 位 PIN

Step 7：启用账号级下载器（可选）

如果需要频道/群组转存、按标签抓取、订阅同步：

docker compose run --rm --no-deps backend npm run login:telegram-user
docker compose up -d

按提示输入手机号和验证码，自动生成 Session 文件。

存储源配置指南

存储类型	推荐场景	关键配置
Cloudflare R2	免费 10GB，全球加速	S3 Compatible，Endpoint 填 R2 终端节点
阿里云 OSS	国内访问快	Bucket + Region + RAM AK/SK
WebDAV	挂载坚果云等	URL + 用户名 + 第三方应用密码
OneDrive / Google Drive	已有订阅	OAuth 流程授权
本地存储	最简单	默认即可

Bot 命令全解

基础命令

命令	说明
/start	身份认证 / PIN 登录
/help	查看完整命令帮助
/storage	查看存储统计 & 清理本地文件
/tasks	查看下载任务队列
/ytdlp <url>	下载视频/音频链接
/delete <ID>	删除文件
/setup_2fa	配置 TOTP 双重验证

任务控制

命令	说明
/task_pause [ID]	暂停任务
/task_resume [ID]	恢复任务
/task_cancel <ID或all>	取消任务
/stop_tasks	停止所有下载
/download_workers <4/8/12/16>	单文件分片并发数
/file_concurrency <1/2/3/4>	同时下载文件数

账号级命令（需启用下载器）

命令	说明
/tg_download	打开按日期/标签下载向导
/tg_download date <频道> <开始> <结束>	按日期批量抓取
/tg_download tag <频道> <#标签>	按标签批量抓取
/tg_sub <频道>	添加频道订阅
/tg_subs	查看订阅列表
/tg_unsub <频道>	取消订阅
/tg_retry	重试失败下载任务

频道/群组自动转存

实际用法

# 按日期范围抓取频道历史
/tg_download date @my_channel 2026-01-01 2026-07-18

# 按标签批量下载
/tg_download tag @wallpaper_channel #壁纸

# 订阅频道，新消息自动同步
/tg_sub @daily_news
/tg_subs
/tg_unsub @daily_news

自动归档结构

telegram/
  └── 频道名/
      ├── images/    ← 图片
      ├── videos/    ← 视频
      └── documents/ ← 文档

yt-dlp 视频下载

/ytdlp https://www.youtube.com/watch?v=xxxxx
/ytdlp https://www.bilibili.com/video/BVxxxxxx
/ytdlp https://x.com/user/status/xxxxx

并发调优建议

模式	文件级并发	分片并发	适合场景
稳定优先	1	4	长期跑任务，最怕中断
默认推荐	2	4	大多数个人用户
速度优先	3	4~8	网络和存储都稳定
激进模式	4	12~16	可能触发限流，慎用

安全加固

生产环境必须启用 HTTPS（COOKIE_SECURE=true）
设置 TELEGRAM_ALLOWED_USER_IDS 限制 Bot 访问
启用 TOTP 双因子认证（Web 和 Bot 均可）
不暴露容器端口到公网，用 Nginx 反代
备份时加密 file-storage 卷（含密钥材料）

备份 & 恢复

chmod +x deploy/backup.sh deploy/restore-verify.sh
BACKUP_DIR=./backups ./deploy/backup.sh
./deploy/restore-verify.sh ./backups/<备份目录>

备份包含：PostgreSQL dump + /data 完整文件 + SHA-256 校验清单。

⚠️ 密钥材料在 file-storage 卷的 /data/secrets/ 中，迁移服务器时务必同时备份，否则登录会话和存储凭证都会失效。

升级更新

git fetch origin
git pull --ff-only origin main
docker compose up -d --build
docker compose ps

常见问题排查

Backend 不健康（/readyz 503）

docker compose exec postgres pg_isready -U tgvault -d tgvault
docker compose logs --tail=200 backend

前端页面空白 / API 请求失败

确认修改 VITE_API_URL 后已重新构建前端
确认 CORS_ORIGIN 与前端域名一致

Bot 无响应

检查 TELEGRAM_BOT_TOKEN 是否正确
确认已发送 /start 并通过 PIN 验证

频道转存失败

确认已启用账号级下载器
确认账号已加入目标频道
尝试降低并发：/file_concurrency 1 + /download_workers 4

用途	方案
个人影音库	TG-Vault → R2 存储 → Emby/Jellyfin
团队文件共享	TG-Vault → WebDAV（坚果云）
频道自动备份	TG-Vault + 订阅同步 → OneDrive
轻量图床	TG-Vault → R2 + 自定义域名

总结

TG-Vault 是目前开源生态中功能最完整的 Telegram 转存方案。核心优势：

✅ 完全自托管，数据在自己手里
✅ 多存储源灵活组合
✅ Bot 交互 + Web 管理双重体验
✅ 频道订阅自动化，一次配置永久运行
✅ 开源 MIT 协议，可自由修改

项目地址：https://github.com/hicocos/tg-vault。有问题欢迎去 GitHub Issues 反馈。

分享