群晖照片异地备份到 Unraid + Immich 相册搭建详细教程：rsync 同步与踩坑全记录

准备项目#

本文示例环境#

4.1 先开三个开关（缺一不可）#

这三条是 DSM 的硬约束：

1. SSH 登录只对 administrators 组开放——普通用户 shell 是 /sbin/nologin，连上直接 Permission denied；

2. 不开家目录服务，authorized_keys 无处安放，报 Could not chdir to home directory；

3. 不开 rsync 服务，即使走 SSH 也会报 rsync error: service disabled (code 52)。

4.2 建一个最小权限的备份账号#

在「控制面板 → 用户与群组」新建账号 backup，关键一步：把它加入 administrators 组（对应上面的硬约束 1）。有效权限再用三层锁住：共享文件夹只读、应用权限只放 rsync、SSH 来源限定。

4.3 最坑的一个：DSM 的 ACL 覆盖了 chmod#

账号建好后，部署公钥时大概率会卡在权限上——即使你把 authorized_keys 设成了 600，sshd 日志里还是报：

1
Authentication refused: bad ACL permission for file /volume1/homes/backup/.ssh/authorized_keys

根因：DSM 家目录 drwx--x--x+ 那个 + 是 synoacltool 挂的扩展 ACL，DSM 给 sshd 打了 patch 专门检查它，太宽就报 bad ACL permission。而 chmod 只改传统权限位，动不了 ACL，所以怎么 chmod 都没用。

正确解法是用 synoacltool -del 删掉 ACL，再 chmod：

1
synoacltool -del /volume1/homes/backup/.ssh/authorized_keys
2
synoacltool -del /volume1/homes/backup/.ssh
3
synoacltool -del /volume1/homes/backup
4
chmod 755 /volume1/homes/backup
5
chmod 700 /volume1/homes/backup/.ssh
6
chmod 600 /volume1/homes/backup/.ssh/authorized_keys
7
chown -R backup:users /volume1/homes/backup/.ssh

跑完验证一下，+ 号应该消失：

1
ls -la /volume1/homes/backup/.ssh/    # authorized_keys 应为 -rw-------，且无 + 号

5.1 生成密钥（注意路径）#

1
mkdir -p /boot/config/ssh
2
ssh-keygen -t ed25519 -N "" -f /boot/config/ssh/syno_pull

为什么放 /boot/config/ssh？ unRAID 的 /root 是内存盘，重启就清空，密钥放那儿会丢。/boot 是 U 盘，能持久化。

5.2 把公钥部署到群晖#

1
ssh-copy-id -i /boot/config/ssh/syno_pull.pub backup@10.x.x.20

（如果报了 ACL 相关的错，就是 4.3 那步没处理干净，回去先删 ACL。）

5.3 密钥持久化（关键一步）#

/boot 是 FAT32，权限位不持久，私钥直接放上面会是 777，被 OpenSSH 以「权限过宽」拒绝。所以正确姿势是「U 盘存源 + 开机复制到内存 + chmod」。

先装 User Scripts 插件（如果没有）：

• Unraid 网页 → Apps（Community Applications） → 搜索 User Scripts → 安装；

• 装完左侧导航栏会出现 User Scripts 入口。

然后在 User Scripts 里新建脚本（点 ADD NEW SCRIPT），运行时机选 At Startup of Array：

1
#!/bin/bash
2
mkdir -p /root/.ssh
3
cp /boot/config/ssh/syno_pull     /root/.ssh/syno_pull
4
chmod 600 /root/.ssh/syno_pull
5
ssh-keyscan 10.x.x.20 >> /root/.ssh/known_hosts 2>/dev/null

5.4 验证免密登录#

1
ssh -i /root/.ssh/syno_pull backup@10.x.x.20 "whoami"

成功的标志：直接输出 backup、不提示密码：

1
backup

如果还提示 backup@10.x.x.20's password:，说明公钥没被接受，回头查 4.3 的 ACL。

6.1 先确认群晖上的备份源路径#

命令里的 /volume1/photo/ 只是示例，你要换成自己群晖上真实的共享文件夹名。先在群晖 SSH 里看：

1
ls /volume1/

会列出所有共享文件夹，比如 photo、video、homes、docker 等，记下你要备份的那个名字，路径就是 /volume1/<文件夹名>/。

如果你想备份的是群晖「家目录」里的照片（Synology Photos 默认存这里），路径通常是 /volume1/homes/<用户名>/Photos。

6.2 先 dry-run 空跑一遍#

正式拉之前，务必先空跑，确认文件量和权限都对：

1
rsync -av --dry-run --stats \
2
  --exclude '@eaDir' --exclude '#recycle' --exclude '@tmp' \
3
  --exclude '@snapshot' --exclude '.DS_Store' --exclude 'Thumbs.db' \
4
  -e "ssh -i /root/.ssh/syno_pull -o BatchMode=yes" \
5
  backup@10.x.x.20:/volume1/photo/ /mnt/user/backup-photos/ 2>&1 | tail -10

参数逐项解释（知道含义才不会瞎改）：

--exclude '@eaDir' 一定要加：那是群晖生成的缩略图/索引目录，不排除会白拉几十万张缩略图、还干扰 Immich 扫描。#recycle、@tmp、@snapshot 同理，都是群晖的系统目录。

看末尾的 Number of files 和 Total file size，确认数量合理、没有一堆 Permission denied，就可以正式跑了。

成功的标志（实测输出示例，数字以你自己的为准）：

1
Number of files: 34,713 (reg: 28,878, dir: 5,725, link: 110)
2
Total file size: 53,988,164,580 bytes

• 文件数、总大小和你群晖上对得上 → 数量没问题；

• 没有刷屏的 Permission denied → 权限没问题；

• 然后去掉 --dry-run 正式拉。

注意：上面这个数字里 @eaDir 还没排除时会虚高（缩略图也算进去了），正式跑带上 --exclude '@eaDir' 后，真实照片数会少一大截，这是正常的。

6.3 正式拉取#

去掉 --dry-run，加上断点续传：

1
rsync -av --partial --info=progress2 \
2
  --exclude '@eaDir' --exclude '#recycle' --exclude '@tmp' \
3
  --exclude '@snapshot' --exclude '.DS_Store' --exclude 'Thumbs.db' \
4
  -e "ssh -i /root/.ssh/syno_pull -o BatchMode=yes" \
5
  backup@10.x.x.20:/volume1/photo/ /mnt/user/backup-photos/

6.4定时自动备份#

在 User Scripts 里把上面的命令包装成脚本，运行时机选 Scheduled（比如每天凌晨 3 点）。首次跑完，之后就是增量同步，只传改动的文件。

7.1 用 Docker Compose 部署（完整配置）#

先装 Docker Compose Manager 插件（如果还没有）：

• Unraid 网页 → Apps（Community Applications） → 搜索 docker compose manager → 安装；

• 装完在 插件 页面能看到它，点开就是 Compose 管理界面。

新建 stack：点 ADD NEW STACK → 名字填 immich → 点进齿轮 → EDIT STACK → 选 COMPOSE FILE，把下面这份 完整可用的 docker-compose.yml（按需进行修改）粘贴进去：

1
name: immich
2

3
services:
4
  immich-server:
5
    container_name: immich_server
6
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
7
    volumes:
8
      - ${UPLOAD_LOCATION}:/data                 # 上传目录（在 .env 里定义）
9
      - /etc/localtime:/etc/localtime:ro
10
      - /mnt/user/backup-photos:/mnt/nas_photos:ro   # 外部库：挂 rsync 同步下来的照片
11
    env_file:
12
      - .env
13
    ports:
14
      - '2283:2283'
15
    depends_on:
16
      - redis
17
      - database
18
    restart: always
19

20
  immich-machine-learning:
21
    container_name: immich_machine_learning
22
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
23
    # 想用核显加速（i5-12400 有 UHD 730），改成下面三行，见 7.5：
24
    #   image: ghcr.io/immich-app/immich-machine-learning:release-openvino
25
    #   devices: [ "/dev/dri:/dev/dri" ]
26
    #   device_cgroup_rules: [ 'c 189:* rmw' ]
27
    volumes:
28
      - model-cache:/cache
29
    env_file:
30
      - .env
31
    restart: always
32

33
  redis:
34
    container_name: immich_redis
35
    image: docker.io/valkey/valkey:9
36
    volumes:
37
      - /mnt/user/appdata/immich/redis:/data     # redis 持久化（否则重启丢任务队列）
38
    restart: always
39

40
  database:
41
    container_name: immich_postgres
42
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
43
    environment:
44
      POSTGRES_PASSWORD: ${DB_PASSWORD}
45
      POSTGRES_USER: ${DB_USERNAME}
46
      POSTGRES_DB: ${DB_DATABASE_NAME}
47
      POSTGRES_INITDB_ARGS: '--data-checksums'
48
    volumes:
49
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data   # 必须落 SSD，见 7.2 的坑
50
    shm_size: 128mb
51
    restart: always
52

53
volumes:
54
  model-cache:

配套的 .env：

1
# 上传照片的存储位置（unRAID 的用户共享路径）
2
UPLOAD_LOCATION=/mnt/user/appdata/immich/photo/
3

4
# 数据库存储位置：必须是 SSD cache 盘（见 7.2 的坑）
5
DB_DATA_LOCATION=/mnt/cache/appdata/immich/db
6

7
# Immich 版本（固定主版本，避免滚动升级出兼容问题）
8
IMMICH_VERSION=v3
9

10
# postgres 密码：改成你自己的强密码
11
DB_PASSWORD=your-strong-password
12
DB_USERNAME=postgres
13
DB_DATABASE_NAME=immich
14

15
# 国内必加：模型下载走 hf-mirror 镜像（见 7.4.1）
16
HF_ENDPOINT=https://hf-mirror.com

几个要点：

• 数据库路径用变量 DB_DATA_LOCATION，统一在 .env 里改，别在 compose 里硬编码（避免 .env 和 compose 两处路径不一致的坑）；

• 外部库挂载 /mnt/user/backup-photos:/mnt/nas_photos:ro，把 rsync 拉下来的照片只读挂进容器；

• HF_ENDPOINT 国内必加；

• IMMICH_VERSION 固定主版本（如 v3），不要用会滚动的 release，避免升级踩兼容坑。

启动：填完 compose 和 env，回到 stack 页面点 COMPOSE UP，等镜像拉取完成（第一次会拉几个 GB）。

首次初始化（第一次打开）：

1. 浏览器访问 http://unraid-ip:2283；

2. 第一次会进入 创建管理员 页面，填邮箱 + 密码（这就是你的 Immich 管理员账号，记牢）；

3. 进入后就是正式界面了。

7.2 postgres 必须落在真实 SSD 上#

compose.yml 里 database 的挂载要特别注意：

1
database:
2
  volumes:
3
    - /mnt/cache/appdata/immich/db:/var/lib/postgresql/data

问题出在 /mnt/cache 这个路径：它是 unRAID 的 cache 池（SSD）挂载点。如果你没配 SSD cache 盘，这个目录根本不存在——Docker 挂载不存在的路径时会自动创建它，创建在 unRAID 的根文件系统里，而根文件系统是内存。于是 postgres 数据全写进内存，一重启就清零，Immich 就显示「重新安装」，人脸识别、标签全没了。

修复：给 unRAID 加一块 SSD 做 cache 池（postgres 本就该在 SSD），或退而求其次把 DB 落到阵列持久化目录。核心原则：postgres 数据必须落在一个真实、持久的磁盘上。

7.3 用「外部库」管理照片#

照片已经在 /mnt/user/backup-photos/ 了，Immich 不用重新上传，直接挂成外部库只做索引。在 compose.yml 的 immich-server 服务里加一个只读挂载：

1
immich-server:
2
  volumes:
3
    - /mnt/user/backup-photos:/mnt/nas_photos:ro

改完 docker compose up -d 重启，然后在 Immich 后台：管理 → 外部库 → 创建外部库 → 导入路径填 /mnt/nas_photos。

外部库是只读索引：Immich 不改动照片原件，只建数据库索引。照片在 /mnt/user/backup-photos/，索引在 postgres——这也再次说明 postgres 必须持久化，否则索引每次重建。

7.4 开启人脸识别#

人脸识别默认就是开启的，由 immich-machine-learning 容器承担，不需要改任何配置。但外部库的照片不会自动全部处理，需要手动触发，而且顺序很关键：先检测、后识别。

1. 先扫描外部库：管理 → 外部库 → 你的库 → 扫描（Scan），让照片进库；

2. 管理 → 任务（Jobs）→ 人脸检测（Face Detection），点右侧 全部（All）；

3. 等检测跑完（Jobs 页有进度条），再点 人脸识别（Facial Recognition） 的 全部（All）；

4. 全部跑完后，到 探索（Explore）→ 人物（People），给聚类出的人脸命名，之后 Immich 会自动归类同名的人。

为什么「人脸识别显示 0」？ 因为人脸识别依赖人脸检测先跑——检测没跑，识别队列永远是 0；而照片没 scan 进库，检测又无从谈起。所以卡在 0 时，从「外部库有没有扫描」往上查。

1
Downloading detection model 'buffalo_l' ... This may take a while.
2
Failed to load detection model 'buffalo_l'. Clearing cache.
3
Attempted to clear cache for model 'buffalo_l', but cache directory does not exist

1
HF_ENDPOINT=https://hf-mirror.com

1
docker compose up -d immich-machine-learning

1
Downloading detection model 'buffalo_l' ... This may take a while.
2
Fetching 4 files: 100%|██████████| 4/4 [00:06<00:00, 1.60s/it]
3
Loading detection model 'buffalo_l' to memory
4
Loading recognition model 'buffalo_l' to memory

7.5 硬件加速（可选）：用核显 OpenVINO#

默认用 CPU 跑，几万张照片会偏慢。i5-12400 自带 UHD 730 核显，可改成 OpenVINO 加速——前提是核显没被其他虚拟机直通占用。

先确认核显可用：

1
ls /dev/dri        # 能看到 renderD128 之类即说明核显可用

改 compose（⚠️ unRAID 上 device_cgroup_rules 这行必须加，否则容器访问不到 /dev/dri）：

1
immich-machine-learning:
2
  image: ghcr.io/immich-app/immich-machine-learning:release-openvino
3
  devices:
4
    - /dev/dri:/dev/dri
5
  device_cgroup_rules:
6
    - 'c 189:* rmw'

改完拉新镜像并重启：

1
docker compose pull immich-machine-learning
2
docker compose up -d immich-machine-learning

怎么确认用上了核显？ 看 ML 日志的 execution provider：

1
docker logs immich_machine_learning 2>&1 | grep -i "execution provider"

• CPUExecutionProvider → 还在用 CPU

• OpenVINOExecutionProvider → 核显生效 ✅

成功的标志：日志里 OpenVINOExecutionProvider 排在第一位（CPU 只作为 fallback 排第二），说明核显已接管推理：

1
Setting execution providers to ['OpenVINOExecutionProvider', 'CPUExecutionProvider'], in descending order of preference

对比改造前（纯 CPU）：['CPUExecutionProvider'] —— 前后一字之差，就是核显是否生效的分水岭。

device_cgroup_rules: 'c 189:* rmw' 是给容器开放 /dev/dri（字符设备 189）的读写权限。unRAID 的 Docker 默认 cgroup 限制较严，漏了这行即使挂载了 /dev/dri 也访问不到——这是 unRAID 上特有的坑。

7.6 其他几个实用配置#

• redis 持久化：官方 compose 的 redis 默认没挂数据卷，重启会丢任务队列，建议加一行：

1
    redis:
2
      volumes:
3
        - /mnt/user/appdata/immich/redis:/data

• 最小识别人脸数：默认 3，即同一个人至少要出现 3 张脸才会被建为「人物」。若某人照片少被隐藏，可在 管理 → 设置 → 机器学习 → 人脸识别 里调低。

• 改参数 vs 换模型：只改检测阈值，重跑「人脸识别-全部」即可；换了识别模型，则要重跑「人脸检测-全部」。

• 双胞胎/相似脸：可在人脸识别设置里调低「最大识别距离」来区分。

7.7 全功能模型清单：env 不用加任何模型配置#

Immich 的机器学习功能默认全部开启，模型会自动下载，不需要在 .env 里写模型名（唯一要加的就是 7.4.1 的 HF_ENDPOINT）。各功能对应模型：

唯一建议动的：中文智能搜索换模型。默认 ViT-B-32__openai 偏英文，中文搜图（如「海边的日落」「春节鞭炮」）效果差，建议换成多语言的 XLM-Roberta 系列。

操作（在 UI 改，不是 env）：管理 → 设置 → 机器学习设置 → 智能搜索 → 模型名称里粘贴：

1
XLM-Roberta-Base-ViT-B-32__laion5b_s13b_b90k

保存后到 Jobs 页点「智能搜索 → 全部」重新建索引。内存够可上更准的 XLM-Roberta-Large-ViT-H-14__frozen_laion5b_s13b_b90k，但更吃内存（32G 还要跑 Windows VM 的话，先用 Base 版）。

⚠️ 网上常见的 CLIP_VISUAL_MODEL_NAME 等 env 变量是 MT Photos（另一个相册软件）的，不是 Immich。Immich 的模型一律在后台 UI 里改。