iCloud Photos Sync Docker 镜像文档

镜像概述和主要用途

iCloud Photos Sync 是一个 iCloud 照片库的单向同步引擎，旨在提供一种简单的方式将完整的 iCloud 照片库备份到本地文件系统。

传统上，这只能通过让 Mac 持续运行 Photos.app（启用"保留原件"）来实现，而这种方法使得文件在没有 Photos.app 的情况下难以查看。

注意：icloud-photos-sync 是一个独立项目，与 Apple Inc. 无任何关联、背书、推荐或其他关联。

核心功能和特性

高效同步功能

• 持续高效地将完整的远程 iCloud 照片库同步到本地文件系统
• 支持 iCloud 共享照片库
• 通过可信设备、SMS 和语音认证支持 MFA 身份验证

  安全密钥支持待实现，如有此使用场景请提供帮助

• 通过缓存 MFA 信任令牌实现自主操作
• 通过高效的差异算法而非完整库拉取，支持大型库
• 完整的 iCloud 照片库备份，包含所有重要文件的原始状态和编辑版本

  Live Photos 支持待实现

WebUI 管理

• 通过简单易用的 WebUI 使用应用程序
• 检查同步状态
• 触发临时同步
• 需要时输入 MFA 代码
• 接收同步状态的推送通知

本地状态管理

• 每个资源仅下载一次，并链接到各自的文件夹
• 无需在数据库中跟踪本地状态，状态通过文件系统（命名和链接）完全反映

文件夹归档功能（可选）

• 归档相册会将所有资源持久化到本地文件系统的相应文件夹中
• 未来同步将忽略该文件夹（因此这些资源不会被更改/删除）
• 如果远程相册被移动，归档文件夹将被移动到相同位置
• 如果远程相册被删除，归档文件夹将被放入"lost+found"类型的文件夹中
• 可选地可以从 iCloud 照片库中删除归档文件夹中的所有照片（除非它们是"收藏夹"），从而减少云存储需求

专用 iCloud 照片应用

• 不依赖提供 iCloud 访问的成熟第三方库
• 连续完整备份无需配置
• 更快支持特定用例需求

使用场景和适用范围

• 需要将 iCloud 照片库备份到本地文件系统的用户
• 希望不依赖 Mac 上的 Photos.app 进行照片备份的用户
• 需要在没有 Photos.app 的情况下访问 iCloud 照片的用户
• 拥有大型照片库并需要高效同步解决方案的用户
• 需要对照片备份进行更多自定义控制的高级用户

使用方法和配置说明

Docker 运行命令

docker run -d \
  --name icloud-photos-sync \
  -p 3000:3000 \
  -v /path/to/photos:/app/photos \
  -v /path/to/config:/app/config \
  -e TZ=Asia/Shanghai \
  steilerdev/icloud-photos-sync

Docker Compose 配置

version: '3'
services:
  icloud-photos-sync:
    image: steilerdev/icloud-photos-sync
    container_name: icloud-photos-sync
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - /path/to/photos:/app/photos
      - /path/to/config:/app/config
    environment:
      - TZ=Asia/Shanghai

配置说明

卷挂载

• /app/photos: 本地存储照片的目录
• /app/config: 应用配置和缓存数据目录

环境变量

• TZ: 设置时区，例如 Asia/Shanghai

访问 WebUI

启动容器后，通过浏览器访问 http://localhost:3000 即可打开 WebUI 进行配置和管理。

限制

由于此应用程序使用未公开的公共 API，存在一些已知限制：

iCloud 共享照片库

虽然此应用正在同步"共享照片库"中的所有资源，但 API 不提供用户文件夹层次结构中共享资源的位置（在启用"共享照片库"时导航到 WebUI 上的文件夹将产生错误）。在此功能可用之前，"共享照片库"资源将仅存在于 _Shared-Photos 文件夹中，因此无法归档。

文件类型支持

文件类型的支持需要由该应用程序硬编码，因为完整列表不可用或无法检索。如果遇到 Unknown filetype descriptor 错误，请报告该问题，以便将文件类型添加到应用程序中。

系统支持

• Debian-11: 开发平台
• Ubuntu-latest: 单元测试支持
• MacOS-latest: 单元测试支持
• Windows-latest: 不计划支持

相关资源

• ***文档
• CLI 参考
• GitHub 仓库
• Docker Hub