TG Vault文档

切换主题

遇到问题？查看 FAQ
文档/可选扩展

qBittorrent 扩展 ​

此扩展通过 qBittorrent 下载到本机后转存，默认关闭。需自行部署下载器，配置共享目录和 API 凭据。

1. 确认同机与目录映射 ​

TG Vault 与下载器必须能访问同一份本地文件。每个任务使用独立 UUID 子目录，不支持远程路径转换。

Docker 部署在原 .env 设置：

dotenv
QBITTORRENT_HOST_INTEGRATION=true
QBITTORRENT_DOWNLOAD_DIR=/qBittorrent/download

第二项为宿主机目录，需预先创建，并允许下载器写入、后端读取。安装器会附加 docker-compose.qbittorrent.yml，将该目录只读挂载到后端 /qBittorrent/download。

下载器写入路径也必须为 /qBittorrent/download。 容器下载器把同一宿主机目录映射到此路径；原生下载器使用该实际路径。自定义容器内路径时，需同时修改后端挂载和 Web 设置。

手动部署的 Compose 命令需保留 qBittorrent 覆盖文件；源码构建还需 build 覆盖。升级仍需备份和数据库迁移，见完整配置。

2. 启用与测试 ​

  1. 在 设置 → 常规 启用扩展，打开 BT 下载。
  2. 填写 API 地址、专用账号/密码和本地下载目录。
  3. 点击 测试连接和目录。测试仅检查填写值，不保存配置或修改下载器全局设置。
  4. 保存生效。密码留空保留原值，凭据加密保存且不回显。

API 地址须从后端可达。宿主机服务可使用 http://host.docker.internal:18080，按实际端口填写；其他容器使用共享网络地址，后端的 127.0.0.1 指自身。

保留 qBittorrent 鉴权、Host 和 CSRF 校验，将实际 API 主机名加入允许域名。WebUI 使用 HTTPS 反代或来源限制，不公开裸 API。

3. 添加与转存 ​

添加磁力链接或最大 10 MiB 的 .torrent 文件。磁力需等待元数据，再选择文件、目标账户和逻辑目录，并决定是否保留本地文件做种。

  • 转存开始后不能改选文件；切换默认存储不改变任务目标。
  • 保留目录结构，下载和转存分别显示进度与速度。
  • 所选文件全部写入并入库后，默认删除下载器种子和源文件；选择保留则继续做种。
  • 存储确认并入库后转存才到 100%。

取消会删除下载器任务及源文件，包括未完成文件，不受“保留本地文件”影响。已转存文件不删除。 需要保留做种时不要使用取消。

4. 失败、历史与关闭 ​

失败可重试，已入库文件不重复上传；清理或删除失败时仅重试对应操作，不重新下载或转存。重启后恢复未结束任务；已有种子不能重复添加，也不接管下载器其他任务。

完成和取消任务进入历史。移除记录不删除存储文件、本地文件或做种任务。关闭扩展只停止转存调度，不删除记录或停止下载器现有下载；下载器离线不影响 TG Vault 启动。

容量与备份 ​

本地转存和媒体处理使用独立副本，需预留额外空间。外部 BT 下载目录和下载器配置不包含在 TG Vault /data 备份中，需另行备份。