用 rclone 连接 iCloudiCloud Drive 与 iCloud Photos 后端的配置、认证原理与实战指南【免费下载链接】rclonersync 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/rclonerclone 自 v1.69 起内置iclouddrive后端可在一个 remote 中同时覆盖iCloud Drive默认服务与iCloud Photos只读照片库两大 Apple 云服务。本文以其官方文档 docs/content/iclouddrive.md 为骨架结合仓库源码讲解完整的交互式配置流程、SRP-6a 免密上送认证机制、Photos 服务的层级结构与磁盘缓存、FUSE 挂载参数以及 Advanced Data ProtectionADP下的故障排查方法帮助你安全地备份、浏览与归档 iCloud 数据。一、后端概览一个 remote两种服务iclouddrive后端在注册时即定义了两种服务类型见 backend/iclouddrive/icloud.go 中的常量定义与 init 注册表服务值含义用途drive默认iCloud Drive访问 iCloud 云盘文件支持读写photosiCloud Photos以只读层级树访问照片图库选择在哪一层生效有三种方式在rclone config中新建 remote 时直接选定service在配置文件中把已有 remote 的service改为photos不改配置仅在使用命令时追加--iclouddrive-service photos临时切换。rclone config之后路由到具体后端的逻辑位于 backend/iclouddrive/icloud.goNewServiceFs解析service选项后默认补为drive再分别分发到 Drive 的NewFs或 Photos 的NewFsPhotos。需要留意的是平台支持范围该后端本体带有//go:build !plan9 !solaris构建标签无法构建的平台上由 backend/iclouddrive/iclouddrive_unsupported.go 提供占位实现。二、初次配置交互式创建与 30 天信任令牌创建 iCloud remote 的前提条件与注意事项使用你常规的 Apple ID 密码配合受信设备弹窗或短信的2FA 验证码⚠️ 重要不接受 App 专用密码App-specific passwords只能用普通密码 2FA。以下示例创建一个专门用于照片的 remoteicloudphotos。若只想用 iCloud Drive让service保持默认值drive即可。首先执行rclone configrclone 会引导你进入交互式配置流程Storage选项中的编号因版本而异选择iclouddrive即可No remotes found, make a new one? n) New remote s) Set configuration password q) Quit config n/s/q n name icloudphotos Option Storage. Type of storage to configure. Choose a number from below, or type in your own value. [snip] XX / iCloud Drive \ (iclouddrive) [snip] Storage iclouddrive Option service. iCloud service to use. Choose a number from below, or type in your own value of type string. Press Enter for the default (drive). 1 / iCloud Drive \ (drive) 2 / iCloud Photos \ (photos) service 2 Option apple_id. Apple ID. Enter a value. apple_id APPLEID Option password. Password. Choose an alternative below. y) Yes, type in my own password g) Generate random password y/g y Enter the password: password: Confirm the password: password: Edit advanced config? y) Yes n) No (default) y/n n Option config_2fa. Two-factor authentication: enter your 2FA code or type sms for a text message Enter a value. config_2fa 2FACODE Remote config -------------------- [icloudphotos] - type: iclouddrive - service: photos - apple_id: APPLEID - password: *** ENCRYPTED *** - cookies: **************************** - trust_token: **************************** -------------------- y) Yes this is OK (default) e) Edit this remote d) Delete this remote y/e/d y最终写入配置的关键字段包括type、service、apple_id、passwordrclone obscure 加密存储、cookies与trust_token均以密文/掩码形式保存由 rclone 自动维护无需手工填写。信任令牌trust token有效期 30 天到期后需重新认证。重新认证有两个途径# 交互式重建 rclone config # 或仅刷新认证状态对应 cmd/config/config.go 中 Use: reconnect remote: 的子命令 rclone config reconnect icloudphotos:在配置阶段的源码实现中重新认证并不只是刷新令牌当config.State 时Config 函数 会主动丢弃旧的 trust token 与 cookies强制走完整 SRP 2FA 流程确保每次 reconnect 都提示 2FA 而不是悄悄复用旧会话。三、认证原理SRP-6a 协议与 2FA 状态机rclone 采用与 iCloud 网页端相同的SRPSecure Remote Password安全远程密码协议与 Apple 身份服务通信。核心承诺是你的密码永远不会被发送到 Apple 服务器——客户端用密码在本地派生密钥与服务端交换密码学证明来验证“你知道密码”这一事实。3.1 认证流程rclone 向 Apple 身份服务发起会话源码中端点位于 api/client.goidmsa.apple.com/appleauth/auth等完成 SRP 密钥交换——密码仅在本地用于派生密钥Apple 向受信设备推送 2FA 提示或允许你请求短信验证码输入 2FA 验证码后rclone 获得可用于后续会话的 trust token 与 cookies。3.2 SRP 参数与本地证明SRP 客户端实现集中在 api/srp.go。它使用RFC 5054 定义的 2048-bit 大素数群g2SHA-256作为协商参数客户端生成 32 字节随机私钥a计算公钥A g^a mod N发送给服务端收到服务端挑战后按 RFC 5054 校验B落在1..N-1区间并拒绝计算得到u 0的非法挑战随后用 PBKDF2(SHA256) 派生的密码密钥、盐值与双方公钥计算会话密钥与证明值M1/M2。服务器只能验证证明拿不到明文密码。3.3 2FA 交互状态机与短信通道iCloud 的 2FA 存在多种形态icloud.go 用显式的状态机覆盖了全部路径若账号没有任何受信设备且配置了受信手机号rclone 会跳过推送直接自动触发短信流程triggerSMSFlow若存在受信设备rclone 显式调用RequestPushNotification向设备推送验证码——这是针对iOS 26.4 上 SRP 409 不再自动推送的兼容处理旧版本上可能产生一次无害的重复推送用户在config_2fa处输入 6 位验证码或输入sms改用短信账号绑定多个手机号时rclone 会先列出手机号供选择再向所选号码发送短信关键中间状态SRP 会话等被 base64 编码存入配置的_auth_session字段以便在“获取验证码”与“校验验证码”两步之间复用会话避免重复做一次 SRP 往返并触发第二次推送。校验通过后调用saveAuthCredentials写入新的trust_token与cookies清空临时会话状态并清除磁盘上旧的认证缓存。3.4 会话保持与自动续期日常使用时非配置阶段若配置中已存有 trust token客户端通过newICloudClienticloud.go以最小开销恢复会话优先复用已缓存的会话与服务端点跳过昂贵的/validate往返。当请求遇到 401/421会话过期时会自动重认证并重放请求详见 api/client.go若此时仍被要求 2FA则返回错误提示用户重新执行rclone config reconnect。四、选择服务--iclouddrive-service命令行覆盖如果不想为照片单独建一个 remote也可以保留service drive的通用 remote如iclouddrive:在需要访问照片库时通过命令行开关临时切换# 列出照片图库第一层即各个 Library rclone lsd iclouddrive: --iclouddrive-service photos # 列出个人图库中的相册 rclone lsd iclouddrive:PrimarySync/ --iclouddrive-service photos # 列出某相册中的全部照片/视频 rclone ls iclouddrive:PrimarySync/All\ Photos/ --iclouddrive-service photos # 把一张 HEIC 照片下载到本地 rclone copy iclouddrive:PrimarySync/Favorites/IMG_0001.HEIC /tmp/ --iclouddrive-service photos即两种用法等价任选其一配置时设service photos得到专用于照片的 remote如示例的icloudphotos配置保持drive按需在命令后追加--iclouddrive-service photos。五、iCloud Photos 的层级结构与只读访问当service photos时remote 呈现一棵只读的、根植于照片图库的层级树第一层照片图库Library——包括你的个人图库PrimarySync以及任何共享图库SharedSync-XXXX第二层及以下相册与文件夹——在 Apple Photos 中组织的嵌套结构原样呈现相册可含子文件夹叶节点照片与视频文件——相册内的媒体资源Live Photo 的.MOV伴随文件也会一并列出。List的层级分发逻辑见 icloudphotos.go根 ID 下列出所有库并附带各库相册数量lib:前缀的目录 ID 列出库内相册album:前缀的目录 ID 则列出相册内媒体或子文件夹。5.1 需要注意的首次列举延迟由于 Apple 照片 API 存在分页上限超大相册如含 75,000 个条目的 All Photos首次冷列举可能需要数分钟。这个开销只在第一次发生——后续列举会命中磁盘缓存详见下文缓存机制。5.2 只读限制iCloud Photos 服务是只读的上传、删除、重命名与移动均不受支持。从源码特性看Photos 后端的能力集仅声明了ReadMetadata等只读特性icloudphotos.go没有暴露任何写接口。若把 Photos remote 当作普通可写目标使用会收到明确的能力错误。六、Photos 元数据--metadata下的五个只读键启用--metadata后iCloud Photos 的条目会暴露以下只读元数据仅当service photos时可用元数据键含义类型示例值只读added-time条目被加入 iCloud 图库的时间RFC 33392006-01-02T15:04:05Z✅favorite是否标记为收藏bool✅height图片高度像素int✅hidden是否被隐藏bool✅width图片宽度像素int✅这些键与fs.RegInfo.MetadataInfo中的注册完全一致见 icloud.goPhotos 对象的Metadata()方法在读取时动态组装icloudphotos.go——added-time内部以毫秒时间戳存储、对外格式化为 RFC 3339。rclone 元数据机制的整体用法可参考仓库文档 fs/operations/operations.md。元数据的典型消费场景是备份后的筛选与检索例如结合rclone copy --metadata保留收藏/隐藏标记或配合rclone lsjson输出做相册级整理。注意favorite、hidden等仅由元数据携带不作为文件系统的真实“属性”持久化到目标。七、磁盘缓存机制首跑并行分页 轻量增量检查iCloud Photos 会把相册清单缓存到本地磁盘保证后续访问快速。这是反复列举大相册时体验差异巨大的关键机制。7.1 首次冷列举并行startRank分区首次列举大相册时Photos API 的 CloudKit 查询接口只支持按startRank记录偏移遍历。rclone 将整个相册按stride photosQueryLimit/2即每次 100 个照片划分成多个分区用多个 worker并行拉取见 api/photos.go 的fetchPhotosParallel。7.2 增量检查约 200ms 的changes/zone此后再次访问rclone 不再全量拉取它会针对该 zone图库调用一次changes/zone接口做一次约 200ms 的轻量变更检查batchCheckForChanges甚至可把多个 zone 的检查合并进单个 API 调用见 api/photos.go。只有确认有变更时才失效并重建对应相册缓存无变更则直接复用。变更结果按新增/删除/相册成员关系/元数据标记分类处理parseDeltaRecords并精确失效受影响的相册而非整库刷新。7.3 缓存位置与清理缓存目录按 remote 与图库 zone 隔离~/.cache/rclone/iclouddrive-photos/remote/zone/其中remote是 remote 名称zone是图库 CloudKit zone如PrimarySync目录由 Photos API 层的cacheSubdir iclouddrive-photos常量拼接而来api/photos.go库元数据libraries.json与各 zone 的albums.json也存放在该命名空间下。缓存清理有两种方式直接删除该目录执行rclone config reconnect remote:——它调用后端的Disconnecticloudphotos.go在清除认证状态的同时移除磁盘缓存。八、FUSE 挂载 iCloud Photos 的推荐参数将 iCloud Photos 以文件系统形式挂载浏览时官方推荐如下组合rclone mount remote: /mnt/photos \ --iclouddrive-service photos \ --vfs-refresh \ --dir-cache-time 1h \ --vfs-cache-mode full \ --attr-timeout 1m \ --read-only各参数作用与取舍--vfs-refresh挂载启动时在后台预热目录缓存浏览相册时即刻就绪--dir-cache-time 1h把目录内存缓存寿命从默认的 5 分钟延长到 1 小时——由于后端增量变更检查很快延长缓存是安全的--vfs-cache-mode full把下载过的照片/视频落盘缓存到本地重复访问走本地 IO--attr-timeout 1m降低内核属性查找频率后端只读属性不会在挂载期内被外部改变因此安全--read-only避免对只读后端产生令人困惑的写错误。再次强调超大相册如数万张照片的 All Photos首次列出的等待不可避免这是 API 分页限制所致耐心等待一次后后续浏览将由磁盘缓存接管。九、Advanced Data ProtectionADP高级数据保护支持iCloud Drive/Photos 后端支持开启 ADP 的账号但有一个关键前提在 iPhone 上进入 设置Apple 账户iCloud确保“在网页上访问 iCloud 数据”Access iCloud Data on the Web为开启状态。若账号启用了 ADPrclone 会在 2FA 之后额外请求PCS cookies一种端到端加密场景所需的授权 cookie。Apple 可能在受信设备上弹出批准请求——必须手动批准PCS cookie 才会签发。从源码看PCS cookie 的获取是按服务域drivews/ckdatabasews作用域的api.New的pcsWSKey参数决定了 cookie 归属哪个云服务空值则完全跳过 PCS 流程api/client.go认证成功后统一由ensurePCSCookies保证存在api/client.go。十、故障排查10.1 PCS cookie 错误与 ADP 批准未完成症状出现Missing PCS cookies from the request或形如requestPCS:的错误。其含义是 ADP 账号所需的授权流程未成功完成——会话请求被服务端以423Locked判定为缺少 PCS cookie见 api/client.go 对 423 的注释。解决步骤确认 “在网页上访问 iCloud 数据” 已开启在受信设备上批准弹出的授权请求重新认证以获取新 cookierclone config reconnect icloudphotos:若 remote 仍残留过期认证状态清空配置中的cookies与trust_token字段仍不行则直接删除并重建该 remote。十一、配置选项速查以下为iclouddrive后端的全部选项与文档自动生成部分一致。标准选项选项Config 键环境变量类型默认值说明--iclouddrive-serviceserviceRCLONE_ICLOUDDRIVE_SERVICEstringdrive取值driveiCloud Drive或photosiCloud Photos--iclouddrive-apple-idapple_idRCLONE_ICLOUDDRIVE_APPLE_IDstring必填Apple ID--iclouddrive-passwordpasswordRCLONE_ICLOUDDRIVE_PASSWORDstring必填Apple ID 密码输入必须用 rclone obscure 加密见 rclone obscure 命令密码之所以要求 obscure 存储是因为后端在运行时会调用obscure.Reveal还原明文参与 SRP 推导icloud.go明文不能直接落盘。高级选项选项Config 键环境变量类型默认值说明--iclouddrive-client-idclient_idRCLONE_ICLOUDDRIVE_CLIENT_IDstringd39ba9916b7251055b22c7f910e2ea796ee65e98b2ddecea8f5dde8d9d1a815d用于 iCloud API 访问的客户端 ID一般无需修改--iclouddrive-encodingencodingRCLONE_ICLOUDDRIVE_ENCODINGEncodingSlash,BackSlash,Del,Ctl,InvalidUtf8,Dot后端编码配置通用编码规则见 overview 的 encoding 一节--iclouddrive-descriptiondescriptionRCLONE_ICLOUDDRIVE_DESCRIPTIONstring空remote 描述运行时还有一组由 rclone 自动写入、用于保持认证状态的非交互键trust_token、cookies与临时_auth_session。请勿手工改动除非在执行故障排查里的“清空认证字段”步骤。十二、实践要点总结认证安全SRP-6a 2FA 保证密码永不上传30 天 trust token 到期后用rclone config reconnect remote:快速续期照片访问两条路专用photosremote 或--iclouddrive-service photos临时切换结构为Library(如 PrimarySync) → 相册/文件夹 → 媒体文件性能关键在缓存首次大相册列举较慢之后 ~200ms 增量检查 磁盘缓存让重复访问近乎瞬时需要释放空间时删~/.cache/rclone/iclouddrive-photos/或执行 reconnect元数据是只读附加值--metadata下仅 Photos 服务暴露width/height/added-time/favorite/hidden挂载用只读姿态配合--vfs-refresh、--vfs-cache-mode full、--read-only可获得流畅的浏览体验ADP 账号先开“在网页上访问 iCloud 数据”2FA 后在受信设备上批准 PCS cookie 请求即可正常使用。相关集成测试入口见 backend/iclouddrive/iclouddrive_test.go基于fstest/fstests的标准后端一致性测试套件版本演进记录可查阅 docs/content/changelog.md 中 iclouddrive 相关条目。【免费下载链接】rclonersync 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
