NAS 部署 Immich 照片管理系统实战：从 Docker Compose 到 AI 智能分类

如果你想把手机里的照片和视频从商业云相册迁回自己的 NAS，Immich 是一个比较适合动手实践的方案。它通过 Docker Compose 运行，照片文件、数据库和机器学习模型分别由不同服务管理，既能提供时间轴浏览、手机自动备份，也能使用人脸识别和物体搜索等功能。

不过，Immich 并不是“装好容器就完成”。真正容易出问题的地方通常集中在三个方面：.env 中的路径没有规划好、照片目录映射错误，以及数据库和原始照片没有独立备份。下面以 NAS 上已经具备 Docker 和 Docker Compose 环境为前提，梳理一套比较稳妥的部署方法。

部署前先规划目录和硬件

Immich 的标准 Docker Compose 部署通常包含四类服务：

• immich_server：负责网页端、API 和主要业务逻辑。
• immich_machine_learning：负责缩略图相关的机器学习任务、人脸识别和智能搜索。
• immich_redis：负责缓存和任务队列。
• immich_postgres：负责保存用户、相册、识别结果等数据库信息。

照片文件和数据库文件不要混在同一个目录中。可以先在 NAS 上规划类似这样的目录：

/docker/immich/
├── compose.yaml
├── .env
├── postgres/
└── model-cache/

/data/photos/immich-library/

这里的 /docker/immich 用于保存 Compose 配置、数据库和模型缓存，/data/photos/immich-library 用于保存 Immich 管理的照片和视频。

如果 NAS 支持多个存储卷，建议把数据库放在响应较快、稳定性较好的本地存储上，把照片库放在容量更大的存储卷上。数据库目录不建议直接放在普通网络共享目录中，网络存储中断或权限异常可能导致数据库启动失败，甚至增加数据损坏风险。

先备份原照片目录

在创建容器之前，先对原照片目录做一次完整备份。至少要保留一份不由 Immich 管理的原始副本，最好再有一份位于不同存储设备上的备份。

原因很简单：Docker 的卷映射不会自动帮你保护文件。如果把宿主机目录写错，或者把一个空目录映射到了容器的照片目录，程序可能会表现为“照片消失”；如果在排查过程中执行了错误的清理操作，风险会进一步扩大。

部署前重点确认以下内容：

• 原照片目录的真实绝对路径。
• NAS 上运行 Docker 的用户是否有读取和写入权限。
• 照片目录是否包含原始文件，还是只有缩略图或同步缓存。
• Immich 的库目录与原始照片目录是否打算分开管理。
• 数据库目录是否位于本地可靠存储，而不是临时目录或不稳定的网络挂载点。

如果只是想让 Immich 管理新上传的照片，可以让 Immich 使用独立的库目录，再通过导入功能处理旧照片。不要在还没有备份的情况下，直接把唯一一份原照片目录作为容器的可写目录。

判断 NAS 是否适合运行 Immich

Immich 的普通网页和手机备份功能，对硬件要求并不算苛刻；真正容易产生资源压力的是缩略图生成、视频处理和机器学习任务。

搜索资料中提到，部署通常需要支持 amd64 或 arm64 的处理器、Docker Compose 环境，以及至少约 6GB 内存，8GB 以上会更宽裕。不同 NAS 系统、容器版本和照片数量会影响实际占用，因此不要把这些数字理解成所有场景下的绝对门槛。

CPU 资源怎么判断

如果照片库规模较小，普通多核 CPU 通常可以完成机器学习任务，只是首次建立索引、生成缩略图和进行人脸识别时会比较慢。资料中也明确提到，机器学习容器默认使用 CPU，面对数万张照片时，处理速度可能明显下降。

可以按下面的思路判断：

• 只是备份手机照片，偶尔浏览：双核或低功耗处理器也可能够用，但首次整理需要耐心等待。
• 照片数量较多，需要人脸识别和智能搜索：建议选择多核 CPU，并预留足够的内存。
• 还要同时运行虚拟机、媒体服务或其他 Docker 容器：不要只看 Immich 的最低需求，要为后台任务预留资源。
• 使用较老的 amd64 设备：需要留意机器学习容器对处理器指令集的要求，部分容器版本可能要求支持 x86-64-v2。

机器学习任务通常不是持续满载，而是在首次扫描、重新索引或批量导入时集中消耗 CPU。可以先让 Immich 完成一小部分照片的识别，观察 NAS 的温度、负载和响应情况，再决定是否扩大任务规模。

GPU 是否必要

GPU 不是运行 Immich 的必需条件。没有 GPU 时，机器学习容器可以使用 CPU 完成识别，只是处理大量照片时速度较慢。

如果 NAS 具备可用的集成显卡、独立显卡或其他硬件加速设备，可以进一步研究 Immich 当前版本支持的机器学习加速方式。但这里有几个前提：

1. NAS 的硬件必须能够被 Docker 容器访问。
2. NAS 系统和容器运行时需要具备对应的设备透传能力。
3. 机器学习镜像、驱动和加速后端必须匹配。
4. 开启硬件加速后，仍然要实际观察识别速度和稳定性。

因此，不建议为了部署 Immich 盲目购买显卡。对于家庭照片库，先使用 CPU 完成部署更稳妥；当照片规模较大、CPU 处理时间确实无法接受，再根据 NAS 的硬件平台研究 GPU 或其他加速方案。

准备 Docker Compose 文件

Immich 的 Compose 文件会随版本变化，建议使用与当前版本匹配的官方 Compose 配置作为基础，不要直接套用来源不明的旧文件。不同版本可能会更换镜像标签、数据库镜像或环境变量，手工拼接旧配置容易造成服务无法启动。

标准部署至少会涉及以下几个服务名称：

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server
    depends_on:
      - redis
      - database
    volumes:
      - ${UPLOAD_LOCATION}:/data
    env_file:
      - .env

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning
    volumes:
      - model-cache:/cache
    env_file:
      - .env

  redis:
    image: valkey/valkey
    env_file:
      - .env

  database:
    image: ghcr.io/immich-app/postgres
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    env_file:
      - .env

volumes:
  model-cache:

这段配置用于说明服务之间的关系和卷映射方式，实际部署时应以对应版本的官方 Compose 文件为准。尤其是数据库镜像、环境变量名称、健康检查和启动依赖，不要因为网上的旧教程看起来可以运行，就随意删改。

配置 .env 环境变量

.env 是这套部署中最值得认真检查的文件。它通常用于保存照片库路径、数据库路径、数据库用户名、数据库密码、时区和版本标签等信息。

一个简化的配置示例可以是：

UPLOAD_LOCATION=/data/photos/immich-library
DB_DATA_LOCATION=/docker/immich/postgres

DB_USERNAME=immich
DB_PASSWORD=请替换为较强的数据库密码
DB_DATABASE_NAME=immich

TZ=Asia/Shanghai
IMMICH_VERSION=release

其中最重要的是两个路径：

UPLOAD_LOCATION=/data/photos/immich-library
DB_DATA_LOCATION=/docker/immich/postgres

UPLOAD_LOCATION 是照片和视频等媒体文件的存储位置，DB_DATA_LOCATION 是数据库文件的位置。两者不能写成同一个目录，也不建议把数据库目录放到照片库内部。

路径配置中的常见错误

使用了 NAS 图形界面显示的别名路径

有些 NAS 会在文件管理器中显示类似“共享文件夹/照片”的路径，但 Docker 实际需要的是宿主机能够识别的真实路径。图形界面中的显示名称不一定等于容器运行时使用的绝对路径。

部署前可以在 NAS 的终端中确认目录是否真实存在：

ls -la /data/photos/immich-library
ls -la /docker/immich

如果命令返回目录不存在，不要直接运行 Compose。先确认共享文件夹挂载位置、Docker 项目目录和实际文件系统路径。

把相对路径放在不确定的位置

下面这种写法本身不一定错误：

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres

但它依赖于 Compose 项目的当前目录。你从不同路径执行命令，或者通过 NAS 管理界面启动项目时，实际目录可能与预期不一致。

对于照片库和数据库，使用明确的绝对路径更容易排查问题。

把宿主机路径和容器路径混淆

在 Compose 中，冒号左侧是 NAS 宿主机路径，右侧是容器内部路径：

volumes:
  - /data/photos/immich-library:/data

这表示 NAS 上的 /data/photos/immich-library 被挂载到容器内的 /data。Immich 容器内部只认识 /data，不会直接认识 NAS 的真实路径。

修改路径后，要同时检查 .env 和 Compose 文件是否引用了同一个变量。不要一处使用 /data/photos，另一处又手工写成 /volume1/photos，否则很容易出现上传位置和扫描位置不一致。

启动并检查容器

进入 Compose 文件所在目录后，先检查配置是否能够被解析：

docker compose config

如果这里已经出现变量缺失、缩进错误或路径异常，不要继续启动。确认无误后再创建容器：

docker compose up -d

查看容器状态：

docker compose ps

如果某个服务没有正常运行，优先查看日志：

docker compose logs --tail=100 immich-server
docker compose logs --tail=100 immich-machine-learning
docker compose logs --tail=100 database

不同 Compose 文件中的服务名称可能略有差异，以实际配置为准。

首次启动时，数据库初始化、模型缓存创建和服务健康检查都可能需要一定时间。不要因为网页暂时打不开，就连续重复执行删除和重建操作。先看容器状态和日志，确认是路径权限、数据库初始化、镜像拉取，还是端口冲突。

初次登录后的检查顺序

服务启动后，可以按以下顺序检查：

1. 打开 Immich 管理页面，确认管理员账号可以正常登录。
2. 查看管理设置中的存储位置，确认库目录指向预期位置。
3. 只上传少量测试照片和视频。
4. 在 NAS 上检查照片是否实际写入 UPLOAD_LOCATION 对应目录。
5. 删除一张测试照片，确认应用内的删除行为不会影响原始备份目录。
6. 再开始导入或备份大量照片。

测试阶段不要直接使用唯一的原始照片库。先用复制出来的测试目录验证路径和权限，能够显著降低误操作风险。

处理已有照片和手机自动备份

如果你已经有一批存放在 NAS 上的照片，建议先明确“导入”和“直接挂载”是两种不同思路。

直接把已有照片目录映射给容器，虽然看起来简单，但会让应用对这批文件的管理边界变得模糊。路径权限、文件变更和删除行为都需要额外确认。更稳妥的做法是先保留原始目录，再将副本导入 Immich 的库中，或者按照当前版本支持的外部库方式配置只读访问。

手机自动备份则应该使用单独的测试账号或测试设备先验证。确认照片上传位置、重复文件处理、视频上传和断点续传都符合预期后，再让家庭成员批量开启自动备份。

要特别注意：Immich 的“手机端已经显示上传完成”，不等于 NAS 已经完成备份。照片真正写入磁盘、数据库记录正常、容器重启后仍然能够读取，才算部署链路完整。

反向代理与 HTTPS 设置

如果只在家庭局域网内使用，可以先通过 NAS 的局域网地址访问 Immich，等容器和存储都稳定后再配置反向代理。

反向代理的基本结构是：

手机或浏览器
    ↓ HTTPS
反向代理
    ↓ 局域网 HTTP
Immich 服务容器

反向代理通常需要完成以下工作：

• 将一个域名或内网域名指向反向代理。
• 将请求转发到 Immich 服务暴露的端口。
• 配置 HTTPS 证书。
• 保留较大的上传请求能力。
• 支持长连接或 WebSocket，避免网页端和移动端出现连接异常。
• 确认代理不会因为上传时间较长而过早断开请求。

Immich 服务端默认使用 2283 端口这一事实在相关资料中有所体现，但具体端口映射仍应以你使用的 Compose 文件为准。如果 Compose 没有把端口发布到 NAS 主机，反向代理可能需要与 Immich 容器处于同一个 Docker 网络中，而不是直接访问宿主机端口。

反向代理配置完成后，不要只测试首页。至少要实际验证：

• 浏览器能否登录。
• 手机客户端能否连接。
• 小照片和大视频能否上传。
• 缩略图是否正常显示。
• 在外网环境下连接是否稳定。
• 代理重启后服务是否仍然可用。

不要直接把数据库、Redis 或机器学习服务暴露到公网。对外提供访问的入口应该只有反向代理，其他内部服务保持在 Docker 网络或 NAS 内网中。

AI 智能识别的实际运行方式

Immich 的人脸识别和智能搜索主要由 immich-machine-learning 容器处理，模型文件会使用缓存卷保存。配置中应保留类似的模型缓存映射：

volumes:
  - model-cache:/cache

模型缓存放在持久化卷中，可以减少容器重建后重复准备模型的情况。这个目录不等同于照片库，也不等同于数据库，三者最好分开管理。

首次导入大量照片时，Immich 可能同时进行缩略图生成、视频处理、人脸识别和智能索引。此时 NAS 负载升高是正常现象，但如果网页和文件服务长时间无响应，就应当降低并发任务或分批导入。

没有 GPU 时，可以先让机器学习容器使用 CPU。判断是否需要加速，不要只看某一时刻的 CPU 百分比，而要观察：

• 首次识别是否在可接受时间内完成。
• NAS 是否影响其他服务的正常使用。
• 批量导入时是否经常触发内存不足。
• 视频处理和缩略图生成是否与机器学习任务互相争抢资源。

如果之后需要启用 GPU，不要直接复制其他平台的参数。群辉、威联通、飞牛以及自建 Linux 主机的设备透传方式并不完全相同，必须先确认主机驱动、Docker 运行时和 Immich 当前版本的支持情况。

数据库、照片和配置的备份策略

Immich 至少包含三类需要考虑的数据：

1. 照片和视频等媒体文件。
2. PostgreSQL 数据库文件。
3. Compose 文件、.env 和模型缓存。

其中，模型缓存可以在必要时重新生成，但照片文件和数据库不能只依赖容器本身。容器删除后，是否能恢复，取决于这些数据是否位于独立的持久化目录中。

备份时不要只备份照片目录。数据库中保存了用户、相册、识别结果以及其他管理信息；如果只有照片而没有数据库，重新部署后可能需要重新扫描和建立索引，原有的组织关系也未必能够完整恢复。

建议至少保留：

/docker/immich/compose.yaml
/docker/immich/.env
/docker/immich/postgres/
/data/photos/immich-library/

备份 .env 时要注意其中包含数据库密码等敏感信息，不要把它随意上传到公开代码仓库或发送到不可信的位置。

如果使用 NAS 的快照或同步功能，也要确认它是否真正覆盖了数据库目录，并且不会在数据库写入过程中制造不一致的副本。重要照片最好再保留一份不与 NAS 同时断电、损坏或被加密影响的备份。

常见故障排查

容器启动后反复重启

先查看对应服务日志，不要直接删除容器。重点检查：

• .env 中是否缺少必要变量。
• 数据库目录是否可写。
• 数据库密码前后是否一致。
• 使用的镜像和 Compose 文件是否属于匹配版本。
• NAS 是否存在内存不足或存储空间不足。

页面能打开，但照片上传失败

这类问题通常与上传路径、权限或反向代理有关。先在容器内确认 /data 是否可写，再检查 NAS 宿主机上的目录是否真的出现新文件。

如果局域网访问正常、反向代理访问失败，重点查看代理的上传大小限制、请求超时和长连接配置。

照片目录突然变空

先不要执行清理、重建或重新导入。检查 .env 中的 UPLOAD_LOCATION 是否改变，再确认当前运行的 Compose 项目目录是否正确。

如果应用只是显示为空，照片可能仍然存在于原来的宿主机目录中。使用 ls 检查实际路径，比在网页端反复刷新更有意义。只要原始备份还在，就可以重新修正映射后再处理。

AI 识别很慢

先区分是模型识别慢、缩略图生成慢，还是数据库和存储响应慢。没有 GPU 时，CPU 处理大量照片本来就可能需要较长时间。

可以先暂停其他大规模导入任务，观察机器学习容器的资源使用情况。若 NAS 同时运行多个高负载服务，应考虑错峰执行，而不是直接提高所有任务的并发量。

一套更稳妥的部署顺序

实际操作时，建议按照下面的顺序进行：

1. 备份原照片目录。
2. 确认 NAS 的 Docker、Compose 和 CPU 架构。
3. 为照片、数据库和模型缓存分别规划目录。
4. 准备与当前版本匹配的 Compose 文件。
5. 修改 .env 中的绝对路径、数据库密码和时区。
6. 使用 docker compose config 检查配置。
7. 先启动容器，不要立即导入全部照片。
8. 上传少量测试文件并核对宿主机实际落盘位置。
9. 确认局域网访问、重启恢复和数据库状态正常。
10. 再配置反向代理和 HTTPS。
11. 最后分批导入旧照片，并观察 CPU、内存和存储负载。

Immich 的核心并不是把几个容器启动起来，而是让照片目录、数据库目录、备份策略和外部访问边界都清晰可控。只要在部署前把路径和备份做好，即使后续需要更换 NAS、调整机器学习配置或重新创建容器，也不会因为一次卷映射错误而丢失唯一的照片原件。