存储源配置
登录 TG Vault 后进入 设置 → 存储源。系统支持本地磁盘、OneDrive、Google Drive、阿里云 OSS、S3 兼容存储和 WebDAV，并允许为云存储添加多个账户。
/target 为当前聊天设置一次性或会话级目标。
本地存储
本地存储无需额外凭据，文件保存在 Docker 的 file-storage 卷中。该卷也包含临时文件、缩略图、Telegram session 和内部安全密钥，因此迁移或恢复时必须整体备份。
适合：低延迟、同机读取、先在本地验证部署。
OneDrive
Microsoft Entra 中创建应用
- 打开 Microsoft Entra 管理中心并进入 应用注册。
- 新建注册，记录 Application (client) ID 和 Directory (tenant) ID。
- 添加 Web 重定向 URI：
https://api.example.com/api/storage/onedrive/callback
- 如果使用客户端密码，在 证书和密码 中创建 Client Secret，并立即安全保存其值。
- 在 TG Vault 的 OneDrive 表单中填写账户名称、Client ID、Tenant ID，以及可选的 Client Secret，然后点击 保存并授权。
回调地址必须与 TG Vault 设置页显示的地址和 Microsoft 平台登记值完全一致。
Google Drive
Google Cloud 中创建 OAuth 客户端
- 打开 Google Cloud Console并创建或选择项目。
- 在 API 和服务 → 库 中启用 Google Drive API。
- 配置 OAuth 同意屏幕；测试阶段把自己的 Google 账户加入测试用户。
- 创建 Web 应用类型的 OAuth 客户端。
- 添加已授权的重定向 URI：
https://api.example.com/api/storage/google-drive/callback
- 在 TG Vault 中填写账户名称、Client ID 与 Client Secret，点击 保存并授权。
- 如需写入共享云端硬盘，填写共享云端硬盘 ID；留空则使用“我的云端硬盘”。授权账户必须已经加入该共享盘并拥有创建文件权限。
如果 Google 返回 403: access_denied，先检查 OAuth 应用是否仍为测试状态，以及当前账号是否已加入测试用户。
阿里云 OSS
- 在 OSS 控制台创建私有 Bucket。
- 记录 Region，例如
oss-cn-hangzhou。 - 建议创建专用 RAM 用户并授予该 Bucket 所需的最小读写权限，而不是使用主账号 AccessKey。
- 在 TG Vault 中填写账户名称、Region、AccessKey ID、AccessKey Secret 和 Bucket。
不要把 AccessKey 写进仓库或截图公开。连接成功后再切换为系统默认账户。
S3 兼容存储
适用于 AWS S3、Cloudflare R2、Backblaze B2、MinIO 和其他兼容服务。
| 字段 | 说明 |
|---|---|
| Endpoint | 服务商给出的 HTTPS API 地址 |
| Region | 区域标识；按服务商要求填写 |
| Access Key ID / Secret | 专用访问密钥 |
| Bucket | 已创建的存储桶名称 |
| Force Path Style | MinIO 或要求路径式寻址的服务通常需要勾选 |
默认只允许 HTTPS Endpoint。只有可信内网测试才在 设置 → 安全 → 网络与存储安全 中开启允许内网和不安全的 WebDAV 地址。
WebDAV
填写：
- 账户名称
- WebDAV URL，例如服务商给出的 HTTPS DAV 入口
- 用户名
- 密码或应用专用口令
坚果云等服务通常要求应用专用密码，而不是网站登录密码。自建 WebDAV 应优先使用有效 HTTPS 证书；超大文件可根据网络状况调整 .env 中的 WebDAV 无活动与上传超时。
飞牛等局域网 WebDAV
默认安全策略会拒绝 HTTP、回环、私有网段和保留地址。在 设置 → 安全 → 网络与存储安全 开启“允许内网和不安全的 WebDAV 地址”后，可添加并实际读写可信局域网 WebDAV。此开关有 SSRF 和 HTTP 明文传输风险，启用时会要求二次确认。
连接地址必须从 backend 容器的网络视角可达：
127.0.0.1指 backend 容器自身，不是 Docker 宿主机。- 如果 WebDAV 只监听宿主机
127.0.0.1，容器通常无法连接。 - 优先填写容器可访问的宿主机局域网地址或同一 Docker 网络中的服务名，并检查端口、防火墙和路由。
- 开关只放宽安全准入，不会绕过网络连通性限制。
测试、切换与删除账户
- 添加账户后先执行连接测试。
- 测试成功，再选择 切换到此账户。
- 新任务会使用新的系统默认目标，旧任务保持原目标。
- 删除账户前，先阅读系统给出的影响预览。账户删除和云端实体文件删除是不同操作，不要在未确认影响时执行。
不同存储的产品能力不同：
- OneDrive 支持分享链接、密码、过期时间和远端配额。
- Google Drive 支持分享链接和远端配额，但不提供 TG Vault 内的分享密码或过期时间。
- 其他存储在界面中不会假装支持提供商未实现的分享能力，可改用下载。
常见问题
授权后窗口没有完成
检查：
- 平台登记的 callback 是否与设置页显示值逐字一致
- 浏览器是否拦截了授权弹窗
连接测试失败
检查 Endpoint、Region、Bucket、权限、DNS、TLS 证书和服务器出站网络。后端日志会给出比浏览器弹窗更完整的原因：
docker compose logs --tail=200 backend