rclone Proton Drive 后端配置与使用指南：将端到端加密的 Proton Drive 接入 rclone

rclone Proton Drive 后端配置与使用指南：将端到端加密的 Proton Drive 接入 rclone

【免费下载链接】rclone"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone

Proton Drive 是一款来自瑞士的端到端加密网盘，本仓库为 rclone 提供了对应的 protondrive 后端，让 rclone 可以像访问本地目录一样上传、下载、同步和挂载 Proton Drive 中的文件。本文以仓库中的官方后端文档 docs/content/protondrive.md 为主体，结合后端实现源码 backend/protondrive/protondrive.go 讲解远程（remote）的交互式创建、全部标准/高级配置项、文件名校验规则、哈希与时间戳能力，以及缓存、去重、Beta 限制等实战要点，帮助读者完整掌握这一后端并能直接落地使用。

一、后端背景与能力边界

Proton Drive（见 protondrive.md 描述）是一个端到端加密的瑞士文件保险库，客户端侧完成全部加解密。rclone 的protondrive后端复用了这套客户端加密机制，从而支持 Proton Drive 的文件传输功能。

需要了解的几个基本事实：

• 路径表示方式：与其他 rclone 后端一致，使用remote:path，且支持任意深度，例如remote:directory/subdirectory。
• API 文档不公开：由于 Proton Drive 不对外发布其 API 文档，本后端通过阅读 Proton 开源客户端源码、观察浏览器流量，以 best-effort 的方式实现（见 protondrive.md）。
• Beta 状态：本后端当前仍处于 Beta，文档声明其实现被认为是正确的且全部集成测试均通过；但由于 Proton Drive 协议随时间演变，可能存在不兼容的账号。若遇到不兼容问题，建议到 rclone 官方论坛反馈（见 protondrive.md）。
• 登录前提（易踩坑）：Proton Drive 的加密密钥必须已经通过浏览器常规登录生成过，否则直接在 rclone 中使用该账号凭据会失败（见 protondrive.md）。也就是说，新注册的账号应先在其网页/桌面客户端登录一次，再配置 rclone。
• 引入版本：该后端从 rclone v1.64.0 开始引入（见文档 front-matter）。

从后端注册源码看，后端名称空间下导出的标识符为protondrive，其注册信息（fs.RegInfo）位于 backend/protondrive/protondrive.go#L64-L205，并在init()中完成。这也是选项文档自动生成的数据来源，文档中的“autogenerated options”注释即指在fs.RegInfo中编辑后运行make backenddocs生成。

二、通过 rclone config 交互式创建远程

在终端运行以下命令进入交互式配置流程：

rclone config

首次配置时，选择新建远程并填写类型protondrive，完整流程如下（摘自 protondrive.md，其中[snip]表示省略的无关选项）：

No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q> n name> remote Type of storage to configure. Choose a number from below, or type in your own value [snip] XX / Proton Drive \ "protondrive" [snip] Storage> protondrive User name user> you@protonmail.com Password. y) Yes type in my own password g) Generate random password n) No leave this optional password blank y/g/n> y Enter the password: password: Confirm the password: password: Option 2fa. 2FA code (if the account requires one) Enter a value. Press Enter to leave empty. 2fa> 123456 Remote config Configuration complete. Options: - type: protondrive - user: you@protonmail.com - pass: *** ENCRYPTED *** Keep this "remote" remote? y) Yes this is OK e) Edit this remote d) Delete this remote y/e/d> y

要点说明：

• name处填写远程别名，后续命令统一用remote:引用（下文示例均可把remote替换为你自定义的名字）。
• user是你的 Proton 账号用户名（邮箱），例如you@protonmail.com。
• password由 rclone 在写入配置文件前自动 obscure 处理，配置文件里显示的pass: *** ENCRYPTED ***即加密后的值。源码中密码的明文解包发生在NewFs阶段，通过obscure.Reveal解密得到，见 backend/protondrive/protondrive.go#L547-L569；obscure 的加解密机制可参考 rclone obscure 命令文档。
• 2fa仅在账号开启了双因素认证时需要填写；未开启时直接回车留空。
• 配置完成后凭据（含内部的 access token、refresh token、salted key pass 等）会被回写保存，便于复用，其内部字段以隐藏选项形式存放在 config map 中，见 backend/protondrive/protondrive.go#L317-L351。

验证与基本用法

配置完成后即可直接用 rclone 命令操作 Proton Drive：

列出 Proton Drive 根目录下的目录：

rclone lsd remote:

列出 Proton Drive 中的所有文件：

rclone ls remote:

把本地目录source复制到 Proton Drive 中名为backup的目录：

rclone copy /home/source remote:backup

后端的目录解析依赖dircache.DirCache（以 Proton Drive 的 root link ID 作为锚点），路径在查询前会经过 sanitize（规范化与编码转换），可参考 backend/protondrive/protondrive.go#L307-L315 以及NewFs中对根目录的初始化逻辑 backend/protondrive/protondrive.go#L537-L644。当根路径既是文件又是目录时会返回fs.ErrorIsFile，这与 rclone 对这类后端的一贯行为一致。

三、标准选项详解

以下是 protondrive 的标准（Standard）选项，均来自后端注册的fs.Option（backend/protondrive/protondrive.go#L69-L97），同时也存在于前端文档 protondrive.md。

关于 2FA 与 OTP 的配合关系，可从源码确认细节（backend/protondrive/protondrive.go#L510-L524）：

1. 若配置了2fa字段，则直接把它作为一次性验证码提交；
2. 若2fa为空但配置了otp_secret_key，则在登录时调用totp.GenerateCode（来自github.com/pquerna/otp/totp）基于当前时间实时生成动态码，再作为TwoFA提交。

因此二选一即可：要么每次手动填最新 2FA 验证码，要么提供静态 TOTP 密钥让 rclone 自动生成动态码（后者更便于脚本化与集成测试）。otp_secret_key属于敏感字段（Sensitive: true且IsPassword: true，见 backend/protondrive/protondrive.go#L98-L108）。

四、高级选项详解

以下高级选项可在交互式配置中选择 "Edit advanced config"，或以长参数形式在命令行覆盖。它们全部定义于 backend/protondrive/protondrive.go#L79-L203，文档部分见 protondrive.md。

mailbox_password（邮箱密码 / 独立密码）

• Config：mailbox_password；环境变量：RCLONE_PROTONDRIVE_MAILBOX_PASSWORD；类型 string；非必填。
• 适用场景：开启“双密码（two-password）”模式的 Proton 账号，需要用邮箱密码来解锁加密密钥。普通单密码账号无需填写。
• 输入同样必须经过 obscure。文档提示其与登录密码的区别详见 Proton 官方知识库文章。
• 代码中它是IsPassword: true的敏感项（backend/protondrive/protondrive.go#L79-L88），明文在NewFs中通过obscure.Reveal还原后作为MailboxPassword传入登录流程。

encoding（文件名编码规则）

• Config：encoding；环境变量：RCLONE_PROTONDRIVE_ENCODING；类型 Encoding；默认值：Slash,LeftSpace,RightSpace,InvalidUtf8,Dot。
• 含义：控制文件名在与 Proton Drive 交互前的转义/还原策略，通用机制参见 overview 编码章节。
• 从默认值可见 Proton Drive 的文件系统限制：不允许文件名中的/、前后空格、非法 UTF-8 字节以及.（作为保留意义字符），rclone 会对这些字符做编码层级的双向转换。源码中默认编码组合定义见 backend/protondrive/protondrive.go#L137-L144，编码与路径清洗逻辑见 backend/protondrive/protondrive.go#L307-L315。

original_file_size（返回加密前文件大小）

• Config：original_file_size；环境变量：RCLONE_PROTONDRIVE_ORIGINAL_FILE_SIZE；类型 bool；默认值：true。
• 作用：Proton Drive 在服务端存储的是加密后的文件，其体积大于明文。开启后 rclone 返回给上层的是解密前的原始文件大小；关闭则返回加密后的大小。
• 文档特别警告：除非有特殊原因需要加密后大小，否则应保持为true，因为Open()等依赖原始内容大小做 seek/range 操作的特性，在拿到错误大小时会无法正常工作。
• 源码佐证：Object.Size()在ReportOriginalSize为真时优先返回originalSize（backend/protondrive/protondrive.go#L1016-L1028）。

app_version（API 客户端版本标识）

• Config：app_version；环境变量：RCLONE_PROTONDRIVE_APP_VERSION；类型 string；非必填。
• 作用：作为当前执行 API 请求的客户端标识随每个请求发送。Proton 对第三方集成推荐形如external-drive-<project>@<version>的格式。留空时 rclone 会自行从自身版本派生出合规值，因此该选项纯属可选。
• 派生实现细节：源码中的protonDriveAppVersionFromRcloneVersion（backend/protondrive/protondrive.go#L364-L433）会用正则[^0-9A-Za-z.+-]+清洗 rclone 版本号中的非法字符，并拼装成external-drive-rclone@<主>.<次>.<补丁>形式（预发布版本附带-stable/-dev/-beta等后缀），最终在 backend/protondrive/protondrive.go#L464-L467 处注入。对应单元测试位于 backend/protondrive/protondrive_internal_test.go，覆盖“由 rclone 版本派生 app version”和“shouldRetry 判定”两处核心逻辑。

replace_existing_draft（覆盖未完成的上传草稿）

• Config：replace_existing_draft；环境变量：RCLONE_PROTONDRIVE_REPLACE_EXISTING_DRAFT；类型 bool；默认值：false。
• 背景：当一次文件上传在完成前被取消或失败，Proton 服务端会留下一个“draft”（草稿）。此后向同一位置再次上传同名文件时会被判定为冲突。
• true：替换该草稿并重新开始上传（集成测试需要设置为 true）。
• false：直接返回错误"a draft exist - usually this means a file is being uploaded at another client, or, there was a failed upload attempt"，本次不上传任何内容。
• 注意：文档声明若此刻恰好有其他客户端也在同一位置并发上传，置 true 时行为未知。该值最终被透传到 Proton-API-Bridge 的配置（config.ReplaceExistingDraft，见 backend/protondrive/protondrive.go#L479）。

enable_caching（元数据缓存开关）

• Config：enable_caching；环境变量：RCLONE_PROTONDRIVE_ENABLE_CACHING；类型 bool；默认值：true。
• 作用：Proton Drive 中的文件和文件夹以“link + keyring”结构表示，启用后 rclone 会缓存这类元数据以显著减少 API 调用、对服务端更友好。
• 重要警告：如果以 VFS 方式挂载 Proton Drive（如rclone mount），请关闭此特性，因为当前实现不会在有外部变更时刷新或清理缓存。
• 缓存一致性边界：缓存面向“rclone 是访问该挂载点的唯一实例”这一场景设计；Proton 的 event 系统（用于感知远端变更的 API 机制）尚未在 bridge 中实现，因此其他客户端造成的更新不会反映到缓存中。若多个客户端并发访问同一挂载点，存在读到过期数据（stale data）的风险。见 protondrive.md 以及代码 backend/protondrive/protondrive.go#L185-L202。
• 源码中DirCacheFlush可清空目录缓存与 bridge 缓存（f.protonDrive.ClearCache()），主要服务于测试场景，见 backend/protondrive/protondrive.go#L936-L942。

description

• Config：description；环境变量：RCLONE_PROTONDRIVE_DESCRIPTION；类型 string；非必填。为 rclone 通用字段，仅用于给远程加备注说明，不影响传输行为。

五、功能特性：哈希、时间戳与文件操作语义

修改时间（Modification times）

Proton Drive 目前不支持更新修改时间。源码中Object.SetModTime直接返回fs.ErrorCantSetModTime（backend/protondrive/protondrive.go#L1038-L1040），Fs.Precision()名义返回time.Second（backend/protondrive/protondrive.go#L931-L934）仅用于表示时间精度假设。这意味着rclone sync等依赖修改时间判断新旧的操作，不能依赖本后端的时间戳语义，需要配合校验和进行决策。

哈希支持

后端只支持SHA1。Fs.Hashes()返回hash.Set(hash.SHA1)（backend/protondrive/protondrive.go#L944-L947），对象级Object.Hash在请求非 SHA1 类型时返回hash.ErrUnsupported；SHA1 值优先取自对象元数据中的 digest，缺省时再通过 API 拉取活动 revision 的文件系统属性获得，见 backend/protondrive/protondrive.go#L993-L1014。因此rclone check、rclone cryptcheck以及--checksum模式等可以正常借助 SHA1 校验两端一致性。

其他传输语义（从源码可推断）

• 分块加密与单线程下载：Proton 明文文件被切成等大（当前约 4 MB，未来可能变化）的数据块，逐块独立加密；块的加密后大小与 SHA1 写入元数据，而原始大小不在元数据中。源码注释明确说明：为避免在拿不到原始块尺寸时做出不安全假设，暂不启用 rclone 的多线程下载，而是把并发下载并解密放在后台完成，因此Fs.Features中NoMultiThreading: true（backend/protondrive/protondrive.go#L583-L592）。
• 未知大小文件不可上传：后端以errCanNotUploadFileWithUnknownSize拒绝流式未知大小的上传（backend/protondrive/protondrive.go#L54）。
• 配额查询：rclone about remote:可用，底层读取账号的MaxSpace/UsedSpace（backend/protondrive/protondrive.go#L949-L971）。
• 清空回收站：rclone cleanup remote:会调用EmptyTrash清空 Proton Drive 回收站（backend/protondrive/protondrive.go#L648-L654）。
• 错误重试策略：shouldRetry只对可恢复错误进行 pacer 重试，例如 HTTP 5xx（503 除外，它由 go-proton-api 内部的 Retry-After 逻辑处理）与带200501Drive 存储类错误码的瞬态失败；对 4xx 永久性校验错误（如无法验证的 key packet、账号未开通的上传格式）不会重试，避免把 pacer 拖到超时，见 backend/protondrive/protondrive.go#L252-L283。

六、命名限制与去重语义

受限字符

• 非法 UTF-8 字节会被替换（处理机制与 overview 中的 invalid UTF-8 章节 描述一致）。
• 文件名左、右两侧的空格会被去除。
• 这两条规则正好对应默认 encoding 中的InvalidUtf8、LeftSpace、RightSpace，其余默认项Slash、Dot对应保留字符/与.的转义（见第四节）。Proton 官方 Web 客户端的相关校验位于其 drive 应用源码的 validation 逻辑中。

重复文件

Proton Drive不允许在同一路径下存在两个完全同名同路径的文件。一旦发生冲突，最终文件是否被覆盖取决于上述高级配置：

• replace_existing_draft=true：替换既有草稿后重传；
• replace_existing_draft=false（默认）：返回 draft 冲突错误，不执行覆盖。

rclone 层面你还可以借助--backup-dir、--suffix、rclone copyto等常规手段避免覆盖误伤，但服务端“不允许重名”是硬性约束，这一点在设计与同步策略时需要特别留意。

七、缓存模型与多客户端并发注意事项

后端默认开启元数据缓存（enable_caching默认 true），缓存对象是 Proton Drive 的 link/keyring 元数据，作用是减少 API 往返。需要重点记住两个边界（文档与代码一致强调，protondrive.md）：

1. 当前没有实现 Proton 的 event 系统，因此其他客户端对同一账户的改动不会主动使缓存失效；
2. 当 rclone 是唯一操作方时缓存是安全高效的；一旦多个客户端同时访问同一挂载点，可能读到过期数据。

实际建议：

• 使用rclone mount/VFS 挂载 Proton Drive 时，显式关闭缓存（--protondrive-enable-caching=false），避免外部客户端更新后缓存脏读；
• 若用批处理同步（rclone copy/sync）等一次性任务且无并发写入方，保持默认即可获得更好的 API 友好度与速度。

八、实现架构与局限性说明

底层依赖链

本后端并不直接对接 Proton 官方 SDK，而是构建在两层库之上（见 protondrive.md）：

1. go-proton-api：提供最基础的 API 调用构件与错误处理（如 429 指数退避），但本质上是“裸”的 API 接口层——例如 Proton Drive 文件的加解密并不在该库中提供。
2. Proton-API-Bridge：在 go-proton-api 之上补齐 gap，封装调用 Proton API 前后的大量复杂任务（尤其是整套加密方案），使 rclone 可以在此之上快速实现。仓库源码以github.com/rclone/Proton-API-Bridge与github.com/rclone/go-proton-api（官方 go-proton-api 的 fork）形式引入，见 backend/protondrive/protondrive.go#L15-L16。

Bridge 层的代码同样来自社区对 Proton 开源客户端与协议观察的产物，官方文档缺失意味着其中可能存在错误。这解释了后端的 Beta 定位——协议演进可能造成部分账号不兼容。

登录与会话复用流程（结合源码）

从 backend/protondrive/protondrive.go#L470-L534 可以还原完整的建连流程：

1. 路由 HTTP 传输层与日志到 rclone 体系，使--dump headers、--ca-cert、-v/-vv等全局开关对 Proton 请求同样生效；
2. 传递replace_existing_draft、enable_caching等选项到 bridge 配置；
3. 检查 config map 中缓存的client_uid、client_access_token、client_refresh_token、client_salted_key_pass（这些以隐藏敏感项存储，见 backend/protondrive/protondrive.go#L109-L136）：有则优先以UseReusableLogin复用；复用失败则清理并回退到用户名/密码登录；
4. 用户名/密码登录时按需填入 mailbox password，并按上一节逻辑填入 2FA 码或由 OTP 密钥现场生成；
5. 登录成功后将返回的会话凭据写回 config map 供下次复用。

这意味着首次rclone config创建远程之后，只要本地凭据缓存有效，后续命令无需每次重新输入密码，也解释了为何配置文件里除了用户名/密码外还会出现若干隐藏的内部 token 字段。

适用范围与已知边界小结

• 不适合作为多人/多进程共享挂载下的实时文件系统（无事件驱动的缓存失效）；单实例 VFS 挂载建议关闭缓存；
• 无法通过 rclone 更新文件修改时间，跨端时间戳一致性需要以 SHA1 为准；
• 服务端同名文件唯一，冲突时由replace_existing_draft决定覆盖或报错；
• 受限于分块加密特性，暂不提供 rclone 多线程下载，大文件传输应评估单连接吞吐；
• 后端为 Beta，遇账号不兼容情形应向 rclone 社区反馈（可附带协议层面细节帮助定位）。

九、进一步探索与验证

• 完整后端文档与自动生成的选项总表：docs/content/protondrive.md
• 后端实现主文件（选项注册、认证、Fs/Object 实现、重试策略、哈希与大小逻辑）：backend/protondrive/protondrive.go
• 集成测试套件（涵盖多组账号配置、上传冲突、删除等端到端场景）：backend/protondrive/protondrive_test.go
• 单元测试（app version 派生、重试判定等内部逻辑）：backend/protondrive/protondrive_internal_test.go
• 文件名编码与非法字符的通用处理规范：docs/content/overview.md
• 密码 obscure 加密/解密用法：rclone obscure 命令

配置完成后，建议先用rclone lsd remote:验证连通性，再以rclone copy --dry-run或rclone check remote:小范围试跑，确认账号的加密密钥已生成、缓存与冲突选项符合你的挂载/同步场景，即可正式投入使用。

【免费下载链接】rclone"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone