Drive Sync 架构：URL、Scopes 与审计

这是面向开发者的 Drive Sync 参考。适用于将同步访问与 REST API 或 MCP server 集成、基于 TrekMail Drive 构建工具，或审计 WebDAV 外观如何强制执行权限。

如果只想将 rclone 或 Finder 连接到 Drive，请从 Drive Sync 概述开始。

Drive Sync 是什么

Drive Sync 是 TrekMail Drive 的 WebDAV 接口。兼容的同步应用可通过独立设备密码和选定权限，访问控制面板与网页邮箱中相同的文件。

接口在固定前缀下使用标准 WebDAV 方法。客户端支持程度不同，因此在用于生产迁移或备份前，请先用一次性文件夹测试所需操作。

URL 布局

Drive URL 针对部署生成，并显示在 Sync devices 中。请复制该 URL，不要根据控制面板域名自行构造。路径以 /dav/files/ 开头：

https://YOUR-DRIVE-HOST/dav/files/

该根目录下有账户树和邮箱树。密码可以打开的内容同时取决于邮箱绑定与所选权限。

账户级树

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

这是控制面板中的 Account Drive。不受单个邮箱限制的密码在具备账户 Drive 权限时可以查看此树。

邮箱范围树

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

设备密码限制为单个邮箱时，只能看到该邮箱的个人树。如果邮箱有个人 Drive 访问权限且账户有共享文件夹，Shared/ 集合会显示与所有邮箱共享的账户文件夹。设有客户存储空间上限的域名中的邮箱在 Shared/ 中没有文件夹；空间用满后，PUT、POST、MKCOL、COPY 和 MOVE 会被以 403 拒绝，DELETE 仍可使用。

限制为单个邮箱的密码看不到 Account Drive 或其他邮箱。不受邮箱限制的密码可以列出账户的 Drive 空间，但每个路径仍需要匹配的账户或邮箱权限。

创建设备密码

可从控制面板的 Sync devices 创建密码，也可在网页邮箱中为当前邮箱创建。控制面板可创建账户级密码或限制到一个邮箱；网页邮箱只能为当前登录邮箱创建。

使用清晰标签，只选择应用所需权限，并为临时连接设置到期时间。密钥只显示一次，请在关闭确认屏幕前保存到应用或密码管理器。

可随时撤销设备密码，而不更改常规 TrekMail 登录密码。已撤销或过期的密码会立即停止工作。

使用设备密码登录

同步通过 HTTPS 使用 HTTP Basic。输入 Sync devices 上显示的用户名及生成的设备密码。不要在同步应用中使用 TrekMail 控制面板密码。

密码撤销或过期后，应用通常会再次请求凭据。每次请求都会检查账户状态、邮箱访问权限、Drive 访问权限和所选权限。

Scope 模型

Drive Sync 使用与 REST API 相同的 scope 字符串，格式为 drive:{family}:{action}。设备密码适用以下八项：

读取路径需要匹配的 :read 权限；创建、更改、移动、复制或删除需要 :write。路径决定应用请求账户还是邮箱访问，因此单邮箱密码无法到达 Account Drive 或其他邮箱。

Sync devices 屏幕只提供适合同步应用的权限。Billing permissions 不属于设备密码。

Share 与 purge 权限

账户有权使用时，设备密码表单可显示 :share 和 :purge。当前 WebDAV 路由 guard 仅将文件操作映射到 :read 和 :write，因此不要假定选择前两项会添加 WebDAV 共享链接或永久删除命令。

常规 WebDAV DELETE 需要 :write，并将文件移到 Trash。WebDAV 不提供原位文件替换或永久清除操作，请使用 Drive 界面完成这些任务。

文件名安全

文件与文件夹名称必须适用于不同操作系统。空名称、路径分隔符、控制字符、误导性文件名字符，以及经 Windows 或 Unicode 规范化后冲突的名称都会被拒绝。名称最多可有 255 个可见字符。

应用收到验证错误时，请在应用中重命名项目后重试。不要通过在文件名中放入路径来绕过错误。

分块上传

小文件可使用普通 PUT。支持 Nextcloud chunked-upload v2 的客户端可在 /dav/uploads/{session-uuid}/ 下创建上传会话，上传带编号的分块，再使用 MOVE 在最终位置组装文件。

上传限制可能因部署和客户端而异。将失败或过期会话视为新的上传尝试。如果其他客户端先创建了目标，请根据冲突响应选择新名称，或刷新文件夹后重试。

审计记录

通过 Sync 成功执行的更改会显示在 Drive 活动历史中。记录标识受影响项目、操作、时间和所用设备密码，管理员可调查异常更改并撤销相应密码。

使用 Drive change feed 的客户端可看到 WebDAV 产生的更改。如果服务要求完全重新同步，请先根据新快照重建本地视图，再继续使用保存的 cursor。

速率限制

Drive Sync 请求受速率限制，以保护服务和文件。客户端收到 429 时，应降低 concurrency，提供时遵循 Retry-After，先重试一个小操作再恢复任务。

可用性

Drive Sync 已在 production 中可用。账户必须有 Drive 访问权限，可用设备密码权限仍取决于账户、邮箱、套餐及创建密码的人。White Label 客户使用相同服务。始终从 Sync devices 复制当前 URL，不要自行构造。

后续阅读

• 最终用户设置请参阅 Drive Sync 概述。
• 签发设备密码的控制面板 UI 请参阅 Sync devices。
• 对应的 REST API 与 MCP 操作请参阅 Drive API 概述和 Drive API Scopes 与权限。
• 同步共用的存储与配额模型请参阅共享存储配额说明。