工作原理与完成边界

组件

组件	用途
Web	管理员操作、文件上传与浏览
后端	Telegram、任务调度、存储读写与媒体处理
PostgreSQL	文件索引、账户配置与任务状态
持久 /data	文件、暂存、预览、Telegram session 和内部密钥
远端存储	保存实际对象，独立于本地备份

文件处理

来源读取 → 本地暂存/处理 → 目标写入 → 数据库登记。

远端目标也需要服务器暂存空间。分片合并、预览与 BT 副本可能同时占盘，容量安排见资源说明。

Telegram 多账号调度

Bot 负责收件、命令与通知；个人账号负责有权访问的频道/群组读取，两者独立连接。多个个人账号按来源权限、冷却、权重和占用调度，已确认可读优先，同负载轮换。

文件下载逐文件选账号，单文件分片不跨账号。扫描优先沿用已分配账号，切换时重新验证来源；扫描与下载分别计占用、共享账号冷却，扫描账号不一定是文件下载账号。添加账号不自动提高当前并发或保证提速，操作见多账号调度。

默认存储、任务目标和目录

• 系统默认供新的默认保存操作使用，不迁移旧文件。
• **Bot /target**设置下一次或当前聊天的目标，不修改系统默认。
• 已提交任务保留目标快照，不随默认账户变化。
• 订阅可固定账户或让未来扫描跟随全局；配置修改不改变已有下载任务。
• 逻辑目录不是任意宿主机路径，也不会自动导入远端既有文件。

索引与实际文件

添加存储不会扫描整盘。索引中的文件若被外部工具移动或删除，可能无法读取。

移除存储账户会删除连接及 TG Vault 关联索引，不删除远端文件。文件删除是另一项操作。不要手工向受管理 uploads 目录导入未索引文件。

完成该怎么判断

状态	含义与检查
/livez 200	活性通过，不代表依赖和文件操作正常
/readyz 200	必需依赖就绪；Bot 非必需时仍可能离线
存储探测通过	对应探测成功，不一定验证全部读写/删除权限
下载 100%	来源读取结束，还要等待上传与入库
批量任务 100%	已发现条目处理结束，仍要看失败与跳过数量
索引可见	已登记结果，还需确认目标文件可读
网关可见	网关已接收，必要时核对背后云盘最终状态

首次部署、换存储或迁移后，用小文件验证上传与下载。