TG2Cloud:Telegram 文件自动转存到网盘,支持 CloudDrive2 与 OpenList

TG2Cloud:Telegram 文件自动转存到网盘,支持 CloudDrive2 与 OpenList
落魄君子TG2Cloud 是一个自托管的 Telegram 文件转存工具:把文件发送或转发给自己的 Bot,由 Linux 主机排队处理,再经 rclone 和 CloudDrive2/OpenList WebDAV 写入自己挂载的云存储。
本文按“选部署方式 → 安装 → 配置网关 → 首次转存 → 日常使用 → 升级与备份”整理,同时补充管理员授权监听、文件命名、家庭共享和手机只读访问。原有的速度估算、失败恢复与旧 TG115 迁移注意事项继续保留。
项目仓库 · v1.5.8 发布与下载 · 一键安装 · Compose 部署 · Compose 管理 · Bot 使用 · 监听指南
本文更新于 2026 年 11 月 10 日,以 TG2Cloud v1.5.8 正式版为操作基线;该版本于 11 月 8 日发布。当前项目支持 Linux,不再以 Windows EXE/PySide6 部署器作为现行安装流程,旧文中的 EXE 下载、按钮步骤与 Windows 构建命令不应继续照搬。
更新脚本不等于更新 Bot;容器健康不等于转存成功;默认卸载不等于保留数据。 升级和删除前先做独立私密备份,按自己的部署方式操作。
固定标签中的部分文档保留发布准备期文字。是否已发布以实际 Release 与资产为准,发布后的核验进度另见本版验收记录;CI、镜像和包校验通过,不代表真实 VPS、网关、手机及灾难恢复全部验收。
项目来源与致谢: TG2Cloud 基于 whyhhh20/TG115 演进,保留 MIT 许可证、原作者版权与必要致谢。感谢原作者和 Telethon、rclone、Docker 等组件贡献者;CloudDrive2、OpenList 及云存储仍受各自许可与服务条款约束。许可证、第三方组件说明
先选择自己的路线:
| 场景 | 入口 | 需要注意 |
|---|---|---|
| 公网 VPS,希望由项目管理安装与 HTTPS | Linux 一键公网向导 | 需要管理域名、80/443 与正确 DNS |
| 可信内网 Linux/NAS 虚拟机,无公网域名 | Linux 一键内网向导 | 只绑定本机私有 IPv4,HTTP 不加密,禁止公网转发 |
| 已熟悉 Docker,自己维护容器 | 对应 Edition 的独立 Compose 包 | format 3 随包 manage.sh 管理;仍与一键实例分别核验身份 |
| 已有实例,只想升级或排错 | 沿用原部署方式 | 一键脚本与独立 Compose 不互相接管,不先卸载重装 |
Windows/macOS 可以作为 SSH 客户端或浏览器使用,但不是当前 Bot 的服务器运行环境。平台范围
一、TG2Cloud 能做什么?
基本链路没有变:
1 | Telegram 私聊发送/转发附件 |
管理员还可单独授权个人 Telegram 账号,监听自己已加入且有权读取的频道/群组,将符合规则的附件生成转存计划。监听默认关闭,不是安装后自动采集全网内容。
- 手动入口仍是 Bot 私聊。 管理员或已授权家人可提交附件;直接发给 Bot 的群组/频道消息不会因此变成有效任务。
- 监听是另一条受控入口。 需要管理员登录个人账号、启用监听与来源;不自动加入、不读取评论、不承诺完整历史、不绕过实际读取限制。
- 不是网盘秒转接口。 数据仍经过主机与网关,消耗带宽、流量、磁盘及网关资源。
- 不只限于 115。 可用目标由本人在 CloudDrive2/OpenList 挂载的存储决定,不代表所有驱动都已验证。
- 大小复验不是内容哈希。 “Bot 完成”不等于云存储官方最终入库,重要资料仍需自行核对。
- 流式不是零磁盘或永久续传。 Bot 减少完整落盘副本,但网关缓存仍占空间;跨进程中断通常需重新传输。
文件分类、主动异常通知、家人配额和外部 WebDAV 都是可选能力,不会因为升级文档就自动开启。项目说明、功能与边界
二、选择 CloudDrive2 版还是 OpenList 版?
两个 Edition 共用 Bot 核心,各有配置、任务库、Session 和存储网关。先选一版走通,不必同时安装。
| 项目 | CloudDrive2 Edition | OpenList Edition |
|---|---|---|
| 一键安装的 Edition 参数 | clouddrive2 |
openlist |
| 标准实例目录 | /opt/tg2cloud-clouddrive2 |
/opt/tg2cloud-openlist |
| 网关容器 | tg2cloud-clouddrive2 |
tg2cloud-openlist |
| Bot 容器 | tg2cloud-clouddrive2-bot |
tg2cloud-openlist-bot |
| 受管 Bot 内部 WebDAV | http://tg2cloud-clouddrive2:19798/dav |
http://tg2cloud-openlist:5244/dav/ |
| 后端回环端口 | 127.0.0.1:19798 |
127.0.0.1:5244 |
| FUSE | 需要 /dev/fuse |
不需要 |
| 正常文件提交 | 临时上传、改名、正式文件大小复验 | 预留最终路径、直接写入、大小复验 |
上表是一键受管部署的目录与地址;独立 Compose 使用自己的部署目录和同版包内配置,不能把两套目录混在一起。Docker 主机名给 Bot 容器使用,不是让 Windows 浏览器访问的地址。
两版可以共存,但使用不同 Bot Token、独立持久化数据,公网管理使用不同域名。网关支持某个云存储,不自动等于其写入、查询大小、改名及清理都适合当前流程,仍需真实验收。
TG2Cloud 按 MIT 开源;VPS、网盘容量、网关会员或第三方功能费用另计,不能把“开源”理解为整条链路没有成本。存储指南、产品配置源码
从旧文章升级,先看这些变化
| 版本阶段 | 与本文操作有关的变化 |
|---|---|
| v1.2.x 及更早 | 历史上提供 Windows EXE;旧操作与旧卸载默认值不作为当前教程 |
| v1.3.0 起 | Linux 模块化源码与命令入口;公网/内网一键安装继续保留 |
| v1.3.3 起 | 家庭成员授权及独立只读读取账号 |
| v1.4.x | 管理菜单、分类、配额、备份预检、外部 WebDAV、管理员监听与转存计划逐步完善 |
| v1.5.0~v1.5.2 | Bot 与 CLI 分别验收,监听恢复优化,新增独立 Compose 部署 |
| v1.5.3 | 新装数据库改用 tg2cloud.db,旧唯一数据库原名保留;Compose 增加可选 HTTPS 向导 |
| v1.5.4~v1.5.5 | 监听限流恢复、规则方案、有界历史补拉与推广前后缀命名清理 |
| v1.5.6 | 凭据处理、私密文件权限、日志轮转与监听独立健康诊断加固 |
| v1.5.7 | 监听下载的有界冷却恢复、来源访问诊断及真实日志限额核对 |
| v1.5.8 | Compose format 3 离线菜单、凭据白名单、资源限额与诊断、升级备份和卸载保护 |
v1.5.8 继续使用业务 schema 3,本轮没有数据库迁移,也没有新增一键安装必填配置;从更早版本升级仍可能经过已有迁移。不能直接用旧镜像打开新库回退,也不能把旧版实机记录当作当前全部场景已通过。更新记录、本版发布与兼容
三、部署之前需要准备什么?
1. Linux 主机、资源与客户端
| 项目 | 基础参考 | 注意事项 |
|---|---|---|
| 主机 | 2 核、4GB 内存、50GB SSD | 批量使用可参考 4 核、8GB、80~100GB;以实际探测与负载为准 |
| 系统与架构 | Debian/Ubuntu,原生 64 位 AMD64 或 ARM64 | 不把 ARM64 支持等同于任意 NAS 厂商系统兼容 |
| 一键安装权限 | root、Python 3.10+、Bash、curl、交互终端 | 缺少 CA、时区或网络工具时按检查提示补齐 |
| 网络 | 能访问 GitHub、镜像源、Telegram 与目标存储 | 标称公网带宽不等于每一段有效速度 |
| 本地电脑 | 可用 SSH 客户端和浏览器即可 | 任务在 Linux 主机运行,不要求电脑持续开机 |
| CloudDrive2 | 宿主机提供 /dev/fuse |
不通过把 Bot 改成特权容器绕过缺失条件 |
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 四项参数
| 参数 | 获取与用途 |
|---|---|
| Bot Token | 向官方 @BotFather 创建自己的 Bot |
| API ID、API Hash | 在自己的 my.telegram.org 应用信息中获取 |
| 管理员数字 ID | 只填一个 Telegram 用户 ID,不是手机号、@用户名、Bot ID 或频道 ID |
安装只设置一个固定管理员。需要多人使用时,安装后通过用户管理授权家人,不向 ALLOWED_USER_ID 填多个 ID,也不靠改这个字段迁移管理员。
基本 Bot 安装不要求个人账号验证码;可选监听登录会在自己的私密 Linux 终端要求手机号、验证码及可能的 2FA。 不向维护者、Bot 聊天或公开日志提交这些信息。填写清单、Telegram 应用申请
4. 存储与凭据
准备足够的目标云存储空间,并由本人在自己的 CloudDrive2/OpenList 后台完成登录、扫码、Cookie 或 OAuth 授权。
| 账号 | 用途 |
|---|---|
| 网盘/网关管理账号 | 自己挂载存储和管理后台 |
| Bot 专用 WebDAV 用户 | 读、写与任务受管清理 |
| 个人 Telegram 监听账号 | 可选,仅管理员授权监听来源 |
| 外部 WebDAV 只读用户 | 可选,供手机/家人读取;不能复用 Bot 或管理员 |
这些密码不能互换。当前一键向导的 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 | 任务暂存预算:20GB |
这不是对所有机器的建议。小盘主机应采用自己的推荐值;20GB 不是硬性最低任务预算,也不是磁盘分区或单文件上限。
- 任务预算约束 Bot 暂存与额度预留。
- 保留线保护真实文件系统,首次向导不允许低于 8GB。
- 单文件超过预算可自动走流式;多个普通任务累计占满预算而排队,不代表全部自动切流式。
- 镜像、网关缓存、历史备份和日志不会因调低预算自动清空。
- 暂存、DB、日志等同盘时不重复相加可用容量;容器看不到的独立网关/Docker 盘仍需宿主机检查。
- 更换安装目录、存储方式或磁盘后,重新核对容量;不要通过把保留线设成接近零来绕过保护。
已有实例升级保留原配置,不静默应用新推荐。独立 Compose 的 setup 能填写预算,但不提供与一键向导相同的完整宿主机资源预检。
v1.5.8 的“业务就绪”和诊断会结合标准 cgroup v1/v2 的容器内存余量与宿主机可用内存,按较小值判断下载条件。能看见宿主还有很多内存,不代表受限 Bot 容器仍有足够余量;未知或过期观察不能当通过。资源硬限制与任务暂存预算是两回事,后文单列说明。磁盘保护、Compose 资源说明
五、Linux 公网一键部署流程
这里替代旧版 Windows 部署器教程。先准备完整 SSH 会话、域名和 Telegram 参数;从当前正式入口安装,不使用历史 EXE 去管理新版本。
本文命令固定到 v1.5.8 的入口文件,便于核对行为。固定入口不等于永久锁住业务版本:向导仍核对执行时最新正式稳定 Release,查看实际显示的目标版本与计划,不默认部署移动的 main 或预发布代码。安装指南
第一步:只读预检,明确 Edition
下面两版择一;只读预检不会安装、升级或执行 WebDAV 写入,但需要联网读取正式版本与临时源码。
1 | # CloudDrive2 Edition |
脚本会执行仓库下载的代码,使用前核对来源。若不希望直接运行远程入口,可以先下载到未占用的文件名,审阅后在交互终端运行。不要使用 curl | bash,不把密码、Token 或 API Hash 放入参数。
网络失败、API 限流、版本或指纹不匹配时停止;外层 Bash 没有报错,也不能替代安装器的实际成功结果。
第二步:启动安装或管理向导
1 | bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.8/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 | # 先预检;示例 IP 必须替换 |
支持本机网卡上的 10.x.x.x、172.16.x.x~172.31.x.x、192.168.x.x,不填公网、回环、Docker 桥接地址或 URL。OpenList 的显式参数为 --edition openlist。
| Edition | 管理页示例 | 后端仍保持 | 独立入口容器 |
|---|---|---|---|
| CloudDrive2 | http://192.168.26.5:19798 |
127.0.0.1:19798 |
tg2cloud-lan-cd2 |
| OpenList | http://192.168.26.5:5244 |
127.0.0.1:5244 |
tg2cloud-lan-openlist |
入口不申请证书、不占用 80/443,也不把后端改为 0.0.0.0。HTTP 不加密,禁止公网端口转发、UPnP 暴露或公网反代。需要公网管理时走相应 HTTPS 方案,不能借内网入口绕过保护。
1 | TG2CLOUD_LAN_BASE=OK |
这些只说明本机基础服务与入口检查通过。还要从另一台可信设备打开页面,配置网关和用户,执行 WebDAV 验收,再测试 Telegram 转存。尚未配置好时选择不验收,之后可单独运行:
1 | bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/TG2Cloud/v1.5.8/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 混用。
| Edition | v1.5.8 正式部署包 |
|---|---|
| CloudDrive2 | TG2Cloud-v1.5.8-compose-clouddrive2.tar.gz |
| OpenList | TG2Cloud-v1.5.8-compose-openlist.tar.gz |
两版使用同一个 COMPOSE-SHA256SUMS.txt;源码用的 SHA256SUMS.txt 不适用于 Compose 包。只下载一版也要看到自己这份显示 OK,不是“没有文件被验证”。校验和用于完整性检查,不是数字签名。
以下以 CloudDrive2 为例,在全新的本地真实目录操作。已有目录时停止核对,不删除旧实例来腾位置:
1 | mkdir /opt/tg2cloud-compose-clouddrive2 && |
OpenList 使用其对应包、目录和下列服务名。NAS 可选择自己的全新本地数据目录,不使用云盘挂载或不安全软链接;厂商 Docker 由原套件维护。
format 3:先认识随包管理菜单
v1.5.8 正式包新增 manage.sh,与完整 https-tools/、https.sh、Compose 和元数据一同校验;不是从 main 复制一个脚本到旧包就能使用。
在实际部署目录运行:
1 | bash manage.sh |
随包宿主菜单需要 Linux root、Python 3.10+、Bash 和本机 Docker Compose,无需在宿主安装 Telethon 等 Bot 依赖;状态和管理不反复下载 main。菜单可复用家人、分类通知、监听、HTTPS、验收和外部只读入口,并提供 17. 资源与安全。
它与一键安装的全局 tg2cloud 菜单不是同一实例生命周期,不默认覆盖已有快捷命令。已安装相应宿主 CLI 时才可使用 tg2cloud compose --root /实际部署目录;没有它就使用随包脚本即可。
下方保留有效的手动初始化、配置网关与启动步骤。新菜单首次未初始化时也调用原隔离 setup;旧 .env 不重新生成。选择一套流程操作,不在两个终端同时用菜单和手动命令改同一实例。Compose 新管理指南
初始化与访问方式
1 | docker compose config --quiet |
setup 要有交互终端,不加 -T,不在后台喂答案。按提示输入 Telegram、WebDAV、预算和管理访问方式;不要把 .env.example 改名当正式 .env。初始化会生成私密配置,不会替你挂载云盘或创建网关用户。
可选访问方式为本机/可信内网、自动 HTTPS、已有反向代理。选项只保存访问计划,不表示证书已经签发;本机/内网只绑定本机回环或私有 IPv4,不绑定公网或 0.0.0.0。
先只启动所选网关,后台配置完成后再启动对应 Bot;不要把两版命令都执行一遍:
| Edition | 先启动网关 | 配置完成后启动 Bot |
|---|---|---|
| CloudDrive2 | docker compose up -d clouddrive2 |
docker compose up -d tg2cloud-clouddrive2-bot |
| OpenList | docker compose up -d openlist |
docker compose up -d tg2cloud-openlist-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 | docker compose ps |
状态和配置检查通过后,再测试真实 Telegram 小文件。不要为省步骤一开始就无差别启动所有服务。Compose 完整分步教程
Compose 的可选 HTTPS
v1.5.8 format 3 完整包包含 manage.sh、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
- 打开实际管理地址,登录自己的 CloudDrive2。
- 添加并授权目标云存储,确认能浏览预期目录且剩余空间足够。
- 开启 WebDAV,创建与安装保存值完全一致的专用用户。
- 选择用户根目录,关闭只读,授予列表、读取、写入、改名及任务清理所需删除能力。
- 返回对应安装/管理流程执行真实写入验收。
CloudDrive2 的账号、版本和会员能力以实际环境为准,不把会员密码填成 Bot WebDAV 密码。
方案 B:OpenList Edition
- 新装使用独立的初始化管理员密码;已有实例使用当前后台密码,重新部署不自动重置。
- 添加并授权目标存储,例如 115 Open,确认能浏览目录。
- 创建专用普通用户,用户名/密码与已保存值一致,不让 Bot 使用管理员账号。
- 设置基本路径,允许列表、读取、WebDAV 写入、创建及必要删除能力。
- 执行验收;正常提交直接写入预留最终路径,不要求 MOVE,不能照搬 CloudDrive2 的临时文件改名策略。
根目录与相对子目录只组合一次
| WebDAV 用户根目录 | Bot 保存子目录 | 最终文件位置示例 |
|---|---|---|
/MyCloud/Telegram |
留空 | /MyCloud/Telegram/文件名.mp4 |
/MyCloud |
Telegram |
/MyCloud/Telegram/文件名.mp4 |
/ |
MyCloud/Telegram |
/MyCloud/Telegram/文件名.mp4 |
MyCloud 只是挂载示例,不是固定名称。子目录不填 VPS 的 /opt/...、手机的 /dav/、完整 URL、.. 或反斜杠,也不在两处重复填写同一层。
同机受管 Bot 继续使用 Docker 内部 WebDAV,不改成管理域名或浏览器内网地址。安装后修改账号/目录,先处理旧任务再通过完整配置更新;已有任务保留接收时的目录,不自动搬家。
Bot 写入用户不能只读;给手机用的外部用户则必须原生只读。两类权限相反,不能为省建号共用一个账号。网关配置与权限对照
七、管理入口、WebDAV 和真实文件分别证明什么?
| 检查层次 | 能证明什么 | 不能替代什么 |
|---|---|---|
| 容器 healthy/本地配置检查 | 服务、配置和基础心跳等检查通过 | Telegram、网关写权限、实际文件 |
| HTTPS/LAN 本机入口 | 本机访问管理页及相应安全检查通过 | 外部电脑、手机或公网可达 |
| WebDAV 写入验收 | 当前 Bot 配置到目的端的写入、大小复验和清理通过 | 云盘官方最终入库、内容哈希 |
| 真实 Telegram 文件 | 当前文件在实际链路中的处理结果 | 所有大小、长期运行、灾难恢复 |
公网 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 私聊发送。
| 命令 | 用途与边界 |
|---|---|
/start、/status、/performance |
查看状态首页 |
/help |
简短帮助 |
/queue、/queue 2 |
每页 5 项最近任务 |
/task 123、/watch 123 |
详情与约每 5 秒的进度订阅;重启后需重新订阅 |
/search 关键词 |
查本人任务,最多显示 5 项,过多时缩小范围 |
/tasks failed、/tasks cancelled |
按状态分页,按回复的下一页命令继续 |
/pause、/resume |
管理员暂停/恢复新任务调度,活动任务继续,暂停跨重启保留 |
/retry 123、/retry all |
适用失败的重排;批量最多检查 100 项,不绕过待核对保护 |
/restart 123 |
对已取消任务请求确认后重新转存 |
/recover 123 |
远端不确定/冲突时请求确认换名重传,保留原远端对象 |
/stream 123 |
将符合条件、尚无完整本地副本的排队/下载失败任务切流式 |
/cancel 123 |
请求取消,可能清理本任务已写入远端对象,不是隐藏记录或暂停 |
/doctor |
管理员只读运行诊断,不创建远端测试文件 |
/orphans、/orphans clean |
管理员遗留临时对象巡检;清理须有效的一次性确认 |
/quota |
已授权成员查看本人配额 |
/transfer、/pending、/cancelinput |
转存设置、待确认计划及取消当前设置输入 |
/listen |
管理员监听管理;普通成员无此权限 |
原生命令菜单仍只注册 /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 | tg2cloud listen login --edition clouddrive2 |
OpenList 将参数换为 openlist。也可从 tg2cloud → 当前 Edition → 16. 监听管理进入;Compose format 3 则使用自己部署目录的 bash manage.sh → 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 或另一个身份绕过。
监听不自动加入来源、不读评论,不解除服务端实际读取限制。历史缺口、暂停与限流都需管理员核对,不用关闭限流或反复重登作为通用修复。监听与恢复完整边界
v1.5.7 起:监听短限流与有限自动恢复
短时间的普通 FloodWait 和 PremiumWait 都可在同一文件分片按 Telegram 要求等待,保留原等待次数/时间上限,不缩短服务端冷却。
短等待耗尽后,尚无远端对象记录的普通监听下载可持久登记冷却并释放活动名额;最多两次自动恢复,同时受已有 MAX_RETRIES 限制,重启不重置次数。冷却结束后仍核验账号、来源、取消状态、配额、磁盘与并发条件。
同一分片等待不会重下已写入内容,但重新排队是从头下载,不是跨重启字节级断点续传。超过 60 秒的等待、授权/权限失效或远端不确定仍保守停止;已有远端现场的流式任务不自动重新排队。
首次元数据响应为空时延迟 1 秒、最多复核一次;仍无附件、附件变化或权限失效则停止。诊断中的 source_access 单列为“监听来源或附件不可读”,不把所有问题都说成需要重新登录;历史失败不会批量自动重试。监听恢复说明
家庭共享与可选分类
安装仍只有一个固定管理员。安装后通过 tg2cloud → 5. Bot 用户管理授权最多 32 位家人;各自私聊同一个 Bot,只管理自己的任务,共用保存目录,不是个人云盘隔离。
停用家人不自动取消已接收任务、删除文件或撤销其外部 WebDAV 读取权限。两版授权互不共享;全局暂停、诊断、资源及遗留清理仍是管理员能力。
分类默认关闭,可从 8. 文件分类设置选择类型、年份、年月或组合,只影响新任务,不搬历史文件。9. 异常通知设置默认不主动发送;可按需启用,不能当离线主机监控。成员配额按日完成量与未完成预留计算,不是网卡重传计费。家庭授权、分类通知与配额
九、转存速度怎么样?2GB 文件要多久?
至少区分三个阶段:
1 | Telegram → VPS |
VPS 标称“千兆带宽”不能保证每个阶段都达到相同速度。WebDAV 接收很快,也不代表上游网盘已经完成写入。
单阶段估算
假设文件为 2GB,按十进制约 2000MB 计算,持续有效速率固定,不考虑排队、检查和重试:
1 | 单阶段耗时 ≈ 文件大小 ÷ 有效速度 |
| 持续有效速度 | 2000MB 的单阶段估算耗时 |
|---|---|
| 1MB/s | 约 33 分 20 秒 |
| 2MB/s | 约 16 分 40 秒 |
| 5MB/s | 约 6 分 40 秒 |
| 10MB/s | 约 3 分 20 秒 |
这不是 TG2Cloud 的实测速度,也不是端到端承诺。MB/s 是每秒兆字节,不要与服务商标注的 Mbps 混淆;2GiB 也不等于这里按十进制计算的 2GB。
普通模式下,若 Telegram 下载为 5MB/s、随后写入 WebDAV 为 2MB/s,两个串行阶段约需:
1 | 2000 ÷ 5 + 2000 ÷ 2 = 1400 秒 |
实际还可能有排队、复验、重试和网关向上游云存储同步的时间。流式模式可以让部分阶段重叠,理想流水线仍受最慢环节约束,不能消除线路与网盘限速。
更有价值的记录方法
使用同一个测试文件,记录提交、开始下载、Bot 完成,以及网盘官方客户端可以打开的时间,结合 /status 的下载、上传与 Bot 运行环境网络采样观察瓶颈。
同时查看 VPS 套餐流量规则:服务商可能只计出站,也可能计算双向流量。上传文件经过服务器,不能因为没有下载到本地电脑就认为 VPS 不消耗流量。状态与测速边界、部署准备
十、Linux 日常维护与程序升级
Bot、离线管理工具和附加功能分别核对
常用入口是 tg2cloud,不是旧 Windows EXE。主机没有命令或仍是旧版时,从当前公网/内网入口确认更新;--check 不更新任何运行组件。
1 | tg2cloud --version |
查看 2. 运行状态核对真实 Bot 版本、容器和入口;tg2cloud --version 核对 CLI,不用本机工具版本替代容器版本。工具更新后应退出旧菜单进程,再重新打开。
外部 WebDAV 的维护代码独立更新:主菜单 15 → 子菜单 8. 升级附加功能。只升级 Bot 不会自动替换旧附加工具,也不能据新文档认定旧机器已具备新菜单。运行维护
当前管理菜单按对象操作
下表为一键实例的统一菜单;Compose format 3 的同名菜单另含 17. 资源与安全,升级、备份和卸载按后文的 Compose 专用说明处理,不能照搬一键实例的删除默认值。
| 序号 | 当前用途 | 重要边界 |
|---|---|---|
| 1 | 安装与升级 | 正式 Release,已有实例保留配置与入口模式 |
| 2、3 | 运行状态、运行日志 | 可重新检查/读取;日志是脱敏快照,不持续跟随 |
| 4 | 服务启停 | 明确选择一个 Bot 或网关,再确认;不无差别重启两者 |
| 5 | Bot 用户与成员配额 | 只管理已授权家人,不更换固定管理员 |
| 6、7 | 凭据、HTTPS/管理入口 | 凭据只在私有终端显示;入口修复另行确认 |
| 8、9 | 分类、异常通知 | 默认可选关闭,只影响对应范围 |
| 10 | 业务就绪 | 最近只读观察,不追加写入或额外登录;过期即未核实 |
| 11 | WebDAV 验收 | 创建、检查并清理随机测试文件,不是只读 |
| 12 | 故障诊断报告 | 白名单摘要,经确认私密导出,不自动上传 |
| 13 | 数据备份管理 | 实例与代理分组,预检不是生产恢复 |
| 14 | 卸载当前实例 | 默认完整清理,先读第十五节 |
| 15、16 | 外部 WebDAV、监听管理 | 两个不同功能,不默认启用 |
以实际版本和菜单文字为准,旧文档编号不同。下文家人授权、分类、通知等公共功能也可从 Compose 自己的同名菜单进入;涉及实例生命周期时仍按部署方式区分。查看日志、退出订阅或关闭 SSH 窗口不等于停止 Bot;暂停、停止和卸载也不是一回事。
每实例旧管理脚本仍保留
以下示例用于一键部署的已安装实例,不在独立 Compose 目录或源码 checkout 中执行。这里的实例内旧 manage.sh 与 format 3 包里的 manage.sh 不是同一个入口,按绝对路径和部署类型区分:
1 | /opt/tg2cloud-clouddrive2/manage.sh status |
OpenList 换成 /opt/tg2cloud-openlist/manage.sh;它另有不持续跟随的 recent-logs。日志可能含文件名,分享前仍要人工脱敏。
| 操作 | CloudDrive2 | OpenList |
|---|---|---|
restart |
重启 Bot | 同时重启网关与 Bot |
restart-bot/restart-openlist |
不提供同名独立入口 | 分别重启所选服务 |
update |
用已安装 payload 重建 Bot | 拉取当前 Compose 固定网关并重建 Bot |
| 通过对应安装入口升级 | 核对正式版本并保留配置升级 | 同左,按自己的 Edition 操作 |
manage.sh update 不下载最新版 TG2Cloud 代码;普通 restart 不重新加载新环境配置。 不要把它们当作完整 Release 升级。命令影响对照
一键部署的推荐升级顺序
- 阅读目标正式版,暂停新调度、等待活动任务,并处理失败保留文件。
- 保存独立私密备份,确认 Edition、实例目录及访问模式。
- 从对应公网/内网入口执行只读预检,核对可信旧版基线与目标版本。
- 确认保留配置升级,不手改版本标记、指纹或网关镜像来绕过检查。
- 核对 Bot 与 CLI 两个实际版本、原配置和任务;退出重开管理菜单。
- 显式 WebDAV 验收,再做真实小文件与外部入口检查。
- 确认稳定后恢复调度,再评估旧备份清理。
旧版本 Release/Tag 被删除时,受支持的历史版本可使用项目已审阅的原提交基线;未知版本仍停止。不要自行下载任意 SHA 冒充旧正式源码,也不以卸载重装解决校验失败。
独立 Compose 的更新不是这套菜单
一键实例使用 tg2cloud 的安装/升级;独立 Compose 使用自己完整包的 bash manage.sh。 两者都能提供菜单,不等于可以互相接管实例或混合容器、网络、Token 与数据目录。
新版 format 3 在随包菜单选择“安装与升级”,核对目标正式版与计划。工具校验 Release、同版包/清单、镜像 digest、Edition 与不可变提交,确认后停止旧 Bot 并做一致性快照,再拉取候选、复核身份和切换。
format 2 升到 format 3
旧 v1.5.7 等完整 format 2 包没有 manage.sh,旧 Bot 也没有新宿主暂停接口。先在 Bot 发送 /pause,等待活动下载、流式、上传及清理结束,保留旧包、镜像身份和私密备份;再在新下载目录校验并解压完整 v1.5.8 包。
用新包工具明确指向原 Compose 实例,例如以下占位路径都要替换:
1 | bash /已核验的新包/manage.sh --root /原Compose目录 |
选择升级并核对目标 v1.5.8,保留 .env、tg2cloud-compose.json、存在的 compose-access.json、data/、config/、downloads/、日志及网关状态,包括数据库和两个 Session。升级后仍保留暂停状态,完成业务验收后才 /resume。不要把新包单个脚本塞入旧 helper。
早期 format 1 没有完整离线工具,不走上述菜单自动升级;仍按原教程先完整备份,再人工核对并替换同版公开文件,保留所有私有数据。format 2/3 的公开脚本与**完整 https-tools/**须成套,不合并不同版本;不伪造包标记求通过。旧包与升级兼容、人工维护步骤
新 Bot 可能写库后,不自动覆盖回退
新 Bot 启动前失败,工具只尝试恢复旧部署文件与原运行状态并核对。新 Bot 已可能启动写库后失败,会停止并保留现场,不自动用旧库覆盖新库,也不自动启动旧代码。
.compose-upgrade.json 保存事务阶段和快照位置;出现 needs-review 或未完成事务时,先保护全部数据、核对匹配版本与一致性快照,不删标记后反复重跑。不把镜像换回旧版当作数据库恢复。Compose 升级与失败处理
修改完整配置与 v1.5.6 加固
一键实例修改 WebDAV 账号/目录之前先处理旧队列;在实例外的私密绝对路径准备匹配版本的完整候选配置,再使用该实例的 apply-config。它会备份、预检并重建 Bot,失败只尝试有限回退;不是只应用一个字段,也不能通过 source .env 执行配置。独立 Compose 按随包管理与配置流程处理,不调用一键实例脚本。
v1.5.6 的重要变化:
- rclone 密码通过标准输入处理,私有候选配置成功后才替换;混淆不是加密。
- 本项目容器配置
json-file日志轮转10m、最多 3 份,Bot 文件日志另行轮转;不是整个主机的总占用上限。 - 当前运行用户拥有的 Session、业务库及已有 SQLite 旁文件收紧为 600;链接、硬链接或归属异常会拒绝,不自动 chown、删库或重新授权。
- 业务就绪/诊断单列个人监听连接、冷却、轮询新鲜度和缺口;Bot 基础健康不能替代监听健康。
新日志配置需在明确更新并创建相应容器后才生效,单纯重启旧容器不应用;共享代理沿原维护流程更新,外部复用代理由其所有者管理。近期异常是本进程有界观察,不是所有历史错误的完整审计。v1.5.6 历史发布说明
v1.5.7 起,升级摘要与故障报告会分别核对 Bot、网关、受管 Nginx 和 Certbot 的实际日志限额与归属,区分已采用、未采用、自定义限额、其他驱动及未核实状态;不拿模板当生效证据,也不自动重建或清理容器。当前运维说明
Compose format 3:资源与凭据隔离
独立 Compose 的 17. 资源与安全可查看并设置 Bot 限额;这三个可选变量只作用于 Compose,不是新增的一键脚本必填参数。
| 项目 | Compose 配置键 | 当前含义 |
|---|---|---|
| 内存硬限制 | TG2CLOUD_BOT_MEMORY_LIMIT |
默认 0 不设;可如 1024M/2G,需高于下载硬门槛 256 MiB,并留缓冲余量 |
| 进程/线程上限 | TG2CLOUD_BOT_PIDS_LIMIT |
默认 256,可设 32~65536 |
| CPU 硬限制 | TG2CLOUD_BOT_CPUS |
默认 0 不设;可如 1、0.5 |
应用前暂停调度、等活动传输结束,再确认仅重建当前 Bot;工具保存私有旧配置并读取 Docker 实际限额核对。核对失败不冒充生效或自动回退。过小内存可能 OOM,这不是网关缓存总额度,也不通过降低磁盘/内存保护来强行下载。
新 Compose 用白名单向 Bot 传配置,OpenList 初始化管理员密码只给网关,不再把整份 .env 交给 Bot。主机配置仍含明文或 Base64,保持受限权限;已有旧容器需通过完整新版部署包重建后才应用隔离,重启不等于生效。
CloudDrive2 的必要 FUSE/特权仍保留,不能把进程限额理解为整个网关已低权限化。资源与凭据保护
十一、备份包含哪些内容?
新旧数据库与两份 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 包含监听与计划等状态,回退须匹配代码和一致性快照。配置与数据库选择
几类备份不能互相代替
| 类型 | 主要覆盖 | 不要假定包含 |
|---|---|---|
| CloudDrive2 升级回退点 | 程序/配置、可用时的业务库快照 | 完整 Session、网关授权、下载、HTTPS |
| OpenList 业务备份 | 程序配置、业务库快照、OpenList 状态 | Telegram Session、下载、共享 HTTPS |
| 一键实例离线快照 | 限定配置、DB、Session、rclone 与所选网关配置;存在且合法的监听 Session | 程序代码、downloads、日志、HTTPS/LAN/附加元数据、云端文件 |
| 共享代理备份 | 两版管理/附加路由、Nginx 配置、认证哈希、证书/ACME、续期记录 | Bot DB、网关授权、全部外部 WebDAV 私密元数据 |
不要递归打包 clouddrive/mounts,那里可能是真实 FUSE 云盘挂载。备份网关状态不等于备份云端文件。完整备份范围
一键部署:主菜单 13
从“数据备份管理”按对象选择实例快照、隔离校验、共享代理备份或清理。实例快照需要确认维护窗口;仅 Bot /pause 不会停止当前传输,更不冻结 SQLite 或 Session。
OpenList 的旧 manage.sh backup 会短暂停止网关和 Bot;CloudDrive2 没有同名业务备份命令,不能照搬。两版都可做共享代理备份,不表示业务回退点包含代理。
标准业务回退点目录:
1 | /opt/tg2cloud-clouddrive2-backups |
只读盘点可用 manage.sh backups。旧 prune-backups N 是直接删除命令,按类型各保留 N 份(1~50、默认 5),不额外交互确认;优先使用有预览和确认的管理流程,不把清理当查询。
独立 Compose:先停机,再做离线备份
format 3 的 bash manage.sh → 13. 数据备份管理可创建实例快照、做隔离恢复预检及单独备份共享代理;按菜单核对维护窗口和实际清单。下列有效的手动离线流程继续保留,不能边运行边宣称已备份静止数据。
在 Bot /pause,等待活动任务结束;进入自己的 Compose 部署目录:
1 | docker compose stop |
确认该项目 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 离线备份
可选加密副本:验证后保留原件
v1.5.8 的 Compose 备份菜单可加密已有备份;宿主需已安装 GnuPG 和 gpgconf,工具不自动安装,也不向 Bot 加依赖。
口令在私密终端隐藏输入两次,仅经 stdin 交给 GnuPG。工具使用 AES256,成功后先解密回读验证,再发布 .gpg 副本;原明文归档仍保留,不会自动删除,应继续限制权限,另存口令并安排加密副本离机保存。
恢复前在私密目录解密,再进行隔离恢复预检。加密回读、结构检查和实际服务恢复是三个不同结论;本轮项目记录仍将真实 Linux 加密回读与用户环境恢复列为待验收。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。
一键实例默认完整卸载可能删除其可识别备份;Compose 新卸载保留独立导出备份,但仍须按实际计划核对范围。重要副本统一另存到将删目录之外,并私密离机保存。恢复前检查、Compose 清理范围
十二、常见问题与排错顺序
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 表示允许放行的额度,不等于已有一个活动任务;实际数量看首页。
核对任务/成员额度、磁盘保留线、挂载与目的端可用性。v1.5.8 的就绪/诊断会另列有效可用内存、容器上限、下载门槛及下载/上传窗口,并按固定类别汇总重试等待、个人额度、暂存额度与真实磁盘等待。
标准 cgroup v1/v2 下取宿主可用与容器有效余量较小值;不能安全读取受支持控制器时退回宿主采样,复杂 NAS/嵌套 cgroup 仍需结合实际限制核对。旧 Bot 缺少新字段显示未核实,不冒充已通过。
监听还需检查个人账号、来源启用、权限、冷却和待确认计划,不把所有排队都归咎于网关,也不靠降低保护门槛或无限增并发消除等待。排队与资源诊断
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;新布局、兼容字段或可识别旧库名称,不代表旧任务已迁移。标准目录区别仍是:
| Edition | 旧默认目录 | 当前一键标准目录 |
|---|---|---|
| CloudDrive2 | /opt/tg115 |
/opt/tg2cloud-clouddrive2 |
| OpenList | /opt/tg115-openlist |
/opt/tg2cloud-openlist |
先处理旧队列,私密保存配置、SQLite 一致性快照、Session、网关授权及必要下载;记录实际 WebDAV 根目录和子目录。新环境通过真实验收前,保留旧环境和独立备份。
优先隔离部署。复用同机时,在维护窗口明确处理旧固定端口与容器归属;不靠改目录名、混用 .env、直接复制运行数据库或改版本文本绕过检查,也不让新旧实例长期共用同一个 Bot Token。
较新 TG2Cloud 的已审阅历史基线升级,不等于任意 TG115 自动迁移;独立 Compose 与一键实例也不是互相导入工具。涉及任务延续时制定专门迁移和回退方案。旧实例与可信升级边界、配置兼容
补充:手机读取与家庭只读账号
可选外部 WebDAV 让手机播放器/文件管理器通过独立 HTTPS 域名读取 Bot 已有目录,不重复挂载网盘、不复制数据,不默认安装或启用。
一键实例运行 tg2cloud → 选择 Edition → 15. 外部 WebDAV,在子菜单完成安装、状态、检查、启停、升级和用户管理。不再下载已退役的 install-webdav.sh;已有 tg2cloud-webdav 命令保留兼容,日常可从统一菜单进入。
Compose format 3 可从自己的 bash manage.sh → 15. 外部 WebDAV管理,共用原只读权限核心,但只接入受管共享代理;第三方代理/schema 3 外部代理仍走候选导出,不自动接管,也不在该模式自动发布 Compose 外部 WebDAV。Compose 能力边界
向导确认实际 Bot 保存目录,再由本人在网关后台创建独立原生只读账号。根目录直接限定到最终共同目录,禁上传、删除、改名和管理;不复用 Bot、管理员或会员凭据,也不把 Nginx 方法限制当成原生权限审计。
| 手机参数 | 填写内容 |
|---|---|
| 协议与端口 | HTTPS、443 |
| 服务器 | 本人配置的外部读取域名,不是管理域名 |
| 根路径 | /dav/ |
| 用户名/密码 | 已启用的独立只读账号 |
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、下载、网关授权与可识别历史备份。 Compose format 3 使用自己的管理菜单和数据去留确认,不套用一键清理模式。两种方式都先停止新接收、等待活动任务,并将必要备份转移到清理范围之外。
v1.4.7 起已退役根目录独立 uninstall.sh;不再使用旧 main 下载地址,也不把 v1.2.0 默认保留数据的旧命令套到当前版本。
一键实例:先只读查看范围
1 | tg2cloud uninstall --edition clouddrive2 --check |
OpenList 换成 openlist;只有确实要核对两套才使用 --edition all --check。也可运行 tg2cloud,选择 Edition → 14. 卸载当前实例。若命令缺失,重新运行原安装入口进入已有实例菜单,不选重新安装。
下面的模式表专指一键实例卸载,不是独立 Compose 的默认数据选择。
| 模式 | 本地实例数据 | 可识别历史备份 |
|---|---|---|
默认/--purge-all |
删除 | 在核验范围内删除 |
--purge-data |
删除 | 保留 |
--keep-data |
保留 | 保留 |
实际卸载会移除所选受管 Bot、网关、项目网络和相应入口;保留数据模式也不是只暂停服务。以下示例明确选择保留数据,仍需核对并确认真实范围:
1 | tg2cloud uninstall --edition clouddrive2 --keep-data --check |
完整清理除默认取消的确认外,另要求 DELETE ALL clouddrive2(或相应 Edition/all);仅删数据模式使用 DELETE …。没有通用 --yes 强删捷径,不混淆三种模式或确认口令。
另一 Edition、外部 WebDAV、共享 HTTPS/复用 Nginx、FUSE 挂载、未知引用或文件归属都会影响计划。发现异常先停止,不强制卸载 FUSE、不递归删 /opt、不全局 Docker prune。系统 Docker/Nginx、其他项目、云端文件、镜像缓存和必要锁元数据不按此清理。
独立 Compose 不用这个卸载器
独立 Compose 不用上方的一键卸载器,但 format 3 已有自己的 bash manage.sh → 14. 卸载当前实例。先处理依赖网关的外部 WebDAV、暂停调度并等活动传输结束,再明确选择保留全部数据,或再次确认删除当前实例数据。
新菜单按当前 Edition 身份、所有将清理目录及共享依赖预检;链接、跨文件系统、嵌套挂载、特殊对象或 CloudDrive2 非空挂载点会停止。它只移除核验属于当前实例的资源,不使用全项目 compose down 去顺带移除其他服务;保留另一 Edition、云端文件、系统软件和独立导出备份。
原有手动停止方式仍有效:确认部署目录和范围后,docker compose stop 暂停服务;docker compose down 移除该项目容器/网络并保留绑定数据。使用包内 HTTPS 时,按自己的入口流程先明确移除对应路由,例如 bash https.sh remove;它不是菜单卸载完成后必须重复执行的一步。
不要交叉用两种生命周期工具、不通过 down -v、系统 prune 或删数据库处理升级问题。公开部署包、操作记录、锁及独立导出备份保留,不等于整台主机恢复出厂状态。Compose 卸载与保护、手动停止使用
完成标记与部分失败
下列为一键卸载器的结果标记;独立 Compose 以自己菜单的计划、事务记录和实际结果为准。
TG2CLOUD_UNINSTALL_CHECK=OK 只表示预检;TG2CLOUD_UNINSTALL_RESULT=OK 表示所选卸载后检查通过,数据去留以计划为准。
PARTIAL、FAILED、INTERRUPTED 可能已部分执行,不能假定自动回滚已删对象。重新预检当前 Edition,核对剩余范围后再决定;完整卸载也不等于把 Linux 软件包、缓存、系统日志或 DNS 逐字节还原。卸载与保护条件
附:从源码查看 Linux 命令
普通使用优先采用正式入口或完整 Compose 包。需要审阅源码时,可以获取固定标签,在符合条件的 Linux 环境查看帮助:
1 | git clone --branch v1.5.8 --depth 1 https://github.com/LuoPoJunZi/TG2Cloud.git |
源码现位于 src/tg2cloud/。帮助与纯标准库 CLI 不等于部署已完成;实际 Bot、网关与可选功能仍按对应依赖和实例条件运行。不要在新 checkout 继续使用旧 Windows build.ps1 或根目录旧 app.* 调用,也不要将下载源码当成已升级服务器。
写在最后
TG2Cloud 的重点是让转存、命名、排队、恢复和维护可观察、可核对,而不是承诺无限速、零成本、全网采集或所有网盘秒传。
先走通自己的管理入口、WebDAV 与真实小文件,再逐步启用监听、家人和外部读取。区分任务完成、网关接收、云盘最终状态,以及备份校验和实际恢复;重要数据始终保留独立副本。
项目与下载:LuoPoJunZi/TG2Cloud。再次感谢 whyhhh20/TG115 原作者及相关组件贡献者。
参考资料
正文以 v1.5.8 正式标签的安装、Compose 及其新版管理、网关、Bot、监听、命名、家庭共享、运维、备份和卸载指南为操作依据;是否正式发布及实际资产,另对照 GitHub Release 与发布后记录。旧手动流程与历史加固说明在仍有效处保留。
资料核对日期:2026 年 11 月 10 日。v1.5.8 标签内有些段落保留发布前的 v1.5.7/“待发布”措辞;当前 v1.5.8 已正式发布,不通过修改历史 Tag 补录结果。功能与实机验收仍分开,文中速度计算继续保留为算术估算,不是本次实测。




