icloud-sync/README.md

iCloud Photos Sync

使用 Docker 自动同步 iCloud 照片到本地。

快速开始

1. 配置

cp .env.example .env

编辑 .env 文件：

APPLE_ID=your@icloud.com
SYNC_INTERVAL=86400
PHOTOS_PATH=./photos

2. 启动

docker compose up -d

3. 认证

# PowerShell
.\icloud.ps1 auth

# Bash
./icloud.sh auth

按提示输入密码和 Apple 发送的验证码。

管理命令

.\icloud.ps1 <命令>    # PowerShell
./icloud.sh <命令>     # Bash

命令	说明
auth	重新认证（Cookie 过期时使用）
logs	查看实时日志
status	查看容器状态
restart	重启容器
sync	立即触发同步

配置说明

环境变量 (.env)

变量	说明	默认值
APPLE_ID	Apple ID	必填
SYNC_INTERVAL	同步间隔（秒）	86400 (24h)
PHOTOS_PATH	照片保存路径	./photos

Docker Compose 配置

更多选项可在 docker-compose.yml 中配置：

变量	说明
folder_structure	文件夹结构，如 {:%Y/%m}
skip_videos	跳过视频
skip_live_photos	跳过实况照片
convert_heic_to_jpeg	HEIC 转 JPEG
auto_delete	同步删除
recent_only	只下载最近 N 张
until_found	增量同步优化

完整配置参考：boredazfcuk/docker-icloudpd

目录结构

icloud-sync/
├── docker-compose.yml   # Docker 配置
├── .env                 # 环境变量（不提交到 Git）
├── .env.example         # 环境变量示例
├── icloud.ps1           # PowerShell 管理脚本
├── icloud.sh            # Bash 管理脚本
├── config/              # Cookie 和认证信息
└── photos/              # 下载的照片
    └── 2026/
        └── 01/

注意事项

• Cookie 约 30 天过期，届时需重新认证：.\icloud.ps1 auth
• 首次同步大量照片可能需要较长时间
• 建议设置 skip_check: "true" 以提高大库同步性能
• 中国区 iCloud 需设置 icloud_china 和 auth_china 为 true

License

MIT