家里囤了3万张iCloud照片之后我用docker-icloudpd在服务器上搭了个自动备份云相册【免费下载链接】docker-icloudpdAn Alpine Linux container for the iCloud Photos Downloader command line utility项目地址: https://gitcode.com/GitHub_Trending/do/docker-icloudpd深夜十一点我瘫在沙发上刷手机相册想找一张去年春天的全家福。翻着翻着屏幕弹出一条红色警告iCloud 存储空间已满。5GB 免费额度早就不够用了照片视频加起来快 20GB要么按月掏钱扩容要么手动搬出来。那一刻我决定把 iCloud 照片同步到自己的服务器上彻底结束云空间焦虑。docker-icloudpd 就是干这件事的——它是一个运行在 Alpine Linux 容器里的 iCloud Photos Downloader只要部署一次之后每天自动把 iCloud 里的照片和视频拉到你的私有服务器还能顺手把苹果的 HEIC 格式转成通用性更好的 JPEG。这篇文章陪你从零跑通它全程照着抄就行。先别急着懂原理20 分钟让同步跑起来我理解你的心态网上教程一堆讲架构的、讲原理的看完还是不知道第一步敲什么。所以咱们反过来先把服务拉起来成就感拿到手再说原理。准备工作3 个文件一条命令你只需要 Docker别的什么都不用装。在服务器上建一个目录然后准备两份配置。第一份是docker-compose.yml内容非常短services: icloudpd: image: boredazfcuk/icloudpd container_name: icloudpd restart: unless-stopped environment: - TZAsia/Shanghai - user你的用户名 volumes: - icloudpd_config:/config - /home/你的用户名/iCloud:/home/你的用户名/iCloud volumes: icloudpd_config:这一段说明/config是容器存放登录凭证的地方用命名卷保存重启不丢后面那个目录挂载是照片落盘的位置记得改成你自己的路径。第二份是照片目录里的安全哨兵文件。容器有个防呆设计只有发现iCloud目录下存在.mounted这个文件才开始下载否则拒绝同步。目的是防止存储卷没挂上时照片全写进系统盘把机器塞爆。mkdir -p /home/你的用户名/iCloud touch /home/你的用户名/iCloud/.mounted最后一条命令启动容器docker compose up -d到这里服务已经启动了。先别急着激动——它还不会下载任何照片因为还没有你的 iCloud 账号信息。关键一步登录认证--Initialise容器第一次跑起来日志里会反复提示缺少凭证文件。这时候进入容器执行初始化命令docker exec -it icloudpd sync-icloud.sh --Initialise按照提示输入 Apple ID 和密码接着你的 iPhone 上会弹出允许登录的确认框批准后得到一个 6 位验证码填进去。这一步完成了两件事密码被写进容器的系统密钥环keyring不是明文躺在配置里生成一个多因素认证MFAcookie后续下载全靠它。看到日志出现Multifactor authentication cookie generated. Sync should now be successful.恭喜你同步引擎正式开工了。第一次运行日志里藏着这个容器的大半秘密同步开始后你会看到容器像话痨一样刷日志。别嫌吵每行都在告诉你它正在干什么。我挑三行最常见的给你翻译成人话INFO Checking icloud.com is accessible INFO Apple ID: a******sexample.com INFO Download destination directory: /home/user/iCloud第一行是连通性检查——它在确认能连上 iCloud 官网。第二行是账号信息注意它自动帮你把邮箱打了码避免日志泄露隐私。第三行是下载目标路径也就是你挂载进去的那个目录。接下来是它工作的核心节奏检查新文件 → 下载 → 睡大觉。默认每 24 小时跑一轮download_interval86400。你的 iPhone 拍照后照片会立刻传上云端容器到点上班把新照片搬回本地。这个定时上班的机制加上两个看不见的守护构成了它的可靠性凭证安全登录 cookie 存在/config里有效期约 30 天。到期前容器会发通知提醒你过期后运行docker exec -it icloudpd reauth.sh就能续期不用重走初始化。健康自检容器内置了健康检查同步出错或 cookie 快过期时容器状态会变成unhealthy方便你接告警。最常用的 5 个设置项各配一句话使用场景所有配置都写在容器内的/config/icloudpd.conf文件里容器首次启动时会自动生成。你也可以直接用docker exec -it icloudpd nano /config/icloudpd.conf编辑。配置项作用什么时候需要它apple_id你的 iCloud 账号必填一切的前提没它同步直接罢工download_interval同步间隔秒默认 86400 即 24 小时照片更新频繁就改小但别低于 43200否则可能被苹果限流convert_heic_to_jpeg下载时把 HEIC 转成 JPEG你的其他设备或相册软件读不了 HEIC 时打开原图会保留folder_structure本地目录结构默认{:%Y/%m/%d}想让照片按年/月/日归档就用默认值省心notification_type通知渠道支持 Telegram、企业微信、邮件等十几种想第一时间知道同步结果时配置比如配 Telegram再补一个对国内用户很友好的开关如果你的账号在 iCloud 中国区把icloud_chinatrue和auth_chinatrue都打开下载和登录都走icloud.com.cn速度快一截。我踩过的 3 个坑你大概率也会遇到配置这东西光看文档永远记不牢真正动手才会撞墙。下面三个坑是我实际踩过的原样讲给你听。坑一同步突然全停日志写着 ACCESS_DENIED有段时间我手贱把同步间隔调成了 6 小时跑了两天容器开始报private db access disabled for this account。查了一圈才明白苹果会限制过于频繁的请求。解决方案很简单——把download_interval调回 4320012 小时以上容器停掉睡一觉隔天再启动就恢复了。苹果的冷静期大约 6 到 12 小时。坑二照片明明在 iCloud本地却一张没下这是我第一次部署时最懵的。容器日志一切正常目录却是空的。后来发现罪魁祸首是我漏了.mounted文件。这个防呆机制认死理目录里没有它就认为存储卷没挂好宁可空跑也不写盘。补上文件后立即正常同步。如果你也遇到服务正常但零下载先查这个文件在不在。坑三开了高级数据保护ADP后一直认证失败iOS 16.2 以后苹果上线了高级数据保护会把 iCloud 照片端到端加密。听起来很安全但它同时关闭了网页端访问照片的通道而这个容器恰恰是通过网页端下载的。解决方案是在苹果账号设置里关闭 ADP。这是官方明确说明的硬性限制不开这个功能之前一切白搭。怎么确认它真的在干活以及两个进阶玩法验收清单同步跑起来后用 3 个检查确认一切正常看目录ls -l /home/你的用户名/iCloud/2025/08能看到按日期分好的照片文件夹看容器状态docker psSTATUS一列显示healthy看最新日志docker logs icloudpd --tail 20最后几行有同步成功的信息。进阶玩法一让 Telegram 当你的遥控器如果配了 Telegram 通知这个容器还有个隐藏技能给机器人发一条消息内容是你配置的user值比如你的用户名它会立刻触发一次手动同步不用等 24 小时。出门在外拍完照顺手发条消息回家照片已经躺在服务器上了。进阶玩法二照片同步到 Nextcloud 云盘容器内置了 Nextcloud 上传功能。在配置里加上nextcloud_uploadtrue以及nextcloud_url、nextcloud_username、nextcloud_password等参数每张下载下来的照片会自动转存到你的 Nextcloud 服务。iCloud 做源头Nextcloud 做归档双重保险家里的 NAS 也能顺势盘活。你已经完成了什么还能再进一步回头看看你已经做到了三件事用一条命令把 iCloud 照片同步服务跑起来、完成了 MFA 认证并理解 cookie 续期机制、掌握了核心配置和排坑方法。从此 iCloud 存储空间满了也不用再续费照片数据完完全全握在自己手里。下一步我建议你先跑通基础同步再用一两周观察日志确认稳定后开启 HEIC 转 JPEG 或 Telegram 通知。折腾的过程中如果忘了某个参数的含义多翻官方配置文档里面每个配置项都写得很详细配置说明文档CONFIGURATION.md同步主脚本源码sync-icloud.sh健康检查脚本healthcheck.shCompose 示例文件docker-compose/docker-compose.example.yml需要自己构建镜像时克隆仓库地址为https://gitcode.com/GitHub_Trending/do/docker-icloudpd。今晚就动手吧。等哪天深夜再翻相册看到那 3 万张照片都在自家硬盘里躺着你会感谢现在这个决定。【免费下载链接】docker-icloudpdAn Alpine Linux container for the iCloud Photos Downloader command line utility项目地址: https://gitcode.com/GitHub_Trending/do/docker-icloudpd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考