SSD Nodes Learn
Руководства Matt ConnorАвтор: Matt Connor · Обновлено 2026-07-24

Как запустить Immich и не потерять данные

Разбор потребления 6 GB RAM, настройки порта 2283 через HTTPS и решения ошибки exit 137. Инструкция по обновлению Immich v3 без поломки базы pgvecto.rs.

Что вы создаете

Immich — это сервис для самостоятельного хостинга резервных копий фото и видео, полноценная замена Google Photos. У сервиса есть мобильное приложение для фоновой загрузки медиафайлов из галереи телефона. В нем доступны временная шкала, альбомы, распознавание лиц и поиск на базе машинного обучения, который находит объекты (например, "beach") или людей без необходимости ручного тегирования. Вы запускаете сервис на собственном VPS; оригинальные файлы хранятся на вашем диске, и никто не сканирует их для показа рекламы.

Установка выполняется с помощью четырех контейнеров из файла Docker Compose проекта. Этот процесс занимает десять минут. Основные сложности описаны далее: контейнер машинного обучения потребляет много оперативной памяти на слабых устройствах, оригиналы файлов быстро занимают место на диске, мобильное приложение не работает с серверами по протоколу HTTP, а частые изменения в API Immich могут привести к тому, что неосторожный docker compose pull сделает базу данных неработоспособной. Если учитывать эти четыре фактора, Immich будет работать стабильно. Если их игнорировать, вы потеряете целые выходные.

Предварительные требования и важные нюансы

  • RAM: в официальной документации указано минимум 6 GB и рекомендуется 8 GB — считайте 4 GB плюс swap минимально допустимым пределом. Контейнеры immich-server и Postgres потребляют мало ресурсов. Контейнер immich-machine-learning потребляет больше всего — он загружает модели CLIP и face-recognition в RAM для создания поисковых индексов. На системе с 2 GB памяти ядро завершит процесс из-за нехватки ресурсов. Добавьте swap, даже если у вас есть 4 GB.
  • Диск: закладывайте объем под всю вашу библиотеку с запасом. Оригинальные файлы копируются полностью, плюс Immich создает миниатюры и изображения для предпросмотра (примерно +10–20% к объему). Для коллекции фотографий объемом 200 GB требуется том на 300 GB. Postgres занимает мало места в сравнении с ними.
  • CPU: подойдет любой современный KVM VPS, но машинное обучение (ML) на CPU работает медленно. Индексация умного поиска при большом импорте может выполняться в фоновом режиме несколько часов. Это нормально; GPU не требуется.
  • Доменное имя, направленное на ваш VPS. Мобильное приложение требует использования HTTPS. Рекомендуется использовать reverse proxy. Такая конфигурация аналогична self-hosted Nextcloud instance with Docker, TLS and backups — Immich является аналогом этого файлового сервера для фотографий.
  • Установленные Docker и Compose plugin — Docker Engine и плагин Compose v2 из официального репозитория Docker, как описано в our Docker Compose basics guide.

Шаг 1: Добавьте swap перед выполнением остальных действий

Самая частая причина сбоя Immich на VPS с малым объемом памяти — завершение процесса ML-контейнера из-за OOM-killer. Сначала выделите ядру дополнительное пространство.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

Команда free -h должна показать строку Swap: со значением 4.0Gi. Это не ускорит работу ML, но предотвратит аварийное завершение контейнера во время индексации на машинах с 4 GB RAM.

Шаг 2: Загрузите официальные compose и env — используйте их, а не копии

Immich фиксирует версии сервисов и, что критически важно, образ базы данных внутри поставляемых файлов. Не используйте compose-файл из блога (включая этот) в качестве первоисточника. Загрузите активы релиза:

sudo mkdir -p /opt/immich && cd /opt/immich
sudo wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Они взяты из тегированного релиза, поэтому ссылки на образы будут верными. Compose-файл определяет четыре сервиса. Рекомендуется изучить их назначение перед началом работы:

  • immich-server (ghcr.io/immich-app/immich-server, контейнер immich_server) — API и веб-интерфейс, работающие на порту 2283. Монтирует ваши загрузки в /data.
  • immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, контейнер immich_machine_learning) — поиск CLIP и распознавание лиц. Кэширует загруженные модели в volume model-cache. Этот сервис потребляет много оперативной памяти.
  • database (контейнер immich_postgres) — Postgres с расширением VectorChord для векторного поиска. Тег образа зафиксирован через digest прямо в compose-файле, например ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... В старых конфигурациях использовался pgvecto.rs; поддержка этого расширения удалена в Immich v3.0, поэтому во всех современных установках используется VectorChord. Никогда не редактируйте этот тег вручную.
  • redis (контейнер immich_redis) — экземпляр Valkey/Redis для очередей задач.

Шаг 3: Настройка .env — место хранения ваших фотографий и базы данных

Откройте .env и настройте четыре параметра. Все параметры ниже отмеченной линии должны оставаться без изменений.

# Where original uploads are stored on the host
UPLOAD_LOCATION=/opt/immich/library

# Where the Postgres data lives. NEVER put this on an NFS/network share.
DB_DATA_LOCATION=/opt/immich/postgres

# "v3" is a floating tag that tracks the latest v3.x. Pin a full tag like
# v3.0.2 instead — then you upgrade on purpose, not by surprise.
IMMICH_VERSION=v3.0.2

# Change this to a long random string. Letters and digits only.
DB_PASSWORD=REPLACE_WITH_A_LONG_RANDOM_STRING

# Set your timezone so timestamps and "on this day" line up
TZ=Europe/London

###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Два правила, которые помогут избежать проблем. UPLOAD_LOCATION должен указывать на ваш большой диск. Если вы планируете подключить volume для данных позже, сразу укажите путь его монтирования. Перенос папки после настройки потребует переноса эскизов и обновления путей к ресурсам. DB_DATA_LOCATION должен находиться на локальном диске: использование Postgres на NFS или SMB приводит к повреждению данных, о чем прямо сказано в документации. Если в DB_PASSWORD использовать только буквы и цифры, вы избежите ошибок экранирования в строке подключения.

Шаг 4: Первый запуск и создание администратора

cd /opt/immich
sudo docker compose up -d
sudo docker compose ps

Правильный результат — четыре контейнера, все в статусе running и в конечном итоге healthy:

NAME                      STATUS
immich_machine_learning   Up (healthy)
immich_postgres           Up (healthy)
immich_redis              Up (healthy)
immich_server             Up (healthy)

Первый up загружает несколько гигабайт образов, поэтому подождите. Отслеживайте прогресс с помощью sudo docker compose logs -f immich-server; когда сервер будет готов, он запишет в лог, что прослушивает порт 2283. Теперь откройте http://YOUR_SERVER_IP:2283 в браузере. При первом посещении появится мастер настройки Getting Started — первый созданный вами аккаунт станет администратором. Установите сложный пароль; этот аккаунт управляет настройками сервера, пользователями и конфигурацией ML, которая потребуется вам позже.

Шаг 5: Мобильное приложение и фоновое резервное копирование

Установите "Immich" из App Store или Play Store. На экране входа необходимо ввести Server Endpoint URL. Введите полный URL-адрес, включая схему, например https://photos.example.com (приложение само добавит /api). Войдите в систему, используя только что созданную учетную запись. Затем откройте экран Backup в приложении, выберите альбомы для защиты (обычно это Camera и Screenshots) и включите Background backup. В iOS фоновое резервное копирование ограничивается операционной системой: загрузка в активном режиме выполняется всегда, а в фоновом — только когда это позволяет ОС.

На этом этапе часто возникают трудности, поэтому прочитайте Шаг 6, прежде чем пытаться настроить приложение.

Шаг 6: HTTPS через обратный прокси — и правило полного URL

Мобильному приложению требуется HTTPS. Установите обратный прокси перед портом 2283 и завершите TLS на нем. Если вы уже используете несколько контейнеров, наиболее удобным вариантом будет Traefik с автоматическим TLS для нескольких Docker-приложений — один блок label направляет photos.example.com в контейнер immich-server и самостоятельно получает сертификат. Если вы предпочитаете nginx, руководство Let's Encrypt с Certbot и nginx поможет получить сертификат и настроить блок proxy_pass http://127.0.0.1:2283;. Для Immich важна одна настройка прокси: увеличьте лимит размера загрузки, так как видео с телефона имеют большой объем. В nginx это параметр client_max_body_size 50000M; внутри блока server — значение по умолчанию 1 MB приведет к ошибке 413 Request Entity Too Large при загрузке видео.

Правило, которое соблюдает приложение: эндпоинт должен быть доступен и, на практике, должен использовать HTTPS. Ошибки типа «приложение не может связаться с сервером» возникают при использовании http:// эндпоинтов или при обращении по прямому IP без указания порта — подробнее об этом ниже.

Шаг 7: Внешние библиотеки против загрузок — импорт существующей структуры фотографий

Существует два способа добавления фотографий в Immich, и они работают по-разному.

  • Uploads (Загрузки) — это активы, которыми управляет Immich. Приложение или веб-интерфейс копирует файл в UPLOAD_LOCATION. Immich может переименовывать, перемещать и удалять их.
  • External libraries (Внешние библиотеки) — это импорт файлов в режиме только для чтения, которые уже находятся в папке на вашем сервере (например, старая структура Pictures или экспорт с NAS). Immich индексирует их на месте и отображает в ленте событий, но никогда не изменяет и не удаляет оригиналы.

Чтобы импортировать существующую структуру, подключите ее в контейнер сервера в режиме только для чтения. Отредактируйте docker-compose.yml в разделе immich-server: и добавьте volume:

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      - /srv/photos:/mnt/media/photos:ro

Флаг :ro гарантирует, что Immich никогда не сможет изменить оригиналы. Пересоберите контейнер с помощью sudo docker compose up -d, затем в веб-интерфейсе перейдите в меню вашего аватара → Administration → External Libraries → Create Library, выберите владельца, нажмите Add в разделе Folders и введите путь внутри контейнера — /mnt/media/photos, а не путь хоста /srv/photos. Нажмите Scan. Использование пути хоста вместо пути контейнера — самая частая ошибка при работе с внешними библиотеками; в этом случае сканирование не найдет файлов и покажет нулевое количество активов.

Шаг 8: Правила обновления, необходимые для Immich

Этот этап определяет стабильность работы Immich. Разработчики Immich выпускают обновления часто, не переносят исправления в старые версии и не поддерживают откат (downgrade). Использование тега v3 с плавающим тегом (floating tag) приведет к повреждению базы данных. Необходимо соблюдать следующие правила:

  1. Фиксируйте версию. Устанавливайте IMMICH_VERSION на конкретный тег, например v3.0.2, а не на плавающий тег v3, который всегда загружает последнюю версию v3.x.
  2. Всегда читайте примечания к релизу (release notes) перед обновлением. Там указаны критические изменения (breaking changes), особенно касающиеся базы данных или расширений векторов. Пример: в версии v3.0 был полностью удален pgvecto.rs. Пользователям старого расширения необходимо было завершить миграцию на VectorChord (внедренную в v1.133) перед обновлением.
  3. Сначала создайте резервную копию базы данных (Шаг 9). Это обязательно всегда, но особенно если в примечаниях указаны изменения в базе данных.
  4. Также скачайте новый compose file. IMMICH_VERSION фиксирует только образы server и ML. Образ Postgres фиксируется через digest внутри docker-compose.yml, поэтому версии, требующие новых расширений базы данных, поставляются с новым compose file. Скачайте оба файла релиза, заново примените ваши значения .env и выполните обновление.
  5. Обновляйте мобильные клиенты примерно в то же время. Сервер поддерживает только свою мажорную версию, а приложение поддерживает текущую и предыдущую мажорные версии. Если версия сервера новее версии приложения, на телефоне отобразится ошибка Your app major version is not compatible with the server! до момента обновления приложения. Рекомендуется сначала обновить приложение.

Команды для выполнения после подготовки новых файлов:

cd /opt/immich
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Шаг 9: Резервное копирование — дамп базы данных ПЛЮС оригиналы, и проверка восстановления

Резервная копия Immich состоит из двух частей. По отдельности они бесполезны. База данных хранит структуру альбомов, лица, поисковые индексы и соответствие между объектом и файлом. Директория originals содержит сами фотографии. Если восстановить только одну часть, вы получите либо фотографии без организации, либо пустую оболочку со ссылками на отсутствующие файлы.

Создайте дамп базы данных с помощью pg_dump внутри контейнера Postgres — конкретно базу данных immich, а не весь кластер:

sudo docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /opt/immich/immich-db-$(date +%F).sql.gz

Затем создайте резервную копию UPLOAD_LOCATION — всего дерева /opt/immich/library, включая подпапки library/, upload/ и profile/ — с помощью restic, rsync или borg на другой машине или в объектном хранилище. Сначала делайте дамп базы данных, а затем — файлов. Это гарантирует, что дамп не будет ссылаться на фотографии, которые еще не скопированы. Внешние библиотеки необходимо резервировать отдельно в их исходных расположениях; Immich не владеет ими.

Теперь важный этап, который все пропускают: проверьте восстановление. Восстановление должно выполняться на чистом стеке, сервер которого ни разу не запускался, на образе Postgres, расширение vector в котором совместимо с дампом. Именно поэтому нельзя использовать произвольные теги образов БД. На чистой системе с тем же compose и .env удалите все старые данные, запустите только базу данных, а затем загрузите дамп:

cd /opt/immich
sudo docker compose down -v
sudo docker compose pull
sudo docker compose create
sudo docker start immich_postgres
sleep 10
gunzip --stdout immich-db-2026-07-15.sql.gz |
  sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" |
  sudo docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
sudo docker compose up -d

Перезапись sed для search_path обязательна для базы данных VectorChord — если ее пропустить, процесс восстановления прервется. Когда стек запустится с вашими оригиналами, откройте web UI: если фотографии и альбомы на месте, резервное копирование работает корректно. Если вы никогда не проводили эту проверку, у вас нет резервной копии — у вас есть только надежда.

Режимы сбоев и соответствующие сообщения

Контейнер ML завершен по причине OOM-kill. Процесс sudo docker compose logs immich-machine-learning прерывается, docker compose ps указывает на Restarting, а код выхода — 137. sudo dmesg | grep -i oom подтверждает это: Out of memory: Killed process ... (python3). Задания поиска и распознавания лиц приостанавливаются. Причина — недостаточный объем RAM для моделей. Способы решения (в порядке приоритетности): добавьте swap (Шаг 1); увеличьте объем RAM на VPS; если это невозможно, отключите ML в Administration → Settings → Machine Learning Settings, выключив Smart Search и Facial Recognition — вы сохраните бэкапы и альбомы, но потеряете поиск по содержимому. Удаление сервиса immich-machine-learning из compose file дает тот же результат.

Postgres отказывается запускаться после обновления. В логах сервера повторяется строка вида The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded. — или, в старых сборках, The pgvecto.rs extension is not available in this Postgres instance.. Причина — образ базы данных, версия расширения в котором ниже, чем версия обновленных данных. Это происходит при ручном изменении тега образа или восстановлении более свежего дампа на старый образ. Решение — используйте образ Postgres соответствующей версии. Возьмите compose file из релиза, который соответствует вашей базе данных. Не выполняйте downgrade; восстанавливайте данные только на совместимый образ.

Мобильное приложение не может связаться с сервером. После ввода URL на экране входа появляется ошибка соединения / Server is not reachable. Три возможные причины: вы ввели http:// вместо https://, который обслуживает прокси; вы подключились напрямую к backend, но не указали порт, поэтому запрос ушел на example.com (порт 443) вместо example.com:2283; или reverse proxy не пересылает /api. Решение — введите полный URL https://photos.example.com и сначала убедитесь, что он открывается в браузере телефона. Если в браузере всё работает, а в приложении — нет, значит, прокси удаляет путь или используется самоподписанный сертификат — приложение отклоняет недоверенные сертификаты.

Закончилось место на диске во время импорта. Загрузка прерывается, миниатюры становятся пустыми, а в логах отображается ENOSPC: no space left on device или, в случае с Postgres, could not extend file ... No space left on device. df -h показывает, что том UPLOAD_LOCATION заполнен на 100%. Именно поэтому необходимо проверять размер диска перед импортом большой библиотеки. Решение: подключите том большего размера, остановите stack, перенесите UPLOAD_LOCATION в новый том, обновите .env и запустите процесс заново — либо расширьте существующий диск, если это позволяет провайдер. При нехватке места Postgres может зависнуть, поэтому сначала освободите место и перезапустите контейнер базы данных, прежде чем предполагать повреждение данных.

FAQ

Сколько RAM и дискового пространства требуется Immich?

Минимальные официальные требования Immich — 6 GB RAM, рекомендуемые — 8 GB. Практический минимум для небольшой библиотеки составляет 4 GB с учетом swap. В любом случае настройте swap, так как контейнер machine-learning потребляет много ресурсов в моменты пиковых нагрузок. Для дискового пространства закладывайте полный размер вашей библиотеки плюс примерно 10–20% на создание эскизов (thumbnails) и превью на локальном хранилище. Никогда не размещайте директорию данных Postgres на сетевом ресурсе. Если вы выбираете другие сервисы для хостинга, руководство по self-hosting в 2026 году сравнивает нагрузку Immich с другими сервисами.

Можно ли запустить Immich без GPU?

Да. Контейнер machine-learning работает на CPU. GPU только ускоряет индексацию smart-search и транскодирование видео (при использовании соответствующего варианта образа). При использовании CPU начальная индексация большой библиотеки может занять несколько часов в фоновом режиме, но это не мешает резервному копированию или просмотру. Если ресурсов системы недостаточно для ML, вы можете отключить Smart Search и Facial Recognition в настройках администратора, сохранив остальной функционал.

Как безопасно обновить Immich?

Закрепите IMMICH_VERSION конкретным тегом, например v3.0.2, перед каждым обновлением читайте release notes и сначала создайте резервную копию базы данных. Поскольку образ Postgres внутри docker-compose.yml закреплен, а не задан через IMMICH_VERSION, необходимо заново скачать файл compose и example.env для целевой версии, применить ваши настройки и запустить docker compose pull && docker compose up -d. Не используйте плавающие (floating) теги версий — Immich часто выпускает обновления с breaking changes и не поддерживает откат (downgrade) версий.

Что именно нужно архивировать?

Необходимо архивировать две вещи: pg_dump базы данных immich и всю директорию оригиналов UPLOAD_LOCATION. База данных содержит альбомы, лица и соответствие файлов объектам; директория содержит сами фотографии. Для восстановления требуются оба компонента, а также образ базы данных с совместимым расширением vector. Сначала делайте дамп базы данных, а затем копируйте файлы. Минимум один раз протестируйте восстановление на тестовой машине — непроверенная копия не является резервной копией.

Как импортировать существующую папку с фотографиями?

Примонтируйте папку в режиме read-only в контейнер immich-server как дополнительный volume (например, - /srv/photos:/mnt/media/photos:ro), пересоздайте контейнер, затем в Administration → External Libraries создайте библиотеку и добавьте путь внутри контейнера /mnt/media/photos. Immich индексирует файлы на месте и никогда не изменяет и не удаляет их. Самая частая ошибка — указание пути хоста вместо пути внутри контейнера, из-за чего сканирование не находит файлы.

#immich#photos#docker#self-hosting#backups