Immich

Обзор

Immich — фотоархив для своего сервера, который повторяет привычный сценарий облачной галереи: приложения для Android и iOS автоматически выгружают снимки и видео, а веб-интерфейс показывает ленту по датам, альбомы, карту, воспоминания и общий доступ по ссылке. Подойдёт семье, которая уходит из Google Photos или iCloud, и фотографу, которому нужен архив без ограничений по объёму.

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

Рецепт поднимает четыре контейнера — сервер, машинное обучение, PostgreSQL 14 с векторными расширениями и Valkey. Оригиналы, превью и транскоды лежат в каталоге на хосте, база — в Docker volume. Уровень reliable заявлен как частичный: база вынесена в отдельный сервис и все контейнеры имеют healthcheck, но в рецепте нет лимитов ресурсов и внешнего мониторинга.

Immich активно развивается и до сих пор регулярно вносит несовместимые изменения. Не пропускайте release notes и делайте backup перед каждым обновлением.

Оценка безопасности

Контейнеры запускаются без privileged, host network и доступа к Docker socket, с no-new-privileges; наружу открыт только порт веб-интерфейса и только на 127.0.0.1. PostgreSQL и Valkey доступны исключительно внутри сети Compose. Публичная регистрация в Immich выключена: учётные записи создаёт администратор.

Фотоархив — чувствительные данные: геометки, лица, распорядок жизни. Публикуйте Immich только по HTTPS, включайте двухфакторную аутентификацию, своевременно обновляйте образы и шифруйте копии, покидающие сервер. Пароль PostgreSQL лежит в .env рядом с рецептом — держите файл с правами 600 и вне Git. Рецепт не задаёт лимиты CPU и памяти, поэтому задания машинного обучения на слабом сервере могут вытеснить остальные сервисы; при необходимости добавьте deploy.resources или отключите машинное обучение.

Образы immich-server и immich-machine-learning просканированы Trivy; результат и список CVE показаны в карточке. Valkey и PostgreSQL закреплены по digest, их теги не совпадают с версией приложения, поэтому в автоматическую проверку они не входят — обновляйте их вместе с upstream Compose.

Пошаговая инструкция

1. Проверьте сервер Ubuntu или Debian

Upstream требует минимум 2 ядра CPU и 6 ГБ RAM, рекомендует 4 ядра и 8 ГБ. Под диск закладывайте объём библиотеки плюс 10–20 % на превью и транскоды: этот рецепт держит и оригиналы, и сгенерированные файлы. Нужны Ubuntu 22.04+ или Debian 12+ с Docker Engine и Docker Compose v2.24+.

docker --version
docker compose version
nproc && free -m && df -h /srv

Начиная с v3 контейнер машинного обучения на amd64 требует уровень микроархитектуры x86-64-v2. Проверьте его до установки:

/usr/bin/ld.so --help | grep -m1 x86-64-v2

Если строка отсутствует, ML-контейнер не запустится: на таком сервере остаётся только отключить машинное обучение и потерять умный поиск и распознавание лиц.

2. Подготовьте файлы и переменные

Поместите файлы рецепта в отдельный каталог и создайте закрытый .env:

mkdir -p ~/services/immich
cd ~/services/immich
cp .env.example .env
chmod 600 .env

IMMICH_VERSION закрепляет версию всех образов Immich; IMMICH_PORT задаёт локальный порт; IMMICH_UPLOAD_LOCATION — каталог на хосте с оригиналами, превью, транскодами и автоматическими дампами базы; IMMICH_DB_VOLUME и IMMICH_MODEL_CACHE_VOLUME — имена Docker volume для PostgreSQL и кэша моделей; IMMICH_DB_USERNAME, IMMICH_DB_DATABASE_NAME и IMMICH_DB_PASSWORD — доступ к базе; TZ задаёт часовой пояс.

Обязательно замените пароль базы и укажите каталог библиотеки на диске с запасом места:

sed -i "s|^IMMICH_DB_PASSWORD=.*|IMMICH_DB_PASSWORD=$(openssl rand -hex 24)|" .env
sudo mkdir -p /srv/immich/library
sed -i "s|^IMMICH_UPLOAD_LOCATION=.*|IMMICH_UPLOAD_LOCATION=/srv/immich/library|" .env

Пароль допускает только символы A-Za-z0-9. Менять его после первого запуска нельзя без пересоздания базы, поэтому задайте значение сразу.

3. Создайте администратора

Оставьте порт доступным только на localhost и запустите стек:

docker compose pull
docker compose up -d
docker compose ps
ssh -L 2283:127.0.0.1:2283 user@server.example

Первый запуск дольше обычного: сервер применяет миграции базы. Откройте http://localhost:2283, создайте учётную запись — первая становится администратором — и пройдите мастер первичной настройки. Публичная регистрация в Immich отключена: остальных пользователей администратор заводит в разделе Administration → Users.

Мобильные приложения для Android и iOS подключаются к тому же адресу и включают фоновую загрузку снимков.

Запуск на VPS

На VPS оставьте bind 127.0.0.1, закройте порт 2283 снаружи и публикуйте сервис только через HTTPS reverse proxy. Проверьте состояние стека и API:

docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:2283/api/server/ping

Все четыре контейнера должны быть healthy. Машинное обучение скачивает модели при первом задании, поэтому первые минуты после загрузки снимков нагрузка на CPU высокая — это ожидаемо.

Доступ в локальной сети

Без TLS используйте SSH-туннель или VPN. Если reverse proxy работает на другом узле доверенной LAN, замените 127.0.0.1 в compose.yaml на конкретный LAN-адрес сервера и ограничьте порт firewall адресом proxy. Не публикуйте Immich на 0.0.0.0 без сетевых ограничений: доступ к ленте означает доступ ко всему архиву снимков и геометкам.

Домен и HTTPS

Замените photos.example.com в выбранном файле из proxy/ одним доменом. proxy/Caddyfile автоматически получает сертификат; proxy/nginx.conf ожидает сертификат Certbot; proxy/traefik.yaml использует resolver letsencrypt. Для Traefik в контейнере замените 127.0.0.1 на доступный ему host gateway.

Все три примера снимают ограничение на размер тела запроса и увеличивают таймауты: без этого загрузка видео с телефона обрывается. Проверьте внешний endpoint:

curl --fail https://photos.example.com/api/server/ping

Резервное копирование

chmod +x backup.sh restore.sh
./backup.sh

Скрипт останавливает immich-server и immich-machine-learning, снимает дамп PostgreSQL через pg_dump и архивирует каталог библиотеки, после чего снова запускает контейнеры. Копирование каталога данных PostgreSQL вместо дампа upstream считает небезопасным, поэтому рецепт всегда использует дамп.

Архив содержит оригиналы, превью и всю базу с метаданными и лицами: зашифруйте его и храните хотя бы одну копию вне сервера. Дополнительно Immich сам делает автоматические дампы базы в UPLOAD_LOCATION/backups — по умолчанию ежедневно в 02:00 с хранением 14 последних; они не заменяют копию файлов.

Восстановление

Восстановление полностью заменяет и базу, и каталог библиотеки:

./restore.sh ./backups/immich-YYYYMMDDTHHMMSSZ.tar
docker compose ps
curl --fail http://127.0.0.1:2283/api/server/ping

Перед заменой скрипт создаёт страховочную копию текущих данных, затем удаляет volume базы и накатывает дамп на чистую базу. Это требование upstream: дамп нельзя восстанавливать поверх схемы, с которой уже работал сервер. База и файлы должны относиться к одному снимку, иначе в ленте появятся записи без файлов.

Обновление

Создайте backup и прочитайте release notes: Immich регулярно вносит изменения, требующие ручных действий. Измените только закреплённый IMMICH_VERSION, затем выполните:

./backup.sh
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 immich-server

Обновляйте версии последовательно и не пропускайте мажорные релизы: миграции базы рассчитаны на переход с предыдущей версии.

Откат

Миграции базы Immich необратимы. Запуск старого образа поверх базы, уже мигрированной новой версией, приводит к ошибкам запуска сервера. Верните прежний IMMICH_VERSION в .env и восстановите архив, созданный перед обновлением:

docker compose pull
./restore.sh ./backups/immich-before-update.tar
docker compose ps

Снимки, загруженные после обновления, в таком архиве отсутствуют. Скопируйте их из UPLOAD_LOCATION отдельно до отката, если они нужны.

Остановка и полное удаление

docker compose down удаляет контейнеры, но сохраняет базу и библиотеку. Полное необратимое удаление после проверки backup:

docker compose down
docker volume rm immich-database immich-model-cache
sudo rm -rf /srv/immich/library
rm -rf ~/services/immich

Источники: требования, установка через Docker Compose, переменные окружения, backup и restore и reverse proxy.

Диагностика

Один из контейнеров не становится healthy

docker compose ps
docker compose logs --tail=200 immich-server
docker compose logs --tail=100 database
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q immich-server)"

immich-server не поднимется, пока база не ответит на healthcheck. Если база падает сразу после старта, чаще всего дело в правах на volume или в изменённом IMMICH_DB_PASSWORD при уже созданной базе: пароль задаётся при инициализации и позже переменной не меняется.

Контейнер машинного обучения перезапускается или падает

На amd64 начиная с v3 образу нужен уровень микроархитектуры x86-64-v2:

/usr/bin/ld.so --help | grep -m1 x86-64-v2
docker compose logs --tail=100 immich-machine-learning

Если поддержки нет, отключите машинное обучение в Administration → Settings → Machine Learning и уберите сервис из compose.yaml. Умный поиск, распознавание лиц, дубликаты и OCR при этом работать не будут.

Загрузка с телефона обрывается на больших видео

Ограничение ставит reverse proxy, а не Immich. В Nginx нужны client_max_body_size 0 и увеличенные proxy_read_timeout и proxy_send_timeout, в Caddy — request_body max_size, в Traefik — middleware buffering с maxRequestBodyBytes: 0. Все три примера в proxy/ уже содержат эти настройки.

Мало места на диске, хотя снимков немного

Кроме оригиналов Immich хранит превью и перекодированные видео. Проверьте, что занимает место:

sudo du -sh /srv/immich/library/*
docker system df -v | grep immich

Каталог backups содержит автоматические дампы базы: их глубину задают в Administration → Settings → Backup. Кэш моделей в volume immich-model-cache можно удалить — он скачается заново.

Умный поиск ничего не находит

Проверьте, что задания выполнены: Administration → Job Queues → Smart Search. Модель CLIP по умолчанию понимает только английские запросы. Русский поиск требует мультиязычной модели, которую выбирают в Administration → Settings → Machine Learning → Smart Search; после смены модели нужно перезапустить задание Smart Search для всей библиотеки.

После обновления сервер не стартует

Смотрите логи миграций:

docker compose logs --tail=200 immich-server | grep -i migration

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

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

База и файлы взяты из разных снимков. Восстановите согласованную пару архивом, созданным backup.sh, и не смешивайте database.sql.gz из одного архива с library.tar.gz из другого.

restore.sh завершается ошибкой psql

Дамп нельзя накатывать на базу, с которой уже работал сервер. Скрипт удаляет volume базы перед восстановлением; если вы восстанавливаете вручную, убедитесь, что база пустая, а immich-server ни разу не запускался после её создания.