Почему Immich перестал запускаться после обновления

После обновления Immich контейнер постоянно перезапускается, а в журнале появляется No vector extension found. Available extensions: vchord, vector? В первую очередь проверьте PostgreSQL: новая версия Immich могла запуститься со старым образом базы, в котором есть только pgvecto.rs.

В Immich 3.0 поддержка pgvecto.rs удалена. Если установка использовала это расширение, нужно перейти на VectorChord. Для обычной установки Docker Compose переход выполняют через совместимый образ PostgreSQL, содержащий и новое, и старое расширение. Затем Immich переносит векторные данные и перестраивает индексы при запуске.

Сама ошибка не означает, что фотографии удалены. Но исправлять её созданием пустой базы, удалением тома PostgreSQL или переустановкой всего проекта нельзя: так можно потерять пользователей, альбомы, связи с файлами и результаты распознавания.

Что означают vectors, vector и vchord

Названия похожи, но это разные расширения PostgreSQL:

Векторные данные описывают содержимое фотографий и лица числовыми наборами. Они используются для умного поиска и распознавания. Установка VectorChord не требует переноса самих оригиналов фотографий в другую базу.

Фраза Available extensions: vchord, vector в ошибке перечисляет поддерживаемые Immich варианты. Она не подтверждает, что эти расширения установлены на вашем PostgreSQL. Наличие нужно проверить SQL-запросом.

Сначала выясните, какая база действительно используется

Дальнейшие команды рассчитаны на Linux, Docker Compose и сервисы immich-server, immich-machine-learning, database. Выполняйте их в каталоге своего Compose-проекта. Если названия отличаются, подставьте свои; посмотреть их можно командой docker compose config --services.

docker compose ps -a
docker compose images
docker compose logs --tail=200 immich-server database

Запишите версию Immich из журнала запуска, образ PostgreSQL и первую существенную ошибку. Предупреждение ExperimentalWarning: WASI, находящееся рядом, само по себе не объясняет отсутствие векторного расширения.

Просмотрите итоговую конфигурацию:

docker compose config

Проверьте образ сервиса database, подключённый каталог данных, параметры DB_HOSTNAME, DB_DATABASE_NAME, DB_VECTOR_EXTENSION и, если задан, DB_URL. Последний может направлять Immich на отдельный PostgreSQL. Тогда изменение локального контейнера database не исправит подключённую базу.

Вывод конфигурации может содержать пароли: изучайте его локально, а перед публикацией удаляйте секреты. Сохраните также Compose override-файлы и настройки панели, если они используются.

Отключите автоматические обновления на время работ и остановите сервисы Immich, оставив PostgreSQL запущенным:

docker compose stop immich-server immich-machine-learning

Если у вас отдельные worker-сервисы, остановите и их. Подключитесь к базе:

docker compose exec database sh -c 'psql -X -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

Команда использует переменные стандартного контейнера PostgreSQL. Для внешней базы подключитесь к серверу и базе, указанным в настройках Immich. Выполните:

SELECT current_database(), current_user;
SHOW server_version;

SELECT extname, extversion
FROM pg_extension
WHERE extname IN ('vectors', 'vector', 'vchord')
ORDER BY extname;

SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('vectors', 'vector', 'vchord')
ORDER BY name;

SHOW shared_preload_libraries;

Первый список показывает активированные расширения текущей базы. Второй — расширения, доступные в установленном окружении PostgreSQL; пустой installed_version означает, что расширение ещё не активировано в этой базе.

• Есть только vectors, а vchord недоступен. Нужен переходный образ или установка необходимых расширений на внешнем PostgreSQL.
• vchord доступен, но не активирован. После подготовки окружения Immich обычно активирует его самостоятельно. Для пользователя без нужных прав потребуется действие администратора базы.
• vchord уже активирован. Запишите его версию до выбора образа: нельзя подставлять образ с более старым VectorChord.
• В проверяемой базе всё правильно, но ошибка не меняется. Сверьте фактическое подключение Immich и применённые переменные контейнера. Возможно, проверяется другой PostgreSQL.

Для выхода из psql используйте \q. Если PostgreSQL сам не запускается, сначала сохраните его журнал и каталог данных; SQL-проверки выполняйте после восстановления совместимого окружения.

Как сохранить базу и фотографии перед исправлением

Нужны копии базы, файлов фотографий и конфигурации. Автоматические дампы Immich обычно находятся в UPLOAD_LOCATION/backups, но не содержат самих фотографий и видео. Скопируйте доступный дамп, созданный до обновления, в отдельное место.

Дополнительно сохраните текущее состояние. Даже если оно уже частично изменено неудачной миграцией, такая копия позволит вернуться к исходной точке расследования.

Если PostgreSQL работает, в Bash выполните:

umask 077
backup_dir="./immich-before-vectorchord-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$backup_dir"
cp docker-compose.yml .env "$backup_dir/"

set -o pipefail
docker compose exec -T database sh -c \
  'pg_dump --clean --if-exists -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
  | gzip > "$backup_dir/immich.sql.gz"

Если основной файл называется compose.yaml, замените имя в команде копирования. Сразу после создания дампа проверьте код завершения:

echo $?

Норма — 0. При другом результате остановитесь и устраните ошибку дампа. Параметр pipefail нужен, чтобы успешное сжатие не скрыло сбой pg_dump. Затем проверьте архив:

gzip -t "$backup_dir/immich.sql.gz"
ls -lh "$backup_dir/immich.sql.gz"

gzip -t при успехе ничего не выводит и завершается с кодом 0. Это проверяет сжатый файл, но не доказывает возможность восстановления базы: надёжная проверка — пробное восстановление в отдельном окружении.

Скопируйте за пределы VPS весь каталог UPLOAD_LOCATION, внешние библиотеки и созданный комплект с дампом. Проверьте наличие файлов и открытие нескольких оригиналов. Если приложение использует дополнительные точки монтирования, включите их в копию.

Если дамп не получается из-за отсутствующей библиотеки расширения, не удаляйте проблемные таблицы. Остановите PostgreSQL и сделайте согласованную копию всего его каталога данных вместе с конфигурацией. Обычное копирование файлов работающей базы не заменяет корректный PostgreSQL-бэкап. Для физической копии понадобятся совместимая основная версия PostgreSQL и нужные библиотеки расширений.

Как выбрать образ для перехода на VectorChord

При выборе нужно сохранить основную версию PostgreSQL и обеспечить доступность той версии pgvecto.rs, которую использовала база. Замена PostgreSQL 16 на 14 или 14 на 16 — отдельная миграция, которую нельзя выполнить простой сменой тега над существующим каталогом данных.

Примеры переходных образов из инструкции Immich по миграции:

Это примеры для указанных исходных состояний, а не список «лучших последних версий». Если у вас PostgreSQL 15 или другая версия pgvecto.rs, подбирайте соответствующий тег. Не используйте latest для случайного выбора окружения базы.

В обсуждении на Reddit пользователь сначала собирался заменить PostgreSQL 15 образом для PostgreSQL 14. После замечания разработчика он сохранил PostgreSQL 15 и сообщил об успешном запуске. В другом случае на Unraid переход на образ с VectorChord и прежним pgvecto.rs также завершился успешно.

Если вы уже пробовали миграцию и активировали более новый VectorChord, типовой переходный образ может не подойти. Например, база с активированным VectorChord 1.x не должна запускаться на образе, предоставляющем только 0.4.3. Понадобится окружение с совместимыми версиями всех ещё используемых расширений либо восстановление копии, сделанной до попыток перехода. Это отдельная ветка восстановления.

Что изменить в Docker Compose

Для стандартной исходной установки PostgreSQL 14 с pgvecto.rs 0.2.0 раздел базы может выглядеть так:

services:
  database:
    container_name: immich_postgres
    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'
      # Для базы на HDD раскомментируйте:
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always

Меняйте соответствующий раздел своего файла, сохраняя необходимые сети и другие собственные настройки. Не заменяйте весь Compose чужим примером.

• Сохраните подключение существующего каталога или тома базы. Значения DB_DATA_LOCATION, имени базы, пользователя и пароля должны соответствовать вашей установке. Смена пути может привести к запуску пустой базы.
• Удалите старый стандартный блок command: от образа pgvecto.rs. В частности, переопределение shared_preload_libraries=vectors.so может помешать загрузке VectorChord. Не переносите старый блок целиком в новый образ.
• Удалите прежний стандартный блок healthcheck:, как показано в инструкции миграции. В официальном образе Immich проверка состояния уже предусмотрена.
• Уберите принудительный выбор DB_VECTOR_EXTENSION=pgvecto.rs. При переходе с pgvector уберите и принудительный выбор pgvector, иначе Immich продолжит использовать его. Обычно лучше оставить автоматический выбор; если задаёте значение явно, для VectorChord используется vectorchord, а не SQL-имя vchord.

Проверьте эти настройки также в override-файлах, Portainer Stack или шаблоне панели. Изменение только .env может не убрать значение, заданное в другом месте.

На этапе исправления сохраняйте выбранную версию Immich; не совмещайте переход расширения с несколькими дополнительными обновлениями. Сервер и machine-learning должны использовать согласованные версии. Если исходная версия ниже 1.107.2, сначала нужен промежуточный переход на 1.107.2 по release notes. После частично выполненного обновления нельзя запускать её поверх уже изменённой базы.

Как применить изменения и дождаться миграции

Проверьте синтаксис Compose, скачайте выбранный образ базы и пересоздайте её контейнер:

docker compose config --quiet
docker compose pull database
docker compose up -d database
docker compose logs --tail=100 database

Продолжайте только после успешного выполнения предыдущих команд. PostgreSQL должен запуститься с существующей базой. Если он сообщает о несовместимой версии файлов данных, остановитесь и верните образ с правильной основной версией PostgreSQL.

Проверить готовность соединения можно так:

docker compose exec -T database sh -c \
  'pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

Ожидается accepting connections. Повторите SQL-проверки из начала статьи: vchord должен быть доступен, а эффективная настройка shared_preload_libraries — включать VectorChord. До запуска Immich поле installed_version для него ещё может быть пустым.

Затем пересоздайте контейнеры приложения, чтобы они получили обновлённые переменные:

docker compose up -d --force-recreate immich-server immich-machine-learning
docker compose logs -f --tail=100 immich-server database

docker compose restart недостаточно для применения изменённого окружения. При штатном переходе в журнале появляются сообщения:

Reindexing clip_index
Reindexing face_index
Reindexed clip_index
Reindexed face_index

Перестроение индексов может занимать заметное время, особенно на большой библиотеке и медленном диске. Не перезапускайте контейнер только потому, что некоторое время нет новой строки. Сначала проверьте нагрузку:

docker stats --no-stream
df -h
journalctl -k --since "30 minutes ago" --no-pager

Нехватка места, сообщения OOM об исчерпании памяти и ошибки диска требуют исправления. Если ошибок нет, а PostgreSQL выполняет работу, дайте миграции завершиться. Из просмотра журнала можно выйти через Ctrl+C: это не останавливает контейнеры.

Для дополнительной проверки из psql:

SELECT pid, command, phase, blocks_done, blocks_total
FROM pg_stat_progress_create_index;

Отчёт зависит от этапа и метода построения индекса. Пустой результат не доказывает зависание. Если работа долго не меняется, сохраните журналы и проверьте ожидания и блокировки PostgreSQL; универсального безопасного тайм-аута для всех библиотек нет.

Что делать, если после смены образа появилась другая ошибка

Чтобы определить источник настройки preload, администратор базы может выполнить:

SELECT name, setting, source, sourcefile, sourceline, pending_restart
FROM pg_settings
WHERE name = 'shared_preload_libraries';

Если источник — командная строка, исправляйте параметры запуска контейнера. Если указан файл — найдите настройку в нём. pending_restart = true означает, что изменение ожидает перезапуска PostgreSQL.

Не применяйте советы с DROP EXTENSION vectors CASCADE, удалением столбцов embedding или очисткой поисковых таблиц как универсальное исправление. В обсуждениях встречаются такие обходные пути, но они меняют или удаляют данные. Штатная миграция рассчитана на сохранение существующих векторов и создание новых индексов.

Если PostgreSQL отдельный или Immich установлен через Unraid

Для внешнего PostgreSQL образ Compose не поможет. На самом сервере базы должны быть установлены совместимые pgvector и VectorChord. При переходе со старого pgvecto.rs сохраняйте и его до окончания преобразования данных.

В официальном порядке миграции используются обе библиотеки:

shared_preload_libraries = 'vchord.so, vectors.so'

Если в этой настройке уже есть другие необходимые библиотеки, сохраните их. После изменения PostgreSQL нужно перезапустить. Затем проверьте доступность расширений; при недостаточных правах пользователя Immich администратор активирует vchord в нужной базе и запускает приложение.

Удаление pgvecto.rs выполняют только после подтверждённой миграции. pgvector удалять нельзя: VectorChord использует его тип данных. Для окружений, где нельзя временно установить оба расширения, существует отдельный ручной порядок преобразования. Не смешивайте его шаги с автоматической миграцией.

В Unraid и других панелях действуют те же требования к версиям и данным, но меняются поля шаблона контейнера PostgreSQL: Repository, путь тома, параметры запуска и переменные. Сохраните прежние сопоставления путей и портов. Для стороннего образа Immich учитывайте инструкцию его сопровождающего; команды Compose нельзя механически переносить в установку, которая им не управляется.

Нужен ли для исправления более мощный VPS

Дополнительная RAM не установит отсутствующее расширение. Сначала исправьте совместимость образа, базы и конфигурации. Увеличение ресурсов помогает при подтверждённой нехватке памяти или слишком медленном перестроении индексов.

В актуальных требованиях Immich указаны минимум 6 ГБ RAM и 2 ядра CPU; рекомендуются 8 ГБ и 4 ядра. Для базы предпочтительно локальное SSD/NVMe-хранилище. Заранее оставьте место под дамп и перестроение индексов; свободное пространство оценивайте на том разделе, где находится PostgreSQL. Скорость миграции зависит от объёма векторов, CPU и диска, поэтому обещать одинаковое время для разных библиотек нельзя.

Если текущей площадке не хватает ресурсов, можно подобрать VPS HSTQ с SSD или NVMe под Immich. При подборе укажите размер фотоархива, объём базы, текущую RAM и нагрузку обработки. Перенос, настройка Immich и администрирование согласуются отдельно; наличие VPS само по себе не заменяет резервное копирование и проверку восстановления.

Как проверить, что переход завершён

После успешного запуска повторите запрос расширений. В базе должны быть активированы vchord и vector. Наличие их названий недостаточно: проверьте и поисковые индексы.

SELECT c.relname AS index_name,
       am.amname AS access_method,
       i.indisvalid
FROM pg_index i
JOIN pg_class c ON c.oid = i.indexrelid
JOIN pg_am am ON am.oid = c.relam
WHERE c.relname IN ('clip_index', 'face_index');

Для штатного перехода на VectorChord ожидаются индексы clip_index и face_index с методом vchordrq и indisvalid = true. Если индексы остались на старом методе, отсутствуют или невалидны, изучите журнал миграции до удаления старого расширения.

Затем проверьте работу библиотеки:

• Контейнер сервера не уходит в цикл перезапусков, а в журнале нет ошибок миграций.
• Вход работает, пользователи и альбомы на месте; количество фотографий соответствует ожидаемому.
• Открываются и скачиваются оригиналы, воспроизводится видео.
• Работают умный поиск, страницы людей и загрузка нового тестового снимка.

Успешная штатная миграция перестраивает индексы существующих векторов. Запускать повторное распознавание и пересчёт всей библиотеки только из-за перехода на VectorChord обычно не требуется. Если какие-то задания действительно завершились ошибкой, разберите их отдельно.

После проверки создайте новый дамп базы. Старые копии, сделанные до перехода, сохраняйте вместе со сведениями о версиях PostgreSQL и расширений: для их восстановления может снова понадобиться pgvecto.rs.

Как восстановиться, если миграция не завершилась

Возврат старого образа Immich поверх уже изменённой базы не является полноценным откатом. Понижение версии приложения не поддерживается как штатная обратная миграция.

1. Остановите приложение и сохраните текущее состояние базы, конфигурацию и журналы.
2. Найдите комплект до обновления: дамп или согласованную физическую копию базы, версии образов и копию файлов библиотеки.
3. Подготовьте отдельное окружение с новым каталогом базы и совместимыми версиями. Исходный каталог оставьте нетронутым.
4. Восстановите базу по инструкции резервного копирования и восстановления для версии, создавшей дамп, подключите копию файлов с прежними путями внутри контейнера и проверьте библиотеку. Порядок восстановления Immich менялся в v2.5.0, поэтому инструкция должна соответствовать вашему бэкапу.
5. Повторите миграцию уже на проверенной копии. Переключайте пользователей после успешной проверки.

Если резервной копии нет, это ещё не означает потерю данных. Часто достаточно вернуть базе недостающие библиотеки совместимых версий. Но сначала сохраните остановленный каталог PostgreSQL. Удалять его, выполнять docker compose down -v или создавать новую библиотеку поверх существующих данных нельзя.

Если сохранились только оригиналы, фотографии можно сохранить и заново импортировать, но это не восстановит автоматически прежние альбомы, пользователей и ручную разметку людей. Поэтому копия файлов не заменяет дамп базы.