Skip to content

About

Harbor 是“港湾”的意思,寓意将 iCloud 中的照片和视频安全地“停靠”到本地、NAS 或服务器。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

iCloudHarbor

License: MIT

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。

1. 生成部署文件

通过 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,更新程序时不要 重复执行安装脚本。

2. 编辑 .env

使用群晖 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,认证时会在终端单独询问。

3. 创建照片目录和安全标记

这里的路径必须和 IH_PHOTOS_PATH 完全一致:

mkdir -p /volume2/photos/iCloud
touch /volume2/photos/iCloud/.icloudharbor-mounted

.icloudharbor-mounted 用于确认照片磁盘已经正确挂载。如果没有这个文件,程序会拒绝下载, 避免照片被误写进容器磁盘。

4. 启动并登录 iCloud

docker compose pull
docker compose up -d
docker exec -it icloudharbor setup
docker logs -f icloudharbor

setup 会询问 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、验证码或通知密钥。

License

MIT

About

Harbor 是“港湾”的意思,寓意将 iCloud 中的照片和视频安全地“停靠”到本地、NAS 或服务器。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages