Immich: настройка памяти и безопасное обновление

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

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

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

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

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

Шаг 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 через reverse proxy и правило полного URL

Мобильному приложению крайне желательно использовать HTTPS, как только оно выходит за пределы вашей домашней сети. Разместите reverse proxy перед портом 2283 и завершайте TLS на нем. Если вы уже используете несколько контейнеров, Traefik with automatic TLS for multiple Docker apps — самый аккуратный вариант: один блок меток направляет photos.example.com в контейнер immich-server и автоматически получает сертификат. Если вы предпочитаете nginx, руководство Let's Encrypt with Certbot and nginx поможет получить сертификат и блок proxy_pass http://127.0.0.1:2283;. Как только прокси настроен, добавление следующего сервиса сводится к созданию нового поддомена; именно так медиа-интерфейс, например Halcyon, the 90s video store skin for Jellyfin, оказывается рядом с Immich на одном сервере. То же самое касается a self-hosted HarnessRouter putting Codex and Claude Code behind one API, который намеренно привязывается к loopback и становится доступным только после того, как прокси завершит TLS перед ним, поэтому измените его стандартные учетные данные перед тем, как указывать на него поддомен. Однако не каждый контейнер должен иметь публичное имя хоста: инструмент только для администратора, такой как a self-hosted open-kritt security scanner, лучше вообще не выводить через прокси, а обращаться к нему через SSH-туннель в редких случаях, когда вам нужен его интерфейс. Другие сервисы обходятся без прокси, так как HTTP — не их протокол; a self-hosted RustDesk relay server — самый наглядный пример, он слушает ряд «сырых» TCP и UDP портов и требует настройки правил файрвола, а не поддомена. Одна настройка прокси важна для Immich: увеличьте лимит размера загружаемых файлов, так как видео с телефонов занимают много места. В nginx это client_max_body_size 50000M; внутри блока server, стандартное значение 1 МБ отклоняет загрузку видео с ошибкой 413 Request Entity Too Large. Если ваш прокси также отвечает на HTTP-01 вызовы Let's Encrypt, убедитесь, что /.well-known/immich по-прежнему направляется в Immich, а не обработчику вызовов.

Правило, которое соблюдает приложение: эндпоинт должен быть доступен точно по тому URL, который вы вводите. Приложение примет обычный http://YOUR_SERVER_IP:2283 (его собственная подсказка для входа — http://your-server-ip:port), но всё, что передается через интернет, должно быть защищено HTTPS. Неверная схема или прямой 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 — это официально поддерживаемый способ следить за релизами. Разработчики Immich стараются ограничивать критические изменения мажорными версиями, но обновление происходит при каждом выполнении команды pull, независимо от того, читали ли вы примечания к релизу. Незапланированное обновление невозможно отменить. Эту же привычку — сначала зафиксировать версию, а затем прочитать примечания — стоит применять к любому долгоживущему контейнеру на сервере. Именно поэтому агент 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. Сначала обновляйте мобильные клиенты. Сервер взаимодействует только с соответствующей ему мажорной версией, а приложение обычно совместимо с текущей и предыдущей мажорными версиями. Когда версия сервера новее версии приложения, текущие релизы (v3.3.1, проверено 2026-10-10) отображают уведомление App update is available с кнопкой Update на телефоне. Immich рекомендует обновлять все мобильные клиенты до обновления сервера.

Фактические команды после того, как вы подготовили новые файлы:

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; или, если это невозможно, перейдите в Administration → Settings → Machine Learning Settings и выключите главный переключатель машинного обучения, что отключит все функции ML сразу. Отключения только Smart Search и Facial Recognition недостаточно, так как OCR и другие типы моделей остаются включенными по умолчанию. Вы сохраните резервные копии и альбомы, но потеряете поиск по содержимому. Удаление сервиса immich-machine-learning из файла compose дает тот же результат.

Сервер Immich не запускается после обновления. Контейнер Postgres может работать нормально; именно immich_server при запуске проверяет версию векторного расширения и отказывается стартовать, а его лог зацикливается с сообщением вида 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 из релиза, который соответствует вашей базе данных, не делайте даунгрейд и восстанавливайте данные только на совместимый образ.

Мобильное приложение не может подключиться к серверу. На экране входа после ввода URL появляется ошибка соединения, например Could not connect to server. Типичные причины: вы ввели http://, хотя прокси обслуживает только https://; вы подключились напрямую к backend, но не указали порт, поэтому попытка идет на example.com (порт 443) вместо example.com:2283; reverse proxy не пересылает /api; или прокси, отвечающий за Let's Encrypt HTTP-01 challenges, направляет /.well-known/immich куда-то, кроме Immich. Решение: введите полный URL https://photos.example.com и сначала убедитесь, что он открывается в браузере телефона. Если в браузере работает, а в приложении нет, значит, прокси обрезает путь или неверно маршрутизирует /.well-known/immich, либо используется самоподписанный сертификат, который приложение отклоняет с ошибкой рукопожатия (handshake error), если в настройках не включена поддержка самоподписанных сертификатов.

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

Как безопасно обновить 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 индексирует файлы на месте и никогда не изменяет и не удаляет их. Самая частая ошибка — указание пути хоста вместо пути контейнера, из-за чего сканирование ничего не находит.