Резервное копирование и восстановление Immich на VPS

Что должно входить в резервную копию Immich

Резервная копия Immich — это три компонента, зафиксированные в один и тот же момент времени. Оригиналы файлов в UPLOAD_LOCATION. SQL-дамп базы данных Postgres. Файлы .env и docker-compose.yml, описывающие стек. Восстановление подразумевает загрузку этого дампа в чистую базу данных при остановленном сервере Immich и последующий запуск остальной части стека. Если нарушить порядок, вы получите работающий Immich с пустой лентой событий поверх заполненного диска.

Разделение важно, так как Immich хранит состояние в двух местах, которые «не знают» друг о друге. В Postgres находятся все альбомы, кластеры лиц, общие ссылки, учетные записи пользователей, API-ключи и пути к каждому активу. В файловой системе хранятся сами изображения. Если восстановить файлы без базы данных, Immich ничего не покажет. Если восстановить базу данных без файлов, каждый актив будет открываться как поврежденное изображение.

Команды здесь приведены для Immich v3.1.0 — версии, актуальной на начало августа 2026 года. По состоянию на 2026-10-25 текущим релизом является v3.3.5, патч безопасности, опубликованный 2026-10-21; его compose-файл, образ базы данных и задокументированные шаги по резервному копированию и восстановлению соответствуют тем, что используются на этой странице. Проект развивается быстро, и задокументированная процедура резервного копирования менялась не один раз, поэтому перед выполнением любых действий проверьте версию, которую вы используете. Если стек еще не запущен, начните с руководства по установке Immich и вернитесь сюда.

Понимание путей к файлам

Две переменные в .env определяют всё содержимое на этой странице. UPLOAD_LOCATION — это родительский каталог, в который Immich записывает все медиафайлы. DB_DATA_LOCATION — это каталог данных Postgres.

Стандартный example.env задает UPLOAD_LOCATION=./library, что является запутывающим значением по умолчанию, так как Immich затем создает папку library внутри него. Ваши оригиналы в итоге оказываются в ./library/library. Укажите абсолютный путь, чтобы скрипт резервного копирования никогда не зависел от того, из какого каталога вы его запустили.

UPLOAD_LOCATION=/srv/immich/data
DB_DATA_LOCATION=/srv/immich/postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
IMMICH_VERSION=v3.1.0

Внутри UPLOAD_LOCATION Immich создает несколько папок. Три из них содержат данные, которые невозможно восстановить никакими задачами:

• library: оригиналы, организованные согласно вашему шаблону хранения
• upload: оригиналы, еще не перемещенные в структуру шаблона, а также загружаемые в данный момент файлы
• profile: фотографии профилей пользователей

Если вы потеряете library, фотография будет утрачена. Immich не хранит вторую копию оригинала ни в каком другом месте.

Почему копирование директории данных Postgres — это не резервная копия

DB_DATA_LOCATION кажется простым вариантом. Это директория, rsync скопирует её, и копирование завершится без ошибок. Если вы копируете её во время работы Postgres, такая копия не является резервной. Если вы копируете её при остановленном Postgres, это резервная копия, но крайне ненадежная. Вот две причины, и вы можете наблюдать, как обе приводят к сбою.

Первая — нарушение целостности (tearing). Postgres сначала записывает каждое изменение в журнал транзакций (WAL), а затем применяет его к файлам таблиц во время контрольной точки. Поэтому в любой момент времени файлы на диске находятся в промежуточном состоянии, а последовательное копирование, занимающее четыре минуты, считывает первый файл в 02:00, а последний — в 02:04. Эти два файла не принадлежат одной транзакции. Когда вы запускаете Postgres на полученном результате, он либо отказывается запускаться с ошибкой PANIC: could not locate a valid checkpoint record, либо запускается и падает при первом чтении поврежденной страницы с ошибкой invalid page in block 1234 of relation base/16384/.... Ни один из этих случаев не позволяет восстановиться из такой копии.

Вторая причина касается копии, сделанной при полной остановке. PostgreSQL документирует полное копирование остановленной директории данных как валидную резервную копию, но эта директория открывается только бинарными файлами, использующими тот же формат хранения. Immich фиксирует образ базы данных по хешу, в настоящее время это ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0. Это Postgres 14 со встроенными расширениями VectorChord, pgvector и pgvecto.rs для векторного поиска. Сам Immich теперь работает на VectorChord; pgvecto.rs остается в образе только для того, чтобы старые установки могли мигрировать с него, а старые резервные копии — восстанавливаться. Более поздний минорный релиз Postgres 14 может открыть директорию без изменений, но другая мажорная версия Postgres — нет. Расширения, от которых зависят ваши таблицы, также должны присутствовать в совместимых версиях. Ваш хост для восстановления должен использовать совместимый образ. SQL-дампу это не важно: это текст, и любой совместимый сервер его выполнит.

pg_dump полностью исключает проблему нарушения целостности. Он считывает всю базу данных внутри единого снимка MVCC (многоверсионное управление параллельным доступом), поэтому видит базу данных в точности такой, какой она была в один момент времени, пока параллельно выполняются другие операции записи. Именно поэтому не нужно останавливать Postgres для создания дампа.

Что можно исключить из резервной копии

Эти данные генерируются заново, поэтому их можно пропустить:

• thumbs: изображения для предварительного просмотра и миниатюры
• encoded-video: перекодированное видео
• DB_DATA_LOCATION: восстанавливается из дампа
• Docker-том model-cache: модели машинного обучения, загружаются повторно по запросу

Исключение этих данных — это компромисс, а не безусловное преимущество. Пересоздание миниатюр и перекодирование для большой библиотеки потребует многочасовой нагрузки на процессор при использовании небольшого VPS, а в ленте всё это время будут отображаться серые заглушки. Вы запускаете их повторно в разделе Administration > Jobs, установив параметры "Generate Thumbnails" и "Transcode Videos" для обработки отсутствующих ресурсов. Если на целевом хранилище для резервных копий достаточно места, включите их, чтобы избежать ожидания. Если вы ограничены в объёме хранилища, исключите их и запланируйте пересоздание. В оценке размера библиотеки Immich описано, насколько сильно эти папки увеличиваются относительно исходных файлов.

Стоит знать ещё об одной папке. В UPLOAD_LOCATION/backups хранятся автоматические дампы базы данных Immich, которые создаются ежедневно в 02:00, при этом сохраняются последние 14 копий; настройки доступны в Administration > Settings > Database Dump Settings. Они не требуют дополнительных затрат ресурсов и действительно полезны. Поскольку они находятся на том же диске, что и защищаемая ими библиотека, они помогают при неудачной миграции, но не при выходе сервера из строя. В любом случае создавайте собственный дамп, так как дамп, запущенный вручную, создаётся одновременно со снимком файлов, к которому он относится.

Создание дампа базы данных

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres \
  | gzip > /srv/immich/backup/immich.sql.gz

Замените immich и postgres на ваши DB_DATABASE_NAME и DB_USERNAME, если вы их изменяли. --clean --if-exists добавляет DROP ... IF EXISTS перед каждым CREATE, чтобы дамп корректно разворачивался в базу данных, в которой уже есть объекты, вместо остановки на первом же из них.

Теперь важная деталь, которая часто незаметно портит скрипты резервного копирования. Эта команда представляет собой конвейер (pipeline), а оболочка сообщает код завершения последней команды в конвейере. Если pg_dump завершится с ошибкой из-за неверного пароля или остановленного контейнера, gzip получит пустой поток, создаст корректный файл gzip и завершится с кодом 0. Ваш скрипт зафиксирует успех, а вы получите бесполезный файл размером 20 байт. Добавьте pipefail в начало каждого скрипта резервного копирования:

#!/usr/bin/env bash
set -euo pipefail

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

ls -lh /srv/immich/backup/immich.sql.gz
gunzip -c /srv/immich/backup/immich.sql.gz | head -n 3

Первая строка корректного дампа содержит -- PostgreSQL database dump. Файл размером в несколько сотен байт означает, что создание дампа завершилось неудачей, независимо от того, что сообщил скрипт.

Запишите версию релиза, которая создала дамп, рядом с самим файлом, запросив эту информацию у работающего сервера:

curl -fsS http://localhost:2283/api/server/version > /srv/immich/backup/immich-version.txt

Этот эндпоинт не требует авторизации и возвращает версию работающего релиза в виде номеров major, minor и patch, поэтому 3, 1 и 0 означают v3.1.0. Не полагайтесь в этом вопросе на .env или на docker inspect --format '{{.Config.Image}}' immich_server, который лишь выводит тег образа, указанный в конфигурации. Стандартный файл задает IMMICH_VERSION=v3 — плавающий тег, который следует за каждым релизом 3.x, поэтому запись с :v3 не дает информации о том, какая именно сборка создала дамп. Фиксируйте точный тег также и в .env.

Приостановка сервера и создание снимка с помощью restic

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

docker stop immich_server

Оставьте immich_postgres запущенным, так как он необходим для дампа. Веб-интерфейс и мобильное приложение будут недоступны до тех пор, пока вы снова не запустите сервер, что для домашнего экземпляра в 03:00 обычно приемлемо.

restic подходит для этой задачи, так как он выполняет дедупликацию и шифрование до того, как данные покинут сервер. Укажите репозиторий, который находится не на этом сервере:

export RESTIC_REPOSITORY=sftp:backup@backup.example.com:/srv/restic/immich
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init

Объектное хранилище работает аналогичным образом и является лучшим решением, если вы хотите полностью вынести копию за пределы вашего оборудования:

export RESTIC_REPOSITORY=s3:https://s3.example.com/immich-backup
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
restic init

Этой точкой доступа может быть бакет MinIO, запущенный вами на второй машине, или любой S3-совместимый провайдер. Репозиторий на том же диске, где находится библиотека, защищает только от случайного удаления и ни от чего более.

Затем создайте снимок, указав именно то, что важно:

restic backup \
  /srv/immich/backup/immich.sql.gz \
  /srv/immich/backup/immich-version.txt \
  /srv/immich/data/library \
  /srv/immich/data/upload \
  /srv/immich/data/profile \
  /srv/immich/.env \
  /srv/immich/docker-compose.yml
docker start immich_server

restic сканирует всё дерево при каждом запуске, но загружает только те блоки, которые он еще не видел. Таким образом, первый снимок переносит всю вашу библиотеку, а каждый последующий — только новые фотографии за день.

Хранение и ключи, которые должны находиться в другом месте

restic forget --prune --keep-daily 7 --keep-weekly 5 --keep-monthly 12

forget удаляет снимки из индекса. --prune — это вторая часть процесса, которая удаляет данные, на которые больше не ссылается ни один снимок. Запускайте forget без --prune, иначе размер занимаемого хранилища не уменьшится.

Проверка структуры требует мало ресурсов, поэтому выполняйте её еженедельно:

restic check

Эта команда проверяет целостность метаданных репозитория. Она не считывает сами данные. Раз в месяц считывайте выборочные данные и сверяйте их с записанными хешами:

restic check --read-data-subset=5%

Это единственная проверка, которая позволяет обнаружить скрытое повреждение данных на стороне хранилища, так как она загружает реальные блоки и пересчитывает их контрольные суммы. Полная проверка --read-data для библиотеки фотографий означает загрузку всего репозитория, что при использовании объектного хранилища с тарификацией по объему трафика стоит реальных денег. Поэтому на практике обычно используют проверку части данных.

Теперь часть, которую часто пропускают. Пароль от репозитория restic восстановить невозможно. Его нельзя сбросить, и служба поддержки здесь не поможет. Если единственная копия пароля хранится в /root/.restic-password на сервере, который вы пытаетесь восстановить, ваши резервные копии останутся зашифрованным набором данных. То же самое касается ключа доступа к объектному хранилищу и DB_PASSWORD из .env. Храните их там, где они не зависят от работоспособности этого сервера: распечатанными в надежном месте или в менеджере паролей на другом устройстве. Если этот менеджер также размещен на вашем сервере, он требует аналогичного подхода, а резервное копирование Vaultwarden — это отдельная задача.

Восстановление Immich в правильном порядке

Порядок восстановления — это то, что превращает хорошие бэкапы в пустые ленты событий. Выполните эту последовательность на новом хосте.

Сначала верните конфигурацию. Она указывает, какую версию запускать и куда ведут пути.

restic restore latest --target /restore \
  --include /srv/immich/.env \
  --include /srv/immich/docker-compose.yml \
  --include /srv/immich/backup

Зафиксируйте версию перед запуском. Прочитайте immich-version.txt, установите IMMICH_VERSION в .env на этот конкретный релиз (v3.1.0 для мажорной версии 3, минорной 1, патча 0) и пока не трогайте самый свежий релиз. Immich не поддерживает понижение версии, даже между патч-релизами, поэтому если более новый сервер запустится с дампом от старой версии и применит миграции, пути назад не будет.

Восстановите медиафайлы.

restic restore latest --target /restore --include /srv/immich/data

Затем переместите library, upload и profile так, чтобы они оказались непосредственно внутри того, на что указывает UPLOAD_LOCATION на данном хосте. Сам путь на хосте может меняться, так как compose-файл привязывает эту директорию к фиксированному пути внутри контейнера. Структура внутри нее меняться не должна.

Запустите базу данных отдельно. Оставьте DB_DATA_LOCATION пустым, чтобы Postgres инициализировал чистый кластер.

cd /srv/immich
docker compose pull
docker compose create
docker start immich_postgres
docker exec immich_postgres pg_isready --username=postgres

pg_isready выводит accepting connections после завершения первоначальной настройки, что занимает несколько секунд. docker compose create собирает все контейнеры, не запуская их, и в этом весь смысл шага: сервер Immich еще не должен работать. Сервер, который запускается с пустой базой данных, применяет миграции, создает свежую схему и просит создать новую учетную запись администратора; в итоге вы будете загружать дамп поверх работающего приложения.

Загрузите дамп.

gunzip --stdout /restore/srv/immich/backup/immich.sql.gz \
  | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
  | docker exec -i immich_postgres psql --dbname=immich --username=postgres \
      --single-transaction --set ON_ERROR_STOP=on

Две части этой команды выполняют важную работу. sed существует, потому что pg_dump в качестве меры безопасности записывает пустой search_path в свой вывод, чтобы неквалифицированные имена в дампе не разрешались в неожиданную схему. Типы векторного поиска Immich находятся в public, поэтому с пустым путем поиска восстановление доходит до первого столбца, объявленного с векторным типом, и psql останавливается с ошибкой ERROR: type "vector" does not exist. Добавление public обратно в путь решает проблему.

--single-transaction --set ON_ERROR_STOP=on оборачивает всё восстановление в одну транзакцию, которая прерывается при первой же ошибке. Вы получаете либо полностью восстановленную базу, либо нетронутую. Без этого сбой на середине процесса оставит базу данных, которая запускается и принимает логин, но в которой отсутствуют неизвестное количество альбомов, что вы обнаружите лишь спустя недели.

Теперь запустите всё остальное.

docker compose up -d
docker compose ps
docker logs -f immich_server

Дождитесь строки запуска, похожей на Immich Server is listening on, затем откройте порт 2283 и войдите под своими старыми учетными данными, так как учетные записи пользователей вернулись вместе с дампом. Если страница входа предлагает создать первую учетную запись администратора, значит, база данных не восстановилась. Остановитесь и снова прочитайте вывод psql.

Предупреждение об официальных инструкциях по восстановлению через командную строку, которые начинаются с docker compose down -v. Команда -v удаляет именованные тома. В стандартном compose-файле UPLOAD_LOCATION и DB_DATA_LOCATION являются bind-монтированиями, поэтому они сохраняются. Если вы изменили любой из них на именованный том, эта команда удалит ваши фотографии. Прочитайте свой compose-файл перед вводом команды.

Почему временная шкала пуста после восстановления

Временная шкала формируется на основе записей в базе данных. Immich никогда не сканирует upload/ при запуске для повторного обнаружения фотографий, так как у файла без записи в базе нет владельца, даты и альбома. Поэтому самая частая ошибка при восстановлении — наличие файлов при отсутствии базы данных. Immich запускается, создает пустую схему и предоставляет работающий экземпляр, в котором ничего нет, хотя диск заполнен вашими фотографиями. Данные не потеряны, но они не отображаются. Решение заключается в развертывании дампа при остановленном сервере, в точности как описано выше.

Второй вариант проблемы менее заметен. База данных восстанавливается, временная шкала заполняется записями, но при попытке открыть любой объект возникает ошибка. Это означает, что записи указывают на файлы, которые контейнер не видит. Обычно это происходит из-за того, что library, upload и profile находятся на один уровень глубже после restic restore --target /restore, который никто не переместил в нужное место. Проверьте это изнутри контейнера, вместо того чтобы строить догадки:

docker exec immich_server ls /data

Стандартный файл compose монтирует UPLOAD_LOCATION в /data, поэтому этот список должен содержать library, upload и profile. Если отображается пустая директория или лишняя папка srv, значит, ваш bind mount указывает на неверный уровень, а с записями в базе всё в порядке.

Соответствие версий при резервном копировании и восстановлении

Immich часто выпускает обновления, и схема базы данных меняется вместе с ними, поэтому дамп содержит схему той версии сервера, на которой он был создан.

Восстановление старого дампа на более новом сервере обычно проходит успешно, так как сервер применяет ожидающие миграции при запуске и обновляет схему. Тем не менее, документация Immich по резервному копированию рекомендует по возможности восстанавливать данные в совместимую версию, поскольку несовпадение версий означает, что миграции будут выполняться непосредственно во время восстановления. Проект вносит критические изменения в мажорные релизы и документирует их в примечаниях к выпуску, поэтому восстановление с переходом через мажорную версию — это то, что нужно изучить в первую очередь.

Восстановление более нового дампа на старом сервере не работает. Дамп содержит таблицы и столбцы, которые старой версии кода неизвестны, а Immich прямо заявляет, что понижение версии не поддерживается даже между патч-релизами. Команды для отката не существует.

Таким образом, безопасное восстановление — это предсказуемый процесс. Запустите именно ту версию, которая создала дамп, разверните его, войдите в систему, убедитесь, что временная шкала полна, и только после этого выполняйте обновление. Обновляйтесь в соответствии с официальной страницей обновлений: изучите примечания к выпуску на предмет критических изменений, установите IMMICH_VERSION в .env на нужную версию и выполните docker compose pull && docker compose up -d. Хранение дампов за неделю также помогает: если окажется, что самый свежий дамп был сделан во время неудачного обновления, у вас останется копия за вчерашний день.

Ежемесячная проверка резервных копий

Резервная копия, которую вы ни разу не восстанавливали — это лишь предположение. Раз в месяц восстанавливайте её на временном экземпляре и просматривайте фотографию. Эта процедура занимает около 20 минут и является единственным способом превратить остальную часть этой страницы в план восстановления.

restic snapshots
restic stats latest

snapshots должен отображать результат выполнения за прошлую ночь. stats latest должен показывать размер, близкий к размеру вашей библиотеки, а не несколько мегабайт.

Выполните восстановление во временный каталог, желательно на отдельном хосте:

restic restore latest --target /tmp/immich-drill

Скопируйте docker-compose.yml и .env из восстановленного набора, затем измените три параметра в копии. Укажите UPLOAD_LOCATION и DB_DATA_LOCATION на каталоги внутри /tmp/immich-drill. Опубликуйте веб-порт на другом значении, например 12283:2283 вместо 2283:2283. Удалите строки container_name:, так как стандартный compose-файл жестко задает имена, такие как immich_server, из-за чего второй стек на том же хосте конфликтует с первым, и Docker отказывается его создавать.

Запустите процедуру восстановления, описанную выше: только база данных, развертывание дампа, затем docker compose up -d. Теперь выполните четыре проверки, подтверждающие работоспособность:

1. Войдите в систему с паролем, который вы использовали до начала тренировки. Работающие учетные записи означают, что дамп успешно восстановлен.
2. Откройте временную шкалу и прокрутите её до самого старого месяца. Наличие активов во всем диапазоне дат означает, что восстановились все строки, а не только последние.
3. Откройте одну фотографию в полном размере и скачайте оригинал.
4. Сравните его с тем же файлом в вашей активной библиотеке с помощью sha256sum. Совпадающие хеши означают, что данные успешно прошли цикл через restic.

Затем завершите тренировку с помощью docker compose down -v в рабочем каталоге и удалите /tmp/immich-drill. Запишите дату там, где вы её увидите, так как ценность этой процедуры заключается исключительно в её повторении в следующем месяце. Если вы все еще выбираете, какому фотосерверу отдать предпочтение, сравнение PhotoPrism и Immich описывает, чем они отличаются именно в этом аспекте.

FAQ

Нужно ли останавливать Immich для создания резервной копии?

Остановите immich_server, но оставьте immich_postgres запущенным. Базу данных не нужно приостанавливать, так как pg_dump считывает данные в рамках одного MVCC-снимка и видит единое согласованное состояние независимо от других операций записи. Файлы — это причина для остановки: сервер записывает новые загрузки, а задача по шаблону хранилища перемещает файлы между директориями. В результате инструмент резервного копирования может прочитать файл в процессе записи и сохранить поврежденную копию без каких-либо ошибок. docker stop immich_server перед созданием снимка и docker start immich_server после него устраняют это состояние гонки.

Можно ли скопировать папку с данными Postgres вместо запуска pg_dump?

Не во время работы Postgres. Потоковое копирование активной директории данных считывает разные файлы в разные моменты времени, поэтому результат не является согласованным состоянием. Postgres отклонит такие данные при запуске с ошибкой PANIC: could not locate a valid checkpoint record или позже выдаст ошибку поврежденной страницы. Полная копия, сделанная при остановленном Postgres, является корректной резервной копией, но она откроется только в той же мажорной версии Postgres с совместимыми расширениями. Immich использует образ Postgres 14 с предустановленными VectorChord, pgvector и pgvecto.rs, и эта директория не откроется в другой мажорной версии. SQL-дамп — это обычный текст, который можно развернуть на любом совместимом сервере, поэтому именно его следует хранить.

Почему моя лента Immich пуста после восстановления?

Потому что лента строится на основе записей в базе данных, а вы восстановили файлы без самой базы. Immich никогда не сканирует upload/ для повторного обнаружения фотографий, поэтому файлы без соответствующих записей остаются невидимыми. Сами фотографии при этом не затронуты. Остановите сервер, разверните дамп в свежеинициализированную базу Postgres, а затем запустите стек. Если же лента заполнена, но ни одна фотография не открывается, проблема обратная: library, upload и profile находятся не непосредственно внутри директории, примонтированной в контейнер. Проверьте это с помощью docker exec immich_server ls /data.

Какие папки Immich можно пропустить при резервном копировании?

thumbs и encoded-video восстанавливаются из оригиналов, а DB_DATA_LOCATION пересоздается из дампа, поэтому их не обязательно включать в резервную копию. Пропуск этих папок экономит место при хранении, но требует времени после восстановления, так как пересоздание превью и транскодированных файлов для большой библиотеки займет часы работы процессора (запускается через Administration > Jobs для отсутствующих ресурсов). Что нельзя пропускать ни в коем случае, так это library, upload и profile, где хранятся единственные копии всех оригиналов.

Можно ли восстановить дамп Immich в более новую версию?

Обычно да, так как сервер применяет ожидающие миграции при запуске и обновляет схему. Обратный процесс невозможен: Immich не поддерживает понижение версии, даже между патч-релизами, поэтому дамп из более новой версии нельзя загрузить в старый сервер. Выполняйте восстановление с IMMICH_VERSION, зафиксированной на той версии, в которой был создан дамп, убедитесь в целостности ленты, а затем обновляйтесь. Записывайте версию рядом с каждым дампом с помощью curl -fsS http://localhost:2283/api/server/version, так как docker inspect отображает только настроенную ссылку на образ, а стандартный IMMICH_VERSION=v3 — это плавающий тег, который не дает никакой информации.