# ВМ 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).

**Команды:**
```bash
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.

**Команды:**
```bash
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):** увеличить виртуальный диск:
```bash
qm resize 200 scsi1 +350G
```

**2. Внутри ВМ (ssh admin@192.168.1.200):** расширить раздел:
```bash
sudo growpart /dev/sdb 1
```

**3. Внутри ВМ:** расширить файловую систему (онлайн, без размонтирования):
```bash
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):
   ```bash
   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](../maintenance/logrotate/README.md).
- **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

- [x] **Базовая политика logrotate:** для системных логов настроена (homelab-lxc.conf — 14 дней, 50 MB, 5 архивов, как в LXC). См. [Logrotate — базовая политика homelab](../maintenance/logrotate/README.md).
- [x] **Корневой диск:** Расширен до 50 GB (было 35 GB). Логи Docker ограничены.
- [x] **Логи 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, миграции, откат при сбое).

---

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

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