在威联通 QNAP NAS 上安装 iCloudPD 和 Immich 照片下载和管理等服务

2026·04·22

软件作用介绍

由于手机照片太多了 99G 占用过多空间，需要删除部分，但是又不方便在线查看和备份，网上寻找解决方案，发现这个方案很不错。

拍摄的视频和照片都通过 iCloud 自动同步到云端，再通过 icloudpd 下载到 NAS 本地存储，这种方式存储到照片好像不是 Live Photos 会拆分成照片和视频保存。
进入相册整理，将目前不需要的照片删除，并将最新拍摄的照片和视频保存到电脑，自动同步到 OneDrive 后自动备份到家中 NAS 本地进行存储，这种方式可以保存原始数据照片信息。

iCloudPD 本质就是一个“下载工具”，专门把你 iCloud 里的照片和视频同步到本地（比如 NAS）。它不负责管理、不提供界面，就是定时帮你把数据拉下来，变成你自己能掌控的文件，更多是解决备份和数据归属的问题。

Immich 则是一个“照片管理系统”，类似自己搭一个 iCloud 相册。它负责把这些照片整理成时间轴、相册，支持搜索、人脸识别、地图等功能，让你在本地也能有接近 iCloud / Google Photos 的使用体验。简单理解，一个负责“拉数据”，一个负责“用数据”。

Container Station 安装

设备是我一直在用的一台 NAS：

型号：TS-532X
CPU：Annapurna Labs AL324
内存：8GB
系统：QTS 5.2.8

平时主要跑一些 Docker 服务，都是通过 Container Station 管理的。

Immich 安装

配置文件

docker-compose.yml

注意：2026年的 Docker Compose 规范已不再强制要求写 version 字段

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release  # 获取 2026 年 4 月最新的稳定版程序
    container_name: immich_server
    network_mode: "host"                             # 开启 Host 模式：容器直接使用 NAS 的 IP。大幅提升局域网照片同步性能。
    environment:
      - PUID=1000                                    # 运行用户 ID：建议对应威联通中对 /share/Container 有权限的用户
      - PGID=1000                                    # 运行组 ID
      - TZ=Asia/Shanghai                             # 强制时区，确保照片快照和日志时间显示正确
      
      # --- 数据库与缓存连接 (Host 模式关键逻辑) ---
      - DB_HOSTNAME=127.0.0.1                        # 因为是 Host 模式，容器间通信必须使用 127.0.0.1（本地回环）
      - DB_USERNAME=postgres
      - DB_PASSWORD=postgres
      - DB_DATABASE_NAME=immich
      - DB_PORT=5432                                 # 占用 NAS 真实的 5432 端口，请确保 App Center 中没开其他 PG 数据库
      - REDIS_HOSTNAME=127.0.0.1
      - REDIS_PORT=6379                              # 占用 NAS 真实的 6379 端口
      
      # --- 机器学习服务 API 地址 ---
      # Host 模式下 Server 无法通过容器名找到 ML，必须显式指向本地的 3003 端口
      - IMMICH_MACHINE_LEARNING_URL=http://127.0.0.1:3003
      
      - UPLOAD_LOCATION=/usr/src/app/upload          # 容器内部逻辑路径（严禁随意修改）
      - IMMICH_WATCH_FOLDERS=/mnt/Photos             # 外部图库监控入口
      
    volumes:
      # 主存储：Immich 手动上传的照片存放在此处。:z 用于处理可能的权限锁
      - /share/Container/immich/upload:/usr/src/app/upload:z
      # 外部库：挂载 NAS 已有的 iCloud 备份文件夹。:ro 表示只读，Immich 绝不会删除你的原始文件
      - /share/iCloud:/mnt/Photos:ro
      - /etc/localtime:/etc/localtime:ro
      # 地理数据汉化：将离线地图标签和多国语言包注入，解决地图显示和反向地理编码问题
      - /share/Container/immich/geodata:/build/geodata
      - /share/Container/immich/geodata/i18n-iso-countries/langs:/usr/src/app/node_modules/i18n-iso-countries/langs
      # 核显直通：调用 Intel/AMD 核显进行视频转码硬件加速，避免 CPU 飙升至 100%
      - /dev/dri:/dev/dri
    depends_on:
      - redis
      - database
    restart: unless-stopped

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:release
    container_name: immich_machine_learning
    network_mode: "host"
    environment:
      - DB_HOSTNAME=127.0.0.1
      - DB_USERNAME=postgres
      - DB_PASSWORD=postgres
      - DB_DATABASE_NAME=immich
    volumes:
      # 模型缓存：存放人脸识别和语义搜索下载的模型（约几百MB到数GB），防止容器重启后重复下载
      - /share/Container/immich/model-cache:/cache
    restart: unless-stopped

  redis:
    # 官方代际更替：Immich 已弃用 Redis 转向 Valkey。Valkey 8 在内存管理和速度上更适应 2026 年的高并发扫描
    image: docker.io/valkey/valkey:8-alpine
    container_name: immich_redis
    network_mode: "host"
    restart: unless-stopped

  database:
    # --- 解决 vchord 报错的关键镜像 ---
    # 1. 保持 PG14：避免跨大版本（14 升 16）导致的数据目录不可读。
    # 2. 包含 vectorchord 0.4.3：Immich v2.7.x 强制要求的最新搜索扩展。
    # 3. 包含 pgvectors：兼容旧版索引，实现启动时的全自动平滑数据迁移。
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    container_name: immich_postgres
    network_mode: "host"
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=immich
    volumes:
      # 数据库文件持久化：NAS 真实的数据存放位置
      - /share/Container/immich/postgres:/var/lib/postgresql/data
    restart: unless-stopped

Host 模式是核心前提

这套配置全部基于 network_mode: host，这带来两个直接影响：

容器之间不能用服务名通信（比如 redis、database 会失效）
所有连接必须写成：

127.0.0.1

所以这里这些配置是必须的：

DB_HOSTNAME=127.0.0.1
REDIS_HOSTNAME=127.0.0.1
IMMICH_MACHINE_LEARNING_URL=http://127.0.0.1:3003

这一点错了，服务直接起不来。

端口冲突必须提前排查

因为 Host 模式是直接占用 NAS 端口，所以这几个端口必须保证“干净”：

5432（PostgreSQL）
6379（Redis / Valkey）
3003（机器学习服务）

如果 NAS 自带这些服务（QNAP 很常见），要先关掉，否则就是：

容器能启动，但服务不可用 / 反复重启

数据库镜像是关键

这里用了：

postgres:14 + vectorchord + pgvectors

这其实是为了避免两个坑：

不能随便升 PostgreSQL 大版本（14 → 16 会直接崩）
Immich 新版强依赖 vectorchord

结论就是一句话：

不要乱换数据库镜像
不要手动升级 PG 版本
数据目录 /postgres 一定要保留好

不然就是“库还在但启动不了”。

iCloud 目录挂载方式

这一段其实是这套方案的精髓：

/share/iCloud → /mnt/Photos:ro

关键点：

:ro（只读）必须保留
Immich 只“读 + 建索引”，不会动原文件

这意味着：

iCloudPD = 数据源 Immich = 索引 + 展示层

两者完全解耦，安全性很高。

IMMICH_WATCH_FOLDERS 才是自动入库核心

IMMICH_WATCH_FOLDERS=/mnt/Photos

这个变量决定了：

Immich 会自动扫描 iCloud 下载的照片
不需要手动上传

但要注意：

新照片不是“实时”，是周期扫描
大量照片第一次导入会非常慢（正常现象）

硬件加速是否生效看这一条

/dev/dri:/dev/dri

这一步决定：

视频转码走 GPU（核显）
还是 CPU 直接拉满 100%

如果你发现：

CPU 一直 100%

基本就是：

NAS 不支持
或权限没给对

模型缓存必须持久化

/model-cache:/cache

这个目录的作用：

存人脸识别、CLIP 模型（几百 MB ~ 几 GB）

如果不做持久化：

每次重启 = 重新下载模型

体验会非常差。

权限问题的本质

你设置了：

PUID=1000
PGID=1000

核心目的就一个：

让 Immich 写入的文件，宿主机也能正常访问

否则常见问题是：

文件存在，但 NAS 看不到 / 无法删除

iCloudPD 安装

安装配置记录

网络选择：host

这套环境其实不复杂，核心就两个目录：

/config：用来存 iCloud 登录相关的数据（cookie、配置）
/iCloud：实际下载下来的照片目录

我这边是直接映射到 NAS：

/Container/icloudpd → /config
/iCloud → /iCloud

权限都给可写，避免后面同步时报错。

容器的环境变量基本就几个关键的：

TZ=Asia/Shanghai（时区）
PUID=1000
PGID=1000
用户组用 administrators

这一步主要是避免文件权限问题，不然后面生成的照片可能宿主机访问不了。

初始化

第一次需要手动做一次认证：

sync-icloud.sh --Initialize

或者直接用 icloud 用户执行：

su - icloud -c "icloudpd --username '你的AppleID' --cookie-directory /config --auth-only"

本质就是生成一份 MFA cookie，后面同步都会用这个。

开始同步

认证完成之后，直接跑：

sync-icloud.sh

容器就会开始把 iCloud 里的照片往 /iCloud 目录同步。

一些细节

/config 下面会生成配置文件：icloudpd.conf
XDG_DATA_HOME 也是指向 /config
.mounted 文件是正常的挂载标记，不用管