diff --git a/README.md b/README.md index ba77061..77044ec 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -> 本地保存位置：新安装可选服务器目录；升级保留原挂载、不迁移。详见 [本地存储位置](docs/local-storage.md)。 -
TG Vault Logo @@ -19,7 +17,7 @@ · Bot 命令 · - 生产部署 + 部署指南

@@ -29,7 +27,6 @@ Forks

- Release v2.4.3 Telegram Bot Docker Compose React TypeScript @@ -43,282 +40,90 @@ ## ✨ 功能概览 -- **Web 管理** — 文件上传、分片大文件上传、文件夹、预览、删除和存储源管理 -- **多存储源** — 本地、OneDrive、Google Drive、阿里云 OSS、S3 兼容存储和 WebDAV -- **账号级下载器** — 频道/群组按日期或标签批量抓取、订阅同步和大文件下载 -- **自动归档** — 默认按来源、频道和文件类型保存，例如 `telegram/channel/images/file.jpg` -- **安全防护** — 首次初始化管理员、HttpOnly Cookie、Origin 校验、签名 URL 和 TOTP 双重验证 - +- **文件管理**：上传、预览、整理文件夹，在浏览器中管理归档内容。 +- **Telegram 转存**：发送文件给 Bot，或从频道、群组批量保存媒体。 +- **订阅同步**：订阅频道，自动保存后续更新。 +- **多种存储**：支持本地磁盘、OneDrive、Google Drive、OSS、S3 和 WebDAV。 +- **自动归档**：按来源、频道和文件类型整理文件。 +- **访问保护**：管理员登录、Bot 用户权限和双重验证。 --- ## 🚀 快速部署 (Docker Compose) -需要 Linux、Bash 4+、Python 3.6+、Git、Docker Engine、Compose 插件和 Buildx，以及已解析到服务器的 Web/API 域名。HTTPS 由宿主机反向代理提供，不包含在 Compose 中。 +准备一台 Linux 服务器，以及用于网页和 API 的两个域名。 -默认构建包含 SBOM/provenance，需要 Compose 2.39+ 和支持构建证明的 builder/镜像存储。较旧环境可主动选择 `--compat`（验证基线为 Compose 2.18+），代价是本次构建不生成这些证明；不改变应用和数据库配置。安装器按实际能力检查，不支持 `docker-compose` v1。详见[部署指南](deploy/DEPLOY.md)。 - -### 1. 克隆仓库 +### 1. 下载项目 ```bash git clone https://github.com/hicocos/tg-vault.git cd tg-vault ``` -### 2. 运行安装向导 +### 2. 运行一键脚本 ```bash ./deploy/install.sh ``` -安装器先检查源码更新和运行环境。缺少组件时，可选择从现有仓库安装、查看手动安装提示或退出；只有输入 `1` 才会安装软件，按 Enter 不授权安装。首次部署填写 Web 和 API 的 HTTPS 地址，确认后生成 `.env`、数据库密码和应用密钥，再构建并启动服务。 +按提示检查环境，填写 Web 和 API 地址，确认后开始安装。 -安装器先等待 PostgreSQL 健康，再启动前后端；升级时保留数据库容器和持久卷。后续使用同一命令更新，详情见[维护与更新](#-维护与更新)。 +### 3. 开始使用 -- **配置 HTTPS** - 将 Web 域名代理到 `127.0.0.1:47832`，API 域名代理到 `127.0.0.1:51947`，为两个入口配置证书后再初始化管理员。 -- **启用 Telegram Bot 基础能力** - 首次打开 Web 并完成管理员初始化后，进入 **设置 → Telegram → Telegram Bot 连接**，填写 Bot Token、API ID、API Hash 和 Bot PIN。凭证会加密保存且不回显；不要把这些内容写入 `.env`。 -- **启用账号级 Telegram 下载器** - 需要频道/群组批量抓取、订阅同步或大文件下载时，再在 **设置 → Telegram → Telegram 账号下载器** 中登录。session 加密保存在服务端。 +按照[部署指南](deploy/DEPLOY.md#4-配置宿主机反向代理)为两个域名配置 HTTPS，然后打开网页创建管理员账号。 -> [!IMPORTANT] -> `VITE_API_URL` 会打包进前端静态文件。修改该地址后必须重新运行 `deploy/install.sh`；仅重启容器不会更新 API 地址。 +进入 **设置 → Telegram** 连接 Bot；需要频道转存或订阅同步时，再登录 Telegram 账号。其他存储服务可在 **设置 → 存储** 中添加。 ---- - -## 🛠️ 环境变量配置 - -常用变量如下，完整模板见 [`.env.example`](.env.example)。 - -

-新手只需填写（2 项） - -- **`VITE_API_URL`** — 前端访问后端的公网地址；示例：`https://api.example.com` -- **`CORS_ORIGIN`** — 允许跨域的前端来源；示例：`https://cloud.example.com` - -两项填写完整 origin（协议、域名及可选端口），不带路径、查询参数或末尾 `/`；生产环境使用 HTTPS。安装器会询问并校验地址，无需预先复制模板。若已复制 `.env.example`，必须将示例地址换成实际域名；按 Enter 会保留已有值。 - -
- -
-安装脚本自动生成 - -- **`DB_PASSWORD`** — 自动生成 64 位十六进制 PostgreSQL 密码 -- **`SESSION_SECRET`** / **`STORAGE_CREDENTIALS_SECRET`** — 新安装时自动生成并保留；升级旧部署时不会覆盖 `/data/secrets` 中已有的持久密钥 - -版本号不保存在 `.env`。安装时会直接从 `backend/package.json` 读取应用版本，并从当前 Git 提交读取源码修订号，只把它们临时传给 Docker 构建。 - -
- -
-高级部署覆盖 - -- **`OAUTH_CALLBACK_BASE_URL`** — 默认继承 `VITE_API_URL`；仅特殊 API 入口时填写 -- **`OAUTH_FRONTEND_ORIGIN`** — 默认继承 `CORS_ORIGIN` 的第一个地址；仅多前端入口时填写 - -
- -
-Telegram 运行配置 - -Telegram 凭证、允许用户、账号登录、来源白名单和下载并发均属于运行配置，统一在 Web **设置 → Telegram** 中管理。新部署不需要在 `.env` 中填写 Telegram 变量，也不需要手动生成 session 文件。 - -旧版本 `.env` 变量仍会被兼容读取，但只用于升级和迁移；不要在新部署中同时维护两套配置。Web 中的设置优先于环境变量。 - -
- -
-常用可选项 - -- **`PORT`** `51947` — 后端监听端口 -- **`UPLOAD_DIR`** `/data/uploads` · **`THUMBNAIL_DIR`** `/data/thumbnails` · **`CHUNK_DIR`** `/data/chunks` -- **`DUPLICATE_FILE_MODE`** `copy` — `copy` 生成副本；`skip` 跳过同名、同目录且同大小的文件 -- **`AUTO_CLEANUP_ORPHANS`** `true` — 自动清理未登记到数据库的本地孤儿文件 - -
- -
-限流与安全项 - -- **普通消息限流** — `TELEGRAM_RATE_WINDOW_MS=60000`，`TELEGRAM_RATE_MAX=30` -- **重型命令限流** — `TELEGRAM_HEAVY_RATE_WINDOW_MS=600000`，`TELEGRAM_HEAVY_RATE_MAX=5` -- **`TRUST_PROXY`** `loopback` · **`COOKIE_SECURE`** `true` · **`JSON_BODY_LIMIT`** `2mb` -- **分片限制** — `MAX_UPLOAD_CHUNK_MB=32`，`MAX_CHUNK_UPLOAD_GB=20`，`CHUNK_GLOBAL_BUDGET_GB=40` -- **磁盘与数量保护** — `CHUNK_DISK_RESERVE_GB=8`，`MAX_TOTAL_CHUNKS=50000` -- **`ORPHAN_CLEANUP_MIN_AGE_MS`** `600000` — 10 分钟内不清理本地孤儿文件 - -
- ---- - -## 🤖 Telegram 配置与能力 - -### Bot 与账号级下载器的区别 - -**只启用 Bot 即可使用：** - -- ✅ 私聊发送文件给 Bot 转存 -- ✅ 任务管理、存储统计和删除文件 - -**额外启用账号级下载器后增加：** - -- ✅ 频道/群组按日期或标签批量抓取 -- ✅ 频道订阅自动同步 -- ✅ 下载受 Bot 限制影响的大文件（仍受 Telegram 账号权限和限流约束） - -### 获取 Bot Token - -1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather) 并开始对话。 -2. 发送 `/newbot`，按提示创建机器人。 -3. 复制 BotFather 返回的 `HTTP API TOKEN`。 -4. 在 TG Vault Web 的“设置 → Telegram”中填写 Token。 - -### 获取 API ID 和 API Hash - -1. 访问 [my.telegram.org](https://my.telegram.org) 并登录 Telegram 账号。 -2. 进入 `API development tools`。 -3. 创建应用后复制 `api_id` 和 `api_hash`。 -4. 在 **设置 → Telegram → Telegram Bot 连接** 中与 Bot Token 一起填写，先测试连接，再保存并启用。 -5. 需要账号级下载器时，在同页使用手机号、验证码和可选两步验证密码登录；无需手工生成或编辑 session 文件。 - -### Telegram Bot 允许用户 - -TG Vault 会限制能通过 Bot PIN 登录的 Telegram 用户。推荐进入 **设置 → Telegram → Telegram Bot 用户权限**，填写一个或多个数字 user id；多个 ID 用英文逗号分隔。 - -获取 user id：让用户在 Telegram 私聊 `@userinfobot` 查看 `Id`。如果允许列表留空，并且后台还没有任何 Telegram 用户认证成功，第一个正确输入 Bot PIN 的用户可自动加入允许列表。之后应在 Web 中明确维护列表。 - -### 账号级下载器什么时候需要？ - -账号级下载器使用登录的 Telegram 用户账号读取媒体，适用于： - -- 频道/群组转存：用户账号需要加入对应频道/群组，并确保能看到历史媒体。 -- 按日期/标签批量抓取：`/tg_download date`、`/tg_download tag` 依赖用户账号访问来源消息。 -- 频道订阅同步：`/tg_sub` 后台扫描依赖用户账号读取频道/群组新消息。 -- 大文件下载：Bot 无法直接下载的文件，可尝试通过有访问权限的用户账号下载。 - -仅登录或明确启用账号时才应连接个人账号；更改界面语言或查看设置不应激活账号。只转存有权访问和保存的内容，遵守 Telegram 限流；遇到冷却或账号限制时，不要反复重试或提高并发。 - -### Telegram 下载设置 - -下载并发在 Web **设置 → 维护 → 高级任务设置** 中调整。先查看适用范围和风险提示，保留默认值，确有需要时再修改；不要通过提高并发绕过账号冷却。 +[查看完整部署指南](deploy/DEPLOY.md) · [Telegram 配置说明](docs/configuration.md#-telegram-配置与能力) --- ## 🧭 Telegram Bot 命令 -
-常用命令 +连接 Bot 后，发送 `/start` 开始使用，发送 `/help` 查看帮助。 -- `/start` 认证 · `/help` 帮助 · `/list [数量] [页码]` 最近文件 -- `/delete <至少 8 位 ID 前缀>` 删除文件 · `/setup_2fa` 配置 TOTP +| 命令 | 用途 | +| --- | --- | +| `/list` | 查看最近文件 | +| `/tasks` | 查看和管理任务 | +| `/storage` | 查看存储状态 | +| `/path_rules` | 设置保存位置 | +| `/tg_download` | 打开频道、群组下载向导 | +| `/tg_sub` | 添加频道订阅 | +| `/tg_subs` | 查看订阅 | -
+频道下载与订阅需要登录有访问权限的 Telegram 账号。
-任务、下载与清理设置 +更多命令 -- **任务控制** — `/task_pause [任务ID]` · `/task_resume [任务ID]` · `/task_cancel <任务ID或all>` · `/stop_tasks` -- **并发设置** — `/download_workers`（别名 `/workers`）· `/file_concurrency`（别名 `/file_workers`、`/download_files`） -- **文件策略** — `/duplicate_mode`（别名 `/duplicate`、`/dup`）· `/cleanup_settings`（别名 `/cleanup`） - -> Web 设置中的“删除任务历史”、`/cleanup_settings` 管理的临时文件清理，以及 `/storage` 中删除本地实体文件，是三类不同操作；危险操作均需单独确认。 +- **文件管理**：`/delete <至少 8 位 ID 前缀>` 删除文件；`/setup_2fa` 设置双重验证。 +- **任务控制**：`/task_pause [任务ID]`、`/task_resume [任务ID]`、`/task_cancel <任务ID或all>`、`/stop_tasks`。 +- **保存目录**：`/p <目录>` 仅用于下一次下载；`/ps <目录>` 用于当前会话；`/pc` 清除自定义目录。 +- **批量下载**：`/tg_download date <频道> <开始日期> <结束日期>`、`/tg_download tag <频道> <#标签>`。 +- **订阅与重试**：`/tg_unsub <频道或订阅ID前缀>` 取消订阅；`/tg_retry [数量] [任务ID]` 重试失败任务。 +- **下载设置**：`/download_workers`、`/file_concurrency`、`/duplicate_mode`、`/cleanup_settings`。
-
-保存位置命令 - -- `/path_rules` — 打开保存位置面板；别名 `/path`、`/save_rules` -- `/p <目录>` — 仅下一次下载使用该目录 -- `/ps <目录>` — 当前会话持续使用该目录 -- `/pc` — 清除下一次 / 本会话自定义目录 - -未设置时按来源、频道和文件类型自动归档；设置后直接保存到指定目录。 - -
- -
-频道/群组转存与订阅（需要账号级下载器） - -- `/tg_download` — 打开按日期 / 标签下载向导；别名 `/tg_dl` -- `/tg_download date <频道> <开始日期> <结束日期>` — 按日期范围抓取 -- `/tg_download tag <频道> <#标签>` — 按标签抓取 -- `/tg_retry [数量] [任务ID]` — 重试失败任务 -- `/tg_sub <频道>` · `/tg_subs` · `/tg_unsub <频道或订阅ID前缀>` — 添加、查看和取消订阅 - -兼容旧命令 `/tg_date`、`/tg_tag`。多文件达到 9 个及以上时自动静默排队，可用 `/tasks` 查看进度。 - -
- ---- - -## 🔐 安全与访问控制 - -TG Vault 默认采用“首次初始化”模式保护 Web 和 API： - -1. 服务启动后，首次访问 Web 页面需创建至少 8 位的管理员密码，使用 `scrypt` 加盐哈希保存到数据库。请在开放给其他用户前完成初始化。 -2. 如果此时已经通过环境变量配置 Telegram Bot，初始化页还会要求创建 Bot 4 位 PIN；新安装也可以先完成网页初始化，再到 **设置 → Telegram** 配置 Bot 和 PIN。 -3. 登录成功后，浏览器会获得 HttpOnly Cookie 会话，前端不再把访问 token 写入 `localStorage`。 -4. 修改类请求会校验 `Origin`，请确保 `.env` 中的 `CORS_ORIGIN` 与前端公网地址一致。 - -> [!IMPORTANT] -> 生产环境请使用 HTTPS。默认 `COOKIE_SECURE=true` 时，浏览器只会在 HTTPS 下发送登录 Cookie；如果你只在本地 HTTP 调试，可临时设置 `COOKIE_SECURE=false`。 -> `deploy/install.sh` 生成的正式部署会额外写入 `COOKIE_SECURE_FORCE=true`，防止遗留环境值意外关闭 HTTPS Cookie；本地 HTTP 调试请不要沿用该强制值，或同时设为 `false`。 - -### 自动密钥说明 - -安装器为新部署生成 `.env` 密钥；未显式配置的内部密钥由应用保存到数据卷的 `/data/secrets/`。迁移时同时备份 `.env`、数据库和完整数据卷。丢失密钥可能导致登录会话失效，TOTP 和第三方存储凭证无法解密。 - -完整的宿主机 Nginx 部署、健康检查、协调备份与隔离恢复校验流程见 [`deploy/DEPLOY.md`](deploy/DEPLOY.md)。仓库提供 `deploy/backup.sh` 和只读归档检查脚本 `deploy/restore-verify.sh`；备份包含密钥材料，必须加密并异地保存。 - -### 双重验证 (TOTP) - -TG Vault 内置支持 TOTP 双重验证（如 Google Authenticator）： - -- Web 端：在个人设置中扫码激活 -- Telegram Bot：发送 `/setup_2fa` 获取设置二维码，并在对话框输入验证码激活 -- 启用后，网页登录和使用 Bot 均需二次验证 - ---- - -## 🌐 反向代理建议 - -如果你使用 Nginx、Nginx Proxy Manager 或 Caddy 部署，请参考以下映射： - -- **前端 / 网页入口** - - 示例域名：`https://cloud.example.com` - - 转发地址：`127.0.0.1:47832` -- **后端 / API 接口** - - 示例域名：`https://api.example.com` - - 转发地址：`127.0.0.1:51947` - -如果前后端使用不同域名，请在后端环境变量中设置： - -```env -VITE_API_URL=https://api.example.com -CORS_ORIGIN=https://cloud.example.com -COOKIE_SECURE=true -``` - -> [!CAUTION] -> 开启 HTTPS 后，`.env` 中的 `VITE_API_URL` 和 `CORS_ORIGIN` 都应使用 `https://`，否则浏览器可能拦截请求。修改 `VITE_API_URL` 后必须重新构建前端镜像，因为它会被打包进静态文件。 - --- ## 🔄 维护与更新 -升级前先备份 `.env`、数据库和文件卷，并安排短暂的服务中断。然后从项目目录运行： +进入自己的 TG Vault 项目目录，运行一键升级脚本： ```bash ./deploy/install.sh ``` -- 自动拉取当前分支的最新代码；遇到本地修改、detached HEAD 或无法快进的更新会停止，不强制覆盖文件。 -- 已有地址按 Enter 保留，输入 `e` 返回编辑。已手动更新源码或需要离线部署时，主动添加 `--skip-source-update`。 -- 仅重建前后端；已有 PostgreSQL 容器使用 `--no-recreate` 保留，停止的数据库会恢复启动。健康检查通过后才报告完成。 +--- -不要用 `docker compose down -v` 排查安装故障，它会永久删除持久化数据。清理 Docker 资源前先检查影响范围，并保留回滚所需的镜像。 +## 📚 文档 + +- [部署指南](deploy/DEPLOY.md)：安装、域名配置、环境兼容与故障排查。 +- [配置与使用](docs/configuration.md)：Telegram 接入、访问权限与高级配置。 +- [本地存储位置](docs/local-storage.md)：选择和查看文件保存目录。 +- [版本更新](https://github.com/hicocos/tg-vault/releases)：查看新增功能与修复。 --- diff --git a/backend/src/services/reproducibleBuildContract.test.ts b/backend/src/services/reproducibleBuildContract.test.ts index dc09303..87a1244 100644 --- a/backend/src/services/reproducibleBuildContract.test.ts +++ b/backend/src/services/reproducibleBuildContract.test.ts @@ -68,8 +68,12 @@ test('installer keeps beginner input to two public origins and derives the rest' assert.match(envExample, /高级覆盖：OAuth/); assert.doesNotMatch(envExample, /^TELEGRAM_/m); assert.match(envExample, /Telegram 不在这里配置/); - assert.match(readme, /新手只需填写（2 项）/); - assert.match(readme, /不要把这些内容写入 `.env`/); + assert.match(readme, /填写 Web 和 API 地址/); + assert.match(readme, /设置 → Telegram/); + assert.match(readme, /docs\/configuration\.md/); + const configurationGuide = fs.readFileSync(new URL('../../../docs/configuration.md', import.meta.url), 'utf8'); + assert.match(configurationGuide, /新手只需填写（2 项）/); + assert.match(configurationGuide, /新部署不需要在 `.env` 中填写 Telegram 变量/); assert.match(deployGuide, /首次运行只需要填写以下 2 项/); assert.match(deployGuide, /Telegram 不属于首次部署的 `.env` 配置/); assert.match(deployGuide, /docker inspect/); diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..2464fb1 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,168 @@ +# 配置与使用指南 + +[返回首页](../README.md) · [部署指南](../deploy/DEPLOY.md) + +## 🛠️ 环境变量配置 + +常用变量如下，完整模板见 [`.env.example`](../.env.example)。 + +
+新手只需填写（2 项） + +- **`VITE_API_URL`** — 前端访问后端的公网地址；示例：`https://api.example.com` +- **`CORS_ORIGIN`** — 允许跨域的前端来源；示例：`https://cloud.example.com` + +两项填写完整 origin（协议、域名及可选端口），不带路径、查询参数或末尾 `/`；生产环境使用 HTTPS。安装器会询问并校验地址，无需预先复制模板。若已复制 `.env.example`，必须将示例地址换成实际域名；按 Enter 会保留已有值。 + +
+ +
+安装脚本自动生成 + +- **`DB_PASSWORD`** — 自动生成 64 位十六进制 PostgreSQL 密码 +- **`SESSION_SECRET`** / **`STORAGE_CREDENTIALS_SECRET`** — 新安装时自动生成并保留；升级旧部署时不会覆盖 `/data/secrets` 中已有的持久密钥 + +版本号不保存在 `.env`。安装时会直接从 `backend/package.json` 读取应用版本，并从当前 Git 提交读取源码修订号，只把它们临时传给 Docker 构建。 + +
+ +
+高级部署覆盖 + +- **`OAUTH_CALLBACK_BASE_URL`** — 默认继承 `VITE_API_URL`；仅特殊 API 入口时填写 +- **`OAUTH_FRONTEND_ORIGIN`** — 默认继承 `CORS_ORIGIN` 的第一个地址；仅多前端入口时填写 + +
+ +
+Telegram 运行配置 + +Telegram 凭证、允许用户、账号登录、来源白名单和下载并发均属于运行配置，统一在 Web **设置 → Telegram** 中管理。新部署不需要在 `.env` 中填写 Telegram 变量，也不需要手动生成 session 文件。 + +旧版本 `.env` 变量仍会被兼容读取，但只用于升级和迁移；不要在新部署中同时维护两套配置。Web 中的设置优先于环境变量。 + +
+ +
+常用可选项 + +- **`PORT`** `51947` — 后端监听端口 +- **`UPLOAD_DIR`** `/data/uploads` · **`THUMBNAIL_DIR`** `/data/thumbnails` · **`CHUNK_DIR`** `/data/chunks` +- **`DUPLICATE_FILE_MODE`** `copy` — `copy` 生成副本；`skip` 跳过同名、同目录且同大小的文件 +- **`AUTO_CLEANUP_ORPHANS`** `true` — 自动清理未登记到数据库的本地孤儿文件 + +
+ +
+限流与安全项 + +- **普通消息限流** — `TELEGRAM_RATE_WINDOW_MS=60000`，`TELEGRAM_RATE_MAX=30` +- **重型命令限流** — `TELEGRAM_HEAVY_RATE_WINDOW_MS=600000`，`TELEGRAM_HEAVY_RATE_MAX=5` +- **`TRUST_PROXY`** `loopback` · **`COOKIE_SECURE`** `true` · **`JSON_BODY_LIMIT`** `2mb` +- **分片限制** — `MAX_UPLOAD_CHUNK_MB=32`，`MAX_CHUNK_UPLOAD_GB=20`，`CHUNK_GLOBAL_BUDGET_GB=40` +- **磁盘与数量保护** — `CHUNK_DISK_RESERVE_GB=8`，`MAX_TOTAL_CHUNKS=50000` +- **`ORPHAN_CLEANUP_MIN_AGE_MS`** `600000` — 10 分钟内不清理本地孤儿文件 + +
+ +## 🤖 Telegram 配置与能力 + +### Bot 与账号级下载器的区别 + +**只启用 Bot 即可使用：** + +- ✅ 私聊发送文件给 Bot 转存 +- ✅ 任务管理、存储统计和删除文件 + +**额外启用账号级下载器后增加：** + +- ✅ 频道/群组按日期或标签批量抓取 +- ✅ 频道订阅自动同步 +- ✅ 下载受 Bot 限制影响的大文件（仍受 Telegram 账号权限和限流约束） + +### 获取 Bot Token + +1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather) 并开始对话。 +2. 发送 `/newbot`，按提示创建机器人。 +3. 复制 BotFather 返回的 `HTTP API TOKEN`。 +4. 在 TG Vault Web 的“设置 → Telegram”中填写 Token。 + +### 获取 API ID 和 API Hash + +1. 访问 [my.telegram.org](https://my.telegram.org) 并登录 Telegram 账号。 +2. 进入 `API development tools`。 +3. 创建应用后复制 `api_id` 和 `api_hash`。 +4. 在 **设置 → Telegram → Telegram Bot 连接** 中与 Bot Token 一起填写，先测试连接，再保存并启用。 +5. 需要账号级下载器时，在同页使用手机号、验证码和可选两步验证密码登录；无需手工生成或编辑 session 文件。 + +### Telegram Bot 允许用户 + +TG Vault 会限制能通过 Bot PIN 登录的 Telegram 用户。推荐进入 **设置 → Telegram → Telegram Bot 用户权限**，填写一个或多个数字 user id；多个 ID 用英文逗号分隔。 + +获取 user id：让用户在 Telegram 私聊 `@userinfobot` 查看 `Id`。如果允许列表留空，并且后台还没有任何 Telegram 用户认证成功，第一个正确输入 Bot PIN 的用户可自动加入允许列表。之后应在 Web 中明确维护列表。 + +### 账号级下载器什么时候需要？ + +账号级下载器使用登录的 Telegram 用户账号读取媒体，适用于： + +- 频道/群组转存：用户账号需要加入对应频道/群组，并确保能看到历史媒体。 +- 按日期/标签批量抓取：`/tg_download date`、`/tg_download tag` 依赖用户账号访问来源消息。 +- 频道订阅同步：`/tg_sub` 后台扫描依赖用户账号读取频道/群组新消息。 +- 大文件下载：Bot 无法直接下载的文件，可尝试通过有访问权限的用户账号下载。 + +仅登录或明确启用账号时才应连接个人账号；更改界面语言或查看设置不应激活账号。只转存有权访问和保存的内容，遵守 Telegram 限流；遇到冷却或账号限制时，不要反复重试或提高并发。 + +### Telegram 下载设置 + +下载并发在 Web **设置 → 维护 → 高级任务设置** 中调整。先查看适用范围和风险提示，保留默认值，确有需要时再修改；不要通过提高并发绕过账号冷却。 + +## 🔐 安全与访问控制 + +TG Vault 默认采用“首次初始化”模式保护 Web 和 API： + +1. 服务启动后，首次访问 Web 页面需创建至少 8 位的管理员密码，使用 `scrypt` 加盐哈希保存到数据库。请在开放给其他用户前完成初始化。 +2. 如果此时已经通过环境变量配置 Telegram Bot，初始化页还会要求创建 Bot 4 位 PIN；新安装也可以先完成网页初始化，再到 **设置 → Telegram** 配置 Bot 和 PIN。 +3. 登录成功后，浏览器会获得 HttpOnly Cookie 会话，前端不再把访问 token 写入 `localStorage`。 +4. 修改类请求会校验 `Origin`，请确保 `.env` 中的 `CORS_ORIGIN` 与前端公网地址一致。 + +> [!IMPORTANT] +> 生产环境请使用 HTTPS。默认 `COOKIE_SECURE=true` 时，浏览器只会在 HTTPS 下发送登录 Cookie；如果你只在本地 HTTP 调试，可临时设置 `COOKIE_SECURE=false`。 +> `deploy/install.sh` 生成的正式部署会额外写入 `COOKIE_SECURE_FORCE=true`，防止遗留环境值意外关闭 HTTPS Cookie；本地 HTTP 调试请不要沿用该强制值，或同时设为 `false`。 + +### 自动密钥说明 + +安装器为新部署生成 `.env` 密钥；未显式配置的内部密钥由应用保存到数据卷的 `/data/secrets/`。迁移时同时备份 `.env`、数据库和完整数据卷。丢失密钥可能导致登录会话失效，TOTP 和第三方存储凭证无法解密。 + +完整的宿主机 Nginx 部署、健康检查、协调备份与隔离恢复校验流程见 [`deploy/DEPLOY.md`](../deploy/DEPLOY.md)。仓库提供 `deploy/backup.sh` 和只读归档检查脚本 `deploy/restore-verify.sh`；备份包含密钥材料，必须加密并异地保存。 + +### 双重验证 (TOTP) + +TG Vault 内置支持 TOTP 双重验证（如 Google Authenticator）： + +- Web 端：在个人设置中扫码激活 +- Telegram Bot：发送 `/setup_2fa` 获取设置二维码，并在对话框输入验证码激活 +- 启用后，网页登录和使用 Bot 均需二次验证 + +--- + +## 🌐 反向代理建议 + +如果你使用 Nginx、Nginx Proxy Manager 或 Caddy 部署，请参考以下映射： + +- **前端 / 网页入口** + - 示例域名：`https://cloud.example.com` + - 转发地址：`127.0.0.1:47832` +- **后端 / API 接口** + - 示例域名：`https://api.example.com` + - 转发地址：`127.0.0.1:51947` + +如果前后端使用不同域名，请在后端环境变量中设置： + +```env +VITE_API_URL=https://api.example.com +CORS_ORIGIN=https://cloud.example.com +COOKIE_SECURE=true +``` + +> [!CAUTION] +> 开启 HTTPS 后，`.env` 中的 `VITE_API_URL` 和 `CORS_ORIGIN` 都应使用 `https://`，否则浏览器可能拦截请求。修改 `VITE_API_URL` 后必须重新构建前端镜像，因为它会被打包进静态文件。