外部 WebDAV（独立附加功能）

v1.4.10 升级与中断恢复#

v1.4.10 将维护代码升级与账号认证分开；旧 v1.4.9 尚不包含此流程。升级只核验候选源码、实例身份和配置兼容，不询问外部密码、不启用路由、不更改后台账号；原访问状态保留，账号认证和公网播放需单独检查。失败或确认期间配置变化时保留原维护工具，旧代码目录仍可人工回退，不自动降级。

从主菜单 15 打开较旧的附加工具时，先提示可下载正式稳定版并更新维护代码；拒绝可继续旧版离线菜单，不会每次状态查询都下载。这个入口也用于解决旧工具因账号未完成、401 而无法升级的问题，必须先发布包含本改进的主工具才可使用。

安装中断或未完成时，外部访问保持关闭，菜单 6 显示“继续完成配置”并成为默认选项。再次选择安装不覆盖现有记录。后端 401 会提示核对后台是否创建并启用独立只读账号、用户名和密码是否一致；不使用 Bot 或管理员凭据替代。

v1.4.7 已正式发布统一管理与 API 2。历史正式 v1.4.6 尚无主菜单 15；以下使用边界和独立只读权限继续适用。

通过单独 HTTPS 域名，在手机文件管理器或播放器中只读访问 Bot 已有上传目录。共享原网关数据，不复制文件、不重新安装或挂载云盘；仍依赖 CloudDrive2/OpenList 和共享 Nginx/Certbot，不是完全独立的文件系统。

::: warning 验证范围 本功能自 v1.3.1 提供，要求对应正式稳定源码资产。隔离 Nginx 认证、只读、编码、密码轮换和 Range 已通过；原生两版账号/目录、手机、ARM64 与公网 ACME 尚未端到端实机验收。发布与资产状态以 GitHub Release 为准。

:::

v1.4.8 安装交互#

以下交互已随 v1.4.8 正式发布。主管理工具与附加工具须分别更新；已有外部 WebDAV 从主菜单 15 进入后选择 8 升级，重新打开才会加载新向导：

• 去掉重复环境检测展示，保留实际检查及失败原因；从主菜单进入时不重复显示启动横幅和网关标题。
• 域名、邮箱和目录正常回显，邮箱回车可跳过。普通字段说明具体错误；密码继续隐藏输入。终端不预读子菜单的答案，恢复回显并处理完整粘贴封装。
• 优先读取已核验实例的 Bot 账号目录：CloudDrive2 尝试识别本机受管 WebDAV 配置中精确匹配的用户记录；加密用户名或未知格式不猜测。OpenList 仅用已有 Bot 凭据向本机认证并读取 /api/me 的 base_path，不询问管理员凭据、不保存令牌、不跟随重定向。
• 无法读取时自动复用与当前实例、配置绑定及镜像一致的历史确认值；仍无法确认才首次补充一次。共享目录按真实根目录与 Bot 相对子目录计算，所有页面显示同一个实际值。
• 后台建号提示显示当前网关管理地址，不再让用户第二次手打路径；安装计划确认、独立账号和原生只读权限确认仍保留。自动读目录不等于自动审核权限，不改 Bot、rclone 或网关配置，不重启服务。

详细读取边界与未执行的实机范围见仓库指南↗。

家庭只读账号（v1.3.3）#

下述多账号菜单由 v1.3.3 提供，v1.3.2 及更旧版本尚不包含。单独升级离线附加工具后，可在外部 WebDAV 的“10. 用户管理”添加、检查、启停、更改密码或移除新增家庭账号；历史 tg2cloud-webdav users --edition clouddrive2 仍兼容，OpenList 使用 --edition openlist。不增加 Bot 命令、不进入主安装、不创建第二个域名或个人目录。

每个账号都需在网关后台人工创建，根目录／base path 必须直接指向向导显示的实际共同目录，只授予读取／列表。CloudDrive2 版本或会员能力不支持独立只读用户时停止，不用 Bot 或管理员凭据替代。外部授权与 Bot 家人名单互不绑定、分别撤销；不因停用 Bot 用户自动关闭手机访问。

新增账号使用相同域名、443、HTTPS 和 /dav/，但用户名与密码各自独立；Nginx 仅保存强哈希，并把客户端同一凭据交给后端验证。主账号在原入口配置中管理。单个成员操作保留其他账号哈希；失败或普通中断时关闭所选账号，后台密码人工修改不能自动回滚。重载可能短暂影响现有读取连接，不重启 Bot／网关。

停用整个入口关闭所有账号，再启用只恢复经过检查的主账号；家人需逐个输入密码、确认共同目录与原生只读后启用。移除不删除后台人工账号、共同目录或云端文件。存在新增账号时，改变共享域名／目录／主账号前先移除其入口授权，防止静默丢失。

首次管理新账号后，附加功能私密记录升为 schema 2，旧工具会拒绝操作；共享代理与附加私密状态分别管理版本，代理模式和兼容边界见HTTPS 指南。单纯代理备份不含整个附加功能私密目录，灾备需同时保护两者；不得公开元数据与哈希。pending／需修复不等于已验收；断电或强制杀进程不保证回滚，先撤销所选入口，再逐个检查恢复，不能直接恢复旧哈希使入口开放。

仍需两个真实 Telegram 用户、两版原生只读账号、手机播放／Range、单账号换密停用及备份恢复实机验收；本地模拟或发布检查不能代替这些检查。正式在线入口只安装经校验的稳定源码，不会下载尚未发布的 main 业务代码。

与主安装的关系#

不加入主安装向导，不默认询问或启用，不增加 Bot 命令和依赖，不改 Bot 账号、rclone、数据库、上传目录或网关监听。管理域名继续禁止 /dav；外部域名只服务 /dav/，不展示后台。不重启 Bot、网关或 Docker。

已有完整受管实例须通过 Compose 标签、目录、挂载、运行指纹核验；未知/部分实例、符号链接、未知共享状态、其他代理占 80/443 时停止，不自动接管。附加宿主代码接受 Debian/Ubuntu、root、Python 3.10+、原生 64 位 AMD64/ARM64、本机 rootful Docker。正式 v1.4.1 与主安装共用平台及公网 NAT 人工确认检查，已有离线工具需显式 upgrade；两个原生 runner 的隔离测试已通过，真实网关账号、目录、Oracle 与手机仍待实机验证，版本边界见部署前准备。

统一管理#

v1.4.7 已将本功能统一放入 tg2cloud；旧版主机须显式更新本地管理工具。无需另跑安装命令，主安装向导仍不默认安装、询问或启用此功能。

tg2cloud

选择当前 Edition → 15. 外部 WebDAV；直接传入该 Edition 与已核验的实际安装目录，不再重复选择网关。子菜单包含安装、状态、连接检查、启停、域名／账号配置、卸载、升级、手机配置和用户管理，退出后返回主管理。

1.  安装外部 WebDAV
2.  查看运行状态
3.  检查连接与配置
4.  启用访问
5.  停用访问
6.  修改域名或账号配置
7.  卸载外部 WebDAV
8.  升级附加功能
9.  查看手机连接配置
10. 用户管理
0.  返回主菜单

尚未安装附加工具时，确认后下载并校验正式稳定源码资产，再进入其独立向导；下载管理组件不等于开放入口，安装另需确认计划。已有工具核验归属和源码完整性后离线启动，日常状态不联网下载。不会从主 helper 的不完整资源包安装，也不会回退 main/RC。校验和不是数字签名。

独立安装#

保留本节标题以兼容旧链接。v1.4.7 移除主分支 install-webdav.sh，历史脚本保留在原版本 Tag；已安装 tg2cloud-webdav 仍兼容。新版统一入口会在确认后从正式稳定源码迁移 API 1 管理代码到 API 2，失败保留旧代码与账号／路由；拒绝可继续旧版离线管理。从 v1.4.7 起，日常安装与维护使用上述 tg2cloud 即可。账号、数据、独立生命周期及 HTTPS 要求不变，不接管未知或部分安装的实例。

::: info v1.3.2 向导优化 新版采用中文编号菜单，保留原英文子命令，0 退出；已安装的离线代码需显式执行附加功能升级，不会自动变成新界面。从 v1.4.7 起可由 tg2cloud → 15. 外部 WebDAV 打开；主实例升级不自动更新附加工具。

:::

::: info 界面微调（v1.4.3） v1.4.3 已提供，独立附加工具需显式升级：编号菜单的数字列与文字列分别左对齐，不在数字前补空格；网关选择回车默认 1（CloudDrive2），输入 2 选择 OpenList、0 退出，仍需独立确认安装计划。操作菜单维持未安装默认 1、已登记默认 2。首次主账号默认 tg2-webdav，可输入其他名称；修改已有配置仍优先保留原账号，不自动改密或扩大目录。家人新增账号不复用主账号默认名；原 Bot／管理员账号冲突检查保持不变。

:::

新向导读取实际 Bot 保存子目录，未设置时显示“使用账号根目录”；账号根目录仍须后台核对。只有实例、目录绑定和网关镜像未变时，才建议复用此前确认值。计划、后台建号与完成页均使用本次实际目录，不固定任何网盘路径。

原生只读账号与目录#

向导要求在后台核实 Bot 用户根目录，再与 Bot 相对子目录计算最终网关逻辑目录。例如 /媒体 加 Telegram 才是 /媒体/Telegram，不是 VPS 暂存目录；不能仅从 Base64 相对子目录推测完整根。Base64 不是加密。拒绝暴露网关 /。

外部账号原生根目录直接等于最终目标，手机 /dav/ 即此目录，不能用管理员加路径改写冒充隔离。

• CloudDrive2：先核实当前版本/会员支持独立 WebDAV 用户，新建专用只读用户并限制根目录；能力不够就取消，不借主账号邮箱密码、匿名或 Bot 用户。
• OpenList：新建普通用户，base path 限定最终目录，只授予 WebDAV 读取/列表，不授予 WebDAV 管理、上传、删除、改名或移动。

第一版采用人工后台建号、输入完整目录并确认原生只读的受支持流程，不猜 API/权限位、不修改后端数据库、不重置管理员、不保留管理令牌。程序随后验证新凭据、匿名拒绝、目录 XML/href 和 HTTPS，但不能声称自动审计了原生权限。后台改名的管理员也需人工排除。

新密码安全生成或隐藏输入，不在参数、日志或 URL 中传递；历史 v1.3.1 经单独确认可只在终端显示。v1.3.2 向导在确认计划后，直接于后台建号说明和最后手机配置中向当前私有终端显示本次密码，不再重复询问；请避免旁观、录屏或分享终端历史。后续查看配置不会显示密码，也不会为回显保存明文。

v1.3.2 向导回车生成 9 位大小写字母及数字随机密码；手动密码不设最低长度或字符种类要求，但拒绝空值、空白、控制字符、非 ASCII 和超过 128 位的输入，提示不包含输入值。短密码保护较弱，建议生成或设置更长的独特密码；后端自身规则仍需满足。

入口单账号 Basic Auth 哈希门禁仅接受新用户，同一组凭据再由本地网关认证；其他后端有效用户、Bot、管理员都不能通过新域名。

HTTPS 与手机#

全部 DNS A/AAAA 直接指向此主机，首次签发 Cloudflare 用“仅 DNS”，安全组允许 80/443。复用共享代理，无代理且端口空闲才建立受管代理；19798/5244 仍只在 127.0.0.1 发布。不支持纯内网 HTTP 降级，不跳过证书校验。

名称：TG2Cloud 文件
协议：HTTPS
服务器：你设置的外部域名
端口：443
根路径：/dav/
用户名：新外部专用用户名
密码：使用新设置的外部专用密码

仅 GET/HEAD/OPTIONS/PROPFIND，其他写方法拒绝；Depth 仅空值/0/1。中文、空格、正常编码和 Range 保留，流式读取不完整落盘。危险点段/重复编码、反斜杠、查询参数拒绝；上游重定向返回 502，不把凭据送往其他主机。限流兼容常规播放，但大量并发枚举仍可能 429。网关须支持安全的本地 WebDAV 读取代理，不能为兼容修改影响 Bot 的全局设置。

检查、维护和卸载#

从 v1.4.7 起，从 tg2cloud → 15. 外部 WebDAV 选择对应操作即可；以下显式子命令继续兼容，用于按参数检查样本等高级操作，无需日常另记一条管理命令：

tg2cloud-webdav
tg2cloud-webdav status --edition openlist
tg2cloud-webdav print-config --edition openlist
tg2cloud-webdav check --edition openlist
tg2cloud-webdav check --edition openlist --sample-file '视频/现有视频.mp4'
tg2cloud-webdav disable --edition openlist
tg2cloud-webdav enable --edition openlist
tg2cloud-webdav configure --edition openlist
tg2cloud-webdav upgrade --edition openlist
tg2cloud-webdav uninstall --edition openlist

CloudDrive2 换 edition。status 仅登记信息；check 输入密码做只读实际检查，样本只读一个字节验证 Range。外部网络播放/拖动仍独立验收。

disable 撤销认证，入口 HTTPS 403，保留配置/证书并继续续期；enable 重新核验原生账号和目录。configure 先关闭旧入口再改域名/账号，失败不恢复匿名或借 Bot 密码；后端人工改密不具备原子回滚。Bot 目录/账号/URL 或网关镜像变化要求显式 configure，不扩大范围；后台私自改账号根目录仍需人工发现。

v1.4.7 的安装／配置修复会在确认计划后，先准备和校验离线维护代码，再修改认证与路由；代码准备失败保留原有入口状态，不提前报告安装完成。修复磁盘空间或权限后可重试原操作；若已进入建号或代理变更阶段，则按需修复状态重新检查与配置。普通复制失败／中断清理本次私密候选，历史残留和未知文件保留且不阻塞新尝试，正式运行代码损坏仍停止而不覆盖。断电或强制杀进程不保证候选已清理，也不保证入口已恢复。

uninstall 只移除本功能路由、活动哈希和记录，不删云文件、Bot 数据、人工后端账号或仍引用的证书，不整体 compose down。先卸载附加入口再卸载底层网关，仅 disable 不解除依赖。仍有外部路由时，移除最后管理域名不会停共享代理。

独立元数据/代码/私密回退点在 /opt/tg2cloud-webdav/，共享认证哈希为 /opt/tg2cloud-proxy/external-auth/，共享备份含证书和认证资料，不能公开。元数据 0600/0700，认证目录 0750、哈希 0640，以实际 worker 组读取。目录只读挂载解决密码轮换旧 inode 问题；校验容器实际读取的摘要。备份校验/隔离解包不等于完整服务恢复；恢复还要原生账号、密码、证书和权限匹配，先关闭再恢复，不盲目覆盖生产。

排查与版本兼容#

首次安装若提示“共享代理挂载含未知路径”，先核对容器实际挂载。Certbot 当前应包含 /opt/tg2cloud-proxy/certbot/status → /status；仅该项缺失时，使用 tg2cloud → 对应 Edition → 7. HTTPS 与管理 → 2. 修复 HTTPS，沿用原管理域名和现有代理模式。确认后可能短暂重载共享管理入口，不重启 Bot／网关；完成并确认挂载出现后，再返回外部 WebDAV 安装操作。完整只读检查命令见仓库排查指南↗。其他来源异常或额外挂载仍须停止核验。

历史 v1.4.6 首次安装失败时，tg2cloud-webdav 可能尚未创建；v1.4.7 修复提前准备维护代码，因此命令存在也不等于入口已启用。历史 v1.4.6 的挂载错误较笼统；v1.4.7 维护已增加只读健康检查与启动后挂载复验，仅在身份核验通过、恰缺 /status 且磁盘 Compose 摘要匹配本次生成配置时，单次重建 Certbot 并完整复验，不重启 Bot／网关。不会通过放宽身份检查绕过未知挂载。从 v1.4.7 起仍可用 tg2cloud 重新进入，不需要为缺少独立命令删除数据。

外部路由在历史 schema 2 引入；当前共享代理还支持记录 external_docker 的 schema 3，不能与附加功能自己的 schema 2 混为一谈。未知版本拒绝覆盖，不自动降级。原 v1.3.0 严格旧工具会停止，使用 v1.3.1 起的匹配工具维护；更旧无校验脚本或桌面恢复包禁止覆盖。主入口先公开验证 helper A，再由 B 固定；附加入口只执行包含本功能完整源码与协议的正式资产。历史 Tag 不变。

实际开放前核对原生权限、外网手机播放、续期 dry-run、所用架构、配置失败/中断、启停/轮换/升级、共享路由保留及备份隔离恢复；这些实机项不因版本发布而写成通过。写操作负面验证仅用模拟后端或明确隔离对象，绝不对真实目录 DELETE /dav/。

v1.4.6 界面维护#

v1.4.6 已统一状态／连接检查页面的停留、刷新和返回，以及用户管理中的 Edition／版本与返回提示。需独立升级附加功能并重新打开命令；主安装和 Bot 流程保持原行为。维护者源码体验和发布门槛见维护开发说明↗。外部只读账号、目录隔离、HTTPS 和人工后台权限确认仍须按本文执行。