适用版本
- Immich v3.x
- Unraid
- PostgreSQL 16（pgvecto-rs）
- PostgreSQL 18（官方 Vector + VChord）
本文记录了一条经过实际验证成功的迁移方案。整个过程采用官方 PostgreSQL 18 数据库，将旧版 pgvecto-rs 数据库迁移到新版 Vector + VChord 数据库，同时完整保留用户、照片、相册、标签等数据。(chatgpt 生成！！！)
前言
升级 Immich v3 后，很多用户都会遇到数据库无法启动的问题，例如：
Error: No vector extension found.
Available extensions: vchord, vector或者：
Detected schema drift产生这些问题的根本原因是：
Immich v3 已经放弃了 pgvecto-rs，改用了 pgvector + VChord。
也就是说：
| Immich 旧版本 | Immich v3 |
|---|---|
| vectors（pgvecto-rs） | vector（pgvector） |
| PostgreSQL 16 | PostgreSQL 18 |
| tensorchord/pgvecto-rs | ghcr.io/immich-app/postgres |
因此，直接升级容器通常无法正常启动，需要迁移数据库。
本文最终实现的效果
迁移完成后，可以保留：
- 所有照片
- 所有视频
- 所有用户
- 所有相册
- 所有标签
- 所有收藏
- 所有分享
- 所有 Memories
- 数据库升级到 PostgreSQL 18
AI 数据（人脸识别、智能搜索）会重新建立索引，不影响照片数据。
恢复数据库到 PostgreSQL 18
完成数据库导出后，就可以开始恢复到新的 PostgreSQL 18 数据库。
整个恢复过程分为四个步骤：
- 创建新的 PostgreSQL 18 数据库
- 删除旧扩展信息
- 恢复数据库
- 验证恢复结果
创建 PostgreSQL 18
首先，在 Unraid 中安装新的 PostgreSQL 18 容器。
建议不要覆盖旧数据库，而是使用新的数据目录，例如：
/mnt/user/appdata/PostgreSQL_Immich18数据库镜像：
ghcr.io/immich-app/postgres:18-vectorchord容器名称：
Immich_PostgreSQL启动后，进入数据库：
docker exec -it Immich_PostgreSQL psql -U postgres查看数据库：
\l应该可以看到：
immich
postgres
template0
template1如果没有 immich，可以创建：
CREATE DATABASE immich;退出：
\q检查新版数据库扩展
进入新数据库：
docker exec -it Immich_PostgreSQL \
psql -U postgres -d immich查看扩展：
\dx正常应该包含：
cube
earthdistance
pg_trgm
uuid-ossp
vector
vchord其中最重要的是：
vector
vchord说明数据库已经满足 Immich v3 的要求。
退出：
\q将备份复制到容器
恢复之前，将备份复制到 PostgreSQL 容器：
docker cp /mnt/user/immich_no_vectors.dump \
Immich_PostgreSQL:/tmp/复制成功后，开始生成恢复列表。
生成恢复对象列表
执行：
docker exec PostgreSQL_Immich \
pg_restore -l /tmp/immich_no_vectors.dump \
> /mnt/user/immich.list这里生成的是整个备份文件的目录。
不要直接恢复。
原因是里面仍然包含旧版 vectors 扩展。
删除 vectors 相关对象
复制一份恢复列表：
cp /mnt/user/immich.list \
/mnt/user/immich_filtered.list删除所有 vectors 内容：
sed -i '/vectors/d' \
/mnt/user/immich_filtered.list同时删除 AI 搜索表：
sed -i '/face_search/d' \
/mnt/user/immich_filtered.list
sed -i '/smart_search/d' \
/mnt/user/immich_filtered.list检查是否已经删除：
grep -Ei "vectors|face_search|smart_search" \
/mnt/user/immich_filtered.list如果没有任何输出：
（无输出）说明过滤成功。
将过滤后的文件复制到 PostgreSQL 18
复制：
docker cp /mnt/user/immich_filtered.list \
Immich_PostgreSQL:/tmp/恢复文件如果尚未复制，也一起复制：
docker cp /mnt/user/immich_no_vectors.dump \
Immich_PostgreSQL:/tmp/开始恢复数据库
执行：
docker exec Immich_PostgreSQL \
pg_restore \
-L /tmp/immich_filtered.list \
-U postgres \
-d immich \
/tmp/immich_no_vectors.dump整个恢复过程中一般不会有输出。
恢复完成后返回：
root@Tower:~#表示恢复成功。
验证数据库恢复
进入数据库：
docker exec -it Immich_PostgreSQL \
psql -U postgres -d immich查看数据表：
\dt应该看到六十多个表，例如：
asset
album
person
memory
library
workflow
user
tag
plugin
video_stream_session
...说明业务数据已经恢复。
退出：
\q验证数据数量
检查照片数量：
docker exec -it Immich_PostgreSQL \
psql -U postgres -d immich \
-c "SELECT count(*) FROM asset;"例如：
count
-------
23600再检查用户：
docker exec -it Immich_PostgreSQL \
psql -U postgres -d immich \
-c "SELECT count(*) FROM \"user\";"例如：
count
-------
2如果这些数量与旧数据库一致，就说明迁移成功。
启动 Immich
确认 Immich 连接的是新的 PostgreSQL：
docker exec immich env | grep DB_例如：
DB_HOSTNAME=<IP地址>
DB_DATABASE_NAME=immich
DB_USERNAME=postgres
DB_PORT=5432确认无误后，启动 Immich。
第一次启动时，很可能会出现：
Detected schema drift以及：
face_search is missing
clip_index does not exist不要紧张。
这是因为新版数据库没有旧版 AI 向量表。
属于正常现象。
下一部分将介绍如何使用 immich-admin schema-check 自动修复数据库结构，并重新创建 face_search、smart_search、face_index 和 clip_index，最终使 Immich 正常启动。
修复数据库结构并完成迁移
完成数据库恢复后，Immich 已经能够读取数据库中的绝大部分业务数据，但第一次启动时通常仍然无法正常运行。
这是因为在导出数据库时，我们主动移除了旧版 AI 向量数据，因此新版数据库缺少了 AI 搜索相关的数据表。
这一步只需要重新创建这些数据表即可。
第一次启动 Immich
启动 Immich 后，可以查看日志：
docker logs -f immich正常情况下会看到类似输出：
Running migrations
Finished running migrations
Checking for schema drift随后可能出现：
Detected schema drift并提示：
The table "face_search" is missing
The table "smart_search" is missing
The index "face_index" is missing
The index "clip_index" is missing紧接着 Immich 会退出，并出现：
relation "clip_index" does not exist这是迁移过程中最容易让人误以为失败的一步。
实际上，这是正常现象。
因为我们恢复的是业务数据，而没有恢复旧版 AI 向量数据库。
使用 schema-check 检查数据库
Immich 已经提供了自动检查工具。
执行：
docker exec -it immich immich-admin schema-check如果数据库正常，会看到：
Migrations are up to date随后输出：
Detected schema drift例如：
TableCreate:
face_search
IndexCreate:
face_index
TableCreate:
smart_search
IndexCreate:
clip_index最下面还会自动生成 SQL。
例如：
CREATE TABLE "face_search" (
...
);
CREATE INDEX "face_index" ...
CREATE TABLE "smart_search" (
...
);
CREATE INDEX "clip_index" ...这些 SQL 正是我们需要执行的内容。
执行 schema-check 生成的 SQL
进入 PostgreSQL：
docker exec -it Immich_PostgreSQL \
psql -U postgres -d immich把 schema-check 输出的 SQL 完整复制进去执行。
执行完成后会看到类似输出：
CREATE TABLE
CREATE INDEX
CREATE TABLE
ALTER TABLE
CREATE INDEX说明数据库已经修复完成。
退出：
\q再次启动 Immich
重新启动 Immich：
docker restart immich查看日志：
docker logs -f immich正常情况下可以看到：
Running migrations
Finished running migrations
Checking for schema drift随后：
Nest application successfully started最后：
Immich Server is listening on http://127.0.0.1:8080说明服务器已经正常启动。
如果同时看到：
Application startup complete以及：
Starting microservices worker则说明整个 Immich 服务已经恢复正常。
登录 Immich
浏览器访问：
http://服务器IP:2283登录后建议首先检查：
- 是否能够正常登录
- 用户是否存在
- 相册是否存在
- Memories 是否正常
- 标签是否正常
- 收藏是否正常
- 分享链接是否正常
如果这些都正常，说明数据库迁移已经成功。
重新建立 AI 搜索索引
由于旧版 vectors 数据没有迁移，因此：
- 人脸识别
- 智能搜索（CLIP）
- 人物搜索
都会重新建立索引。
进入：
Administration打开：
Jobs依次运行：
Generate Thumbnails
Generate CLIP Embeddings
Facial Recognition
Smart Search根据照片数量不同，整个过程可能需要数小时。
等待任务全部完成即可。
清理旧数据库
确认新数据库已经稳定运行几天后，就可以删除旧数据库。
停止旧 PostgreSQL：
docker stop PostgreSQL_Immich删除容器：
docker rm PostgreSQL_Immich如果确认不会再回退，可以删除旧数据库目录：
/mnt/user/appdata/PostgreSQL_Immich建议至少保留一周备份后再删除。
建议重新备份 PostgreSQL 18
迁移完成后，建议立即备份新的数据库。
执行：
docker exec Immich_PostgreSQL \
pg_dump \
-U postgres \
-Fc \
immich \
> /mnt/user/immich_pg18_backup.dump以后恢复时，直接使用这个备份即可，无需再次处理 vectors 扩展。
常见问题
1. No vector extension found
原因：
旧数据库仍然使用 vectors 扩展。
解决：
迁移到 PostgreSQL 18，并恢复到 vector + vchord 数据库。
2. extension “vectors” is not available
原因：
恢复了旧数据库中的 CREATE EXTENSION vectors。
解决：
使用 pg_restore -l 生成恢复列表，并删除所有包含 vectors 的条目。
3. relation “clip_index” does not exist
原因：
AI 搜索数据表未创建。
解决：
运行：
docker exec -it immich immich-admin schema-check执行其自动生成的 SQL。
4. Detected schema drift
原因：
数据库结构与当前 Immich 版本不一致。
解决：
按照 schema-check 提供的 SQL 修复即可。
迁移总结
本次迁移最终采用了以下路线：
PostgreSQL 16
│
▼
导出数据库（排除 AI 向量表）
│
▼
删除 vectors 扩展信息
│
▼
恢复到 PostgreSQL 18
│
▼
schema-check 修复数据库结构
│
▼
Immich 正常启动
│
▼
重新建立 AI 搜索索引整个过程中，照片、视频、用户、相册、标签等业务数据全部保留，仅重新生成了 AI 向量索引。
实践证明，这是一条稳定、可靠且易于复现的迁移方案。
后记
这次迁移过程中，一个重要的经验是：
数据库迁移最重要的不是尝试很多方案，而是确定一条正确的路线，并坚持执行到底。
中途频繁切换方案，容易引入新的问题，也会浪费大量时间。
最终采用的方案——导出业务数据 → 删除旧版 vectors 扩展对象 → 恢复到 PostgreSQL 18 → 使用 schema-check 修复数据库结构——顺利完成了整个迁移过程，也为今后的升级提供了一条清晰、可复用的路径。
希望本文能够帮助遇到同样问题的用户少走弯路，顺利完成 Immich 数据库升级。
