242 lines
18 KiB
Markdown
242 lines
18 KiB
Markdown
# ВМ 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): 35 GB, занято **~29 GB (87%)** — система, образы/кэш в пределах корня. **Критично:** мало свободного места; при росте логов или обновлениях возможны сбои. Следить за местом и логированием (см. TODO).
|
||
- **Данные** (sdb1): 344 GB, смонтирован в **/mnt/data**, занято ~177 GB (55%). Здесь: библиотека 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`.
|
||
|
||
---
|
||
|
||
## Логи и ротация
|
||
|
||
- **Docker:** данные Docker (образы, контейнеры, overlay) хранятся в **/mnt/data/docker** (Docker Root Dir). Логи контейнеров — драйвер **json-file** без ограничения размера и количества файлов (Config:{} у immich_server и immich_postgres). При активной работе логи могут разрастаться и занимать место на **корневом** разделе (если логи пишутся на корень) или в overlay на /mnt/data — уточнить расположение логов контейнеров (часто в /mnt/data/docker/containers). В любом случае ограничение логов не задано (см. TODO).
|
||
- **Системный logrotate:** стандартные правила (apt, dpkg, cloud-init, unattended-upgrades, wtmp). Отдельных правил для Immich или Docker нет.
|
||
|
||
**Риск:** корневой диск заполнен на 87%. Рост логов, обновления и кэш могут привести к нехватке места. Необходимо ограничить логи Docker и следить за местом на корне (см. TODO).
|
||
|
||
---
|
||
|
||
## Запуск и порядок поднятия
|
||
|
||
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. **Корневой диск 87%:** Критично мало свободного места. При 100% возможны сбои обновлений и работы сервисов. Срочно: освободить место и/или перенести часть данных на /mnt/data, ограничить логи Docker (см. TODO).
|
||
3. **Логи Docker без лимитов:** Ротация не настроена — возможен рост логов и заполнение диска.
|
||
4. **Доступ по портам:** Сервисы доступны по 2283, 2284, 8001, 8501, 8086 из LAN. Снаружи доступ только через NPM (https://immich.katykhin.ru → 2283). Не пробрасывать порты напрямую в интернет.
|
||
5. **GPU и PCI-passthrough:** ВМ использует hostpci0 (VGA). Убедиться, что драйверы NVIDIA и доступ к GPU корректны для immich_machine_learning.
|
||
|
||
---
|
||
|
||
## TODO по ВМ 200
|
||
|
||
- [ ] **Корневой диск:** Снизить использование корня (87%). Варианты: перенести логи Docker на /mnt/data (если сейчас пишутся на корень), очистить старые образы/кэш (`docker system prune` с осторожностью), увеличить размер корневого диска ВМ в Proxmox. Настроить мониторинг и оповещение при заполнении >90%.
|
||
- [ ] **Логи Docker:** Включить ограничение размера логов для всех контейнеров Immich и deduper: в `docker-compose.yml` добавить для каждого сервиса `logging: driver: json-file options: max-size: "100m" max-file: "3"` или задать default в `/etc/docker/daemon.json`. Убедиться, что Docker Root Dir остаётся на /mnt/data и логи не пишутся на корень. После изменений перезапустить контейнеры.
|
||
- [ ] **Права на конфиги:** Ограничить доступ к .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.
|