Immich 群晖 Container Manager 完整部署文档

适用：DSM 7.x，Container Manager，Docker Compose 项目方式部署 用途：个人照片视频自托管相册，支持外部只读挂载NAS存量照片、人脸识别、地图、元数据检索，手机APP自动备份

一、简介

Immich 是一款开源自托管照片与视频管理系统，功能对标谷歌相册。

  • 手机端APP可自动备份手机照片视频
  • 支持外部库只读挂载NAS原有照片，不改动原始文件
  • 内置人脸识别、地理地图、搜索、相册共享、标签归档
  • 所有数据保存在自己NAS，不上传第三方云端

本方案采用外部库 :ro 只读挂载，Immich不会修改、移动、删除NAS原图，保障原始照片安全。

二、部署前准备

2.1 目录规划（File Station手动新建）

在群晖存储空间，创建Docker项目目录，示例：

/volume2/docker/immich
├── ./library       # Immich默认库，手机上传照片存放目录
├── ./pgdata        # PostgreSQL数据库存储（人脸、标签、元数据）
└── ./cache         # 缓存、缩略图缓存目录

外部照片目录（独立共享文件夹，不要放在immich项目目录内） /volume3/photo ：存放存量历史照片，只读挂载进容器

2.2 共享文件夹权限配置

  1. 打开群晖【控制面板】→【共享文件夹】，找到 photo
  2. 切换到【权限】标签，添加用户 sc-container-manager
  3. 权限设置：读取，勾选【应用到所有子文件夹和文件】→保存

    sc-container-manager 是Container Manager运行容器的系统账号，缺少此权限会导致容器无法读取照片。

2.3 端口规划

  • 2283：Immich Web页面 + API（对外访问端口）

    确认群晖本地端口2283未被其他容器占用

三、Docker Compose 配置文件

新建 docker-compose.yml，放到 /volume2/docker/immich

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    container_name: immich-server
    restart: unless-stopped
    volumes:
      - ./library:/usr/src/app/library
      - ./pgdata:/usr/src/app/pgdata
      - ./cache:/usr/src/app/cache
      # 只读挂载NAS存量照片目录
      - /volume3/photo:/mnt/nas_photo:ro
    environment:
      - TZ=Asia/Shanghai
      - DB_HOSTNAME=immich-db
      - DB_USERNAME=postgres
      - DB_PASSWORD=postgres
      - DB_DATABASE=immich
    ports:
      - "2283:2283"
    depends_on:
      - immich-db
    networks:
      - immich-net

  immich-microservices:
    image: ghcr.io/immich-app/immich-microservices:release
    container_name: immich-microservices
    restart: unless-stopped
    volumes:
      - ./library:/usr/src/app/library
      - ./pgdata:/usr/src/app/pgdata
      - ./cache:/usr/src/app/cache
      #  microservices同样需要挂载照片目录用于扫描、生成缩略图
      - /volume3/photo:/mnt/nas_photo:ro
    environment:
      - TZ=Asia/Shanghai
      - DB_HOSTNAME=immich-db
      - DB_USERNAME=postgres
      - DB_PASSWORD=postgres
      - DB_DATABASE=immich
    depends_on:
      - immich-db
    networks:
      - immich-net

  immich-db:
    image: tensorchord/pgvecto-rs:pg16-v0.7
    container_name: immich-db
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      - TZ=Asia/Shanghai
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=immich
    networks:
      - immich-net

networks:
  immich-net:

四、群晖Container Manager 创建项目步骤

  1. 打开【Container Manager】→【项目】→【创建】
  2. 项目名称：immich
  3. 【路径】选择 /volume2/docker/immich
  4. 【源】选择 docker-compose.yml，点击【加载】，粘贴上面yml内容
  5. 点击【下一步】，确认配置，勾选【启动项目】→完成
  6. 等待镜像拉取完成，容器自动启动。

    首次拉取镜像体积较大，建议配置Docker国内镜像加速源。

五、Immich 网页初始化向导

  1. 浏览器访问 http://群晖内网IP:2283
  2. 创建管理员账号（邮箱+密码，记住账号密码）
  3. 初始化向导页面说明：
    • 存储模板：存储模板功能可以自动移动文件，本次使用外部只读库，关闭存储模板
    • 备份页面：仅介绍3-2-1备份原则，无需配置，直接下一步
    • 移动端APP：记录服务器地址，用于手机APP连接

⚠️ 重要：外部挂载目录为只读，不要开启存储模板引擎，开启会持续报错。

六、网页端添加外部资源库（读取NAS存量照片）

  1. 右上角头像 →【管理】→左侧菜单【外部库】
  2. 右上角【创建资源库】
    • 名称：NAS照片
    • 所有者：选择你的管理员账号，点击创建
  3. 在新建库详情页：
    • 文件夹区域，点击【添加】
    • 路径填写容器内路径：/mnt/nas_photo

      ❗禁止填写宿主机路径 /volume3/photo

  4. 添加完成后，右上角更多菜单，执行【扫描新库文件】
  5. 切换左侧【任务队列】，查看扫描任务进度：
    • 发现资产
    • 提取元数据
    • 生成缩略图
    • 人脸识别 任务全部执行完成后，左侧【照片】菜单即可看到全部NAS照片。

外部库设置说明

  1. 资源库监控（实验功能）：不推荐开启，会持续占用NAS IO资源。
  2. 定期扫描：可后续按需开启，设置每日定时扫描新增照片；首次导入优先手动扫描。

七、手机APP接入

  1. 手机安装 Immich APP（安卓 / iOS）
  2. 服务器地址填写：http://群晖内网IP:2283
  3. 输入管理员账号密码登录
  4. 在APP设置开启自动备份，手机照片视频会上传保存到Immich默认库 /usr/src/app/library

手机上传文件，保存在NAS /volume2/docker/immich/library，不会写入外部只读库 /volume3/photo。

八、数据备份策略（重点）

  1. 原始照片（/volume3/photo） 使用群晖快照、共享文件夹复制任务做备份，原图安全不依赖Immich。
  2. Immich数据库与元数据（pgdata） Immich网页后台【管理】→【维护】，手动导出数据库备份；建议定时备份pgdata目录。

    Immich数据库保存人脸信息、标签、相册、收藏等元数据；数据库损坏不会丢失原始照片，但是所有标签、人脸数据会丢失。

九、常见问题排查

9.1 外部库扫描看不到照片

  1. 检查群晖共享文件夹权限：sc-container-manager 是否拥有photo目录读取权限，并应用到子文件夹。
  2. 确认 /volume3/photo 内存在图片/视频文件，空目录扫描结果为空。
  3. Compose文件中 immich-server 和 immich-microservices 两个容器都必须挂载 /volume3/photo:/mnt/nas_photo:ro，缺少microservices挂载会无法生成缩略图。
  4. 检查任务队列，查看扫描任务是否报错。

9.2 容器启动失败

  1. 检查目录权限：群晖docker目录不要使用root只读权限。
  2. 端口冲突：确认2283端口没有被其他服务占用。
  3. 查看容器日志，排查数据库初始化失败问题。

9.3 扫描大量文件，NAS卡顿

  1. 关闭【资源库监控】实验功能。
  2. 大批量照片导入，选择夜间手动扫描，避开NAS业务高峰时段。

十、安全说明

  1. 本部署方案为HTTP内网访问，外网访问建议配置反向代理+HTTPS证书。
  2. 管理员密码复杂度提高，不要弱密码。
  3. 外部库采用:ro只读挂载，最大程度保护原有照片不会被Immich修改删除。