升级 Immich-未完纪

破坏性变更

原文链接列出了包含破坏性变更的版本。每次发布新版本，都应先阅读发布说明，处理其中列出的破坏性变化。

如果 .env 使用 IMMICH_VERSION，先更新为最新或目标版本，然后在 docker-compose.yml 所在目录升级并重启：

docker compose pull && docker compose up -d

如需清理空间，可以删除旧版本已不用的镜像：

docker image prune

版本策略

Immich 遵循语义化版本，格式为 major.minor.patch。作者计划将 API、部署等破坏性变化限制在主版本发布。可使用 :v3 等元标签，让 Docker 镜像跟随当前主版本；这些标签不跟随候选发布。

移动客户端通常兼容当前及前一个主版本，但服务器只兼容匹配的主版本。因此建议先升级全部移动客户端，再升级服务器。

不向旧版本回移补丁，建议所有用户运行最新稳定版。不支持降级，即使仍在同一小版本内也不支持。

迁移到 VectorChord

如果通过 Docker Compose 部署，在配置中看到 ghcr.io/immich-app/postgres，且没有显式设置 DB_VECTOR_EXTENSION，那么数据库已使用 VectorChord，本节不适用。

如果不使用 Docker Compose，且启动时出现 pgvecto.rs 废弃警告，请向发行方案维护者咨询，或按具体部署调整说明。

Immich 已从废弃的 pgvecto.rs 迁到后继 VectorChord，它几乎在各方面改善性能。本节说明 Docker Compose 迁移方法。

修改前先备份数据库。虽然作者尽力使迁移平滑，仍可能失败。备份后按下列 diff 修改 docker-compose.yml：

  [...]

  database:

    container_name: immich_postgres

-   image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:739cdd626151ff1f796dc95a6591b55a714f341c737e27f045019ceabf8e8c52

+   image: ghcr.io/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'

+     # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs

+     # DB_STORAGE_TYPE: 'HDD'

    volumes:

      # Do not edit the next line. If you want to change the database storage location on your system, edit the value of DB_DATA_LOCATION in the .env file
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data

-   healthcheck:

-     test: >-

-       pg_isready --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" || exit 1;

-       Chksum="$$(psql --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" --tuples-only --no-align

-       --command='SELECT COALESCE(SUM(checksum_failures), 0) FROM pg_stat_database')";

-       echo "checksum failure count is $$Chksum";
-       [ "$$Chksum" = '0' ] || exit 1

-     interval: 5m

-     start_interval: 30s

-     start_period: 5m

-   command: >-

-     postgres

-     -c shared_preload_libraries=vectors.so

-     -c 'search_path="$$user", public, vectors'

-     -c logging_collector=on

-     -c max_wal_size=2GB

-     -c shared_buffers=512MB

-     -c wal_compression=on

+   shm_size: 128mb

    restart: always
    [...]

如果此前没有使用默认 pg14 或 pgvectors0.2.0，必须调整 PostgreSQL 主版本及 pgvecto.rs 版本。默认镜像 docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0 可直接按上面修改。

例如，旧镜像为 docker.io/tensorchord/pgvecto-rs:pg16-v0.3.0 时，新镜像应是 ghcr.io/immich-app/postgres:16-vectorchord0.3.0-pgvectors0.3.0，而不是 diff 中的默认值。

修改后正常启动 Immich。启动时会修改数据库，依硬件和图库规模，可能需要数秒至数分钟。超过10万项资产或较弱服务器，日志在 Reindexing clip_index、Reindexing face_index 停留一段时间属于正常现象。如果没有错误，请耐心等待。

切换 VectorChord 后，不应降级到 Immich 1.133.0以下。 遇到迁移问题，可通过原文 GitHub 或 Discord 链接联系项目。

VectorChord 常见问题

多服务共享独立 PostgreSQL，如何迁移？

参考原文链接的独立 PostgreSQL 文档。路径取决于当前使用 pgvecto.rs 还是 pgvector，以及 Immich 是否具有数据库超级用户权限。

为什么删除这么多 Compose 配置？健康检查是否取消？

这些配置现已纳入镜像本身，同时加入额外调优。

现有数据库备份是否还能使用？

新镜像包含 pgvector、pgvecto.rs 以及 VectorChord，可以恢复采用前两者的已有备份。切换 VectorChord 后生成的备份，则必须用包含 VectorChord 的镜像恢复。

迁移后还需要 pgvecto.rs 吗？

只在迁移中或恢复使用 pgvecto.rs 的备份时需要。迁移并成功启动后，可选择不包含 pgvecto.rs 的更精简镜像，如 ghcr.io/immich-app/postgres:14-vectorchord0.4.3，并按实际 PostgreSQL 版本调整。

数据库放在 SSD 或 HDD 有何区别？

二者性能特征不同，最佳设置也不同。两套配置都能兼容 SSD/HDD，但合适配置可改善响应。作者通常建议尽可能将数据库放在 SSD。

新镜像能否用于 Immich 之外的普通 PostgreSQL？

可以，它是标准 PostgreSQL 容器镜像，额外包含 VectorChord、pgvector，以及可选的 pgvecto.rs。若此前将旧镜像用于其他用途，也可以类似使用新镜像。

原文：Upgrading，页面标注最后更新2026年9月28日。本文为中文译稿，镜像版本、摘要和命令保留原文；示例 diff 含变量占位，不含实际密码。本次未执行升级、清理镜像或迁移。Immich 软件采用 GNU AGPL v3；文档许可仍需分别核验，转载依据用户明确授权。

文章版权归作者所有，未经允许请勿转载。

THE END

技术译文

升级 Immich