TG-Vault 部署与使用教程：Telegram 全自动转存到私有云

本文基于 hicocos/tg-vault 的 main 分支编写，核对版本为提交 2d6204b（2026-07-17）。该项目目前没有 GitHub Release 和 tag，生产环境若重视可复现性，建议部署时固定到已验证的提交，而不是长期无条件追踪 main。

TG Vault 是一个面向个人或小团队的 Telegram 转存与私有文件管理系统。它由 React 前端、Node.js 后端和 PostgreSQL 组成，既可以在网页里上传、预览、删除及管理文件，也能把 Telegram Bot 当作随手投递文件的入口。

它支持本地磁盘、OneDrive、Google Drive、阿里云 OSS、S3 兼容存储和 WebDAV。Telegram 侧还可以调用 yt-dlp 下载链接、按规则归档文件；登录 Telegram 用户账号后，则可进一步抓取频道/群组媒体和同步订阅。

先弄清两种 Telegram 模式

TG Vault 的 Bot 功能 与 账号级下载器 不是一回事：

只配置 Bot：可以私聊发送文件、查看任务和存储统计、删除文件、使用 /ytdlp。
再登录 Telegram 用户账号：才能按日期或标签抓取频道/群组媒体、自动同步订阅，并更稳定地处理超出 Bot 下载能力的大文件。

因此，如果只想把 Bot 当作私人上传入口，不必生成用户账号 Session。Session 权限更高，也更敏感，遵循“能不用就不用”的最小权限原则更稳妥。

一、部署前准备

建议准备：

一台已安装 Docker Engine 与 Docker Compose 插件的 Linux 服务器；
两个已解析到服务器的域名，例如：
- cloud.example.com：Web 前端；
- api.example.com：后端 API；
宿主机上的 Nginx、Caddy 或面板反向代理，用于申请证书并提供 HTTPS；
若启用 Telegram：Bot Token，以及 Telegram API ID/API Hash。

官方 Compose 不包含 Nginx 或 Certbot。它只启动 frontend、backend、postgres 三个服务，并把前后端分别绑定到宿主机回环地址：

127.0.0.1:47832 → 前端；
127.0.0.1:51947 → 后端。

这种绑定方式值得保留：外网只访问反向代理的 80/443 端口，不应直接放行 47832、51947 或 PostgreSQL。

二、获取代码并准备配置

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

生成数据库密码：

openssl rand -hex 32

然后编辑 .env：

nano .env

一个适合双域名、HTTPS 部署的基础示例如下。请替换示例域名和所有秘密值，不要原样使用：

DB_PASSWORD=替换为_openssl_rand_hex_32_生成的随机值

VITE_API_URL=https://api.example.com
CORS_ORIGIN=https://cloud.example.com
DOMAIN=cloud.example.com
COOKIE_SECURE=true

PORT=51947
UPLOAD_DIR=/data/uploads
THUMBNAIL_DIR=/data/thumbnails
CHUNK_DIR=/data/chunks

DUPLICATE_FILE_MODE=copy
AUTO_CLEANUP_ORPHANS=true

TELEGRAM_BOT_TOKEN=
TELEGRAM_API_ID=
TELEGRAM_API_HASH=
TELEGRAM_ALLOWED_USER_IDS=
TELEGRAM_USER_SESSION_FILE=/data/telegram_user_session.txt
TELEGRAM_DOWNLOAD_WORKERS=4
TELEGRAM_FILE_DOWNLOAD_CONCURRENCY=2

YTDLP_BIN=yt-dlp
YTDLP_WORK_DIR=./data/uploads/ytdlp
YTDLP_MAX_CONCURRENT=1

必须理解的几个变量

DB_PASSWORD：PostgreSQL 用户 tgvault 的密码，应使用高强度随机值。
VITE_API_URL：浏览器访问后端的公网地址，必须带 http:// 或 https://。它是前端构建时变量，修改后需要重新构建前端，而非只重启容器。
CORS_ORIGIN：允许发起跨域请求的前端 Origin，应是完整且精确的地址，例如 https://cloud.example.com，不要填写路径，也不建议随意设为 *。
DOMAIN：应用主域名，不带协议。
COOKIE_SECURE：生产环境保持 true，这样登录 Cookie 只经 HTTPS 发送。本地纯 HTTP 排错时才临时设为 false。
TRUST_PROXY：模板默认 loopback，宿主机反代到回环端口时通常无需修改。不要为了省事无条件信任所有代理。

项目会在首次运行时把内部密钥持久化到 /data/secrets/。也可以在 .env 中显式设置至少 32 字符的 SESSION_SECRET 和 STORAGE_CREDENTIALS_SECRET，但无论采用哪种方式，都必须安全保管；尤其不要把 .env 提交到 Git。

可分别生成：

openssl rand -hex 32
openssl rand -hex 32

三、配置 Telegram Bot

1. 创建 Bot

在 Telegram 私聊 @BotFather；
发送 /newbot；
按提示设置名称和以 bot 结尾的用户名；
保存 BotFather 返回的 HTTP API Token，并写入：

TELEGRAM_BOT_TOKEN=1234567890:请替换为真实Token

Bot Token 相当于机器人密码。若曾泄露，应立即在 BotFather 中撤销并重新生成。

2. 获取 API ID 与 API Hash

访问 my.telegram.org，使用自己的 Telegram 账号登录，进入 API development tools 创建应用，取得 api_id 与 api_hash：

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=请替换为真实APIHash

当前项目中，Bot 和账号级下载器共用这组 API 配置。

3. 限制允许使用 Bot 的用户

强烈建议预先设置 Telegram 数字用户 ID：

TELEGRAM_ALLOWED_USER_IDS=123456789,987654321

多个 ID 用英文逗号分隔。可以通过 Telegram 的 @userinfobot 查询自己的数字 ID。

若该项留空，且系统尚无任何 Telegram 用户认证成功，第一个正确输入 Bot PIN 的用户会被自动加入允许列表。这虽然方便首次安装，却会扩大初始化阶段的抢占风险，因此公网部署最好不要留空。初始化后也可在 Web 后台的“设置 → Telegram Bot 设置”维护名单。

四、校验、构建并启动

README 将前后端分开构建；Compose 文件本身也定义了构建参数。更简洁且不容易漏掉 VITE_API_URL 的做法是先验证配置，再由 Compose 一次完成构建和启动：

docker compose config --quiet
docker compose up -d --build
docker compose ps

如果希望完全按分步方式构建，可执行：

set -a
source .env
set +a

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

两套方法二选一即可，不需要重复执行。

修改 VITE_API_URL 后，至少要重新构建并创建前端容器。直接使用 docker compose up -d --build 最省心。

查看健康状态和后端日志：

docker compose ps
curl -fsS http://127.0.0.1:51947/livez
curl -fsS http://127.0.0.1:51947/readyz
docker compose logs --tail=100 backend frontend postgres

/livez 返回成功只说明后端进程还活着；/readyz 成功才表示数据库、存储和安全密钥等依赖已就绪。

五、可选：启用账号级 Telegram 下载器

只有需要频道/群组批量抓取、订阅同步或更稳定的大文件下载时，才执行：

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

按终端提示输入手机号、Telegram 登录验证码；若账号启用了 Telegram 云密码，还需输入该密码。命令会通过 Compose 的 /data 持久卷保存 Session，默认位置是：

TELEGRAM_USER_SESSION_FILE=/data/telegram_user_session.txt

生成后启动或重建服务：

docker compose up -d --build

安全提醒：这个 Session 代表已登录的 Telegram 用户账号，并不只是 Bot Token。任何能读取它的人都可能获得相应账号访问能力。不要把它复制到网页、聊天记录或代码仓库；备份也应加密。用于下载器的账号必须已经加入目标频道/群组，并有权查看历史消息。

六、配置 HTTPS 反向代理

推荐采用两个域名，分别反代：

公网入口	上游地址
`https://cloud.example.com`	`http://127.0.0.1:47832`
`https://api.example.com`	`http://127.0.0.1:51947`

反向代理至少应传递 Host、X-Real-IP、X-Forwarded-For 和 X-Forwarded-Proto。API 站点还要为上传设置合适的请求体上限及读写超时。若使用 Nginx，可按业务规模设置类似：

client_max_body_size 500M;
proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;

这里的 client_max_body_size 是反向代理限制；MAX_UPLOAD_CHUNK_MB 则是应用的单分片限制，两者不是同一个概念。仓库示例值为单片 64 MB，请让代理限制足够容纳实际请求。

启用 HTTPS 后确认：

VITE_API_URL=https://api.example.com
CORS_ORIGIN=https://cloud.example.com
COOKIE_SECURE=true

若前端能打开但登录或 API 请求失败，优先检查浏览器控制台中的 CORS、Mixed Content 和 Cookie 提示，再核对这三个变量是否与实际地址逐字一致。

七、首次初始化与 2FA

首次访问 https://cloud.example.com 时，系统会要求创建：

至少 8 位的网页管理员密码；
用于 Bot /start 认证的 4 位 PIN。

两者会使用 scrypt 加盐哈希后保存。登录后使用 HttpOnly Cookie，会对修改类请求校验 Origin。即便如此，4 位 PIN 的搜索空间仍然很小，因此必须配合 TELEGRAM_ALLOWED_USER_IDS，并建议随后启用 TOTP 双重验证：

Web：在个人设置中扫码开启；
Bot：发送 /setup_2fa，按对话完成绑定。

八、存储、并发与文件策略

Docker 中真正需要保留的数据

Compose 使用两个 named volume：

tg-vault_postgres-data：PostgreSQL 数据；
tg-vault_file-storage：/data 下的上传文件、缩略图、分片状态、日志、Telegram 用户 Session 和内部密钥等。

实际卷名前缀会受 Compose 项目名影响，可用下面的命令核对：

docker volume ls | grep tg-vault

docker compose down 默认不会删除 named volume；但 docker compose down -v 会删除卷，可能造成永久数据损失，不要在日常维护中使用。

重复文件与孤儿清理

DUPLICATE_FILE_MODE=copy
AUTO_CLEANUP_ORPHANS=true
ORPHAN_CLEANUP_MIN_AGE_MS=600000

copy：出现同名、同目录、同大小文件时生成副本；
skip：跳过这类重复文件；
自动孤儿清理会清除本地 uploads 中未登记到数据库的文件，默认保护最近 10 分钟内的文件。

如果手工向 volume 写文件、做迁移或排错，先关闭自动清理或确认文件已正确登记，避免它被当成孤儿文件删除。

Telegram 并发不要一味调高

Telegram 下载有两层并发：

TELEGRAM_FILE_DOWNLOAD_CONCURRENCY=2
TELEGRAM_DOWNLOAD_WORKERS=4

前者控制同时下载几个文件，后者控制单个文件内部并发拉取多少个约 512 KB 的分片。默认 2 × 4 是较稳妥起点；文件并发可设 1/2/3/4，分片 worker 可选 4/8/12/16。高并发可能触发 Telegram 限流、连接中断或远端存储限速，只有在网络和目标存储都稳定时再逐步增加。

九、常用 Bot 操作

通过 /start 完成 PIN（以及已启用时的 TOTP）验证后，可使用：

/storage：存储统计；
/tasks：任务队列；
/task_pause [任务ID]、/task_resume [任务ID]：暂停或恢复；
/task_cancel <任务ID或all>：取消任务；
/ytdlp <https://链接>：解析一个视频链接并保存到当前存储源；
/path_rules、/p <目录>、/ps <目录>、/pc：控制保存目录。

启用账号级下载器后，还可使用：

/tg_download date @channel 2026-01-01 2026-01-31
/tg_download tag @channel #壁纸
/tg_sub @channel
/tg_subs
/tg_unsub @channel

执行批量抓取前，先确认内容来源、下载和再存储行为符合频道规则及当地法律。

十、备份与恢复

仅备份上传目录是不够的。一次可恢复的备份应在同一维护窗口内包含：

PostgreSQL custom-format dump；
完整 file-storage 卷；
版本、时间和 SHA-256 清单。

仓库提供协调备份脚本。它会先检查空间，然后在数据库导出和 /data 归档期间停止后端，避免上传、删除或 Telegram 后台任务跨越两个快照：

chmod +x deploy/backup.sh deploy/restore-verify.sh
BACKUP_DIR=./backups ./deploy/backup.sh

备份会短暂停止 API，请安排维护窗口。备份包含 Session、TOTP 及第三方存储凭证等敏感材料，完成后应限制文件权限、加密并异地保存。

恢复前先做只读校验：

./deploy/restore-verify.sh ./backups/<backup-directory>

校验脚本不能代替恢复演练。建议定期在隔离环境恢复数据库与文件卷，并检查 /readyz、数据行数、文件完整性及加密凭证是否可读。

十一、更新与回滚意识

当前仓库没有 Release/tag。更新前先确认工作区和备份：

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

若 git status --short 有输出，先人工判断改动来源，不要用强制重置覆盖生产配置。更新后检查：

curl -fsS http://127.0.0.1:51947/livez
curl -fsS http://127.0.0.1:51947/readyz
docker compose logs --tail=100 backend frontend postgres

为了便于回滚，可在升级前记录当前提交：

git rev-parse HEAD

需要特别说明：仓库当前 deploy/DEPLOY.md 的更新示例仍写有 feat/telegram-task-center 分支，而仓库默认分支及最新 README 均使用 main。本文采用 main，避免把历史文档中的分支名带入生产命令。

十二、上线前安全检查清单

DB_PASSWORD、Bot Token、API Hash、Session 均未提交 Git；
TELEGRAM_ALLOWED_USER_IDS 已明确配置；
Web 与 API 均只通过 HTTPS 暴露；
47832、51947 只绑定 127.0.0.1，5432 未暴露公网；
CORS_ORIGIN 与实际前端 Origin 完全一致；
COOKIE_SECURE=true；
管理员密码足够长，Web 与 Bot 均启用了 TOTP；
已备份 PostgreSQL 与完整 /data，备份已加密并异地保存；
已测试 /livez、/readyz 和一次实际上传；
没有在日常命令中使用 docker compose down -v；
更新前记录提交 SHA，并阅读代码变更。

参考来源

TG Vault 仓库：https://github.com/hicocos/tg-vault
最新 README（main）：https://github.com/hicocos/tg-vault/blob/main/README.md
环境变量模板：https://github.com/hicocos/tg-vault/blob/main/.env.example
Docker Compose：https://github.com/hicocos/tg-vault/blob/main/docker-compose.yml
服务器部署与备份说明：https://github.com/hicocos/tg-vault/blob/main/deploy/DEPLOY.md
Nginx 示例：https://github.com/hicocos/tg-vault/blob/main/deploy/nginx-site.conf
协调备份脚本：https://github.com/hicocos/tg-vault/blob/main/deploy/backup.sh
本文核对的 main 提交：https://github.com/hicocos/tg-vault/commit/2d6204b2b3095a10d524e15358ae91dc70301552
Telegram BotFather：https://t.me/BotFather
Telegram API development tools：https://my.telegram.org

资料核对时间：2026-07-18（UTC）。项目迭代较快，正式部署前请再次比较 .env.example、docker-compose.yml 与 README。

菜单

分享