在威联通 QNAP NAS 上安装 iCloudPD 和 Immich 照片服务
软件作用
iCloudPD 本质就是一个“下载工具”，专门把你 iCloud 里的照片和视频同步到本地（比如 NAS）。它不负责管理、不提供界面，就是定时帮你把数据拉下来，变成你自己能掌控的文件，更多是解决备份和数据归属的问题。
Immich 则是一个“照片管理系统”，类似自己搭一个 iCloud 相册。它负责把这些照片整理成时间轴、相册，支持搜索、人脸识别、地图等功能，让你在本地也能有接近 iCloud / Google Photos 的使用体验。简单理解，一个负责“拉数据”，一个负责“用数据”。
Docker 的配置文件（YAML）
docker-compose.yml
注意：2026年的 Docker Compose 规范已不再强制要求写 version 字段
Immich 配置文件
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