SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor · Обновлено 2026-08-28

Настройка Immich: требования к RAM и обновление сервера

Узнайте, как избежать ошибки exit 137 при нехватке 6 ГБ RAM, настроить HTTPS на порту 2283 и решить проблему несовместимости базы pgvecto.rs при обновлении Immich v3.

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

Immich — это сервис для резервного копирования фото и видео с возможностью самостоятельного хостинга, полноценная замена Google Photos. В нем есть мобильное приложение, которое загружает снимки с камеры в фоновом режиме, а также функции временной шкалы, альбомов, распознавания лиц и поиска на основе машинного обучения, который находит «пляж» или конкретного человека без необходимости ручной разметки. Вы запускаете его на собственном VPS, оригинальные файлы хранятся на вашем диске, и никто не сканирует их для показа рекламы. Если вы все еще выбираете между ним и другим очевидным кандидатом, в нашем сравнении PhotoPrism и Immich приведены их требования к оперативной памяти, возможности мобильных приложений и команды для резервного копирования.

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

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

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

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

Самая частая причина сбоя Immich на небольших VPS — завершение процесса ML-контейнера по сигналу OOM (Out of Memory). Сначала предоставьте ядру дополнительное пространство для работы.

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 оперативной памяти.

Шаг 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 и распознавание лиц. Кэширует загруженные модели в томе model-cache. Этот сервис наиболее требователен к оперативной памяти.
  • database (контейнер immich_postgres) — Postgres с расширением VectorChord, которое обеспечивает работу поиска по сходству. Тег образа зафиксирован по хешу прямо в файле 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 должен указывать на ваш основной диск. Если вы планируете подключить том с данными позже, сразу установите путь к точке его монтирования, так как перенос данных впоследствии потребует перемещения миниатюр и обновления путей к ресурсам. Параметр 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. Разместите reverse proxy перед портом 2283 и завершайте TLS на нём. Если вы уже запускаете несколько контейнеров, Traefik с автоматическим TLS для нескольких Docker-приложений — самый аккуратный вариант: один блок labels направляет photos.example.com в контейнер immich-server и сам получает сертификат. Если вы предпочитаете nginx, руководство Let's Encrypt с Certbot и nginx поможет получить сертификат и блок proxy_pass http://127.0.0.1:2283;. После настройки прокси добавление следующего сервиса обычно сводится к созданию нового поддомена. Так рядом с Immich на том же сервере можно разместить медиаклиент вроде Halcyon, оболочки для Jellyfin в стиле видеопроката 90-х. То же относится к самостоятельно размещаемому HarnessRouter, который предоставляет Codex и Claude Code через единый API. Он намеренно привязывается к loopback и становится доступен только после того, как прокси завершает TLS перед ним. Поэтому измените его пароль по умолчанию до того, как укажете на него поддомен. Однако не каждому контейнеру нужен публичный hostname. Например, административный инструмент вроде самостоятельно размещаемого сканера безопасности open-kritt лучше вообще не включать в прокси, а подключаться к его UI через SSH-туннель только при необходимости. Другие сервисы не используют прокси, потому что вообще не работают по HTTP. Яркий пример — самостоятельно размещаемый relay-сервер RustDesk. Он прослушивает несколько портов TCP и UDP и требует правил firewall, а не поддомена. Для Immich важна одна настройка прокси: увеличьте лимит размера загрузки, поскольку видео с телефона занимают много места. В nginx это client_max_body_size 50000M; внутри server block. Значение по умолчанию 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: и добавьте том:

  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 выпускает обновления часто, не выполняет бэкпорт исправлений и не поддерживает откат версий. Слепое использование плавающего тега v3 в конечном итоге приведет к повреждению базы данных. Привычка фиксировать версию, а затем читать примечания к выпуску, полезна для любого долгоживущего контейнера на сервере. Именно поэтому агент KiroCrew для self-hosted решений фиксируется на конкретном проверенном теге, а не обновляется автоматически при каждой перезагрузке. Дисциплина включает следующие правила:

  1. Фиксируйте версию. Установите IMMICH_VERSION на конкретный тег, например v3.0.2, а не на плавающий v3, который всегда загружает новейшую версию v3.x.
  2. Всегда читайте примечания к выпуску перед обновлением. В них указываются критические изменения, особенно касающиеся базы данных или векторных расширений. Выпуск v3.0 — наглядный пример: в нем полностью удалили pgvecto.rs, поэтому пользователям старого расширения пришлось завершить миграцию на VectorChord (представленную еще в v1.133) перед обновлением.
  3. Сначала создайте резервную копию базы данных (Шаг 9). Это правило действует всегда, но особенно важно, если в примечаниях упоминается база данных.
  4. Загружайте новый compose-файл. IMMICH_VERSION фиксирует только образы сервера и ML. Образ Postgres фиксируется по дайджесту внутри docker-compose.yml, поэтому для версий, требующих новых расширений базы данных, выпускается новый compose-файл. Загрузите оба файла из релиза, повторно примените свои значения .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 состоит из двух частей, и одна без другой бесполезна. База данных хранит структуру альбомов, лица, поисковые индексы и карту соответствия ресурсов файлам. Директория с оригиналами содержит сами фотографии. Если восстановить что-то одно, вы получите либо фотографии без организации, либо пустую оболочку, указывающую на отсутствующие файлы. Такая двухкомпонентная структура — не особенность Immich: системе поддержки Chatwoot требуется такая же пара из дампа Postgres и директории с загрузками, иначе восстановленный почтовый ящик останется без вложений. Копирование директории данных Postgres как файлового дерева выглядит как быстрый способ обойти этап создания дампа, но это не является пригодной для использования резервной копией. Это ловушка, которую полное руководство по резервному копированию и восстановлению Immich разбирает наряду с ошибкой при восстановлении, из-за которой вы остаетесь с пустой лентой событий.

Создайте дамп базы данных с помощью 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 на другую машину или в объектное хранилище. Любой планировщик, выполняющий эту задачу — запись в cron или таймер systemd — должен иметь способ оповещения об ошибках. Юнит systemd OnFailure=, настроенный на ваш собственный сервер уведомлений ntfy, пришлет сообщение на телефон в ту же ночь, когда дамп не удастся создать, вместо того чтобы вы узнали об этом только во время восстановления. Сначала делайте базу данных, затем файлы, чтобы дамп никогда не ссылался на фотографию, которую резервное копирование файлов еще не успело скопировать. Внешние библиотеки копируйте отдельно из их реального источника; 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; если ее пропустить, восстановление прервется на полпути. Когда стек поднимется с вашими оригиналами на месте, откройте веб-интерфейс: если ваши фотографии и альбомы на месте, значит, резервное копирование работает. Если вы никогда этого не делали, у вас нет резервной копии, у вас есть только надежда.

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

Контейнер 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). Задачи поиска и распознавания лиц при этом зависают. Причина — нехватка оперативной памяти для моделей. Способы исправления в порядке приоритета: добавьте swap (шаг 1); увеличьте объем RAM на VPS; или, если это невозможно, отключите ML в разделе Administration → Settings → Machine Learning Settings, выключив Smart Search и Facial Recognition. Вы сохраните резервные копии и альбомы, но потеряете возможность поиска по содержимому. Удаление сервиса immich-machine-learning из файла compose дает аналогичный результат.

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 из релиза, соответствующего вашей базе данных, не выполняйте понижение версии (downgrade) и восстанавливайте данные только на совместимый образ.

Мобильное приложение не может подключиться к серверу. На экране входа после ввода URL отображается ошибка подключения / Server is not reachable. Есть три причины: вы ввели http://, хотя прокси обслуживает только https://; вы подключились напрямую к бэкенду, но не указали порт, поэтому приложение обратилось к example.com (порт 443) вместо example.com:2283; или обратный прокси не пересылает /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%. Именно поэтому размер диска нужно рассчитывать до импорта большой библиотеки. Для восстановления подключите диск большего объема, остановите стек, переместите UPLOAD_LOCATION на новый диск, обновите .env и запустите стек снова. Либо расширьте существующий диск, если ваш провайдер это позволяет. Postgres может зависнуть при заполнении диска, поэтому перед тем, как делать выводы о повреждении данных, освободите место и перезапустите контейнер базы данных.

FAQ

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

Официальные требования Immich составляют минимум 6 ГБ оперативной памяти, рекомендуется 8 ГБ. На практике для небольшой библиотеки нижним пределом является 4 ГБ при наличии swap. В любом случае настройте swap, так как контейнер машинного обучения вызывает резкие скачки потребления ресурсов. Для диска закладывайте объем вашей библиотеки плюс примерно 10–20% на создаваемые миниатюры и превью. Используйте локальное хранилище; никогда не размещайте каталог данных Postgres на сетевом диске. Если вы еще решаете, что запускать, руководство по self-hosted сервисам на 2026 год сравнивает потребление ресурсов Immich с другими сервисами.

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

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

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

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

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

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

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

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

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