TG2Cloud 可以把你提交给私人 Telegram Bot 的文件，自动排队并写入自己挂载的云存储。Windows 部署器负责安装和管理，VPS 负责执行任务，CloudDrive2 或 OpenList 负责连接网盘。

本文从首次部署讲到日常使用和维护，重点说明每一步应该填写什么、何时才算成功，以及哪些操作会影响现有数据。

项目仓库 · 部署器下载 · v1.1.1 发布说明 · 新手使用说明

本文于 2026 年 10 月 1 日根据 TG2Cloud v1.1.1 标签文档和源码整理。受管部署的 HTTPS 流程与旧版有明显区别，不要直接照搬 v1.0.2 的 SSH 隧道按钮教程。后续界面与默认值以对应版本为准；文中的速度计算是估算，不是实测成绩。

项目来源与致谢： TG2Cloud 基于 whyhhh20/TG115 二次开发，沿用 MIT 许可证并保留原作者版权信息。感谢原作者与相关开源组件的贡献者。它是对原项目的持续完善，不是从零开发的替代叙述；来源与许可见仓库说明和许可证。

一、TG2Cloud 能做什么？

传统的保存方式通常是先把 Telegram 文件下载到手机或电脑，再上传到网盘，最后清理临时文件。TG2Cloud 把选择文件之后的重复步骤交给自己的 VPS：

1
2
3
4
5
6
7
8
9
10
11
12

本人在 Telegram 中选择文件
          ↓
发送或转发到自己的 Bot 私聊
          ↓
TG2Cloud 将任务写入 SQLite 持久队列
          ↓
普通模式：完整下载到 VPS，再上传
流式模式：Telegram → rclone 传输管道
          ↓
CloudDrive2 / OpenList WebDAV
          ↓
本人在网关中挂载的目标云存储

它适合个人资料归档与备份，但需要先明确以下边界：

• 不是频道采集器。 当前只受理配置用户与 Bot 的一对一私聊，不自动监听频道、不批量抓取频道历史；群组或频道消息不会创建任务。
• 不是网盘秒转接口。 文件仍经过传输链路，需要 VPS 带宽、流量与可用资源。
• 不只限于 115。 115 是主要测试与文档示例之一，实际可用目标由你在 CloudDrive2 或 OpenList 中挂载的存储决定，不能据此推断所有网盘均已验证。
• 不承诺内容哈希一致。 Bot 主要通过 WebDAV 远端大小检查确认接收，不接入上游网盘官方完成接口。
• 流式不等于零磁盘。 它减少 Bot 的完整下载副本，网关缓存、容器、日志等仍占空间。

项目的使用方式是“手动选择、自动处理”：选择和内容授权由你负责，排队、传输、状态记录与收尾由服务处理。工作原理与重要边界

二、选择 CloudDrive2 版还是 OpenList 版？

两版共用 Bot 任务核心和 PySide6 部署界面，使用不同的存储网关、部署入口和运行资源。选择自己已经使用或更熟悉的一版即可，不必同时安装。

同机 WebDAV 地址中的主机名属于 Docker 网络，供 Bot 容器使用，不是给 Windows 浏览器访问的地址。后端端口也不应公开到互联网。

两版可共存，但要使用不同的管理域名，并避免同时长期使用同一个 Bot Token。CloudDrive2/OpenList 能挂载某个存储，也不自动代表该存储具备可靠的写入、检查和清理能力，仍需做真实验收。产品配置源码、双版本说明

TG2Cloud 按 MIT 许可证开源；VPS、网盘容量、CloudDrive2 功能与会员权益是另外的使用条件，不能把“项目开源”理解为整套链路免费。第三方组件说明

老用户需要注意的版本变化

这些变化并不意味着每一版都重新验证了所有 Telegram、网盘与文件规模的组合。v1.1.1 发布说明明确区分了本轮 HTTPS 检查与沿用的转存验收基线。版本记录、本次验证范围

三、部署之前需要准备什么？

1. VPS 与本地电脑

安装脚本的基础硬检查约为 1.8GB 内存、安装文件系统至少 8GB 可用空间，但这只是初步门槛，不代表达到它就适合所有任务。部署器还会检查安装盘、Docker 数据盘、已有下载、备份占用、inode 和最终填写的预算。

50GB 是推荐容量，不是保证全部用于临时文件；系统、Docker、日志与网关缓存也会占用空间。部署准备、资源说明

2. VPS 登录信息

准备服务器 IP 或域名、SSH 端口、用户名，以及密码或 SSH 私钥。使用带口令的私钥时，还需准备私钥口令。

首次连接必须核对服务器主机密钥指纹。能够输入正确密码，不等于可以跳过服务器身份确认。

3. Telegram 四项参数

Token、API ID、API Hash 和用户数字 ID 的用途不同，不能互相替代。不要把真实参数放在教程示例、公开截图或 Issue 中。申请步骤见 Telegram Bot 官方教程和 Telegram 应用创建说明。

4. 网关与目标存储

准备能够在所选网关中正常挂载的存储账号、足够的目标空间，以及计划为 TG2Cloud 创建的专用 WebDAV 用户。

两类凭据应分开处理：

1
2
3
4
5

网盘账号、扫码、Cookie、Token 或 OAuth 授权
    → 由本人在自己的 CloudDrive2 / OpenList 后台完成

WebDAV 用户名、密码与目标路径
    → 与 TG2Cloud 的运行配置对应

部署器不要求你向维护者提供网盘登录密码、Cookie、OAuth Token、Telegram 私人账号密码或验证码。不要把 CloudDrive2 会员密码填成 WebDAV 密码。填写信息清单

5. 管理域名与端口

同机受管部署需要可用的管理域名。 使用两版时，每个 Edition 准备不同的域名，例如：

1
2

CloudDrive2：https://cloud.example.com
OpenList：   https://list.example.com

将实际域名的全部 A/AAAA 记录直接指向 VPS；没有可用 IPv6 时，不要留着指向其他机器的 AAAA 记录。首次签发证书时，Cloudflare 使用“仅 DNS”，不需要向部署器提供 Cloudflare API Token。

自行在服务商安全组和防火墙开放 TCP 80/443。若现有 Nginx、Caddy、Apache、Traefik 或其他服务占用了这些端口，部署器会停止，不会自动修改或关闭它们。HTTPS 配置说明

取消受管 CloudDrive2、使用已有外部 WebDAV 的模式，不强制配置本地网关的 HTTPS 入口；但必须填写 Bot 容器实际能够访问的目的地址。不能把这个例外套用到同机受管部署。部署后端源码

四、本地任务预算应该怎么设置？

两版源码默认：

1
2
3

本地任务预算：20GB
磁盘最少保留：8GB
时区：Asia/Shanghai

这是表单默认值，不是对每台 VPS 的通用建议。连接成功后，点击“检测 VPS 并推荐”，再主动应用合适的方案：

例如约 2 核、1.9GB 内存、33GB 可用空间的实例，检测可能推荐流式优先 8GB/8GB。此时应采用自己的检测结果，不要因为教程写着默认 20GB/8GB 就强行改回去。

还要区分：

• 本地任务预算约束 Bot 为任务保存的本地文件。
• 磁盘保留线保护真实文件系统的安全空间。
• 网关缓存、镜像、备份和日志不会因为调小任务预算自动清空。
• 单文件超过本地预算会自动采用流式模式；仅因多个任务累积额度不足而排队，不等于所有任务都会自动转流式。
• 更改安装目录或 CloudDrive2 管理方式后，应重新检测。

部署器不会自动分区、格式化、扩容、挂载磁盘或迁移 Docker 数据目录。不要通过把安全线调到接近零来绕过资源检查。存储建议与流式边界

五、Windows 图形化部署完整流程

下面按首次受管安装整理。CloudDrive2 与 OpenList 的共同顺序是：

1
2
3
4

下载校验 → 测试 SSH → 填写 Telegram 与 WebDAV
→ 检测资源 → 部署基础容器 → 配置 HTTPS
→ 挂载网盘、创建 WebDAV 用户 → 真实 WebDAV 验收
→ 发送小文件确认完整链路

第一步：下载对应 Edition，并校验

从 GitHub Releases 下载所需 EXE 和 同一版本的 SHA256SUMS.txt。

在 Windows PowerShell 中按所下载版本执行：

1
2
3
4
5

# CloudDrive2 Edition
Get-FileHash ".\TG2Cloud-CloudDrive2-Deployer.exe" -Algorithm SHA256

# OpenList Edition
Get-FileHash ".\TG2Cloud-OpenList-Deployer.exe" -Algorithm SHA256

将输出与清单中对应文件的校验值比较，不要使用其他版本或自己以前构建的校验值。

v1.1.1 的 EXE 未提供商业代码签名，SmartScreen 可能提示“未知发布者”。确认来源与完整性，不要为运行程序关闭 Defender、Windows Security 或跳过安全检查。下载与发布说明

第二步：测试 SSH，核对服务器身份

填写 VPS 地址、端口、用户名与登录方式；非 root 且没有免密 sudo 时补充 sudo 密码，然后点击“测试 SSH”。

首次连接将弹出的主机密钥指纹与服务商控制台核对。连接成功后查看资源探测结果；连接失败先处理身份、网络或认证问题，不要连续点击部署。

第三步：填写 Telegram 与 WebDAV 参数

填写 Bot Token、API ID、API Hash 和本人数字 ID。

CloudDrive2 版预先确定专用 WebDAV 用户名与密码，稍后在网关后台创建同样的用户；同机受管安装保持默认 Docker 内网地址。

OpenList 版按照“配置 WebDAV”页记录本次生成的用户信息。部署器不会在关闭后自动保存表单密码，请存入自己的密码管理工具，尤其是首次管理员密码与随机 WebDAV 密码。

第四步：应用存储建议

确认安装目录、是否管理 CloudDrive2 容器、本地任务预算、磁盘保留线与时区。

点击“检测 VPS 并推荐”，主动应用均衡或流式优先建议。正式写入前还会复检，任一关键文件系统不安全时都会停止。

第五步：部署基础环境

点击“一键部署基础环境”，等待依赖下载、镜像构建与服务健康检查。

期间不要重复点击部署、网络修复或 WebDAV 验收。安装耗时受线路和 VPS 性能影响，不把文档中的参考时间理解成保证。

基础容器健康后，部署器会自动打开“HTTPS 管理入口”对话框；此时处于 “待配置 HTTPS”，还不能把它当作完整部署成功。

第六步：配置 HTTPS 管理入口

填写当前 Edition 的纯域名，例如 cloud.example.com，不带 https://、端口、路径或通配符。

先“检测环境”，再“配置 HTTPS”。可填写 Let’s Encrypt 联系邮箱；省略邮箱意味着无法接收到期提醒，不意味着不需要续期。

等待 DNS、端口、证书、Nginx 配置、HTTPS、HTTP 跳转、公开 WebDAV 阻断与后端回环监听检查通过。受管部署只有完成这些检查，主界面才显示“部署完成”。

第七步：登录网关并设置存储

通过“打开 CloudDrive2 域名”或“打开 OpenList 域名”进入管理页，按下一节完成网盘授权、目录和专用用户配置。

HTTPS 管理入口只代理管理界面，不能填到 Bot 的 WebDAV 地址中。公网 /dav 和 /dav/ 返回 403 是预期行为。

第八步：验收后再发送文件

执行“WebDAV 验收”，等待：

1

TG2CLOUD_DESTINATION=OK

通过后，向自己的 Bot 私聊发送一个小文件，再到网盘官方客户端检查位置、大小与可打开性。HTTPS 正常、容器 healthy、WebDAV 验收通过和真实文件成功，是不同层次的结果，不要混为一谈。首次部署流程、HTTPS 说明

六、两种网关分别怎样配置？

方案 A：CloudDrive2 Edition

同机受管部署的 Bot WebDAV 地址保持：

1

http://tg2cloud-clouddrive2:19798/dav

HTTPS 通过后，在自己的 CloudDrive2 管理页依次完成：

1. 登录 CloudDrive2。
2. 添加并授权自己的目标存储。
3. 确认能够浏览目标目录。
4. 开启 WebDAV。
5. 创建与部署器配置一致的 TG2Cloud 专用 WebDAV 用户。
6. 关闭只读，确认具备读取、写入、改名和删除能力。

目标路径只配置一次。以下以 115 的示例挂载名称说明：

115open 是示例，不是所有网盘都必须使用的名称。不要在用户根目录和相对子目录里重复填写同一段路径。

取消“在 VPS 上安装并管理 CloudDrive2 容器”后，代表使用外部 CloudDrive2；需要改成从 Bot 容器可达的真实 WebDAV 地址及现有凭据。容器里的 127.0.0.1 指向容器自身，不能随意拿宿主机回环地址替代。CloudDrive2 配置说明

方案 B：OpenList Edition

同机网关的内网地址为：

1

http://tg2cloud-openlist:5244/dav/

HTTPS 通过后，在自己的 OpenList 中完成：

1. 全新安装使用本次生成的首次管理员密码；已有实例使用原管理员凭据。
2. 添加并授权目标存储，例如 115 Open。Cookie、Token 与 OAuth 信息只在自己的 OpenList 后台处理。
3. 按“配置 WebDAV”页创建专用普通用户，使用完全相同的用户名和密码。
4. 设置该用户的基本路径，授予目录列表、读取、创建／写入及删除能力。
5. 回部署器执行真实 WebDAV 验收。

新装建议用户名为 tg2cloud，WebDAV 密码由部署器在本地生成，默认 28 位；只有明确点击“重新生成”才会改变当前会话值。首次管理员密码与 WebDAV 密码是两项不同配置。

首次管理员密码只在全新 OpenList 数据目录初始化时生效。重新部署不会自动重置已有实例；看到新生成的表单密码，不代表原管理员密码已经更换。

目标子目录默认留空，即写入专用用户的 WebDAV 根目录。需要时填写 Telegram 或 Media/Telegram 等相对路径，避免与用户基本路径重复。

从 v1.0.2 起，OpenList 版采用预留最终文件名后直接写入，不依赖 WebDAV MOVE 完成改名；不要照搬 CloudDrive2 的临时文件收尾步骤。

已有实例默认保留 VPS 当前完整 .env。明确选择覆盖表单时，还可选择“仍保留 VPS 当前 WebDAV 与管理员配置”，让原凭据在 VPS 内合并。如果确实要更换 WebDAV 凭据，就不能同时要求继续保留旧值，还必须在 OpenList 中同步修改。OpenList 配置与凭据说明、产品配置源码

七、HTTPS 与 WebDAV 验收分别证明什么？

HTTPS 自检与外部访问

部署器的 HTTPS 请求自检从 VPS 回环地址访问 Nginx，并使用真实域名校验证书，避免 NAT 回环限制产生误报。

本机自检通过，不等于公网 443 已经可达。 配置完成后，应从 Windows 浏览器或其他外部网络确认：

• HTTPS 管理页能够正常访问，证书无警告。
• HTTP 能跳转到相应 HTTPS 地址。
• 公网 /dav 与 /dav/ 返回 403。
• VPS 公网 IP 加 19798/5244 端口不能直接访问管理后台。

本机正常而外部失败时，先检查 DNS、安全组、防火墙与 Cloudflare 设置，不要通过公开后端端口或跳过证书校验来“修复”。HTTPS 自检与公网验收

WebDAV 真实写入验收

GUI 验收从 Bot 容器内使用当前运行配置，执行以下操作：

1
2
3
4
5
6
7
8
9
10
11
12

生成 256 字节随机测试文件
          ↓
认证、访问目标目录并写入
          ↓
检查远端大小
          ↓
CloudDrive2：改名后复验
OpenList：直接检查最终文件
          ↓
删除远端与本地测试文件
          ↓
TG2CLOUD_DESTINATION=OK

这是会写入和删除测试文件的操作，不是只读诊断。认证成功或能够列目录，都不能替代完整验收；写入成功但清理失败，也不算全部通过。

OpenList 界面会按 Bot、网关服务、认证、目录、写入、大小、最终落盘和清理逐项显示结果。失败后的未执行步骤不应被理解成通过，排错时先看第一处失败阶段。验收说明、验收源码

真实 Telegram 文件

WebDAV 通过之后，再依次安排适合自己环境的测试：

1. 一个 5～20MB 小文件，先确认完整链路。
2. 一个常用大小的普通落盘文件。
3. 一个手动切换或超过预算的流式文件。
4. Bot 重启后的任务恢复。
5. 一个可删除测试任务的取消与远端清理。

这里是给使用者的验收建议，不是本文的实测记录。v1.1.1 的发布说明也明确：本轮未重新完成所有 OpenList Bot/WebDAV、401/429 恢复、长期续期和备份恢复的真实环境验收，不应把 HTTPS 检查扩大为所有业务已重测。版本验证范围

八、日常转存与 Bot 命令

向自己的 Bot 私聊发送 /start 或 /help，然后提交有权保存的文件。Bot 返回任务编号后，使用 /queue、/task 编号 和 /status 观察处理。

命令速查

下表中的 123 是示例，应替换为真实任务编号。

输入框左侧的原生命令菜单注册 7 项常用命令：/status、/queue、/pause、/resume、/doctor、/orphans、/help。菜单注册失败时仍可手动发送文字命令。Bot 命令说明

取消和临时文件清理属于删除操作。 /cancel 不只是隐藏列表记录；它可能删除任务对应的临时与正式远端文件。只有确认远端清理完成，才继续删除本地副本并标记取消；失败时保留数据。/orphans clean 需要按 Bot 返回的有效确认码操作，不应当作只读查询。命令源码

首页和 VPS 资源页

/start、/status 与 /performance 打开同一个紧凑首页：

• ⏳：排队数量。
• ⬇️：活动下载数量。
• ⬆️：活动上传数量。
• ❌：失败数量。

四项即使为零也显示，历史完成数量不放在首页。下方三个快捷按钮分别是 📋 任务列表、🖥 VPS 资源、🔄 原地刷新；CPU、内存、可用磁盘和本地额度放在资源页，不与 Bot 任务数量混在一起。

刷新编辑当前消息，不会不断发送新状态消息。流式速度同时出现在下载和上传方向，VPS 网络采样则是另一个指标，不能把三个数字相加当作端到端速度。状态与首页说明

“Bot 完成”怎么理解？

“Bot 完成”不等于网盘官方端已经确认最终保存，也不等于内容哈希一致。 CloudDrive2/OpenList 可能还有自身缓存或后续处理，Bot 没有查询所有上游网盘的官方完成接口。

当前不需要逐个执行人工确认命令。首次使用、更换存储或保存重要文件时，仍应通过网盘官方客户端检查大小与可打开性，需要更高完整性保证时自行比较文件哈希。完成边界、安全政策

九、转存速度怎么样？2GB 文件要多久？

至少区分三个阶段：

1
2
3

Telegram → VPS
VPS → CloudDrive2 / OpenList WebDAV
CloudDrive2 / OpenList → 目标网盘

VPS 标称“千兆带宽”不能保证每个阶段都达到相同速度。WebDAV 接收很快，也不代表上游网盘已经完成写入。

单阶段估算

假设文件为 2GB，按十进制约 2000MB 计算，持续有效速率固定，不考虑排队、检查和重试：

1

单阶段耗时 ≈ 文件大小 ÷ 有效速度

这不是 TG2Cloud 的实测速度，也不是端到端承诺。MB/s 是每秒兆字节，不要与服务商标注的 Mbps 混淆；2GiB 也不等于这里按十进制计算的 2GB。

普通模式下，若 Telegram 下载为 5MB/s、随后写入 WebDAV 为 2MB/s，两个串行阶段约需：

1
2

2000 ÷ 5 + 2000 ÷ 2 = 1400 秒
约 23 分 20 秒

实际还可能有排队、复验、重试和网关向上游云存储同步的时间。流式模式可以让部分阶段重叠，理想流水线仍受最慢环节约束，不能消除线路与网盘限速。

更有价值的记录方法

使用同一个测试文件，记录提交、开始下载、Bot 完成，以及网盘官方客户端可以打开的时间，结合 /status 的下载、上传与 VPS 网络指标观察瓶颈。

同时查看 VPS 套餐流量规则：服务商可能只计出站，也可能计算双向流量。上传文件经过服务器，不能因为没有下载到本地电脑就认为 VPS 不消耗流量。状态语义、部署准备

十、VPS 日常维护与程序升级

以下命令在 通过 SSH 登录后的 Linux VPS 执行，不是在 Windows 博客项目目录中执行。自定义安装位置时替换为实际路径。

运行状态与日志

1
2
3
4
5
6
7
8
9
10
11
12

# CloudDrive2 Edition：查看状态
sudo /opt/tg2cloud-clouddrive2/manage.sh status

# 查看最近 30 分钟、末尾最多 200 条日志，并持续跟随
# 退出跟随按 Ctrl+C，不会因此停止 Bot
sudo /opt/tg2cloud-clouddrive2/manage.sh logs

# 核对配置、代码指纹与基础心跳
sudo /opt/tg2cloud-clouddrive2/manage.sh check

# 真实 WebDAV 写入、改名与清理验收
sudo /opt/tg2cloud-clouddrive2/manage.sh verify

OpenList 使用自己的管理脚本：

1
2
3
4
5
6

sudo /opt/tg2cloud-openlist/manage.sh status
sudo /opt/tg2cloud-openlist/manage.sh check
sudo /opt/tg2cloud-openlist/manage.sh verify

# OpenList 提供不持续跟随的近期日志入口
sudo /opt/tg2cloud-openlist/manage.sh recent-logs

脚本日志有脱敏处理，分享前仍需人工检查文件名、地址及个人信息。容器 healthy 只表示基础运行与心跳正常，不能替代 WebDAV 写入验收。

重启、重建与升级不是一回事

manage.sh update 不会从 GitHub 下载最新 TG2Cloud 源码；只下载新版 EXE 也不会自动更新 VPS 上的 Bot。 OpenList 的 update 拉取的是当前 Compose 固定的镜像，不是自动追随任意最新版本。CloudDrive2 管理脚本、OpenList 管理脚本

推荐升级顺序：

1. 阅读新版本发布说明，处理队列与失败保留文件，安排维护窗口。
2. 保存必要的私有备份，确认 Edition 和安装目录。
3. 下载并校验新版部署器。
4. 默认保留 VPS 当前 .env，重新执行“一键部署基础环境”。
5. 检查 HTTPS 管理入口、服务健康和实际配置。
6. 执行 WebDAV 验收，再用真实小文件检查链路。
7. 稳定之后才评估旧回退点的清理。

重新部署识别到完整 TG2Cloud 安装时，默认保留配置、SQLite、rclone.conf 与持久数据；只有明确勾选“使用本页配置覆盖 VPS 当前 .env”，才会应用当前表单。更换目的账号或路径之前，应先处理已有任务，避免将旧任务发送到新目的端。升级说明

单独应用配置

将准备好的完整新配置保存在安装目录之外、仅自己可访问的绝对路径，再使用：

1
2
3

sudo /opt/tg2cloud-clouddrive2/manage.sh apply-config /absolute/new-config.env
sudo /opt/tg2cloud-clouddrive2/manage.sh check
sudo /opt/tg2cloud-clouddrive2/manage.sh verify

/absolute/new-config.env 是示例路径，需要替换，系统不会自带这个文件。OpenList 换成对应 Edition 的脚本路径。

apply-config 会备份旧配置、预检、重建 Bot 并检查实际环境；失败时按脚本机制尝试恢复。单纯 restart 不会把 Windows 表单中的新密码应用到 VPS，也不能替代配置更新。

当前只有有限的内部失败回退，没有正式自动 Restore 或 Uninstall，不要因此省略独立备份。升级与配置边界

十一、备份包含哪些内容？

两版备份范围不同

CloudDrive2 当前没有手动“创建安全备份”的 UI，不要为它套用 OpenList 的 backup 命令。

OpenList 的日常管理区提供安全备份；脚本命令为：

1

sudo /opt/tg2cloud-openlist/manage.sh backup

该操作涉及短暂停止 Bot 与 OpenList以保护网关状态的一致性，结束后重新启动并检查健康。应安排维护窗口，不要在大量任务传输期间随意点击。备份说明

默认备份目录与历史保留

1
2

/opt/tg2cloud-clouddrive2-backups
/opt/tg2cloud-openlist-backups

只读盘点：

1
2

sudo /opt/tg2cloud-clouddrive2/manage.sh backups
sudo /opt/tg2cloud-openlist/manage.sh backups

部署会统计备份占用，超过 5GB 时提示，不会在升级中自动清空旧回退点。

下面是删除命令，不是查询命令；确认恢复点可用、Edition 正确，并完成升级后的真实文件检查后，才考虑执行：

1
2

# 每类保留最新 5 份符合规则的备份，删除更旧的记录
sudo /opt/tg2cloud-clouddrive2/manage.sh prune-backups 5

脚本只处理本 Edition 备份目录中特定命名的普通文件，不清理旧 TG115 备份。不要扩大为手动删除整个 /opt。

HTTPS 代理必须独立备份

两版现有备份均不包含：

1

/opt/tg2cloud-proxy

至少独立保护以下内容：

• state/domains.json：两个 Edition 的域名与后端映射。
• docker-compose.yml、nginx/nginx.conf、nginx/conf.d/：代理与续期配置。
• 完整 certbot/letsencrypt/：证书、私钥、账户与续期状态，包括 live/、archive/、renewal/。

live/ 中可能是符号链接，不能只复制链接而遗漏目标。备份前安排维护窗口，避免两个部署器同时修改代理，并暂停 Certbot 续期；结束后恢复续期并检查状态。代理备份本身不要求停止 Bot，但同时备份 Edition 数据时应遵守该数据的一致性要求。

目录、备份文件应限制访问权限，并私密保存；证书私钥与服务凭据不能上传公共仓库或 Issue。当前没有一键代理恢复，恢复应先在隔离环境检查归档、权限与映射，再验证 Nginx、本机 HTTPS、外部访问和续期，不能直接覆盖生产 /opt。代理独立备份与恢复边界

可读取的备份不等于已验证的恢复方案。 升级回退点、网关状态、失败保留文件和云端文件是不同数据，需要按自己的恢复目标分别保护。

十二、常见问题与排错顺序

Q：没有 Telegram Premium 能用吗？

部署准备项没有将 Premium 列为前提，不能把没有会员直接理解为不能部署。但文件能否发送、转发与读取，仍受 Telegram 规则、内容权限和实际账号条件影响。项目不承诺解除文件大小限制、复制限制或获得固定速度。

Q：没有域名还能按旧教程部署吗？

当前同机受管 CloudDrive2/OpenList 流程必须完成 HTTPS，不能把 v1.0.2 的 SSH 隧道按钮步骤当作 v1.1.1 的日常入口。底层固定端口隧道只保留兼容和故障恢复能力。

使用已有外部 WebDAV 的 CloudDrive2 模式是另一种部署分支，不要求配置本地管理容器 HTTPS，但需要真实可达的外部目的端，不能仅靠取消勾选来省略必需的存储服务。HTTPS 适用边界、部署后端源码

Q：本地电脑必须一直开着吗？

任务运行在 VPS，正常情况下不依赖 Windows 部署器持续开启。关闭电脑不会因此停止服务端传输；VPS、Bot、网关与网络仍需正常运行。

Q：一直排队，是不是卡住了？

先看 /status、/task 编号 与 /doctor，依次确认：

1. 是否曾执行 /pause；暂停状态跨重启保留，需要时使用 /resume。
2. 本地额度、真实磁盘安全线与资源是否充足。
3. 网关是否在线，存储挂载是否有效。
4. 当前 WebDAV 凭据、目录和写入权限是否正确。
5. 是否遇到目的端限流。

不要直接重装或盲目提高并发。读取状态使用只读诊断，需要写入检查时再执行 WebDAV 验收。

Q：普通任务失败后能否继续传？

持久队列恢复的是任务管理状态，不保证所有协议与故障都支持字节级断点续传。普通上传失败可能保留已经下载的完整本地文件；流式任务没有完整副本，中断后通常需要从头读取并重传。

先看 /task 编号 的失败原因，修复后再重试。/stream 适用于排队或下载失败任务，不是任意状态都能强制切换。

Q：401 Unauthorized 怎么处理？

优先核对 Bot 当前运行配置与专用 WebDAV 用户是否一致。已有安装默认保留 VPS .env，Windows 表单改了但没有应用，原凭据仍可能生效；仅重启不能完成配置更新。

明确应用配置后再做 check 和 verify。网络修复不能代替密码、用户或权限修正。

Q：429 Too Many Requests 要等多久？

这是限流信号，先暂停高频验收与批量重试，按服务端提示等待，不要通过反复改密码、创建用户或增加并发加压。

v1.1.1 的 OpenList 只读健康探测新增保护：

• 401 认证失败冷却 5 分钟。
• 429 从 60 秒逐步退避，连续限流最多延长至 15 分钟。
• 状态按钮刷新不会绕过冷却，成功探测短时间复用。
• 显式 WebDAV 写入验收不使用这套缓存。

这些是客户端保护间隔，不是服务端保证的解封时间，也不代表 CloudDrive2 采用相同策略。只下载新 EXE 不会让旧 VPS payload 自动获得修复，仍需明确升级。401/429 说明、v1.1.1 发布说明

Q：HTTPS 检查通过，浏览器却打不开？

本机自检和公网连通是两回事。检查全部 A/AAAA、安全组、防火墙、80/443 归属与 Cloudflare 模式。

填入的是纯域名，不能是 URL、IP 或通配符。后台端口仍保持回环监听，不要改成 0.0.0.0，也不要使用跳过 TLS 校验的访问方式。

Q：管理域名的 /dav 返回 403，是否异常？

这是预期阻断策略。公网入口只开放管理界面，Bot 使用 Docker 内网 WebDAV；不要把管理域名写入传输配置，也不要删除阻断规则来让验收通过。

Q：HTTPS 与证书以后怎样维护？

共享目录为 /opt/tg2cloud-proxy，容器为 tg2cloud-proxy-nginx 和 tg2cloud-proxy-certbot。Certbot 每 12 小时尝试续期，Nginx 每 6 小时安全重载证书；仍应检查续期状态与证书有效期，自动任务不是永不失效的保证。

更新一个 Edition 的域名应通过部署器配置并完成检查。移除一个域名只影响对应路由；移除最后一个后共享代理停止，证书文件默认保留。被移除的 Edition 会恢复“待配置 HTTPS”，这不是卸载 Bot。

v1.1.1 的共享事务锁用于保护配置和移除操作，遇到竞争提示应等待，不要手动删除锁文件。HTTPS 运维说明

Q：lookup tg2cloud-clouddrive2 或容器网络异常？

先核对 Bot 与受管网关是否在线并位于正确 Docker 网络。只有此类网络问题且符合部署器提示时，才使用“修复 CloudDrive2 网络”。

该操作不能修复 401、429、只读用户、云盘容量不足或 HTTPS 证书错误。检测到未知端口占用时，脚本会拒绝自动修改。

Q：能够列目录，却上传、改名或删除失败？

列表权限不等于写权限。CloudDrive2 需要读写、改名、删除；OpenList 当前至少需要列表、读取、写入、删除，不依赖 MOVE 收尾。

同时检查底层网盘配额、挂载授权、驱动限制和目标路径。尤其不要忽略验收末尾的删除失败，更不能递归删除整片目录来“清理现场”。WebDAV 排错

Q：密码正确，却提示 SSH 主机密钥变化？

重装系统或更换实例后，服务器主机密钥可能变化。应先通过服务商控制台核对当前 IP、服务器身份及旧／新指纹，确认变化合理后，再选择“更新并重新连接”。

当前主机记录位于 %APPDATA%\TG2Cloud-Deployer\known_hosts；不要清空整个记录文件来绕过校验，也不要接受原因不明的新密钥。

Q：磁盘看着足够，为什么部署器拒绝？

安装目录与 Docker 数据目录可能位于不同文件系统；总硬盘容量也不等于当前可用空间。检查安装盘、Docker 盘、下载、备份、保留线与 inode。

CloudDrive2 受管部署还需 /dev/fuse。无 FUSE 时先联系服务商确认，不要仅靠提高容器权限绕过条件。部署与排错说明

十三、旧 TG115 用户怎样迁移？

v1.1.1 不提供旧 TG115 的自动原地迁移，也没有声明旧队列和状态已完成真实环境迁移验收。

新部署使用独立目录、容器和网络，不自动接管、移动、覆盖、停止或删除旧资源。发现旧目录、已停容器或旧网络可能只提示；占用固定 19798/5244 端口、或目标新资源归属不明时会停止。

迁移前：

1. 处理旧队列，记录需要保留的失败任务和下载文件。
2. 使用旧项目的备份流程，私密保存配置、SQLite、网关状态与必要下载。
3. 记录 WebDAV 根目录、相对子目录和实际权限。
4. 不让新旧实例长期共用一个 Bot Token。
5. 新环境通过 WebDAV 和真实文件验收前，保留旧环境与独立备份。

优先使用独立 VPS 部署新实例。必须复用同机时，在维护窗口人工处理旧端口占用；不要仅改名目录、直接复制数据库或混用旧 .env 来绕过检测。

内部保留的 tg115.db 文件名、部分 TG115_* 环境别名及兼容标记，不表示部署器会自动导入旧数据。确实需要延续队列时，应制定单独的迁移与回退方案，不把全新安装流程当作状态迁移。从 TG115 迁移

十四、安全与使用范围

自托管让你控制部署位置和配置，但不自动消除账号、数据与第三方组件风险。

• 仅处理自己有权保存、备份和使用的内容，遵守平台规则与适用要求。
• 不公开 SSH 私钥、VPS 密码、Bot Token、API Hash、WebDAV 密码、网盘 Cookie、OAuth Token 或 Telegram Session。
• 日志、数据库、截图与备份都可能含个人数据，分享前人工脱敏。
• 部署器不自动保存表单密码；rclone obscure 是混淆，不是加密，VPS root 仍可读取服务配置。
• 受管 CloudDrive2 使用 FUSE，Compose 中启用了 privileged 和宿主 PID 命名空间，不能把 Bot 容器的非 root 限制等同于整个网关低权限。
• CloudDrive2 是第三方专有组件，其内部上传逻辑不在 TG2Cloud 源码审查范围内。建议与钱包、数据库等重要业务隔离。
• 管理域名公开的是登录界面，应使用强密码并保持组件更新；HTTPS 不代替后台鉴权。
• 19798/5244 只保持回环监听，不直接公开到互联网；Bot WebDAV 留在内网。
• 备份可能包含服务凭据与证书私钥，使用受限权限、安全传输并按需加密。

Bot 容器使用 UID/GID 10001、只读根文件系统、no-new-privileges 并移除 capabilities。这是降低风险的措施，不是对第三方网关或云存储的完整安全保证。安全政策、第三方组件说明、Compose 配置

附：需要自行构建部署器时

普通用户优先使用正式 Release。希望查看源码或自行构建时，可在有 Git 与所需构建环境的 Windows PowerShell 中使用固定标签：

1
2
3
4
5
6

git clone --branch v1.1.1 --depth 1 https://github.com/LuoPoJunZi/TG2Cloud.git
cd TG2Cloud

# 二选一；默认 .\build.ps1 则同时构建两版
.\build.ps1 -Edition CloudDrive2
.\build.ps1 -Edition OpenList

产物位于：

1
2

dist/TG2Cloud-CloudDrive2-Deployer.exe
dist/TG2Cloud-OpenList-Deployer.exe

自行构建的 EXE 与 Release 不必具有相同 SHA-256，不能拿官方校验值判断自己的构建。两版是独立入口，不在同一个 EXE 内切换后端；旧 Tkinter Classic 与 CMD 启动器已经不属于当前交付流程。构建依赖与运行时处理以标签中的 build.ps1、requirements-build.txt 为准。源码构建说明

写在最后

TG2Cloud 的价值，是把选好文件之后的排队、下载、上传、检查与收尾整理成一套可观察、可重试的流程，而不是承诺无限速、零成本或所有网盘都能秒传。

初次使用先让 HTTPS、WebDAV 和一个真实小文件走通，再逐步增加文件规模与并发。重要文件保留独立备份，分清 Bot 完成、网关接收和云端最终状态，才能更稳妥地使用这套工具。

项目与下载入口：LuoPoJunZi/TG2Cloud。再次感谢 whyhhh20/TG115 原作者及相关开源组件贡献者。

参考资料

功能与操作主要依据 v1.1.1 项目说明、发布说明、新手文档及对应标签源码；HTTPS、升级、备份、任务状态与迁移分别链接到具体章节来源。Telegram 凭据申请参考官方文档，速度计算为本文在明确假设下的算术估算。

资料整理日期：2026 年 10 月 1 日。本文不替代使用者的实际环境验收，也不把仓库记录的验证范围扩大成所有云存储、文件大小和恢复场景均已通过。