iCloud照片下载器完全使用指南

🚀 基础入门：3分钟上手iCloud照片备份

三步安装法

1. 获取代码

   git clone https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader
   cd icloud_photos_downloader
   

2. 安装依赖

   ./scripts/install_deps
   

3. 验证安装

   icloudpd --version
   

首次使用流程

1. 基础命令模板

   icloudpd --username [e-mail] --directory ~/Pictures/icloud_backup
   

2. 认证流程

   • 输入Apple ID密码（推荐使用系统密钥链存储）
   • 完成两步验证（根据提示输入验证码）

常见问题
Q: 提示"认证失败"但密码正确？
A: 检查是否开启了双重认证，需要使用专用App密码而非账户密码

Q: 能否在无图形界面的服务器上使用？
A: 可以，通过--cookie-directory参数指定缓存位置实现无交互认证

🚀 核心功能：5大场景化解决方案

🌴 旅行照片备份方案

场景需求：旅行期间自动备份手机拍摄的照片，避免存储空间不足
解决方案：

icloudpd --username [e-mail] \
  --directory ~/TravelPhotos/2024_Summer \
  --until-found 5 \
  --skip-videos \
  --set-exif-datetime

💡 技巧：--until-found 5会在发现5张已存在的照片后停止检查，大幅提升增量同步效率

🧹 空间清理方案

场景需求：下载后自动清理云端旧照片，释放iCloud存储空间
解决方案：

icloudpd --username [e-mail] \
  --directory ~/Pictures/icloud_archive \
  --keep-icloud-recent-days 30 \
  --size original

⚠️ 注意：此操作会删除云端照片，请先确认本地备份完整

🎥 视频专项备份

场景需求：仅下载视频文件并按年份分类存储
解决方案：

icloudpd --username [e-mail] \
  --directory ~/Videos/iCloud \
  --folder-structure "{:%Y}" \
  --skip-photos \
  --recent 50

💡 技巧：--folder-structure支持strftime格式，可按拍摄时间自动分类

🕵️ 选择性下载方案

场景需求：仅下载特定相册的照片
解决方案：

# 先列出所有相册
icloudpd --username [e-mail] --list-albums

# 下载指定相册
icloudpd --username [e-mail] \
  --directory ~/Pictures/FamilyAlbum \
  --album "家庭聚会"

🌐 国内用户优化方案

场景需求：解决国内访问iCloud速度慢的问题
解决方案：

icloudpd --username [e-mail] \
  --directory ~/Pictures/iCloud \
  --domain .cn \
  --watch-with-interval 3600

💡 技巧：--domain .cn参数将请求路由到中国区服务器，提升访问速度

常见问题
Q: 如何查看所有可用相册？
A: 使用--list-albums参数获取相册列表，中文相册名需注意编码问题

Q: 下载的照片方向不正确怎么办？
A: 添加--set-exif-datetime参数会自动修复EXIF方向信息

🚀 高级应用：专家级功能探索

🔄 无人值守同步方案

场景需求：7×24小时自动同步iCloud照片
实现步骤：

1. 创建同步脚本sync_icloud.sh：

   #!/bin/bash
   icloudpd --username [e-mail] \
     --directory /media/backup/icloud \
     --until-found 10 \
     --watch-with-interval 1800 \
     --log-level info \
     --log-file /var/log/icloud_sync.log
   

2. 设置权限并添加到系统服务：

   chmod +x sync_icloud.sh
   # 配置systemd服务实现开机自启
   

📊 元数据管理方案

场景需求：保留照片完整元数据，支持专业后期处理
解决方案：

icloudpd --username [e-mail] \
  --directory ~/ProfessionalPhotos \
  --xmp-sidecar \
  --keep-unicode-in-filenames \
  --set-exif-datetime

⚠️ 注意：--xmp-sidecar会为每张照片生成.xmp元数据文件，需确保存储空间充足

🔒 多账户隔离方案

场景需求：管理多个iCloud账户的照片备份
解决方案：

# 账户1：个人照片
icloudpd --username [e-mail] \
  --directory ~/iCloud/Personal \
  --cookie-directory ~/.pyicloud/personal

# 账户2：工作照片
icloudpd --username [e-mail] \
  --directory ~/iCloud/Work \
  --cookie-directory ~/.pyicloud/work

常见问题
Q: 如何监控同步状态？
A: 结合--log-file和邮件通知功能，使用--email-notifications参数配置告警

Q: 同步中断后会重复下载吗？
A: 不会，工具会自动识别已下载文件，可使用--until-found 0强制完整检查

🚀 实战案例：从新手到专家

新手避坑指南

错误案例1：命令行直接输入密码

错误做法：

icloudpd --username [e-mail] --password mypassword123  # 危险！

正确做法：
省略--password参数，让工具交互式提示输入，或使用密钥链存储

错误案例2：盲目使用自动删除功能

错误做法：

icloudpd --username [e-mail] --delete-after-download  # 已废弃！

正确做法：
使用更安全的--keep-icloud-recent-days参数：

icloudpd --username [e-mail] --keep-icloud-recent-days 30

错误案例3：忽视存储空间监控

错误做法：
无限制同步所有照片导致磁盘空间耗尽
正确做法：
结合--size和--recent参数控制下载量：

icloudpd --username [e-mail] --size medium --recent 100

参数组合速查表

使用场景	命令模板	核心优势
快速测试	icloudpd --username [e-mail] --recent 5 --dry-run	安全验证配置，不实际下载
增量同步	icloudpd --username [e-mail] --until-found 10	智能断点续传，节省时间
空间清理	icloudpd --username [e-mail] --keep-icloud-recent-days 30	自动清理旧照片，释放空间
视频备份	icloudpd --username [e-mail] --skip-photos --folder-structure "{:%Y/%m}"	按年月分类存储视频
服务器同步	icloudpd --username [e-mail] --watch-with-interval 3600 --log-file sync.log	无人值守，持续同步

企业级部署建议

1. 多账户管理：为每个账户创建独立配置文件和缓存目录
2. 存储策略：使用RAID存储确保数据安全，定期校验文件完整性
3. 监控告警：配置日志监控和邮件通知，及时发现同步异常
4. 权限控制：限制执行用户权限，避免敏感信息泄露

常见问题
Q: 企业环境中如何批量部署？
A: 使用配置文件存储参数，结合脚本实现批量账户管理

Q: 如何处理大量历史照片的首次同步？
A: 分阶段进行，先使用--recent小批量测试，再逐步扩大范围