当前位置：

社区首页

文章详情

群晖NAS下部署 Immich 图库完整指南

适用于 Synology NAS + Docker 环境

本文基于实际部署经验撰写，重点解决中国大陆网络环境下 HuggingFace 被屏蔽导致 Machine Learning 模型无法下载的问题

环境说明
前置准备
部署 Immich 核心服务
解决 ML 模型下载问题（核心重点）
配置 Smart Search 和 Facial Recognition
可选：将 ML 服务迁移到高性能设备
常见问题排查

一、环境说明

最低要求

Synology NAS（支持 Docker / Container Manager）
DSM 7.0 以上
建议至少 4GB 内存（8GB 更佳）
足够的存储空间

本指南测试环境

Synology DS918+（Intel Celeron J3455, 4GB RAM）
Immich v3
中国大陆网络环境（HuggingFace 无法直接访问）

二、前置准备

2.1 安装 Container Manager

在 DSM 套件中心安装 Container Manager（旧版 DSM 中为 Docker 套件）。

2.2 安装 Git（可选）

在 DSM 套件中心安装 Git 套件。后续下载模型时可能用到。

2.3 使用镜像源拉取 Docker 镜像

由于 ghcr.io 在中国大陆可能无法直接访问，需要使用镜像加速。本指南使用 xuanyuan.run 镜像站，你也可以替换为其他可用的 Docker 镜像加速站点。

镜像地址对照：

提示： Docker 镜像加速站点经常变动，请搜索最新可用的 ghcr 镜像站。

三、部署 Immich 核心服务

3.1 创建项目目录

在 NAS 上通过 SSH 或 File Station 创建目录：

/volume1/docker/immich/

3.2 创建 .env 文件

# Immich 环境变量配置

UPLOAD_LOCATION=./library

DB_DATA_LOCATION=./postgres

IMMICH_VERSION=v3

DB_PASSWORD=你的数据库密码 # 请修改为强密码，仅使用 A-Za-z0-9

DB_USERNAME=postgres

DB_DATABASE_NAME=immich

# 【关键】HuggingFace 镜像站点，解决中国大陆无法访问 HuggingFace 的问题

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

⚠️ HF_ENDPOINT 是本指南最关键的配置之一。如果不设置，ML 容器将无法从 HuggingFace 下载模型。

3.3 创建 docker-compose.yml

通过 DSM Container Manager → Project → 创建项目，选择上述目录，启动即可。

或通过 SSH（需要管理员权限）：

cd /volume1/docker/immich

docker compose up -d

四、解决 ML 模型下载问题（核心重点）

⚠️ 这是在中国网络环境下部署 Immich 最容易踩坑的地方。

4.1 问题说明

Immich 的 Machine Learning 服务需要从 HuggingFace 下载 AI 模型文件。这些模型用于：

Smart Search（智能搜索）：CLIP 模型，如 XLM-Roberta-Large-Vit-B-16Plus
Facial Recognition（人脸识别）：antelopev2 模型
OCR（文字识别）：PP-OCRv5_mobile 模型

在中国大陆，huggingface.co 无法直接访问，导致模型下载失败，ML 服务无法正常工作。

4.2 方案一：通过 HF_ENDPOINT 自动下载（推荐）

在 .env 文件中设置：

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

ML 容器内的 Python huggingface_hub 库会自动使用该镜像站下载模型。

优点： 无需手动操作，容器启动后自动下载。
缺点： 首次启动较慢，需要等待模型下载完成。

4.3 方案二：手动下载模型文件

如果方案一因网络问题失败，可以通过 SSH 手动下载模型文件。

步骤 1：查询模型文件列表

通过 API 查询模型包含的文件：

# 查询 CLIP 模型文件列表

wget -q -O - "https://hf-mirror.com/api/models/immich-app/XLM-Roberta-Large-Vit-B-16Plus" | python3 -m json.tool

# 查询人脸识别模型文件列表

wget -q -O - "https://hf-mirror.com/api/models/immich-app/antelopev2" | python3 -m json.tool

也可以直接在浏览器访问：

CLIP 模型：https://hf-mirror.com/immich-app/XLM-Roberta-Large-Vit-B-16Plus/tree/main
人脸模型：https://hf-mirror.com/immich-app/antelopev2/tree/main

步骤 2：使用脚本批量下载

创建下载脚本（以 CLIP 模型 XLM-Roberta-Large-Vit-B-16Plus 和人脸模型 antelopev2 为例）：

提示： 使用 nohup 防止 SSH 断连导致下载中断：
nohup bash /tmp/download_models.sh > /tmp/download.log 2>&1 &
tail -f /tmp/download.log # 查看进度

步骤 3：验证下载完成

# 检查 CLIP 模型

du -sh /volume1/docker/immich/model-cache/clip/XLM-Roberta-Large-Vit-B-16Plus/

find /volume1/docker/immich/model-cache/clip/XLM-Roberta-Large-Vit-B-16Plus -type f | wc -l

# 检查人脸模型

du -sh /volume1/docker/immich/model-cache/facial-recognition/antelopev2/

find /volume1/docker/immich/model-cache/facial-recognition/antelopev2 -type f | wc -l

CLIP 模型约 2.6GB，人脸模型约 1.2GB。

4.4 方案三：通过 Docker 容器下载

如果 NAS 上没有 python3，可以通过临时 Docker 容器下载：

4.5 模型目录结构说明

下载完成后，model-cache 目录结构应如下：

4.6 可用CLIP某型对比

建议中文用户选择支持多语言的模型，这样可以直接用中文搜索照片，例如搜索"日落"、"海滩"、"家庭聚餐"等。

五、配置 Smart Search 和 Facial Recognition

5.1 在 Immich Web UI 中配置模型

访问 http://你的NAS_IP:2283，进入管理界面：

Administration → Settings → Machine Learning → Smart Search
- 设置模型名称为你下载的模型，例如 XLM-Roberta-Large-Vit-B-16Plus
- 点击 Save
Administration → Settings → Machine Learning → Facial Recognition
- 确认模型为 antelopev2

5.2 配置外部库排除规则

如果你导入了 NAS 上已有的照片目录，需要排除 Synology 系统生成的元数据文件夹：

Administration → External Libraries → 编辑你的外部库 → Exclusion Patterns，添加：

**/@eaDir/**

**/#recycle/**

**/#snapshot/**

**/._*

⚠️ 不设置排除规则会导致 Immich 尝试处理 Synology 的缩略图和元数据文件，大幅增加处理队列数量。

5.3 运行索引任务

建议按以下顺序执行：

先运行 Smart Search
- Administration → Jobs → Smart Search → 点击 All
- 建议 concurrency 设为 3
- 完成后即可使用搜索功能
再运行 Face Detection
- Administration → Jobs → Face Detection → 点击 All
- 建议 concurrency 设为 3
Face Recognition 自动执行
- 人脸检测完成后自动开始
- concurrency 固定为 1，无法修改