homelab-docs/docs/containers/container-200.md

ВМ 200 (Immich): Immich, PostgreSQL, Redis, ML, deduper

Подробное описание KVM-ВМ 200 на Proxmox (192.168.1.200): хост для Immich (фото/видео), PostgreSQL, Redis (Valkey), Immich Machine Learning (CUDA), upload-optimizer, power-tools, public-proxy и отдельный стек immich-deduper + Qdrant. Домен: immich.katykhin.ru. Данные и Docker размещены на отдельном диске /mnt/data (350 GB).

---

Общие сведения

• Тип: KVM-виртуальная машина (управление: qm на Proxmox).
• Имя ВМ: immich
• IP: 192.168.1.200/24
• ОС: Debian 13 (trixie)
• Ресурсы: 3 core, 10 GB RAM, GPU (hostpci0 для VGA; ML-контейнер с NVIDIA).
• Доступ: SSH под пользователем admin (не root): ssh admin@192.168.1.200 с хоста 192.168.1.150 или из LAN. Для выполнения команд с правами root: sudo ....

Диски:

• Корневой диск (sda1): 50 GB — система, образы/кэш в пределах корня. Логи Docker ограничены (см. ниже).
• Данные (sdb1): 350 GB, смонтирован в /mnt/data. Здесь: библиотека Immich, БД PostgreSQL, Docker root, containerd, Ollama, данные deduper.

---

Доступ и логины

• ВМ (Debian): пользователь admin (вход по SSH-ключу или паролю; пароль задан при cloud-init, хранить в менеджере паролей). Root через sudo.
• Immich (веб): учётные записи — пользователи Immich (создаются в веб-интерфейсе). Доступ к сервисам:

Сервис	Доступ	Адрес
Immich	Публичный (NPM)	https://immich.katykhin.ru
Power Tools	Публичный (Basic Auth в NPM)	https://immich-pt.katykhin.ru
Public Share	Публичный (NPM)	https://share.katykhin.ru
Deduper	Только LAN	http://192.168.1.200:8086

Логины и пароли Power Tools / Immich — в менеджере паролей; в открытую документацию не вносить.

---

Сервисы (Docker Compose)

Два проекта:

1. Immich — /opt/immich/docker-compose.yml. Сеть immich_default; дополнительно сеть immich-deduper (external) для доступа postgres к deduper.
2. immich-deduper — /opt/immich-deduper/docker-compose.yml. Сеть immich-deduper (external), общая с Immich для доступа к БД.

Контейнер	Образ / тег	Порты (хост)	Назначение
immich_upload_optimizer	miguelangel-nubla/immich-upload-optimizer:latest	2283	Прокси перед Immich (оптимизация загрузок); NPM смотрит сюда
immich_server	immich-app/immich-server:v2	2284→2283	Основное приложение Immich
immich_postgres	immich-app/postgres:14-vectorchord...	—	PostgreSQL с расширениями (pgvector и др.)
immich_redis	valkey/valkey:9	—	Кэш/очереди
immich_machine_learning	immich-app/immich-machine-learning:v2-cuda	—	ML (распознавание и т.д.), с GPU
immich_power_tools	varun-raj/immich-power-tools:latest	8001→3000	Дополнительные утилиты
immich_public_proxy	alangrainger/immich-public-proxy:latest	8501→3000	Публичный прокси к Immich
immich-deduper	razgrizhsu/immich-deduper:latest-cpu	8086	Поиск дубликатов
immich-deduper-qdrant	qdrant/qdrant:v1.16.3	—	Векторная БД для deduper

---

1. Immich (основной стек)

Каталог: /opt/immich/
Compose: docker-compose.yml, переменные из .env (не коммитить).

Порты: Внешний доступ в NPM настроен на 2283 (upload_optimizer). Дополнительно открыты: 2284 (server), 8001 (power-tools), 8501 (public-proxy).

Пути из .env (на хосте):

• UPLOAD_LOCATION — каталог загруженных файлов (фото/видео). На момент проверки: /mnt/data/library (~148 GB).
• DB_DATA_LOCATION — данные PostgreSQL. На момент проверки: /mnt/data/postgres (~657 MB).

Тома (по умолчанию из .env):

• ${UPLOAD_LOCATION} → /data в immich_server (и в upload_optimizer через upstream).
• ${DB_DATA_LOCATION} → /var/lib/postgresql/data в immich_postgres.
• model-cache (volume) → кэш моделей ML в immich_machine_learning.
• /etc/localtime — для времени.

Переменные окружения (.env): DB_PASSWORD, DB_USERNAME, DB_DATABASE_NAME, DB_HOST, DB_PORT, IMMICH_URL, IMMICH_API_KEY, EXTERNAL_IMMICH_URL, GEMINI_API_KEY (и др.). Файл содержит секреты — не публиковать, ограничить права (chmod 600).

Команды:

cd /opt/immich && docker compose up -d
docker logs immich_server
docker logs immich_upload_optimizer

---

2. Immich Machine Learning

Использует образ с CUDA и deploy.resources.reservations.devices (nvidia, count: 1). Кэш моделей в volume model-cache. Контейнер не публикует порты; общается с immich_server по внутренней сети.

---

3. Upload optimizer, power-tools, public-proxy

• immich_upload_optimizer: принимает трафик на 2283, проксирует на immich-server:2283. NPM проксирует https://immich.katykhin.ru на 192.168.1.200:2283.
• power-tools: веб-интерфейс на порту 8001 (внутри LAN).
• immich_public_proxy: порт 8501, прокси к immich-server:2283 (для публичных ссылок и т.п.).

---

4. PostgreSQL и Redis

• immich_postgres: данные в /mnt/data/postgres. Healthcheck включён. Подключение из deduper через сеть immich-deduper (database подключён к default и immich-deduper).
• immich_redis: Valkey 9, без постоянного тома в стандартной конфигурации (при перезапуске кэш сбрасывается).

---

5. immich-deduper

Каталог: /opt/immich-deduper/
Compose: docker-compose.yml, переменные из .env.

Порты: 8086 (хост).

Тома (из .env):

• DEDUP_DATA — каталог данных deduper (на момент проверки: /opt/immich-deduper/data, ~231 MB с учётом всего каталога). Внутри: кэш и данные Qdrant (DEDUP_DATA/qdrant).
• IMMICH_PATH — путь к библиотеке Immich только для чтения (/mnt/data/library).
• Подключение к БД Immich через переменные PSQL_* и сеть immich-deduper.

Команды:

cd /opt/immich-deduper && docker compose up -d
docker logs immich-deduper

---

Порты (сводка на хосте)

Порт	Сервис / примечание
2283	Upload optimizer (основной вход для NPM)
2284	Immich server (прямой доступ)
8001	Power-tools
8501	Public proxy
8086	immich-deduper

---

Расширение диска данных (без даунтайма)

Диск данных ВМ (sdb1, /mnt/data) можно увеличить на Proxmox без остановки Immich. Пример: с 350 GB до 700 GB.

1. На хосте Proxmox (192.168.1.150): увеличить виртуальный диск:

qm resize 200 scsi1 +350G

2. Внутри ВМ (ssh admin@192.168.1.200): расширить раздел:

sudo growpart /dev/sdb 1

3. Внутри ВМ: расширить файловую систему (онлайн, без размонтирования):

sudo resize2fs /dev/sdb1

Операция занимает порядка 30 секунд; перезагрузка не требуется.

---

Включение Machine Learning и Smart Search

После загрузки фото можно включить ML (распознавание, смарт-поиск). Предусловия: GPU passthrough в ВМ настроен и работает (nvidia-smi внутри ВМ), в compose для immich-machine-learning заданы runtime: nvidia и deploy.resources.reservations.devices (nvidia).

1. Включить ML через API (подставить свой API-ключ из .env или из веб-интерфейса Immich → Administration → API Keys):

   curl -s "http://192.168.1.200:2284/api/system-config" -H "x-api-key: YOUR_API_KEY" | \
     python3 -c "import sys,json; c=json.load(sys.stdin); c['machineLearning']['enabled']=True; print(json.dumps(c))" | \
     curl -s -X PUT "http://192.168.1.200:2284/api/system-config" -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -d @-
   

2. Сменить CLIP-модель для поиска на русском: Immich UI → Administration → Settings → Machine Learning → Smart Search → Model Name: nllb-clip-large-siglip__mrl → Save.

3. Язык пользователя: в настройках пользователя Immich выставить русский (NLLB-модель ожидает запросы на языке из настроек).

4. Запустить переиндексацию: Administration → Jobs → Smart Search → нажать «All». На большом объёме фото (порядка десятков тысяч) на GPU займёт 20–30 минут.

5. По желанию снизить RAM ВМ до 8 GB после индексации (на хосте Proxmox): qm set 200 --memory 8192 --cores 3.

---

Логи и ротация

• Базовая политика (как в LXC): на ВМ настроен logrotate /etc/logrotate.d/homelab-lxc.conf — 14 дней, 50 MB, 5 архивов, сжатие (системные логи в /var/log). На ВМ 200 пакет logrotate был установлен вручную (в образе по умолчанию не было); после установки активен таймер logrotate.timer. Подробнее: Logrotate — базовая политика homelab.
• Docker: данные Docker (образы, контейнеры, overlay) хранятся в /mnt/data/docker (Docker Root Dir). Логи контейнеров — драйвер json-file с ограничениями в /etc/docker/daemon.json: max-size: "10m", max-file: "3" (до 30 MB на контейнер). Логи пишутся в /mnt/data/docker/containers.
• Системный logrotate: стандартные правила (apt, dpkg, cloud-init, unattended-upgrades, wtmp) плюс homelab-lxc.conf. Отдельных правил для Immich или Docker нет.

Корневой диск расширен до 50 GB; логи Docker ограничены.

---

Запуск и порядок поднятия

1. Создать внешнюю сеть (если ещё нет):
   docker network create immich-deduper
2. Immich:
   cd /opt/immich && docker compose up -d
   Порядок: database, redis → immich-server (и ML, upload_optimizer, power_tools, public_proxy).
3. Deduper:
   cd /opt/immich-deduper && docker compose up -d

После смены .env или compose: перезапуск соответствующих стеков. Обновление образов: docker compose pull && docker compose up -d (для Immich при обновлении проверять совместимость БД и миграции).

---

Уязвимости и риски

1. Секреты в .env: В /opt/immich/.env и /opt/immich-deduper/.env хранятся пароли БД, API-ключи (IMMICH_API_KEY, GEMINI_API_KEY), креды для deduper (PSQL_*). Файлы не должны попадать в публичный репозиторий. Ограничить права (chmod 600), хранить бэкапы в защищённом месте.
2. Корневой диск: Расширен до 50 GB; логи Docker ограничены (10m × 3 файла на контейнер). Следить за местом при обновлениях.
3. Доступ по портам: Сервисы доступны по 2283, 2284, 8001, 8501, 8086 из LAN. Снаружи доступ только через NPM (https://immich.katykhin.ru → 2283). Не пробрасывать порты напрямую в интернет.
4. GPU и PCI-passthrough: ВМ использует hostpci0 (VGA). Убедиться, что драйверы NVIDIA и доступ к GPU корректны для immich_machine_learning.

---

TODO по ВМ 200

• Базовая политика logrotate: для системных логов настроена (homelab-lxc.conf — 14 дней, 50 MB, 5 архивов, как в LXC). См. Logrotate — базовая политика homelab.

• Корневой диск: Расширен до 50 GB (было 35 GB). Логи Docker ограничены.

• Логи Docker: В /etc/docker/daemon.json заданы log-driver: json-file, max-size: "10m", max-file: "3". Логи в /mnt/data/docker/containers.

• Права на конфиги: Ограничить доступ к .env (chmod 600), не коммитить в публичные репозитории.

• Резервное копирование: Регулярный бэкап критичных данных (оценка размеров на момент документации):

  • /mnt/data/library — библиотека Immich (фото, видео, превью). ~148 GB. Основной объём; бэкап обязателен (внешний диск, сетевое хранилище).
  • /mnt/data/postgres — данные PostgreSQL Immich. ~657 MB. Для консистентного бэкапа предпочтительно дамп:
    docker exec immich_postgres pg_dump -U <DB_USERNAME> <DB_DATABASE_NAME> > backup_immich_$(date +%Y%m%d).sql (подставить из .env). Хранить дампы вне ВМ.
  • /opt/immich — docker-compose.yml, .env (секреты), hwaccel.ml.yml. ~20 KB. Обязательно; .env не коммитить.
  • /opt/immich-deduper — docker-compose.yml, .env, каталог data (данные и кэш Qdrant). ~231 MB. Восстановление deduper возможно заново, но данные индексов — в data.
  • /mnt/data/docker — образы и метаданные контейнеров (~16 GB). При восстановлении ВМ образы можно заново скачать; при необходимости бэкапить только метаданные томов или полный каталог.
  • /mnt/data/ollama — данные Ollama (~4.1 GB). Бэкапить при использовании Ollama на этой ВМ.

  Учитывать, что /mnt/data смонтирован с отдельного диска (tank или аналог в Proxmox); при бэкапе с хоста включить этот диск или снапшоты.

• Документация по обновлению Immich: Зафиксировать процедуру обновления (версия в IMMICH_VERSION, backup БД, docker compose pull, миграции, откат при сбое).

---

Связь с другими документами

• Архитектура и подключение — таблица контейнеров и ВМ, домен immich.katykhin.ru, схема сети.
• Контейнер 100 (nginx) — NPM, через который проксируется immich.katykhin.ru.
• Paperless + Ollama: поиск по документам — использование Ollama (обычно на этой ВМ) для ответов по документам из Paperless.