docs: simplify Chinese and English readmes
This commit is contained in:
hicocos committed
1 parent
179d80d0ff
commit
8ee66d7137
2 files changed
+34
-108
No files matched your search
@@ -6,23 +6,23 @@
|
||||
|
||||
# TG Vault
|
||||
|
||||
面向个人与小团队的 Telegram 文件转存、媒体归档和多存储源文件管理系统。在 Web 中管理文件，将 Telegram 私聊、频道或群组中有权保存的内容归档到自己的存储。
|
||||
Telegram 文件转存与归档工具，支持 Web 文件管理和多种存储服务。
|
||||
|
||||
[快速部署](#快速部署) · [Bot 命令](#telegram-bot-命令) · [部署指南](deploy/DEPLOY.md) · [English](README_EN.md)
|
||||
[快速部署](#快速部署) · [部署指南](deploy/DEPLOY.md) · [版本发布](https://github.com/hicocos/tg-vault/releases)
|
||||
|
||||
## 功能概览
|
||||
|
||||
- 文件上传、文件夹整理、搜索和媒体预览。
|
||||
- Telegram Bot 文件转存，频道/群组按日期或标签批量下载，频道订阅同步。
|
||||
- Web 与 Bot 任务管理：查看进度、保存去向和失败明细，暂停、继续、取消及重试。
|
||||
- 本地磁盘、OneDrive、Google Drive、阿里云 OSS、S3 和 WebDAV 存储，按来源与目录规则归档。
|
||||
- 管理员密码、Bot 用户允许列表与 PIN、TOTP 双重验证。
|
||||
- Telegram 文件转存、频道/群组按日期或标签批量下载、订阅同步。
|
||||
- Web 文件上传、搜索、文件夹整理与媒体预览。
|
||||
- Web 与 Bot 任务管理：进度、失败明细、暂停、继续及重试。
|
||||
- 本地磁盘、OneDrive、Google Drive、阿里云 OSS、S3 和 WebDAV 存储。
|
||||
- 管理员密码、Bot 用户允许列表与 TOTP 双重验证。
|
||||
|
||||
TG Vault 不是 Telegram 权限或下载限制的绕过工具。频道下载与订阅需要登录能访问来源的 Telegram 用户账号；仅向 Bot 发文件不要求登录个人账号。本项目的 Bot 下载使用 MTProto，而非 HTTP Bot API 的 `getFile`；不能套用后者的文件大小限制，也不能保证任意文件可下载。直接发送给 Bot 且没有可重读来源的文件仍由 Bot 下载，登录个人账号不会自动解除该路径的限制。详见[配置说明](docs/configuration.md#telegram-配置与能力)。
|
||||
频道下载与订阅需要有来源访问权限的 Telegram 用户账号，不绕过 Telegram 权限或服务端限制。
|
||||
|
||||
## 快速部署
|
||||
|
||||
准备 Linux 服务器、Docker Compose，以及同一主域名下的 Web/API 两个 HTTPS 地址，例如 `cloud.example.com` 与 `api.example.com`。证书和反向代理由宿主机或管理面板提供。
|
||||
准备 Linux 服务器、Docker Compose，以及同一主域名下的 Web/API 两个 HTTPS 域名。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/hicocos/tg-vault.git
|
||||
@@ -30,67 +30,30 @@ cd tg-vault
|
||||
./deploy/install.sh
|
||||
```
|
||||
|
||||
首次安装无需预先复制 `.env.example`。按提示填写 Web/API 地址和新的专用文件目录；安装器生成数据库密码及应用密钥，默认拉取 GHCR 的 `ghcr.io/hicocos/tg-vault-backend:latest`、`ghcr.io/hicocos/tg-vault-frontend:latest`，无需本机编译。文件目录默认是安装目录下的 `data`，已有部署保留原挂载，不自动迁移文件。
|
||||
默认从 GHCR 拉取最新镜像，支持 amd64/arm64，无需登录或本机编译；拉取失败时自动源码构建兜底。首次安装**不要预先复制 `.env.example`**，按提示填写地址和文件保存目录。
|
||||
|
||||
1. 按[部署指南](deploy/DEPLOY.md#4-配置宿主机反向代理)配置 Web → `127.0.0.1:47832`、API → `127.0.0.1:51947` 的 HTTPS 反向代理。
|
||||
2. **首次初始化前限制两个入口的访问，仅允许自己访问。** 第一个完成初始化的人会设置管理员密码；没有默认管理员密码。通过 HTTPS 创建至少 8 位的强密码后再开放服务。
|
||||
3. 在 **设置 → Telegram** 填写 Bot Token、API ID、API Hash，设置 Bot PIN 与数字用户 ID 允许列表。频道下载或订阅还需要在同页登录个人 Telegram 账号。
|
||||
4. 在 **设置 → 存储** 添加其他存储账户；妥善备份配置、数据库和完整 `/data`。
|
||||
1. 按[部署指南](deploy/DEPLOY.md#4-配置宿主机反向代理)配置 HTTPS：Web → `127.0.0.1:47832`，API → `127.0.0.1:51947`。
|
||||
2. **初始化前仅允许自己访问两个入口**，打开网页设置管理员密码，再开放服务。
|
||||
3. 在 **设置 → Telegram** 连接 Bot、配置用户权限；需要频道下载或订阅时，再登录 Telegram 用户账号。
|
||||
|
||||
镜像拉取失败、平台不受支持或前后端发布不一致时，脚本自动尝试本地源码构建；也可用 `./deploy/install.sh --build` 强制构建，旧构建环境加 `--compat`。每次更新均拉取 `latest`，不锁定版本；升级前务必备份。详见[完整部署指南](deploy/DEPLOY.md)。
|
||||
|
||||
## Telegram Bot 命令
|
||||
|
||||
连接后发送 `/start` 验证身份，发送 `/help` 查看完整命令和参数。文件浏览与搜索使用 Web。
|
||||
|
||||
| 命令 | 用途 |
|
||||
| --- | --- |
|
||||
| `/tasks` | 查看任务、进度与控制按钮 |
|
||||
| `/storage` | 查看存储状态 |
|
||||
| `/path_rules` | 设置保存位置与目录规则 |
|
||||
| `/target` | 设置当前聊天的存储目标 |
|
||||
| `/tg_download` | 打开频道/群组日期或标签下载向导 |
|
||||
| `/tg_sub`、`/tg_subs` | 管理和查看订阅 |
|
||||
| `/tg_retry` | 重试失败任务 |
|
||||
| `/setup_2fa` | 设置 TOTP 双重验证 |
|
||||
|
||||
频道任务的处理进度包括成功、失败和跳过，100% 不等于全部成功。扫描总量可能未知；排队或 Telegram 冷却不代表正在传输。暂停阻止后续读取，但已发出的请求和存储写入可能仍需收尾。
|
||||
Bot 发送 `/start` 开始，`/help` 查看命令。强制源码构建使用 `./deploy/install.sh --build`；更多选项见[部署指南](deploy/DEPLOY.md)。
|
||||
|
||||
## 备份与更新
|
||||
|
||||
从项目根目录执行协调备份，再运行安装器更新：
|
||||
升级前备份 `.env`、数据库和完整文件数据，然后在项目目录运行：
|
||||
|
||||
```bash
|
||||
BACKUP_DIR=/path/to/secure-backups ./deploy/backup.sh
|
||||
./deploy/restore-verify.sh /path/to/secure-backups/<timestamp>
|
||||
./deploy/install.sh
|
||||
```
|
||||
|
||||
备份脚本在归档期间停止 backend，结束时恢复其原运行状态。**另行安全备份 `.env` 和反向代理配置**；脚本只包含数据库、完整 `/data` 与校验清单，不包含远端存储的文件。归档校验不是恢复演练。升级自动应用数据库迁移，回退时必须考虑数据库与文件的一致性，不要直接覆盖旧版本。不要用 `docker compose down -v` 排障。详见[备份与恢复](deploy/DEPLOY.md#7-备份与恢复)。
|
||||
|
||||
## 本地构建与贡献
|
||||
|
||||
容器构建使用 Node.js 24；本地构建也建议使用 Node.js 24 和 npm。两个子项目分别安装依赖与构建：
|
||||
|
||||
```bash
|
||||
npm --prefix backend ci
|
||||
npm --prefix frontend ci
|
||||
npm --prefix backend run build
|
||||
npm --prefix frontend run build
|
||||
```
|
||||
|
||||
本地运行后端还需要 PostgreSQL 和 `DATABASE_URL`；缩略图/转码需要 ffmpeg。开发启动与环境要求见[配置说明](docs/configuration.md#本地开发)。提交变更时说明用途、复现步骤与实际执行的检查；保留锁文件，并同步中英文说明。数据库结构变更应同步 schema、迁移和 `init.sql`，不要改写已发布迁移。
|
||||
|
||||
GitHub Actions 使用仓库自带的 `GITHUB_TOKEN` 发布 amd64/arm64 通用镜像，无需额外注册表凭据；仅发布任务获授 `packages: write`。首次发布后，维护者需在 GitHub Packages 中将两个容器包的可见性设为 Public，安装者才能匿名拉取。API 地址在容器启动时通过 `VITE_API_URL` 注入，无需为不同域名重新编译；该值公开可见，不能放入秘密。
|
||||
|
||||
发布、提交或共享问题日志前，确认不含 `.env`、Token、API Hash、密码、Cookie、Telegram session、数据库/备份、用户文件或服务器私有信息。不要提交 `node_modules`、`dist`、覆盖率、临时调试/冒烟脚本及本地执行报告；忽略规则不能移除已经进入 Git 历史的秘密，泄露后应撤销/轮换并清理历史。
|
||||
脚本更新源码并拉取 `latest`，保留原配置和数据挂载。详见[备份与恢复](deploy/DEPLOY.md#7-备份与恢复)；不要用 `docker compose down -v` 排障。
|
||||
|
||||
## 文档
|
||||
|
||||
- [部署指南](deploy/DEPLOY.md)：安装、HTTPS、备份、恢复与更新。
|
||||
- [配置与使用](docs/configuration.md)：环境变量、Telegram、存储与权限。
|
||||
- [本地存储位置](docs/local-storage.md)：挂载、路径确认与数据保护。
|
||||
- [版本发布](https://github.com/hicocos/tg-vault/releases)。
|
||||
- [本地开发](docs/configuration.md#本地开发)：开发环境与构建检查。
|
||||
|
||||
## 开源协议
|
||||
|
||||
|
||||
+17
-54
@@ -6,23 +6,23 @@
|
||||
|
||||
# TG Vault
|
||||
|
||||
Telegram file transfer, media archiving and multi-storage file management for individuals and small teams. Manage files in the web UI and archive content you are entitled to save from Telegram private chats, channels and groups to your own storage.
|
||||
Telegram file transfer and archiving with web file management and multiple storage providers.
|
||||
|
||||
[Quick start](#quick-start) · [Bot commands](#telegram-bot-commands) · [Deployment guide](deploy/DEPLOY.md) · [简体中文](README.md)
|
||||
[Quick start](#quick-start) · [Deployment guide](deploy/DEPLOY.md) · [Releases](https://github.com/hicocos/tg-vault/releases)
|
||||
|
||||
## Features
|
||||
|
||||
- File uploads, folder organization, search and media previews.
|
||||
- Telegram Bot transfers, channel/group batch downloads by date or tag, and channel subscription sync.
|
||||
- Web and Bot task management: progress, destinations, failure details, pause, resume, cancel and retry.
|
||||
- Local disk, OneDrive, Google Drive, Aliyun OSS, S3 and WebDAV storage, with source and directory rules for archiving.
|
||||
- Administrator password, Bot user allowlist and PIN, and TOTP two-factor authentication.
|
||||
- Telegram file transfers, channel/group batch downloads by date or tag, and subscription sync.
|
||||
- Web uploads, search, folder organization and media previews.
|
||||
- Web and Bot task management: progress, failure details, pause, resume and retry.
|
||||
- Local disk, OneDrive, Google Drive, Aliyun OSS, S3 and WebDAV storage.
|
||||
- Administrator password, Bot user allowlist and TOTP two-factor authentication.
|
||||
|
||||
TG Vault does not bypass Telegram permissions or download restrictions. Channel downloads and subscriptions require a Telegram user account with access to the source; sending files directly to the Bot does not require a personal account. Bot downloads in this project use MTProto, not the HTTP Bot API's `getFile`: its size limit cannot simply be applied here, and arbitrary files are not guaranteed to download. Direct Bot messages without a readable original source still use Bot downloads; adding a personal account does not automatically remove that path's restrictions. See [configuration](docs/configuration.md#telegram-配置与能力).
|
||||
Channel downloads and subscriptions require a Telegram user account with source access. TG Vault does not bypass Telegram permissions or server limits.
|
||||
|
||||
## Quick start
|
||||
|
||||
Prepare a Linux server, Docker Compose, and two HTTPS addresses under the same parent domain, such as `cloud.example.com` and `api.example.com`. The host or your management panel provides certificates and the reverse proxy.
|
||||
Prepare a Linux server, Docker Compose, and Web/API HTTPS domains under the same parent domain.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/hicocos/tg-vault.git
|
||||
@@ -30,67 +30,30 @@ cd tg-vault
|
||||
./deploy/install.sh
|
||||
```
|
||||
|
||||
Do not copy `.env.example` before a fresh installer run. Enter your Web/API addresses and a new dedicated storage directory. The installer generates the database password and application keys, then pulls `ghcr.io/hicocos/tg-vault-backend:latest` and `ghcr.io/hicocos/tg-vault-frontend:latest` from GHCR without compiling locally. The default file directory is `<installation>/data`; existing deployments retain their original mount, with no automatic file migration.
|
||||
The installer pulls the latest amd64/arm64 images from GHCR without a registry login or local compilation, falling back to a source build if pulling fails. **Do not copy `.env.example` before a fresh install.** Follow the prompts for addresses and a storage directory.
|
||||
|
||||
1. Configure HTTPS reverse proxies for Web → `127.0.0.1:47832` and API → `127.0.0.1:51947` as described in the [deployment guide](deploy/DEPLOY.md#4-配置宿主机反向代理).
|
||||
2. **Restrict both endpoints to your own access until initialization is complete.** The first person to finish setup chooses the administrator password; there is no default password. Set a strong password of at least eight characters over HTTPS before opening access.
|
||||
3. Under **Settings → Telegram**, enter the Bot Token, API ID and API Hash, set a Bot PIN, and configure an allowlist of numeric user IDs. For channel downloads or subscriptions, also log in with a personal Telegram account on that page.
|
||||
4. Add other storage accounts under **Settings → Storage** and back up the configuration, database and complete `/data` directory.
|
||||
1. Configure HTTPS proxies as described in the [deployment guide](deploy/DEPLOY.md#4-配置宿主机反向代理): Web → `127.0.0.1:47832`, API → `127.0.0.1:51947`.
|
||||
2. **Restrict both endpoints to yourself until initialization is complete.** Open the web UI and set an administrator password before allowing access.
|
||||
3. Under **Settings → Telegram**, connect your Bot and configure user permissions. Sign in with a Telegram user account for channel downloads or subscriptions.
|
||||
|
||||
If pulling fails, the platform is unsupported, or the two images belong to different revisions, the installer falls back to a local source build. Use `./deploy/install.sh --build` to force source builds, adding `--compat` for older build environments. Updates always pull `latest` rather than pinning a version; back up before upgrading. See the [deployment guide](deploy/DEPLOY.md), currently in Chinese.
|
||||
|
||||
## Telegram Bot commands
|
||||
|
||||
After connecting, send `/start` to authenticate and `/help` for the full command list and arguments. Browse and search files in the web UI.
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `/tasks` | View tasks, progress and controls |
|
||||
| `/storage` | View storage status |
|
||||
| `/path_rules` | Configure save locations and directory rules |
|
||||
| `/target` | Set the storage target for the current chat |
|
||||
| `/tg_download` | Open the channel/group date or tag download wizard |
|
||||
| `/tg_sub`, `/tg_subs` | Manage and list subscriptions |
|
||||
| `/tg_retry` | Retry failed tasks |
|
||||
| `/setup_2fa` | Configure TOTP two-factor authentication |
|
||||
|
||||
Channel processing progress includes successful, failed and skipped items; 100% does not mean all files succeeded. Scan totals may be unknown. Queued tasks and Telegram cooldowns do not indicate active transfer. Pausing stops subsequent reads, but in-flight requests or storage writes may still finish.
|
||||
Send `/start` to the Bot to begin, or `/help` for commands. Use `./deploy/install.sh --build` to force a source build. See the [deployment guide](deploy/DEPLOY.md) for other options; detailed guides are currently in Chinese.
|
||||
|
||||
## Backup and updates
|
||||
|
||||
Create a coordinated backup from the project root before updating with the installer:
|
||||
Back up `.env`, the database and complete file data before upgrading, then run from the project directory:
|
||||
|
||||
```bash
|
||||
BACKUP_DIR=/path/to/secure-backups ./deploy/backup.sh
|
||||
./deploy/restore-verify.sh /path/to/secure-backups/<timestamp>
|
||||
./deploy/install.sh
|
||||
```
|
||||
|
||||
The backup script stops the backend while archiving, then restores its previous running state. **Back up `.env` and reverse-proxy configuration separately.** The script includes the database, complete `/data` and a checksum manifest, not files held by remote storage providers. Archive verification is not a restore drill. Upgrades automatically apply database migrations; rollback must preserve database/file consistency rather than simply running an older image. Do not troubleshoot with `docker compose down -v`. See [backup and recovery](deploy/DEPLOY.md#7-备份与恢复).
|
||||
|
||||
## Local builds and contributions
|
||||
|
||||
Container builds use Node.js 24; Node.js 24 and npm are also recommended for local builds. Install and build each subproject independently:
|
||||
|
||||
```bash
|
||||
npm --prefix backend ci
|
||||
npm --prefix frontend ci
|
||||
npm --prefix backend run build
|
||||
npm --prefix frontend run build
|
||||
```
|
||||
|
||||
Running the backend locally also requires PostgreSQL and `DATABASE_URL`; thumbnails/transcoding require ffmpeg. See [local development](docs/configuration.md#本地开发) for startup and environment details. Describe the purpose, reproduction steps and checks actually performed in contributions. Keep lockfiles and Chinese/English documentation in sync. Database changes should update the schema, migrations and `init.sql`; do not rewrite released migrations.
|
||||
|
||||
GitHub Actions publishes universal amd64/arm64 images using the repository's built-in `GITHUB_TOKEN`, with `packages: write` granted only to publishing jobs. No additional registry credentials are required. After the first publication, maintainers must set both container packages to Public in GitHub Packages to allow anonymous pulls. The container receives `VITE_API_URL` at startup, so different domains do not require recompilation. This address is public: never include secrets in it.
|
||||
|
||||
Before publishing commits or sharing issue logs, exclude `.env`, tokens, API hashes, passwords, cookies, Telegram sessions, databases/backups, user files and private server details. Do not commit `node_modules`, `dist`, coverage, temporary debug/smoke scripts or local execution reports. Ignore rules do not remove secrets already committed to Git history; revoke/rotate leaked credentials and clean the history.
|
||||
The script updates source and pulls `latest`, retaining existing configuration and data mounts. See [backup and recovery](deploy/DEPLOY.md#7-备份与恢复). Do not troubleshoot with `docker compose down -v`.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Deployment guide](deploy/DEPLOY.md): installation, HTTPS, backups, recovery and updates.
|
||||
- [Configuration and usage](docs/configuration.md): environment variables, Telegram, storage and permissions.
|
||||
- [Local storage locations](docs/local-storage.md): mounts, path verification and data protection.
|
||||
- [Releases](https://github.com/hicocos/tg-vault/releases).
|
||||
- [Local development](docs/configuration.md#本地开发): development setup and build checks.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in new issue
Block a user