Docker部署iCloud照片同步服务（icloudpd）通用教程

康师傅阿伦

Docker部署iCloud照片同步服务（icloudpd）通用教程

本教程基于镜像，详细介绍如何通过Docker Compose部署iCloud照片同步服务，特别适配中国区iCloud用户，包含完整配置流程、常见故障解决方案及后期维护方法，网上搜了些教程都不能正确配置，借助ai搞定了，顺便总结分享一下，新手不专业，不对的地方希望大佬指教。

一、前置准备

1.1 环境要求

• 已安装Docker及Docker Compose

1.2 核心目录规划

建议采用「配置文件与数据分离」的目录结构，可以手动先把文件夹建好，便于维护：

目录路径	用途	权限要求
/vol2/1000/docker/icloudpd	存储docker-compose.yml及配置文件	当前用户可读写（UID/GID通常为1000:1001）
/vol2/1000/Photos/iCloud	存储同步的iCloud照片/视频	与容器内用户权限一致

1.3 权限配置（关键步骤）

避免Docker权限问题，提前配置目录权限（这个似乎很有必要，之前一直在这里出错）：

# 创建核心目录
sudo mkdir -p /vol2/1000/docker/icloudpd /vol2/1000/Photos/iCloud

# 设置权限（替换1000:1001为你的UID:GID，可通过id命令查询）
sudo chown -R 1000:1001 /vol2/1000/docker /vol2/1000/Photos

# （可选）将当前用户加入docker组，避免每次使用sudo
sudo usermod -aG docker $USER
newgrp docker  # 立即生效

二、核心配置（docker-compose.yml）

在 /vol2/1000/docker/icloudpd目录下创建配置文件（docker-compose界面手动操作），适配中国区iCloud的关键配置已标注：

services:
  icloudpd:
    container_name: icloudpd  # 容器名称，便于管理
    environment:
      # 基础配置
      - TZ=Asia/Shanghai  # 时区，确保日志时间准确
      - apple_id=your_icloud@icloud.com  # 替换为你的iCloud账号
      - authentication_type=MFA  # 中国区iCloud必须用MFA，国际版可用2FA
      - user_id=1000  # 与宿主机UID一致，避免权限问题
      - group_id=1001  # 与宿主机GID一致
    
      # 中国区适配（核心）
      - icloud_china=true  # 启用中国区iCloud连接
      - auth_china=true  # 中国区专属认证流程
    
      # 同步策略
      - download_path=/iCloud  # 容器内存储路径，与挂载对应
      - synchronization_interval=86400  # 同步间隔（秒），86400=24小时
      - folder_structure={:%Y/%m}  # 照片目录结构（年/月），可自定义
      - auto_delete=false  # 禁止自动删除云端文件
      - convert_heic_to_jpeg=true  # 自动将HEIC转为JPEG（可选）
    
      # 下载选项
      - download_videos=true  # 同步视频
      - skip_existing=true  # 跳过已存在文件，避免重复下载
    image: boredazfcuk/icloudpd:latest  # 最新镜像
    healthcheck:
      test: /usr/local/bin/healthcheck.sh
      start_period: 30s  # 启动后30秒再检查健康状态
    restart: always  # 异常退出时自动重启
    volumes:
      - icloudpd_config:/config  # Docker卷，存储认证信息和配置
      - /vol2/1000/Photos/iCloud:/iCloud  # 宿主机目录挂载到容器

volumes:
  icloudpd_config:  # 命名卷，持久化存储认证数据

三、部署与初始化流程

3.1 启动容器

cd /vol2/1000/docker/icloudpd  # 进入配置目录
docker compose up -d  # 后台启动容器

首次启动会自动拉取镜像(可以手动在docker-compose里启动)，耐心等待即可。可通过 docker compose ps查看容器状态，显示 Up表示启动成功。

3.2 关键步骤：初始化认证（必做）

容器启动后需完成iCloud认证，否则无法同步，这是解决「密钥环文件缺失」的核心操作（用shh命令）：

# 执行初始化命令，进入交互式认证
docker exec -it icloudpd sync-icloud.sh --Initialise

按以下流程完成认证：

1. 输入iCloud账号密码（输入时无明文显示，输完回车即可）；
2. 苹果设备（iPhone/iPad/Mac）会收到MFA验证码提示；
3. 在终端输入收到的6位验证码，回车确认；
4. 看到「Authentication completed successfully」表示认证成功。

3.3 验证挂载有效性

容器会检查挂载目录是否可用，若出现「Failsafe file /iCloud/.mounted not present」错误，执行以下命令修复：

# 在宿主机创建挂载验证文件
touch /vol2/1000/Photos/iCloud/.mounted
chown 1000:1001 /vol2/1000/Photos/iCloud/.mounted  # 权限与目录一致

四、常见故障与解决方案

4.1 权限相关错误

• ：permission denied while trying to connect to Docker daemon：当前用户无Docker权限，执行 sudo usermod -aG docker $USER后重新登录终端，或临时用 sudo docker compose命令。
• ：su: unknown user iclouduser：容器内用户未创建，在docker-compose.yml中添加启动命令自动创建用户：entrypoint: > sh -c "addgroup -g 1001 icloudgroup && `` adduser -D -u 1000 -G icloudgroup iclouduser && exec sync-icloud.sh"

4.2 认证相关错误

• ：Keyring file /config/python_keyring/keyring_pass.cfg does not exist：未完成初始化认证，重新执行 docker exec -it icloudpd sync-icloud.sh --Initialise完成MFA验证。
• ：Apple ID not set：环境变量中apple_id配置错误，检查docker-compose.yml中账号是否正确，修改后执行 docker compose up -d --force-recreate重建容器。

4.3 挂载相关错误

• ：Failsafe file /iCloud/.mounted file is not present：参考3.3节，在宿主机挂载目录创建验证文件并配置正确权限。
• ：照片同步后宿主机无文件 ：检查docker-compose.yml中挂载路径是否正确（冒号前后无空格），权限是否为1000:1001，可通过 ls -la /vol2/1000/Photos/iCloud确认权限。

4.4 镜像相关错误

• ：bash: executable file not found in $PATH：该镜像基于Alpine Linux，无bash环境，所有命令改用sh，例如 docker exec -it icloudpd sh。

五、后期维护与常用操作

5.1 查看同步状态与日志

# 实时查看同步日志（按Ctrl+C退出）
docker compose logs -f

# 查看容器基本状态
docker compose ps

# 查看已同步文件数量
ls -la /vol2/1000/Photos/iCloud/* | wc -l

5.2 手动触发同步

默认24小时自动同步，如需立即同步：

docker exec -it icloudpd sync-icloud.sh

5.3 修改配置与重启

# 编辑配置文件
nano /vol2/1000/docker/icloudpd/docker-compose.yml

# 重启容器使配置生效
docker compose down && docker compose up -d

5.4 备份与迁移

• 照片数据：直接备份 /vol2/1000/Photos/iCloud目录即可；
• 认证配置：Docker卷 icloudpd_config存储认证信息，可通过 docker volume inspect icloudpd_config查看存储路径并备份。

六、注意事项

   1. 中国区iCloud必须配置`icloud_china=true`和`auth_china=true`，否则无法连接；       2. MFA验证码有效期较短，认证时需确保苹果设备在手边；       3. 首次同步大量照片时，建议在非高峰时段执行，避免网络拥堵；       4. 不要随意删除`icloudpd_config`卷，否则会丢失认证信息，需重新完成MFA验证；       5. 定期通过`docker compose pull`更新镜像，获取最新功能和bug修复。   

七、总结

本教程核心围绕「权限配置-容器启动-认证初始化-故障排查」四个环节，其中和是部署成功的关键。中国区用户需特别注意专属配置项，避免因区域问题导致连接失败。按照流程操作后，服务会自动在后台运行，每天同步iCloud照片至本地，实现数据备份与管理的自动化。