Immich на сервере: частые ошибки и решения

MAATRIX

Immich — самостоятельный аналог Google Photos: автобэкап фото и видео с телефона на свой сервер, распознавание лиц, поиск по содержимому кадра, общие альбомы. Работает через Docker Compose и состоит из нескольких контейнеров — сервера, базы Postgres, Redis, контейнера машинного обучения. Именно эта многослойность и рождает большинство проблем: бэкап с телефона не стартует, распознавание лиц зависает, диск заканчивается быстрее, чем кажется. Разберём частые ошибки Immich по порядку и что с ними делать.

Бэкап с телефона не работает или обрывается

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

• сервер отдаётся по HTTPS с валидным сертификатом (Let's Encrypt через reverse proxy — Traefik или Nginx);
• в адресе приложения указан полный URL с портом, если он нестандартный: https://photos.vashdomen.ru/api;
• reverse proxy не режет keepalive-соединения раньше времени — для Nginx увеличьте таймауты:

proxy_read_timeout 600s;
proxy_send_timeout 600s;
client_max_body_size 50000M;

Отдельная особенность iOS — фоновый бэкап работает не постоянно, а по расписанию ОС и при подключении к Wi-Fi и питанию; это ограничение Apple, а не баг Immich. Проверить, что сервер вообще принимает соединение, можно так:

curl -I https://photos.vashdomen.ru/api/server/ping

Если ответ не приходит — проблема на уровне сети или прокси, а не в самом Immich.

Контейнер machine learning падает или ест всю память

За распознавание лиц, умный поиск по описанию кадра (CLIP) и дубликаты отвечает отдельный контейнер immich-machine-learning. Он же — главный потребитель ресурсов: модели грузятся в память при первом обращении и держатся там. На сервере с 2-4 ГБ RAM контейнер может падать по OOM прямо во время фоновой обработки библиотеки. Посмотреть причину падения:

docker compose logs -f immich-machine-learning
docker stats immich_machine_learning

Если видите Killed в логах или контейнер перезапускается в цикле — не хватает памяти. Варианты: увеличить RAM сервера, либо облегчить модели через переменные окружения в .env:

MACHINE_LEARNING_CLIP_MODEL=ViT-B-32__openai
MACHINE_LEARNING_FACIAL_RECOGNITION_MODEL=buffalo_s

Более лёгкие модели (buffalo_s вместо buffalo_l, ViT-B-32 вместо более крупных) заметно снижают потребление памяти ценой чуть менее точного распознавания. На сервере без выделенного GPU распознавание идёт на CPU и первичная обработка большой библиотеки (несколько тысяч фото) может занимать часы — это ожидаемо, не баг. Про распределение ресурсов между контейнерами подробнее разобрано в статье про лимиты CPU и памяти в Docker.

Ошибки прав доступа на папку с библиотекой

После установки или переноса сервера в логах появляется EACCES: permission denied при попытке сохранить файл или сгенерировать миниатюру. Immich внутри контейнеров работает от пользователя с UID/GID, заданными в .env (PUID/PGID), а папка на хосте, куда смонтирован UPLOAD_LOCATION, часто принадлежит другому пользователю — особенно если вы копировали данные с другого сервера через sudo или rsync от root. Проверьте владельца и приведите его в соответствие:

ls -la /opt/immich/library
chown -R 1000:1000 /opt/immich/library

Значения 1000:1000 — это дефолтные PUID/PGID в официальном .env, но если вы их меняли, используйте свои. После смены владельца перезапустите контейнеры:

docker compose down
docker compose up -d

Отдельно проверьте, что каталог примонтирован именно как том, а не остался пустым внутри контейнера из-за опечатки в пути в docker-compose.yml — тогда файлы «сохраняются», но исчезают при пересоздании контейнера.

Ошибки Postgres и pgvecto при обновлении версии

Immich хранит метаданные в Postgres с расширением для векторного поиска (pgvecto.rs или pgvektor в зависимости от версии образа). Обновление Immich без обновления образа базы данных — частая причина ошибок вида extension "vectors" has no update path или сервер не стартует после docker compose pull. Правило простое: версии сервера и образа Postgres в docker-compose.yml обновляются согласованно, по инструкции конкретного релиза в release notes на GitHub, а не «просто последний тег». Перед любым обновлением обязательно снимите бэкап базы:

docker compose exec -T database pg_dumpall -U postgres > immich_db_backup.sql

Если после обновления сервер не поднимается, смотрите логи именно контейнера базы:

docker compose logs database | tail -n 50

Откатиться проще всего, вернув прежний тег образа в docker-compose.yml и подняв контейнеры заново — база при этом останется совместимой, если вы не успели применить необратимую миграцию. Про резервное копирование Docker-томов в целом — в статье про бэкап Docker volume. Если Postgres падает по нехватке памяти при индексации векторов — это уже классический сценарий, разобранный в статье Postgres out of memory.

Большие видео не загружаются или обрываются

Фото с айфона загружаются, а видео 4K по 500 МБ-1 ГБ — нет: приложение показывает ошибку или зависает на проценте. Здесь две типовые причины. Первая — лимит на размер тела запроса в reverse proxy (см. client_max_body_size выше, для Traefik — аналогичный параметр в middleware). Вторая — таймаут: мобильная сеть отдаёт файл медленно, и если прокси или сам Immich обрывает соединение по времени, а не по объёму, крупные видео будут стабильно падать именно на мобильном интернете, хотя по Wi-Fi всё грузится нормально. Проверьте очередь заданий в интерфейсе (Administration → Jobs) — зависшие задания «Video Conversion» часто указывают не на сеть, а на нехватку CPU для транскодирования: Immich перекодирует видео в совместимый формат фоново, и на слабом процессоре очередь просто растёт быстрее, чем разгребается.

Диск заканчивается быстрее, чем ожидалось

Библиотека на 200 ГБ фото неожиданно занимает 350-400 ГБ на диске. Это не утечка — так работает Immich по умолчанию: он хранит оригиналы, генерирует превью нескольких размеров под галерею и (если включено) перекодированные версии видео. Проверить реальное распределение:

du -sh /opt/immich/library/*

Основной прирост обычно даёт thumbs и encoded-video. Если место критично, ограничьте качество перекодирования видео в настройках сервера (Administration → Storage) или увеличьте диск — на слабом NVMe/SSD экономить на дисковом пространстве под фотобиблиотеку не стоит, читать миниатюры для тысяч фото на медленном диске будет и так небыстро. Про то, как быстро съедается место на VPS и что с этим делать в целом, — в статье закончилось место на диске VPS.

Частые вопросы