NAS 中的照片和视频已经按目录保存，但逐层打开文件夹查看并不方便。这次使用 Immich 提供统一的浏览入口：原文件继续留在挂载分区中，通过外部资源库建立索引，在页面中查看照片和播放视频。

部署沿用前文的目录规划，应用数据与数据库放在 SSD 上，已有媒体目录以只读方式挂载。immich-server 使用 UID 1000、GID 2000 运行，与 docker-nas 共享组对应。

为什么选择 Immich

这里需要的是照片与视频的浏览体验，而不只是文件列表。Immich 可以扫描已有媒体、提取元数据、生成缩略图，并按时间线展示内容；视频还可以生成用于播放的转码版本，具体兼容性取决于源文件、浏览器与转码配置。

Immich 需要数据库、后台任务和额外的缩略图空间，并不是最轻量的文件浏览器。本例以现有配置为基础，只部署服务端、Valkey 和 PostgreSQL，不部署机器学习服务。

目录结构与界面展示的区别

已有文件可能按下面的方式归档：

图片/
└── 用户A/
    ├── 2025/
    │   └── 12/
    │       └── 图片1.jpg
    └── 2026/
        └── 10/
            └── 图片2.jpg

把“用户A”作为外部资源库的导入路径，可以递归索引下方的年月目录，原文件不需要移动。

Immich 官方目前没有将外部资源库目录自动转换为相册的机制。因此，无法自动化实现期望的功能。需要手动创建相册，也可以在扫描完成后手动整理。参见 外部资源库与相册的官方说明 。

准备目录

mkdir -p /mnt/ssd/docker/compose/immich
mkdir -p /mnt/ssd/docker/data/immich/{data,postgres}
sudo chown -R 1000:2000 /mnt/ssd/docker/data/immich/data
宿主机目录 容器目录 用途
/mnt/ssd/docker/data/immich/data /data 上传文件、缩略图、转码文件等应用数据
/mnt/ssd/docker/data/immich/postgres /var/lib/postgresql/data 数据库，保存账户、索引与相册等信息
/mnt/hdd/ /mnt/media 已有照片与视频，挂载为只读

已有媒体目录需要允许 UID 1000 或 GID 2000 读取文件、进入各级目录。这里不批量修改原文件的所有者，按前文的共享组权限配置即可。

1000:2000 只用于 immich-server，不要直接套用到 PostgreSQL。数据库镜像使用自身的运行身份管理数据目录；数据库应保存在本地、支持 Linux 权限的文件系统中，不使用 SMB/NFS 网络共享。

创建配置文件

Compose 配置

创建 /mnt/ssd/docker/compose/immich/compose.yaml：

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:release
    # 使用前文配置的共享组访问媒体目录。
    user: '1000:2000'
    env_file:
      - .env
    volumes:
      # 可写目录：上传文件、缩略图与转码产物。
      - ${UPLOAD_LOCATION}:/data
      # 只读目录：已有照片与视频。
      - ${STORAGE_DIR}:/mnt/media:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - 2070:2283
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd
    healthcheck:
      test: redis-cli ping | grep -q PONG || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # 数据库放在 SSD 上，保留默认存储类型。
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      # PostgreSQL 数据目录单独持久化。
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always
    healthcheck:
      disable: false

env_file 将 .env 中的数据库连接参数传入服务端。仅把 .env 放在 Compose 目录中，只会参与 Compose 变量替换，不会自动把所有变量传给容器。

外部媒体挂载保留 :ro，避免应用修改或删除原文件；/data 与数据库目录仍然需要可写。非 root 运行方式可参考 Immich 官方 FAQ 。

环境变量

在同目录下创建 .env：

UPLOAD_LOCATION=/mnt/ssd/docker/data/immich/data
DB_DATA_LOCATION=/mnt/ssd/docker/data/immich/postgres
STORAGE_DIR=/mnt/hdd/

# 替换为自己的随机密码，仅使用字母和数字。
DB_PASSWORD=ChangeThisToYourRandomPassword123
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

STORAGE_DIR 是宿主机上的媒体根目录。后台添加外部资源库时，需要填写映射后的容器路径 /mnt/media/...。

文中保留草稿中的服务与依赖镜像配置。Immich 的服务端和数据库扩展需要配套使用，首次部署或升级时，应对照 对应发行版的 Compose 文件 ，不要单独替换数据库大版本或扩展镜像。官方安装步骤见 Docker Compose 部署文档 。

启动服务

cd /mnt/ssd/docker/compose/immich
docker compose pull
docker compose up -d
docker compose logs --tail=100 immich-server

在浏览器访问 http://服务器IP:2070，按页面提示创建管理员账户。

本例没有部署机器学习容器，初始化后在管理设置中关闭机器学习相关任务。首次索引时的缩略图生成与视频转码仍会占用 CPU 和 SSD 空间，先扫描少量文件确认浏览、播放正常，再扩大扫描范围。

添加外部资源库

以宿主机目录 /mnt/hdd/图片/用户A 为例：

  1. 使用管理员账户进入“管理 → 外部库”。
  2. 创建资源库，选择所属账户，并将图库命名为“用户A”。
  3. 添加导入路径 /mnt/media/图片/用户A。
  4. 保存后执行扫描，等待索引和缩略图任务完成。
  5. 返回照片时间线，查看已识别的照片与视频。

配置方法参考 官方外部资源库指南 。导入路径必须使用容器内路径，不填写宿主机的 /mnt/hdd/...。只添加需要展示的子目录，避免把整个挂载分区作为扫描范围。

外部资源库用于索引原位置上的媒体，不需要通过上传方式再复制一份原文件；缩略图和转码产物会占用额外空间。每个外部资源库归属一个账户，目录名称“用户A”本身不会自动建立账户或访问隔离。

日常浏览与更新

照片与文件夹

时间线适合按拍摄日期查看媒体。希望保留文件夹浏览入口时，可在账户设置的功能选项中开启文件夹视图。

需要独立展示“用户A”的内容时，可以分配给对应账户，或手动整理相册。

视频播放

扫描后等待视频相关任务完成，再测试页面播放。播放不兼容或转码较慢时，检查管理后台的转码设置与任务日志。本例未开启硬件加速，使用 CPU 处理；N100 的硬件转码需要另外配置，不在这份 Compose 中默认启用。

新增文件

通过共享目录添加照片或视频后，需要重新扫描，才能更新索引。可以手动执行，也可以在管理设置中配置外部资源库的扫描周期。

只读挂载限制对原文件的写入，不会阻止数据库索引和缩略图生成。若在 Immich 之外移动或重命名文件，重新扫描后可能被识别为新条目，原条目上的相册关联等信息也可能丢失。使用方式与限制见 外部资源库文档 。

使用中发现的问题

以下是本次使用中的实际现象，未确认具体原因。

部分图片格式识别异常

挂载额外存储并添加为外部资源库后，发现部分图片格式识别存在问题（不显示封面图、展示比例不对）。

视频预览的方向键行为不符合预期

在大图预览界面中查看视频时，按键盘左、右方向键，实际会切换到上一个或下一个媒体条目，而不是控制当前视频的播放进度。

按键 期望行为 实际行为
左方向键 当前视频快退 切换到上一个媒体条目
右方向键 当前视频快进 切换到下一个媒体条目

这一交互与视频播放器的使用预期不一致，影响连续观看体验。

数据保留与升级

应用数据、数据库和原始媒体需要分别备份。只保留 /mnt/hdd/ 中的原文件，不能恢复账户、相册和应用设置；只备份数据库，也不能代替原文件备份。

升级前查看发行说明和官方 Compose 变更，确认服务端、数据库及相关扩展的兼容关系。备份方法参考 Immich 备份与恢复文档 。