如何把 Immich 接入已有的 Postgres 数据库并安装 VectorChord 扩展
如何把 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 迁移
- 确认 pgvector 至少为
0.7.0;低于该版本时先升级,然后用psql执行ALTER EXTENSION vector UPDATE;。 - 按第一步的流程安装 VectorChord 并配置
shared_preload_libraries。 - 若 Immich 没有 superuser 权限,执行
CREATE EXTENSION vchord CASCADE;。 - 删除
.env中的DB_VECTOR_EXTENSION=pgvector变量——如果它存在,Immich 会继续使用 pgvector。 - 启动 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。