iCloudHarbor 是一个运行在 Docker 中的 iCloud Photos 备份工具。它会定时把照片、视频、 Live Photo 和 RAW 下载到 Linux、群晖或其他 NAS。
当前版本:
0.6.4。只支持从 iCloud 备份到本地,不会删除 iCloud 中的照片。
它支持断点续传和文件校验;容器重启后会继续同步,已经下载的照片不会重复下载。通知、 扫描加速、RAW、相册、命名等选项都在 CONFIGURATION.md 中说明,首次 部署不需要配置。
下面以群晖路径为例:
- 程序配置保存在
/volume1/docker/icloudharbor/config; - 照片保存在
/volume2/photos/iCloud。
请先确认设备已经安装 Docker 和 Docker Compose。
通过 SSH 进入 NAS,然后运行:
mkdir -p /volume1/docker/icloudharbor
cd /volume1/docker/icloudharbor
curl -fsSL https://raw.githubusercontent.com/lwx-cloud/icloudHarbor/main/deploy/install.sh | sudo bash完成后会生成:
config/
.env
docker-compose.yaml
安装脚本只用于首次部署。再次运行会覆盖
.env和docker-compose.yaml,更新程序时不要 重复执行安装脚本。
使用群晖 File Station 打开 .env,也可以在终端使用:
vi .env只需要修改或确认下面这些参数:
| 参数 | 填什么 | 用途 |
|---|---|---|
IH_APPLE_ID |
Apple Account 邮箱 | 指定需要备份的 iCloud 账号。 |
IH_PHOTOS_PATH |
例如 /volume2/photos/iCloud |
照片在 NAS 上的保存目录。 |
IH_REGION |
global 或 china |
普通账号用 global;云上贵州账号用 china。 |
IH_PUID |
NAS 用户的 UID | 让下载文件属于正确的 NAS 用户。 |
IH_PGID |
NAS 用户组的 GID | 让下载文件属于正确的 NAS 用户组。 |
安装脚本通常会自动填写 UID/GID。群晖可以运行下面的命令核对:
id 管理员用户名例如输出包含 uid=1026、gid=100,就分别填写 1026 和 100。不要直接照抄别人的数字。
其余参数保持默认即可:
| 参数 | 默认作用 |
|---|---|
IH_CONFIG_PATH |
保存数据库、登录状态和程序配置,不要随意更换。 |
IH_CONFIG_MODE=env |
每次启动都以 .env 和程序默认值生成配置,普通部署保持此值。 |
IH_TIMEZONE |
日志和定时任务使用的时区。 |
IH_SYNC_INTERVAL=12 |
每 12 小时检查一次;只能填写 6、12 或 24。 |
IH_RUN_ON_START=true |
容器启动后立即检查一次。 |
IH_PHOTO_SIZE=original |
下载照片原始版本。 |
IH_NOTIFY=false |
默认关闭通知。 |
Apple 密码不要写进 .env,认证时会在终端单独询问。
这里的路径必须和 IH_PHOTOS_PATH 完全一致:
mkdir -p /volume2/photos/iCloud
touch /volume2/photos/iCloud/.icloudharbor-mounted.icloudharbor-mounted 用于确认照片磁盘已经正确挂载。如果没有这个文件,程序会拒绝下载,
避免照片被误写进容器磁盘。
docker compose pull
docker compose up -d
docker exec -it icloudharbor setup
docker logs -f icloudharborsetup 会询问 Apple 密码,并在需要时询问双重认证验证码。输入密码时终端只显示星号。
认证成功后可以退出操作界面,照片下载会在主容器后台继续执行。
看到日志开始扫描图库或下载照片,就说明部署完成。
# 查看下载日志
docker logs -f icloudharbor
# 查看状态
docker exec -it icloudharbor status
# 立即请求一次后台同步
docker exec -it icloudharbor sync
# Apple 登录失效后重新认证
docker exec -it icloudharbor setup
# 只读预览下一次同步
docker exec -it icloudharbor plan
# 列出可访问的图库和相册
docker exec -it icloudharbor list
# 备份 SQLite 数据库
docker exec -it icloudharbor backup
# 清除 Apple 登录状态和本地保存的密码
docker exec -it icloudharbor reset其他参数见 CONFIGURATION.md。
如果手工修改过 config/config.yaml,从 0.6.1 升级到 0.6.2 或更高版本前请先按
升级说明备份配置并设置 IH_CONFIG_MODE=yaml。
普通 .env 用户不需要这一步。
进入部署目录后运行:
cd /volume1/docker/icloudharbor
docker compose pull
docker compose up -d --force-recreate --remove-orphans
docker exec -it icloudharbor status更新不会删除照片、数据库或登录状态。不要重新运行首次安装脚本。
其他旧版本升级以及完整扫描一次的建议见 CONFIGURATION.md 的常见配置。
| 想设置什么 | 查看位置 |
|---|---|
| 通知 | 通知配置 |
| 下载照片尺寸、Live Photo、RAW/JPEG | 媒体 |
| 指定相册、日期或加快日常扫描 | 相册和筛选 |
| 按日/月/年整理目录、共享权限、文件名和并发数 | 路径、权限和下载 |
| Cron、多通知渠道等高级功能 | 高级 config.yaml 与 yaml 模式 |
遇到 marker_missing、AUTH_REQUIRED 或目录权限问题,请查看
CONFIGURATION.md 的常见问题。
/config包含 Apple 登录状态和数据库,应当持久化并定期备份。不要公开 Apple 密码、 Cookie、验证码或通知密钥。