docker-icloudpd API完全指南：从集成到扩展开发

俞予舒Fleming

1259人浏览 · 2025-09-25 05:35:18

俞予舒Fleming · 2025-09-25 05:35:18 发布

docker-icloudpd API完全指南：从集成到扩展开发

【免费下载链接】docker-icloudpd An Alpine Linux 3.18.3 container for the iCloud Photos Downloader command line utility 项目地址: https://gitcode.com/GitHub_Trending/do/docker-icloudpd

docker-icloudpd是一个基于Alpine Linux的Docker容器，用于iCloud照片下载器（iCloud Photos Downloader）。它能够同步多个iOS设备的照片流到服务器，支持系统密钥环安全存储凭据、HEIC到JPG转换，以及多种通知方式。本文将详细介绍其API配置、集成方法和扩展开发要点。

核心配置文件解析

配置文件路径

所有配置项均通过CONFIGURATION.md文件管理，容器首次启动时会在/config/icloudpd.conf生成默认配置。核心环境变量仅推荐设置TZ（时区），其他配置通过配置文件调整：

# 基础配置示例 [CONFIGURATION.md](https://gitcode.com/GitHub_Trending/do/docker-icloudpd/blob/e9beca57a0f047100ba293a627d60fd89a4c5cdd/CONFIGURATION.md?utm_source=gitcode_repo_files#L10-L18)
apple_id = your_apple@example.com  # 必选，iCloud账号
user = photosync                  # 容器内用户名，影响文件所有权
download_path = /home/photosync/iCloud  # 下载目录
download_interval = 86400         # 同步间隔（秒），默认24小时

关键配置项说明

配置项	用途	示例值
`authentication_type`	认证类型	`MFA`（默认，需多因素认证）
`convert_heic_to_jpeg`	HEIC转JPG	`true`（保留原图）
`folder_structure`	目录结构	`{:%Y/%m/%d}`（按日期组织）
`nextcloud_upload`	Nextcloud同步	`true`（启用上传）

容器部署与初始化

网络与数据卷配置

推荐创建专用Docker网络避免DNS问题，并挂载配置卷和照片目录：

# 创建专用网络 [CONFIGURATION.md](https://gitcode.com/GitHub_Trending/do/docker-icloudpd/blob/e9beca57a0f047100ba293a627d60fd89a4c5cdd/CONFIGURATION.md?utm_source=gitcode_repo_files#L253-L260)
docker network create \
  --driver=bridge \
  --subnet=192.168.115.0/24 \
  --gateway=192.168.115.254 \
  icloudpd_bridge

# 创建容器 [CONFIGURATION.md](https://gitcode.com/GitHub_Trending/do/docker-icloudpd/blob/e9beca57a0f047100ba293a627d60fd89a4c5cdd/CONFIGURATION.md?utm_source=gitcode_repo_files#L263-L273)
docker create \
  --name icloudpd_sync \
  --network icloudpd_bridge \
  --env TZ=Asia/Shanghai \
  --volume icloudpd_config:/config \
  --volume /host/photos:/home/user/iCloud \
  boredazfcuk/icloudpd

初始化认证流程

容器启动后需执行初始化命令设置密码和MFA cookie：

# 初始化密钥环与认证 [CONFIGURATION.md](https://gitcode.com/GitHub_Trending/do/docker-icloudpd/blob/e9beca57a0f047100ba293a627d60fd89a4c5cdd/CONFIGURATION.md?utm_source=gitcode_repo_files#L293)
docker exec -it icloudpd_sync sync-icloud.sh --Initialise

执行后按提示输入Apple ID密码和MFA验证码，凭据会加密存储在/config/python_keyring/目录。

功能集成指南

照片同步与格式转换

启用HEIC转JPG需配置：

convert_heic_to_jpeg = true
jpeg_quality = 90  # 0-100，默认90
jpeg_path = /home/user/iCloud/jpg  # 可选，分离存储JPG

转换后的文件默认与原图同目录，可通过jpeg_path指定独立路径。

通知系统配置

支持多种通知方式，以即时消息工具为例：

notification_type = 即时消息工具
im_token = 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11  # 应用令牌
im_chat_id = -1001234567890  # 接收者ID
im_polling = true  # 启用消息监听（接收同步指令）

发送容器用户名即可触发手动同步（需im_polling=true）。

Nextcloud集成

配置自动上传下载文件至Nextcloud：

nextcloud_upload = true
nextcloud_url = https://nextcloud.example.com
nextcloud_username = sync_user
nextcloud_password = your_password
nextcloud_target_dir = Photos  # 远程目录

删除本地文件时可同步删除云端（需nextcloud_delete=true）。

高级功能与扩展开发

自定义同步逻辑

通过single_pass=true禁用循环同步，结合宿主cron实现自定义调度：

single_pass = true  # 单次运行后退出

容器重启策略需设为no，避免重复执行。

钩子脚本扩展

可通过修改launcher.sh或sync-icloud.sh添加自定义逻辑，例如：

同步前执行文件备份
下载后触发第三方处理
扩展通知至其他消息平台

多账户与权限隔离

为不同Apple ID创建独立容器，通过user_id和group_id匹配宿主用户ID，避免权限冲突：

# 多账户示例：为家庭账户创建独立容器
docker create \
  --name icloudpd_family \
  --env TZ=Asia/Shanghai \
  --volume icloudpd_family_config:/config \
  --volume /host/family_photos:/home/family/iCloud \
  --user 1001:1001  # 宿主用户ID:组ID
  boredazfcuk/icloudpd