TG2Cloud 是一个自托管的 Telegram 文件转存工具：把文件发送或转发给自己的 Bot，由 Linux 主机排队处理，再经 rclone 和 CloudDrive2／OpenList WebDAV 写入自己挂载的云存储。

本文按“选部署方式 → 安装 → 配置网关 → 首次转存 → 日常使用 → 升级与备份”整理，同时补充管理员授权监听、文件命名、家庭共享和手机只读访问。原有的速度估算、失败恢复与旧 TG115 迁移注意事项继续保留。

项目仓库 · v1.5.6 发布与下载 · 一键安装 · Compose 部署 · Bot 使用 · 监听指南

本文更新于 2026 年 11 月 3 日，以 TG2Cloud v1.5.6 正式版为操作基线；该版本于 11 月 1 日发布。当前项目支持 Linux，不再以 Windows EXE／PySide6 部署器作为现行安装流程，旧文中的 EXE 下载、按钮步骤与 Windows 构建命令不应继续照搬。

更新脚本不等于更新 Bot；容器健康不等于转存成功；默认卸载不等于保留数据。 升级和删除前先做独立私密备份，按自己的部署方式操作。

固定标签中的部分文档保留发布准备期文字。是否已发布以实际 Release 与资产为准，发布后的核验进度另见本版验收记录；CI、镜像和包校验通过，不代表真实 VPS、网关、手机及灾难恢复全部验收。

项目来源与致谢： TG2Cloud 基于 whyhhh20/TG115 演进，保留 MIT 许可证、原作者版权与必要致谢。感谢原作者和 Telethon、rclone、Docker 等组件贡献者；CloudDrive2、OpenList 及云存储仍受各自许可与服务条款约束。许可证、第三方组件说明

先选择自己的路线：

Windows／macOS 可以作为 SSH 客户端或浏览器使用，但不是当前 Bot 的服务器运行环境。平台范围

一、TG2Cloud 能做什么？

基本链路没有变：

1
2
3
4
5
6
7
8
9
10

Telegram 私聊发送／转发附件
          ↓
SQLite 持久任务队列
          ↓
普通模式：完整下载到 Linux，再上传
流式模式：Telegram → rclone 传输管道
          ↓
CloudDrive2／OpenList WebDAV
          ↓
本人在网关中挂载的目标云存储

管理员还可单独授权个人 Telegram 账号，监听自己已加入且有权读取的频道／群组，将符合规则的附件生成转存计划。监听默认关闭，不是安装后自动采集全网内容。

• 手动入口仍是 Bot 私聊。 管理员或已授权家人可提交附件；直接发给 Bot 的群组／频道消息不会因此变成有效任务。
• 监听是另一条受控入口。 需要管理员登录个人账号、启用监听与来源；不自动加入、不读取评论、不承诺完整历史、不绕过实际读取限制。
• 不是网盘秒转接口。 数据仍经过主机与网关，消耗带宽、流量、磁盘及网关资源。
• 不只限于 115。 可用目标由本人在 CloudDrive2／OpenList 挂载的存储决定，不代表所有驱动都已验证。
• 大小复验不是内容哈希。 “Bot 完成”不等于云存储官方最终入库，重要资料仍需自行核对。
• 流式不是零磁盘或永久续传。 Bot 减少完整落盘副本，但网关缓存仍占空间；跨进程中断通常需重新传输。

文件分类、主动异常通知、家人配额和外部 WebDAV 都是可选能力，不会因为升级文档就自动开启。项目说明、功能与边界

二、选择 CloudDrive2 版还是 OpenList 版？

两个 Edition 共用 Bot 核心，各有配置、任务库、Session 和存储网关。先选一版走通，不必同时安装。

上表是一键受管部署的目录与地址；独立 Compose 使用自己的部署目录和同版包内配置，不能把两套目录混在一起。Docker 主机名给 Bot 容器使用，不是让 Windows 浏览器访问的地址。

两版可以共存，但使用不同 Bot Token、独立持久化数据，公网管理使用不同域名。网关支持某个云存储，不自动等于其写入、查询大小、改名及清理都适合当前流程，仍需真实验收。

TG2Cloud 按 MIT 开源；VPS、网盘容量、网关会员或第三方功能费用另计，不能把“开源”理解为整条链路没有成本。存储指南、产品配置源码

从旧文章升级，先看这些变化

v1.5.6 继续使用业务 schema 3；从更早版本升级仍可能经过已有迁移。不能直接用旧镜像打开新库回退，也不能把旧版实机记录当作当前全部场景已通过。更新记录、本版发布与兼容

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

1. Linux 主机、资源与客户端

50GB 只是容量参考，不保证都能给任务暂存。系统、Docker、日志、网关缓存和历史备份也占空间；一键脚本还会核对安装盘、Docker 盘、inode 和所选预算。

内网向导要求本机 rootful Docker Engine 28+、Compose v2；独立 Compose 教程采用 Docker Engine 28+、Compose 2.24.0+。已有 Docker／NAS 套件由原方式维护，不直接替换厂商组件或批量卸载其他服务。Linux 范围、Compose 前置条件

2. SSH 与主机身份

准备主机 IP／域名、SSH 端口、用户名及密码或私钥；使用带口令的私钥还需其口令。

首次连接核对主机密钥指纹。重装或换机后出现密钥变化，先通过服务商控制台确认；不要清空整个 known_hosts 来绕过校验。

文中的安装、管理和 Docker 命令在目标 Linux 终端运行，不在本机 Hexo 博客目录中执行。 Bot 的 /status 等命令则在 Telegram 私聊中发送，两者不要混用。

3. Telegram 四项参数

安装只设置一个固定管理员。需要多人使用时，安装后通过用户管理授权家人，不向 ALLOWED_USER_ID 填多个 ID，也不靠改这个字段迁移管理员。

基本 Bot 安装不要求个人账号验证码；可选监听登录会在自己的私密 Linux 终端要求手机号、验证码及可能的 2FA。 不向维护者、Bot 聊天或公开日志提交这些信息。填写清单、Telegram 应用申请

4. 存储与凭据

准备足够的目标云存储空间，并由本人在自己的 CloudDrive2／OpenList 后台完成登录、扫码、Cookie 或 OAuth 授权。

这些密码不能互换。当前一键向导的 Bot WebDAV 密码留空可生成 8 位随机值，也可自己设置更长的合适密码；旧实例升级保留已有值，不会自动换成新默认。配置参考

5. 域名与端口

公网一键部署需要可用的管理域名。两版共存时分别准备，例如 cloud.example.com 与 list.example.com。

将全部 A／AAAA 正确指向主机；没有可用 IPv6 时不保留错误 AAAA。首次 ACME 签发按指南使用 Cloudflare“仅 DNS”，自行开放安全组／防火墙 TCP 80/443。

现有 Nginx、Caddy 或其他服务占用端口时，不自动关闭它们。受支持的已有 Docker Nginx 可按专门流程接入，须检查真实配置、挂载与授权；不是“检测到端口占用就强制重装代理”。复用 Nginx

公网 NAT 主机网卡可能只有私有地址。新向导在严格条件下允许人工核对云控制台分配的公网 IPv4，不把正确公网 A 记录改成私网地址，也不通过第三方出口 IP 查询猜测映射；确认后仍需 ACME、本机自检和外部访问验收。公网 NAT 说明

可信内网使用独立入口，无需域名，但 HTTP 不加密；它不是公网 HTTPS 的关闭开关。

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

一键向导会探测资源，提供“流式优先”“均衡”“手动”方案，再按计划确认。手动默认参考仍是：

1
2
3

任务暂存预算：20GB
磁盘最少保留：8GB
新装默认时区：Asia/Shanghai

这不是对所有机器的建议。小盘主机应采用自己的推荐值；20GB 不是硬性最低任务预算，也不是磁盘分区或单文件上限。

• 任务预算约束 Bot 暂存与额度预留。
• 保留线保护真实文件系统，首次向导不允许低于 8GB。
• 单文件超过预算可自动走流式；多个普通任务累计占满预算而排队，不代表全部自动切流式。
• 镜像、网关缓存、历史备份和日志不会因调低预算自动清空。
• 暂存、DB、日志等同盘时不重复相加可用容量；容器看不到的独立网关／Docker 盘仍需宿主机检查。
• 更换安装目录、存储方式或磁盘后，重新核对容量；不要通过把保留线设成接近零来绕过保护。

已有实例升级保留原配置，不静默应用新推荐。独立 Compose 的 setup 能填写预算，但不提供与一键向导相同的完整宿主机资源预检。磁盘保护、部署说明

五、Linux 公网一键部署流程

这里替代旧版 Windows 部署器教程。先准备完整 SSH 会话、域名和 Telegram 参数；从当前正式入口安装，不使用历史 EXE 去管理新版本。

本文命令固定到 v1.5.6 的入口文件，便于核对行为。固定入口不等于永久锁住业务版本：向导仍核对执行时最新正式稳定 Release，查看实际显示的目标版本与计划，不默认部署移动的 main 或预发布代码。安装指南

第一步：只读预检，明确 Edition

下面两版择一；只读预检不会安装、升级或执行 WebDAV 写入，但需要联网读取正式版本与临时源码。

1
2
3
4
5

# CloudDrive2 Edition
bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.6/install.sh) --edition clouddrive2 --check

# OpenList Edition：选这一版时才执行
bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.6/install.sh) --edition openlist --check

脚本会执行仓库下载的代码，使用前核对来源。若不希望直接运行远程入口，可以先下载到未占用的文件名，审阅后在交互终端运行。不要使用 curl | bash，不把密码、Token 或 API Hash 放入参数。

网络失败、API 限流、版本或指纹不匹配时停止；外层 Bash 没有报错，也不能替代安装器的实际成功结果。

第二步：启动安装或管理向导

1

bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.6/install.sh)

不带参数时先选 Edition：未安装进入新装向导，完整已有实例进入统一管理菜单。已有实例以保存的公网／内网模式为准，不因为换了入口就隐式转换。

新装按提示核对域名、资源方案、Telegram 四项信息、专用 WebDAV 用户／密码及保存子目录。子目录不确定时先留空，在网关后台给用户限定好根目录。

当前向导新装默认 Asia/Shanghai，不再单独询问；WebDAV 用户可默认 tg2cloud，密码留空按当前生成策略处理。升级保留原配置、密码、预算和时区，不用新表单覆盖旧值。

第三步：查看计划，明确确认

最终确认默认取消。确认后才进入依赖准备、基础环境、候选校验、备份、安装或切换，以及必要的 HTTPS 操作。

过程中不要从另一终端反复安装、修复或操作同一实例。APT、镜像下载与构建耗时取决于环境；进度阶段不是根因，先看第一处有效错误和真实退出状态。

确认安装计划后，可获得本地 tg2cloud 管理命令。已有实例没有它时，重新运行当前入口，核对计划并确认安装／更新管理工具；--check 不会替你安装该命令。

第四步：完成 HTTPS，再配置网关

公网受管部署需要证书、HTTPS 管理页、HTTP 跳转、管理域名 /dav 阻断与后端回环监听检查。基本容器成功而 HTTPS 失败时，应续做检查，不能当作全部部署完成，也不删除数据库重装。

首次建号所需 WebDAV 信息及 OpenList 初始化管理员密码，会在默认中文新装流程的当前私有终端集中显示，不写普通日志；后续“查看凭据”或显式兼容参数可能仍逐项确认。不要录屏或公开终端历史。

随后打开实际管理域名，由本人挂载云存储，并创建与已保存信息一致的专用用户。Let’s Encrypt 邮箱不能再当作到期提醒：其到期邮件服务已于 2025 年 6 月 4 日停止，仍需检查证书与续期记录。证书公告

第五步：验收后再提交真实文件

运行 tg2cloud，选择当前 Edition → 11. WebDAV 验收，核对随机文件创建／删除提示并确认。

1

TG2CLOUD_DESTINATION=OK

之后向 Bot 私聊发送自己的小文件，并在网关和云盘官方客户端核对名称、大小与可打开性。安装摘要中的“通过”“未执行”“未核实”各有含义，不把未执行步骤当成功。验收说明

补充：内网与独立 Docker Compose 部署

方案 A：可信内网一键向导

使用符合要求的 Linux 主机或 NAS 虚拟机，填写运行脚本那台主机自己的私有 IPv4，而不是另一台电脑或 NAS 宿主机的地址。

1
2
3
4
5

# 先预检；示例 IP 必须替换
bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.6/install-lan.sh) --edition clouddrive2 --lan-ip 192.168.26.5 --check

# 再运行交互向导，选择实际 Edition
bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.6/install-lan.sh)

支持本机网卡上的 10.x.x.x、172.16.x.x～172.31.x.x、192.168.x.x，不填公网、回环、Docker 桥接地址或 URL。OpenList 的显式参数为 --edition openlist。

入口不申请证书、不占用 80/443，也不把后端改为 0.0.0.0。HTTP 不加密，禁止公网端口转发、UPnP 暴露或公网反代。需要公网管理时走相应 HTTPS 方案，不能借内网入口绕过保护。

1
2
3

TG2CLOUD_LAN_BASE=OK
TG2CLOUD_LAN_ENTRY=OK
HTTPS=NOT_APPLICABLE

这些只说明本机基础服务与入口检查通过。还要从另一台可信设备打开页面，配置网关和用户，执行 WebDAV 验收，再测试 Telegram 转存。尚未配置好时选择不验收，之后可单独运行：

1

bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.6/install-lan.sh) --edition clouddrive2 --verify

OpenList 换成 openlist。地址变化时不通过 --lan-ip 隐式迁移；建议 DHCP 保留或固定 IP。另行备份 /opt/tg2cloud-lan/<edition>/，不把业务回退包当作内网入口备份。内网指南

方案 B：独立 Compose，自己维护容器

Compose 不是一键安装器生成目录的快捷接管方式。使用 Release 对应的 Compose 包，不要拿 source.tar.gz 或另一版本的 YAML 混用。

两版使用同一个 COMPOSE-SHA256SUMS.txt；源码用的 SHA256SUMS.txt 不适用于 Compose 包。只下载一版也要看到自己这份显示 OK，不是“没有文件被验证”。校验和用于完整性检查，不是数字签名。

以下以 CloudDrive2 为例，在全新的本地真实目录操作。已有目录时停止核对，不删除旧实例来腾位置：

1
2
3
4
5
6

mkdir /opt/tg2cloud-compose-clouddrive2 &&
cd /opt/tg2cloud-compose-clouddrive2 &&
curl -fLO https://github.com/LuoPoJunZi/TG2Cloud/releases/download/v1.5.6/TG2Cloud-v1.5.6-compose-clouddrive2.tar.gz &&
curl -fLO https://github.com/LuoPoJunZi/TG2Cloud/releases/download/v1.5.6/COMPOSE-SHA256SUMS.txt &&
sha256sum --ignore-missing -c COMPOSE-SHA256SUMS.txt &&
tar -xzf TG2Cloud-v1.5.6-compose-clouddrive2.tar.gz --strip-components=1

OpenList 使用其对应包、目录和下列服务名。NAS 可选择自己的全新本地数据目录，不使用云盘挂载或不安全软链接；厂商 Docker 由原套件维护。

初始化与访问方式

1
2

docker compose config --quiet
docker compose run --rm setup

setup 要有交互终端，不加 -T，不在后台喂答案。按提示输入 Telegram、WebDAV、预算和管理访问方式；不要把 .env.example 改名当正式 .env。初始化会生成私密配置，不会替你挂载云盘或创建网关用户。

可选访问方式为本机／可信内网、自动 HTTPS、已有反向代理。选项只保存访问计划，不表示证书已经签发；本机／内网只绑定本机回环或私有 IPv4，不绑定公网或 0.0.0.0。

先只启动所选网关，后台配置完成后再启动对应 Bot；不要把两版命令都执行一遍：

内网直接访问初始化时填写的主机地址加端口。若保留回环地址，可在自己的电脑另开 SSH 终端，例如：

1

ssh -N -L 19798:127.0.0.1:19798 用户名@服务器地址

核对主机身份，保持隧道窗口，再用同一电脑浏览器打开 http://127.0.0.1:19798。OpenList 改用 5244；非默认 SSH 端口按实际加 -p。这是独立 Compose 的系统 SSH 方案，不是恢复旧 Windows 部署器按钮。

完成第六节网关挂载和专用用户设置，再按表格启动所选 Bot，然后检查：

1
2

docker compose ps
docker compose run --rm setup python -m tg2cloud.compose check

状态和配置检查通过后，再测试真实 Telegram 小文件。不要为省步骤一开始就无差别启动所有服务。Compose 完整分步教程

Compose 的可选 HTTPS

v1.5.6 完整包包含 https.sh 和配套 https-tools/。在已初始化、身份和服务可核对的部署目录，可用宿主机 root 运行：

1

bash https.sh

该可选功能另需宿主 Python 3.10+ 等条件；普通 Compose 初始化不要求主机安装 Bot 的 Python 依赖。自动模式复用受管 Nginx＋Certbot，已有其他代理时只导出候选配置，由你审阅、测试并按原代理方式接入，不擅自修改或 reload 其他站点。

compose-access.json 是访问计划；setup 不会申请证书，导出候选不等于已接入，HTTPS 本机检查也不等于公网通过。包的 YAML、镜像 digest、元数据和完整 helper 必须同版，不能只复制一个脚本。Compose HTTPS 说明

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

无论从哪条部署路线开始，云存储授权与专用 WebDAV 用户都要由本人在网关后台完成。向导保存了用户名／密码，不等于已在网关创建同名账号。

方案 A：CloudDrive2 Edition

1. 打开实际管理地址，登录自己的 CloudDrive2。
2. 添加并授权目标云存储，确认能浏览预期目录且剩余空间足够。
3. 开启 WebDAV，创建与安装保存值完全一致的专用用户。
4. 选择用户根目录，关闭只读，授予列表、读取、写入、改名及任务清理所需删除能力。
5. 返回对应安装／管理流程执行真实写入验收。

CloudDrive2 的账号、版本和会员能力以实际环境为准，不把会员密码填成 Bot WebDAV 密码。

方案 B：OpenList Edition

1. 新装使用独立的初始化管理员密码；已有实例使用当前后台密码，重新部署不自动重置。
2. 添加并授权目标存储，例如 115 Open，确认能浏览目录。
3. 创建专用普通用户，用户名／密码与已保存值一致，不让 Bot 使用管理员账号。
4. 设置基本路径，允许列表、读取、WebDAV 写入、创建及必要删除能力。
5. 执行验收；正常提交直接写入预留最终路径，不要求 MOVE，不能照搬 CloudDrive2 的临时文件改名策略。

根目录与相对子目录只组合一次

MyCloud 只是挂载示例，不是固定名称。子目录不填 VPS 的 /opt/...、手机的 /dav/、完整 URL、.. 或反斜杠，也不在两处重复填写同一层。

同机受管 Bot 继续使用 Docker 内部 WebDAV，不改成管理域名或浏览器内网地址。安装后修改账号／目录，先处理旧任务再通过完整配置更新；已有任务保留接收时的目录，不自动搬家。

Bot 写入用户不能只读；给手机用的外部用户则必须原生只读。两类权限相反，不能为省建号共用一个账号。网关配置与权限对照

七、管理入口、WebDAV 和真实文件分别证明什么？

公网 HTTPS 与可信内网要分别检查

公网从独立网络检查 HTTPS 证书、HTTP 跳转、管理域名 /dav 与 /dav/ 的阻断，以及公网 IP 加 19798/5244 不能直接打开后台。本机自检使用回环与真实域名校验证书，不能代替外网检查。

LAN 从另一台可信设备访问实际 IP 和端口；HTTPS=NOT_APPLICABLE 只是模式不适用，不是证书通过。独立 Compose 根据自己选择的回环、内网或 HTTPS 方案分别验收。

管理域名的 /dav 返回 403 是预期保护；可选外部 WebDAV 使用另一独立域名和只读账号，不能混为同一个入口。

WebDAV 验收确实会创建和删除文件

验收从 Bot 容器使用实际保存配置，生成 256 字节随机文件，依次检查认证、目录、写入和远端大小。CloudDrive2 另执行改名与复验；OpenList 输出 MOVE 不需要的结果，直接复验最终路径。

最后删除远端及本地测试文件并复查，完整成功标记为：

1

TG2CLOUD_DESTINATION=OK

能列目录不等于可写，能上传不等于清理通过。错误、中断或未执行阶段不当成功，也不通过公开后端端口、跳过 TLS 或递归删除网盘目录来让检查“变绿”。写入验收与失败分层

再做真实 Telegram 小文件测试

先使用可重复获取的自有小文件，再逐步测试普通落盘、流式、Bot 重启恢复。只有愿意删除的测试任务才用于取消与清理测试。

“Bot 完成”表示程序负责的传输、大小复验与收尾完成，不等于网盘官方接口确认或内容哈希一致。重要文件还需在官方客户端核对名称、大小、可打开性，必要时自行比较哈希。

本文没有操作读者的 Telegram、VPS 或云盘；项目本版发布记录也明确保留真实环境待验收项。验证与恢复边界、本版记录

八、日常转存、命名与管理员监听

先走通手动私聊，再增加自动化

管理员打开自己的 Bot，发送 /start 或 /help，提交有权保存的附件。收到持久化接收回执和任务编号后，不因排队而反复转发；先通过任务详情查原因。

安装后可授权家人，但群组／频道直接给 Bot 发消息仍不是有效的手动任务入口。管理员个人账号监听另行启用，见本节后半部分。

命令速查

123、关键词和页码都是示例，命令在自己的 Bot 私聊发送。

原生命令菜单仍只注册 /status、/queue、/pause、/resume、/doctor、/orphans、/help 七项。菜单里看得到不等于有权限，其他带参数命令可手动输入。完整 Bot 指南

状态、速度与失败计数不要混看

首页 ⏳ 为排队数，⬇️ 为活动下载，⬆️ 为活动上传（含流式），❌ 为当前统计范围内的失败；为零也显示。三个快捷按钮分别打开任务列表、管理员 VPS 资源页、原地刷新。

• 下载速度是 Telegram 到 Bot，上传速度是 Bot／rclone 写 WebDAV，不是网关继续向云盘写入的速度。
• 流式的同一管道采样同时出现在两个方向，不能当两次独立测速相加。
• 管理员 🌐 为 Bot 运行环境网卡收发合计，Docker 中通常是容器采样，不保证代表整台 VPS。
• 家人只看本人任务和速度，其 🌐 是本人下载／上传合计，不显示管理员资源页。
• 页面更新时间不是实际 WebDAV 探测时间，冷却与探测看 /doctor；首页刷新是快照，不等于持续测速。

失败数按实例时区的本地日历周统计仍失败的任务，每周一 00:00 切换，不是滚动七天，也不会清空历史。查询历史失败用 /tasks failed。

失败后选对恢复方式

网络／5xx 等可恢复失败先排查后 /retry；401／403 修正凭据与权限，429 等待服务端限制，不盲目批量加压。

已取消任务用 /restart 请求确认；远端大小不一致、提交不确定或冲突时，用 /recover 的确认流程换名重传，不覆盖不确定文件。普通模式尽量保留完整本地副本；流式通常没有完整副本。

取消只有确认受管远端清理后才继续本地收尾；不能核对时保留数据。/orphans 只扫描配置目标第一层的受管 .uploading-*，不是递归扫网盘；扫描不完整时禁止清理，删除最多 100 项并再次核验引用。任务恢复指南

文件名从哪里来？

当前不是“所有视频都按说明改名”。通常保留有意义原名；数字名、默认编号、随机 ID 或明确污染名，才尝试从实际收到的可靠说明提取标题。无可靠说明就安全兜底，不猜视频内容。

完整且已验证的媒体组可共用说明，保留成员自己的季集／章节和真实扩展名。只收到单个视频而没有说明时，不会自动去读来源评论、其他消息、网页或画面文字，也不做 OCR。

v1.5.5 起清理新文件名与说明候选两端明确的域名／账号推广标记；保留有效标题、扩展名和原名审计。不追溯改名已登记任务或云端文件。

可在 Bot 转存设置选择兼容命名、说明标题优先或字段模板，并先预览。人工改名影响本次计划；来源规则须明确保存，只对未来计划生效。命名规则与示例

管理员授权监听：先登录，再启用账号与来源

监听默认关闭，不增加一个必填账号。只在管理员的 Linux 私密交互终端执行，以下 Edition 二选一：

1
2

tg2cloud listen login --edition clouddrive2
tg2cloud listen status --edition clouddrive2

OpenList 将参数换为 openlist。也可从 tg2cloud → 当前 Edition → 16. 监听管理进入。手机号和验证码在当前终端可见，2FA 隐藏；不发给 Bot、不写命令参数，也不公开 Session。

个人 Session 位于 data/listener/personal.session，与 data/bot.session 分开。登录成功后仍需在 Bot /listen 中明确启用账号，再添加自己已加入且有权读取的来源。

新增来源先暂停，默认仅视频、确认后转存；v1.5.5／v1.5.6 源码默认至少 50 MB（50×1024² 字节），排除“广告、内部群、搜索引擎”，匹配文件名与说明，无大小上限。已有来源不自动改规则。

按来源设置筛选、命名、保存目录和自动／确认模式，先用“测试规则”只读预览，再保存并启用。添加、修改规则不等于自动启用；账号与来源是两个开关，首次及重新启用从当前时点开始。

新来源在 Bot 保存目录下按来源名称建立目录，再按视频、图片等类型归档；不会因频道改名自动搬目录，已有来源仍保留旧策略。修改目录只影响未来计划，不移动历史文件。监听设置与目录

待确认计划、历史补拉与限流边界

• 手动默认自动入队；可切确认模式。/pending 每页 10 项，每人最多 200 项，7 天过期；未确认不下载、不预留额度。
• 单项可确认、仅本次改名、选择授权目录或忽略；批次最多 20 项，入队后冻结名称、规则和目录。
• 来源可保存最多 8 个规则方案，预览后原子应用到最多 8 个来源，不顺便更改命名、目录或启停。
• 自动重启补拉有最多 6 小时窗口，不承诺补全全部历史。另有最近 1／6／24 小时的手动历史预览，最多检查 100 条／20 秒；确认最多登记 5 个待确认计划，不改正常监听游标。
• 来源“失败恢复”只对符合条件的下载失败做小批核验，最多 5 项／30 秒；不把远端不确定对象批量重传。
• 限流按 Telegram 要求等待，短等待恢复不是跨重启字节级续传；授权失效、无权限或附件变化仍停止，不借 Bot 或另一个身份绕过。

监听不自动加入来源、不读评论，不解除服务端实际读取限制。历史缺口、暂停与限流都需管理员核对，不用关闭限流或反复重登作为通用修复。监听与恢复完整边界

家庭共享与可选分类

安装仍只有一个固定管理员。安装后通过 tg2cloud → 5. Bot 用户管理授权最多 32 位家人；各自私聊同一个 Bot，只管理自己的任务，共用保存目录，不是个人云盘隔离。

停用家人不自动取消已接收任务、删除文件或撤销其外部 WebDAV 读取权限。两版授权互不共享；全局暂停、诊断、资源及遗留清理仍是管理员能力。

分类默认关闭，可从 8. 文件分类设置选择类型、年份、年月或组合，只影响新任务，不搬历史文件。9. 异常通知设置默认不主动发送；可按需启用，不能当离线主机监控。成员配额按日完成量与未完成预留计算，不是网卡重传计费。家庭授权、分类通知与配额

九、转存速度怎么样？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 的下载、上传与 Bot 运行环境网络采样观察瓶颈。

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

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

Bot、离线管理工具和附加功能分别核对

常用入口是 tg2cloud，不是旧 Windows EXE。主机没有命令或仍是旧版时，从当前公网／内网入口确认更新；--check 不更新任何运行组件。

1
2
3

tg2cloud --version
tg2cloud listen --help
tg2cloud

查看 2. 运行状态核对真实 Bot 版本、容器和入口；tg2cloud --version 核对 CLI，不用本机工具版本替代容器版本。工具更新后应退出旧菜单进程，再重新打开。

外部 WebDAV 的维护代码独立更新：主菜单 15 → 子菜单 8. 升级附加功能。只升级 Bot 不会自动替换旧附加工具，也不能据新文档认定旧机器已具备新菜单。运行维护

当前管理菜单按对象操作

以实际版本和菜单文字为准，旧文档编号不同。查看日志、退出订阅或关闭 SSH 窗口不等于停止 Bot；暂停、停止和卸载也不是一回事。

每实例旧管理脚本仍保留

以下示例用于一键部署的已安装实例，不在独立 Compose 目录或源码 checkout 中执行：

1
2
3

/opt/tg2cloud-clouddrive2/manage.sh status
/opt/tg2cloud-clouddrive2/manage.sh check
/opt/tg2cloud-clouddrive2/manage.sh logs

OpenList 换成 /opt/tg2cloud-openlist/manage.sh；它另有不持续跟随的 recent-logs。日志可能含文件名，分享前仍要人工脱敏。

manage.sh update 不下载最新版 TG2Cloud 代码；普通 restart 不重新加载新环境配置。 不要把它们当作完整 Release 升级。命令影响对照

一键部署的推荐升级顺序

1. 阅读目标正式版，暂停新调度、等待活动任务，并处理失败保留文件。
2. 保存独立私密备份，确认 Edition、实例目录及访问模式。
3. 从对应公网／内网入口执行只读预检，核对可信旧版基线与目标版本。
4. 确认保留配置升级，不手改版本标记、指纹或网关镜像来绕过检查。
5. 核对 Bot 与 CLI 两个实际版本、原配置和任务；退出重开管理菜单。
6. 显式 WebDAV 验收，再做真实小文件与外部入口检查。
7. 确认稳定后恢复调度，再评估旧备份清理。

旧版本 Release／Tag 被删除时，受支持的历史版本可使用项目已审阅的原提交基线；未知版本仍停止。不要自行下载任意 SHA 冒充旧正式源码，也不以卸载重装解决校验失败。

独立 Compose 的更新不是这套菜单

保留同 Edition 的旧部署包、固定镜像和数据；在新下载目录校验目标完整包。暂停、停机、离线备份后，按官方教程替换同版公开文件与**完整 https-tools/**，不把两版 helper 混合。

保留 .env、tg2cloud-compose.json、存在时的 compose-access.json、data、config、downloads、日志及网关状态。之后按教程拉取、检查再启动，不能只改镜像为 latest 或让一键安装器接管。Compose 升级步骤

修改完整配置与 v1.5.6 加固

修改 WebDAV 账号／目录之前先处理旧队列；在实例外的私密绝对路径准备匹配版本的完整候选配置，再使用 apply-config。它会备份、预检并重建 Bot，失败只尝试有限回退；不是只应用一个字段，也不能通过 source .env 执行配置。

v1.5.6 的重要变化：

• rclone 密码通过标准输入处理，私有候选配置成功后才替换；混淆不是加密。
• 本项目容器配置 json-file 日志轮转 10m、最多 3 份，Bot 文件日志另行轮转；不是整个主机的总占用上限。
• 当前运行用户拥有的 Session、业务库及已有 SQLite 旁文件收紧为 600；链接、硬链接或归属异常会拒绝，不自动 chown、删库或重新授权。
• 业务就绪／诊断单列个人监听连接、冷却、轮询新鲜度和缺口；Bot 基础健康不能替代监听健康。

新日志配置需在明确更新并创建相应容器后才生效，单纯重启旧容器不应用；共享代理沿原维护流程更新，外部复用代理由其所有者管理。近期异常是本进程有界观察，不是所有历史错误的完整审计。v1.5.6 发布说明

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

新旧数据库与两份 Session

v1.5.3 起，**新装使用 data/tg2cloud.db**；旧实例只有 data/tg115.db 时继续使用原文件，保留任务与授权，不自动改名或造空库。两库并存会停止，不自动合并。

Bot Session 为 data/bot.session；可选个人监听为 data/listener/personal.session。业务库快照成功不代表同时保存了两份 Session，更不等于网关授权和所有下载都已备份。

不要只复制活跃 .db，不要删 WAL／SHM 求通过，不把重命名数据库当作升级步骤。 当前 schema 3 包含监听与计划等状态，回退须匹配代码和一致性快照。配置与数据库选择

几类备份不能互相代替

不要递归打包 clouddrive/mounts，那里可能是真实 FUSE 云盘挂载。备份网关状态不等于备份云端文件。完整备份范围

一键部署：主菜单 13

从“数据备份管理”按对象选择实例快照、隔离校验、共享代理备份或清理。实例快照需要确认维护窗口；仅 Bot /pause 不会停止当前传输，更不冻结 SQLite 或 Session。

OpenList 的旧 manage.sh backup 会短暂停止网关和 Bot；CloudDrive2 没有同名业务备份命令，不能照搬。两版都可做共享代理备份，不表示业务回退点包含代理。

标准业务回退点目录：

1
2

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

只读盘点可用 manage.sh backups。旧 prune-backups N 是直接删除命令，按类型各保留 N 份（1～50、默认 5），不额外交互确认；优先使用有预览和确认的管理流程，不把清理当查询。

独立 Compose：先停机，再做离线备份

在 Bot /pause，等待活动任务结束；进入自己的 Compose 部署目录：

1
2

docker compose stop
docker compose ps -a

确认该项目 Bot 与网关都已停止，再运行：

1

docker compose run --rm setup python -m tg2cloud.compose backup --offline-confirmed

--offline-confirmed 是你确认已经停机，不是工具替你停机；setup 没有 Docker Socket，不能证明其他写入者已停止。备份不含 downloads、日志、云端文件及独立 HTTPS，失败暂存有需要时另行保护。

保留当前包与固定镜像；仅备份、不升级时，核对结果后再 docker compose up -d，最后通过 Bot /resume 恢复调度。Compose 离线备份

HTTPS、LAN 与外部读取另行保护

受管代理位于 /opt/tg2cloud-proxy，备份位于 /opt/tg2cloud-proxy-backups。应完整保存域名状态、Compose／Nginx 配置、认证资源和 certbot/letsencrypt/ 中的 live/、archive/、renewal/，不能只复制符号链接。

对应 LAN 记录 /opt/tg2cloud-lan/<edition>/、外部 WebDAV 私密目录 /opt/tg2cloud-webdav/ 及所用代理模式的恢复信息，也要逐项规划。复用外部 Nginx 的文件级维护不能套用受管代理整目录覆盖。

代理备份、核验、隔离演练、续期 dry-run 和历史清理是不同操作。dry-run 可能产生测试账户／日志，不是完全只读；成功也不代表正式续签或长期续期可靠。断连后先检查状态，不反复启动演练。代理维护

能读备份，不等于已恢复服务

菜单／离线工具的结构、哈希与数据库预检，只在隔离目录验证材料，没有一键覆盖生产实例的正式 Restore。先保留当前完整数据，再匹配版本、镜像、配置、DB、Session 和网关授权，隔离验证后决定恢复。

监听升级可能涉及事务迁移；旧程序不理解新目录策略、计划和远端保护记录。不要删表降 schema、只换旧镜像或拼接不同时间点文件，也不要同时运行同一 Token 的两套 Bot。

默认完整卸载可能删除这些可识别备份；重要副本必须放到卸载清理范围之外，并私密离机保存。恢复前检查

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

Q：没有 Telegram Premium 能用吗？

基本部署不把 Premium 列为前提，但能否发送、转发或下载仍受 Telegram 实际规则、权限和限流影响。TG2Cloud 不承诺解除文件大小、复制或服务端限制，也不保证固定速度。

监听遇 FLOOD_PREMIUM_WAIT 时按本版有界等待与恢复处理，不代表没有来源权限，也不应反复重新下载整部文件；超限或普通 FloodWait 仍保留冷却与人工核对。监听限流

Q：没有域名可以部署吗？

公网一键受管安装仍需 HTTPS 域名。可信内网可用 LAN 入口；独立 Compose 可保留回环并使用 SSH 隧道或已维护的代理。不能用 LAN HTTP 加公网端口映射代替 HTTPS。

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

不需要。Bot、任务和网关运行在 Linux 主机。若浏览器通过自己的 SSH 隧道访问后台，关闭隧道只影响该管理通道，不等于关闭服务端任务。

Q：一直排队，或并发窗口显示 1，是不是卡住了？

先看 /task 编号、管理员 /doctor 和暂停状态。窗口为 1 表示允许放行的额度，不等于已有一个活动任务；实际数量看首页。

核对任务／成员额度、磁盘保留线、挂载与目的端可用性。监听还需检查个人账号、来源启用、权限、冷却和待确认计划，不把所有排队都归咎于网关。

Q：上传速度是 0、网络速度很高，怎么判断？

校验、改名、本地清理不是字节上传；短文件可能很快写完。首页是手动刷新的快照，网卡收发、Bot 上传及网关继续向云盘写入的范围不同，不用相减或相加推算端到端速度。

先查任务阶段与当前版本，不能以单个显示值直接断言卡死、无限速或云盘已最终完成。状态与测速说明

Q：401、403、429 怎么处理？

401 核对当前运行配置与专用用户是否一致，别把管理员密码当 WebDAV 密码；403 核对根目录和读写／删除权限，并确认不是在用管理域名传文件。

429 停止重复验收，等待网关或上游限制解除。OpenList 只读探测的 401 冷却 5 分钟，429 按 60、120、240、480、900 秒退避；刷新不会绕过它，冷却结束也不保证服务端已放行。显式写入验收不使用这套缓存。

Q：HTTPS 本机通过，外部浏览器打不开？

检查全部 A／AAAA、安全组、防火墙、80/443、Cloudflare 与公网 NAT 映射。管理端口仍保持受控绑定，不改成公网 0.0.0.0 或关闭证书校验来修复。

Q：管理域名的 /dav 被拒绝，是故障吗？

通常是预期保护。Bot 使用内部 WebDAV；手机使用另行安装的外部只读域名。三种地址与账号不能互换。

Q：证书以后怎样维护？

受管 Certbot 每 12 小时检查，Nginx 每 6 小时重载；检查成功不等于证书已经续签。查看实际续期时间、文件变化和到期记录，界面维护时间统一 UTC。

受管维护中，剩余不足 22 天会提醒；最近检查失败或已有记录超过 26 小时未更新时，可能显示“HTTPS 可用，续期待检查”。即时 HTTPS 可用不代表续期故障已解决；旧实例“尚无记录”也不直接判失败。

填写邮箱不会恢复已停止的到期邮件；dry-run 通过仍不替代长期自动续期与外网检查。外部复用 Nginx 按其独立方案维护，不套用受管容器循环。证书与代理维护

Q：lookup 容器名、路径、权限或磁盘异常？

先确认所选 Bot／网关在线、受管网络正确、访问的是对应容器地址，且当前使用正确实例目录。网络修复不能代替密码、容量或云盘授权修正。

安装盘和 Docker 盘可能不同，总硬盘不等于当前可用空间；用宿主机只读 df -h、df -i、docker system df 核对，不删除 DB、Session 或整个 /opt。

CloudDrive2 仍需要 FUSE；NAS 文件系统不支持所需权限时按平台范围处理，不全局 chmod 777、替换厂商 Docker 或把 Bot 改 root。

Q：来源没有接收、历史没补齐，为什么？

登录监听账号不等于启用；账号和来源分别有开关，新增来源先暂停。小于默认 50 MB、命中排除词、未确认计划或未开启图片类型，都可能不入队；先用当前规则测试。

暂停期间不自动补抓全部历史，正常重启最多有界补拉 6 小时。手动历史预览也有时间／数量上限，不推进正常游标；不要反复添加来源或降低权限保护求全量采集。

Q：旧数据库名、旧日志或配置别名还能保留吗？

可以保留已被程序识别的兼容数据。tg115.db 不代表部署了错误项目；新旧库并存则停止核对，不手改名、不创建空库、不删除 WAL。旧变量兼容读取不表示可以混入另一套账号。

Q：APT 源报错或旧 Release 查询失败，能否直接重装？

不能据此删实例。APT 问题先核对活跃源的协议、主机、路径、发行代号与签名设置；只修正已确认条目，不整份换源或禁用签名。旧版本可信基线失败时保留服务、数据与备份，交由可追溯的正式流程处理。

更多细分错误见FAQ。提供反馈只附脱敏的版本、阶段、时间和相关错误，不公开完整配置、数据库、Session 或私人文件。

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

当前仍不自动接管旧 TG115；新布局、兼容字段或可识别旧库名称，不代表旧任务已迁移。标准目录区别仍是：

先处理旧队列，私密保存配置、SQLite 一致性快照、Session、网关授权及必要下载；记录实际 WebDAV 根目录和子目录。新环境通过真实验收前，保留旧环境和独立备份。

优先隔离部署。复用同机时，在维护窗口明确处理旧固定端口与容器归属；不靠改目录名、混用 .env、直接复制运行数据库或改版本文本绕过检查，也不让新旧实例长期共用同一个 Bot Token。

较新 TG2Cloud 的已审阅历史基线升级，不等于任意 TG115 自动迁移；独立 Compose 与一键实例也不是互相导入工具。涉及任务延续时制定专门迁移和回退方案。旧实例与可信升级边界、配置兼容

补充：手机读取与家庭只读账号

可选外部 WebDAV 让手机播放器／文件管理器通过独立 HTTPS 域名读取 Bot 已有目录，不重复挂载网盘、不复制数据，不默认安装或启用。

一键实例运行 tg2cloud → 选择 Edition → 15. 外部 WebDAV，在子菜单完成安装、状态、检查、启停、升级和用户管理。不再下载已退役的 install-webdav.sh；已有 tg2cloud-webdav 命令保留兼容，日常可从统一菜单进入。

向导确认实际 Bot 保存目录，再由本人在网关后台创建独立原生只读账号。根目录直接限定到最终共同目录，禁上传、删除、改名和管理；不复用 Bot、管理员或会员凭据，也不把 Nginx 方法限制当成原生权限审计。

Bot 家人授权与手机读取账号是两套权限，添加／停用一边不自动改变另一边。家人共同读取同一目录，不生成个人云盘；查看目录、实际播放与 Range 拖动仍需分别验收。

外部入口需要自己的公网 HTTPS／ACME 条件，纯内网 NAS 安装成功不代表能自动签发外部证书。主实例更新不自动升级附加维护工具；先主菜单 15 → 8 核对并显式更新，不能沿用不认识新状态的旧工具。

主卸载前须先卸载附加入口解除依赖，只“停用访问”还不够；不会删除云端文件或替你删除人工创建的网关用户。外部 WebDAV 完整说明、家庭共享边界

十四、安全与使用范围

• 仅处理本人有权保存、备份和使用的内容，遵守 Telegram、网关、云存储及来源规则；监听不自动加入、不代替授权。
• 不公开 SSH 私钥、Bot Token、API Hash、WebDAV 密码、网盘 Cookie、OAuth、个人验证码、2FA、Session、DB 或备份。
• 默认新装建号终端可能显示凭据；不要录屏或分享历史。Base64 与 rclone obscure 都不等于加密。
• Bot 仍使用 UID/GID 10001、只读根文件系统及移除 capabilities；CloudDrive2 的 FUSE／特权属于网关，不能理解为整个系统低权限。
• 管理与只读入口、写入与读取账号分开；HTTP 只在可信内网，不开放后台公网端口或跳过 TLS。
• v1.5.6 遇私密文件链接、硬链接或归属异常会拒绝；不要通过放宽权限、删库或重建 Session 绕过。
• 附加账号、证书私钥、日志文件名与授权状态也可能含隐私，备份受限并私密离机保存。
• 管理命令的只读、重启、写入、删除各有边界，不逐项“试跑”维护命令；并发操作前先核对 Edition 和锁。

CloudDrive2 等第三方组件的内部行为不属于 TG2Cloud 的完整可审计范围。建议与其他重要业务隔离，不把开源、容器健康或 CI 结果当作零风险保证。安全政策、第三方组件

十五、卸载前先预检，分清“停服务”和“删数据”

只想升级或排错，不要先卸载。当前默认完整卸载会删除所选实例配置、数据库、Session、下载、网关授权与可识别历史备份。 先停止新接收、等待活动任务，并将必要备份转移到清理范围之外。

v1.4.7 起已退役根目录独立 uninstall.sh；不再使用旧 main 下载地址，也不把 v1.2.0 默认保留数据的旧命令套到当前版本。

一键实例：先只读查看范围

1

tg2cloud uninstall --edition clouddrive2 --check

OpenList 换成 openlist；只有确实要核对两套才使用 --edition all --check。也可运行 tg2cloud，选择 Edition → 14. 卸载当前实例。若命令缺失，重新运行原安装入口进入已有实例菜单，不选重新安装。

实际卸载会移除所选受管 Bot、网关、项目网络和相应入口；保留数据模式也不是只暂停服务。以下示例明确选择保留数据，仍需核对并确认真实范围：

1
2

tg2cloud uninstall --edition clouddrive2 --keep-data --check
tg2cloud uninstall --edition clouddrive2 --keep-data

完整清理除默认取消的确认外，另要求 DELETE ALL clouddrive2（或相应 Edition／all）；仅删数据模式使用 DELETE …。没有通用 --yes 强删捷径，不混淆三种模式或确认口令。

另一 Edition、外部 WebDAV、共享 HTTPS／复用 Nginx、FUSE 挂载、未知引用或文件归属都会影响计划。发现异常先停止，不强制卸载 FUSE、不递归删 /opt、不全局 Docker prune。系统 Docker/Nginx、其他项目、云端文件、镜像缓存和必要锁元数据不按此清理。

独立 Compose 不用这个卸载器

在确认自己的部署目录、无活动任务并备份后，docker compose stop 暂停服务；docker compose down 移除该项目容器／网络，保留宿主机绑定数据。

若使用包内 HTTPS，先通过 bash https.sh remove 明确移除对应路由。不要让一键卸载器接管 Compose，不通过 down -v、系统 prune 或删数据库处理升级问题；彻底删除本地资料另行核对路径与备份范围。Compose 停止使用

完成标记与部分失败

TG2CLOUD_UNINSTALL_CHECK=OK 只表示预检；TG2CLOUD_UNINSTALL_RESULT=OK 表示所选卸载后检查通过，数据去留以计划为准。

PARTIAL、FAILED、INTERRUPTED 可能已部分执行，不能假定自动回滚已删对象。重新预检当前 Edition，核对剩余范围后再决定；完整卸载也不等于把 Linux 软件包、缓存、系统日志或 DNS 逐字节还原。卸载与保护条件

附：从源码查看 Linux 命令

普通使用优先采用正式入口或完整 Compose 包。需要审阅源码时，可以获取固定标签，在符合条件的 Linux 环境查看帮助：

1
2
3
4

git clone --branch v1.5.6 --depth 1 https://github.com/LuoPoJunZi/TG2Cloud.git
cd TG2Cloud
python3 scripts/run_source.py install --help
python3 scripts/run_source.py lan --help

源码现位于 src/tg2cloud/。帮助与纯标准库 CLI 不等于部署已完成；实际 Bot、网关与可选功能仍按对应依赖和实例条件运行。不要在新 checkout 继续使用旧 Windows build.ps1 或根目录旧 app.* 调用，也不要将下载源码当成已升级服务器。

写在最后

TG2Cloud 的重点是让转存、命名、排队、恢复和维护可观察、可核对，而不是承诺无限速、零成本、全网采集或所有网盘秒传。

先走通自己的管理入口、WebDAV 与真实小文件，再逐步启用监听、家人和外部读取。区分任务完成、网关接收、云盘最终状态，以及备份校验和实际恢复；重要数据始终保留独立副本。

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

参考资料

正文以 v1.5.6 正式标签的安装、Compose、网关、Bot、监听、命名、家庭共享、运维、备份和卸载指南为操作依据；是否正式发布及实际资产，另对照 GitHub Release 与发布后记录。

资料核对日期：2026 年 11 月 3 日。v1.5.6 标签内有些段落保留开发时期“未发布／待发布”措辞，不据此否认实际 Release；同样不把旧版用户验收扩大成当前版本全部场景通过。文中速度计算是保留的算术估算，不是本次实测。