群晖 NAS 升级 Immich（Container Manager 面板版)

全程只用 File Station + Container Manager，不需要 SSH、不需要命令行。 适用环境：DSM 7.x / Container Manager 项目部署 / 镜像标签写死为 :v3 / 数据库已是 VectorChord 版本。 示例版本：v3.3.6 → v3.4.1

一、升级前先记住三件事

另外，如果弹窗里出现「请阅读发行说明」「使用 WatchTower 或其他自动更新机制」这类字样，重点看两处：数据库变更和移动端变更。建议先把手机 App 升到最新版，再升服务器端。

二、步骤一：备份（File Station）

打开 File Station → docker/immich-app（按你实际项目目录为准）。

1. 复制配置文件

勾选 compose.yaml 和 .env → 右键「复制到」另一个共享文件夹，或直接「下载」到电脑。

2. 拿一份数据库 dump

• 找到 .env 里 UPLOAD_LOCATION 指向的目录（本例为同目录下的 library），展开它，找 backups 文件夹，把最新的 .sql.gz 复制出来。
• 若 backups 是空的：打开 Immich 网页 → 管理 → 任务队列 / 作业 → 建立工作 → 选 Database Backup → 等它执行完，再回 File Station 复制。

3. 确认照片本体有备份

library/、upload/、profile/ 这三类是不可重建的原始资料，确认它们本身已有另一份异地备份。升级过程不会动这些文件夹，但备份该做还是要做。

直接复制 pgdata 文件夹不算备份，别做。

三、步骤二：停止项目

Container Manager → 项目 → immich → 右上角「停止」。

项目运行时 YAML 配置页是只读状态（界面底部会提示「项目运行时，配置为只读状态」），必须先停。

是「停止」，不是「删除项目」。删除会连容器一起清掉，没必要。

四、步骤三：修改 YAML（只改两行）

点项目里的 YAML 配置 分页 → 全选删除 → 贴入下面整份 → 储存。

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.nju.edu.cn/immich-app/immich-server:v3.4.1
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /volume3/photo:/mnt/nas_photo:ro
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    networks:
      - immich_network

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.nju.edu.cn/immich-app/immich-machine-learning:v3.4.1
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    depends_on:
      - database
    restart: always
    networks:
      - immich_network

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9
    restart: always
    networks:
      - immich_network

  database:
    container_name: immich_postgres
    image: ghcr.nju.edu.cn/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always
    networks:
      - immich_network

volumes:
  model-cache:

networks:
  immich_network:
    driver: bridge

改动只有两行：

- image: ghcr.nju.edu.cn/immich-app/immich-server:v3
+ image: ghcr.nju.edu.cn/immich-app/immich-server:v3.4.1

- image: ghcr.nju.edu.cn/immich-app/immich-machine-learning:v3
+ image: ghcr.nju.edu.cn/immich-app/immich-machine-learning:v3.4.1

三个「不要动」

• 不要动 postgres:14-vectorchord0.4.3-pgvectors0.2.0：这已经是官方 v3 要求的 VectorChord 数据库镜像，改了反而会触发多余的向量扩展迁移。
• 不要动 valkey:9、所有 volumes、ports、env_file、networks。
• 不要改 .env：网上教程常让改 IMMICH_VERSION，但这份 compose 是把标签直接写死在 YAML 里的，没有引用该变量。.env 里就算还留着 IMMICH_VERSION=v3 也不影响，改它无效。

为什么顺手钉成固定版本

原本的 :v3 是浮动标签，每次拉取都会跟到当时最新的 v3.x。WatchTower 之类的自动更新机制会在你没读发行说明的情况下把服务推上新版本——这正是升级弹窗特意提醒的事。改成 v3.4.1 后，升不升级完全由你控制。

如果装了 WatchTower，记得把 immich_server、immich_machine_learning 加进排除清单，否则它仍可能按 digest 把容器重建掉。

五、步骤四：启动

回项目页 → 启动。

Container Manager 发现本地没有 v3.4.1 标签，会自动从镜像源拉取并重建容器。可切到「映像」分页看拉取进度。

• 只有 immich_server 和 immich_machine_learning 会被重建
• redis、database 保持原样
• 所有卷和照片资料不会丢失

六、步骤五：验证

1. Container Manager → 项目 → immich →「容器」分页，四个容器都亮绿灯
2. 打开 Immich 网页，管理界面版本应显示 v3.4.1，升级弹窗不再出现
3. 逐项检查：能登录、既有照片与缩图在、上传一张新图成功、人物辨识／搜索正常
4. 首次启动若跑数据库迁移，页面短暂连不上、日志停在 Reindexing clip_index / Reindexing face_index 都是正常的，不要中断，照片多时可能要几分钟

确认无误后，到「映像」分页删掉旧的 :v3 镜像腾空间（不删也不影响运行）。

七、常见状况

八、以后每次升级的固定套路

1. File Station 备份 compose.yaml、.env、最新的 library/backups/*.sql.gz
2. 读目标版本的发行说明，重点看数据库与移动端变更
3. 停止项目 → YAML 里把两个镜像标签改成新版本号 → 启动
4. 开网页确认版本号与既有资料正常

附：本次环境速查