如何把 Immich 接入已有的 Postgres 数据库并安装 VectorChord 扩展

原创2026-09-09 20:09:112,279 阅读
文章标签:后端前端移动开发计算机视觉机器学习图像处理音视频Web

如何把 Immich 接入已有的 Postgres 数据库并安装 VectorChord 扩展

Immich 默认使用专用的 Postgres 容器,但如果你有已经自建的 Postgres 服务器,也可以让 Immich 直接连接它。这个做法官方并不推荐作为默认方案,但文档明确提供了完整的准备步骤,要求你对 Postgres 和 Linux 命令行有基本熟悉程度。按 docs/docs/administration/postgres-standalone.md 的流程完成准备后,Immich 服务器可以通过 DB_URL 连接你的现有 Postgres,并使用 VectorChord 扩展承载智能搜索与人脸识别的向量索引。

版本与兼容性要求

开始操作前,先核对以下版本范围,这是文档明确给出的兼容性边界:

组件 要求
Postgres >= 14, < 20
pgvector >= 0.7, < 0.9(VectorChord 的前置依赖,必须先安装)
VectorChord >= 0.3, < 2.0

Immich 服务器会在启动时检查 VectorChord 版本以确认兼容性,如果找不到兼容版本会拒绝启动。这是本文后面验证步骤的依据。

第一步:安装 pgvector 与 VectorChord 扩展库

在承载 Postgres 的服务器上,先安装 pgvector。在 Debian/Ubuntu 上最简单的方式是添加 PostgreSQL 官方 Apt 仓库后执行:

# NN 替换为你的 Postgres 版本,例如 16
apt install postgresql-16-pgvector

然后按 VectorChord 官方文档安装该扩展(仓库文档指向 VectorChord 官网的安装说明页)。安装完成后,编辑 Postgres 的 postgresql.conf,加入:

shared_preload_libraries = 'vchord.so'

如果 shared_preload_libraries 已经设置了其他库,用逗号分隔追加,例如文档给出的写法:

shared_preload_libraries = 'pg_stat_statements, vchord.so'

修改后需要重启 Postgres 数据库使预加载库生效(文档的迁移步骤中在修改该参数后均包含重启 Postgres 这一步)。

第二步:设置 DB_URL 指向已有 Postgres

在 Immich 的 .env 文件中设置 DB_URL 环境变量,文档给出的格式为:

DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename'

# require a SSL connection to Postgres
# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require'

# require a SSL connection, but don't enforce checking the certificate name
# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require&sslmode=no-verify'

上面示例中的 immichdbusername、immichdbpassword、postgreshost、postgresport、immichdatabasename 是文档示例值,替换为你实际的数据库用户名、密码、主机、端口和库名。

使用 DB_URL 时有两条文档明确的规则,需要注意:

  • 当 DB_URL 被定义后,DB_HOSTNAME、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_DATABASE_NAME 这些变量会被忽略(见 docs/docs/install/environment-variables.md)。
  • 所有 DB_ 变量必须提供给所有 Immich worker,包括 api 和 microservices,即应统一放在各容器共用的 .env 文件中。

关于 SSL 参数,两份文档的写法不一致:postgres-standalone.md 示例中跳过证书名校验的写法是 ?sslmode=require&sslmode=no-verify,而 environment-variables.md 中给出的写法是 ?sslmode=require&uselibpqcompat=true,并说明这种写法可同时保证 Immich 和 pg_dumpall(数据库备份工具)正常连接。两者来自不同文档,本文不代为取舍,请按你实际使用的 Immich 版本对应文档执行。

第三步:配置 Immich 数据库用户权限

默认方式:授予 superuser

Immich 默认期望在数据库中有 superuser 权限,并且需要安装特定扩展。在 psql 控制台中执行:

ALTER USER <immichdbusername> WITH SUPERUSER;

<immichdbusername> 替换为你在 DB_URL 中使用的用户名。

可选方式:不授予 superuser(仅建议高级用户)

文档对这种方式有两条明确警告:它只推荐给高级用户,升级 Immich 时经常需要手动干预;并且由于自动备份使用了 pg_dumpall,自动备份需要 superuser 权限。

如果确定不授予 superuser,需要在 psql 中按文档给出的 SQL 准备数据库(<immichdatabasename>、<immichdbusername> 替换为实际值):

CREATE DATABASE <immichdatabasename>;
\c <immichdatabasename>
BEGIN;
ALTER DATABASE <immichdatabasename> OWNER TO <immichdbusername>;
CREATE EXTENSION vchord CASCADE;
CREATE EXTENSION earthdistance CASCADE;
COMMIT;

CREATE EXTENSION vchord CASCADE; 这条语句在有 superuser 的场景下不需要手动执行,只在非 superuser 场景(以及后文的迁移场景)中出现。

启动与验证

数据库准备完成后启动 Immich。文档给出的可验证信号是:Immich 服务器启动时会检查 VectorChord 版本,兼容范围内(>= 0.3, < 2.0)则正常启动,找不到兼容版本则拒绝启动。因此:

  • 服务器能正常启动,说明 Postgres 连接、扩展库与 VectorChord 版本这一链路的兼容性检查已通过;
  • 服务器拒绝启动且版本检查不通过,回到第一步核对 pgvector / VectorChord 是否安装、shared_preload_libraries 是否包含 vchord.so 并重启过 Postgres。

在涉及重建索引的迁移流程中,文档给出的等待信号是启动日志中出现 Reindexed face_index 和 Reindexed clip_index 两条日志,可作为迁移场景的完成标志。

后续更新 VectorChord 版本

以后安装新的 VectorChord 版本时,需要手动更新扩展并重建索引。连接到 Immich 数据库后执行:

ALTER EXTENSION vchord UPDATE;
REINDEX INDEX face_index;
REINDEX INDEX clip_index;

可选分支:已有 Immich 数据时迁移向量索引

如果你的现有 Postgres 上已经有 Immich 数据,需要把旧的向量索引迁到 VectorChord。

从 pgvector 迁移

  1. 确认 pgvector 至少为 0.7.0;低于该版本时先升级,然后用 psql 执行 ALTER EXTENSION vector UPDATE;。
  2. 按第一步的流程安装 VectorChord 并配置 shared_preload_libraries。
  3. 若 Immich 没有 superuser 权限,执行 CREATE EXTENSION vchord CASCADE;。
  4. 删除 .env 中的 DB_VECTOR_EXTENSION=pgvector 变量——如果它存在,Immich 会继续使用 pgvector。
  5. 启动 Immich,让它用 VectorChord 创建新索引。

注意 VectorChord 本身使用 pgvector 的类型,所以完成这些步骤后不要卸载 pgvector。另外根据 docs/docs/install/environment-variables.md,DB_VECTOR_EXTENSION 未设置时 Immich 会在启动时自动探测数据库,多个扩展同时存在时优先顺序是 VectorChord、pgvector。

从 pgvecto.rs 迁移

pgvecto.rs 的支持自 Immich 3.0 起被移除,仍在使用它的部署需要迁移到 VectorChord。最省事的办法是迁移期间同时安装两个扩展:保留 pgvecto.rs,再安装 pgvector(>= 0.7, < 0.9)和 VectorChord,把 shared_preload_libraries= 'vchord.so, vectors.so' 写入 postgresql.conf 并重启 Postgres;等待启动日志出现 Reindexed face_index 与 Reindexed clip_index 后,执行 DROP EXTENSION vectors; 和 DROP SCHEMA vectors;,从 shared_preload_libraries 中移除 vectors.so 并再次重启 Postgres,最后卸载 pgvecto.rs 包(例如 Debian 系环境 apt-get purge vectors-pg14,pg14 按实际版本替换)。若两个扩展无法共存,文档还提供了手动迁移路径:先用一段 SQL 查询 smart_search.embedding 列的维度值,删除旧的 clip_index、face_index 索引并把 embedding 列改回 real[],安装 VectorChord 后把 smart_search.embedding 改回 vector(<number>)(<number> 即第一步查出的维度值)、face_search.embedding 改回 vector(512),再启动 Immich 重建索引。

已知限制

  • 该接入方式不是官方默认推荐方案,没有现成 Postgres 时文档建议直接使用默认的专用 Postgres 容器。
  • 不授予 superuser 的路径仅面向高级用户,升级 Immich 时常需手动干预,且自动备份依赖 pg_dumpall、必须有 superuser 权限。
  • pgvector 是 VectorChord 的前置依赖并提供其使用的数据类型,任何情况下都不应在 VectorChord 就位后卸载 pgvector。
登录后查看全文
immich