Документация

Документация предназначена для администраторов, которые размещают Wanmory на NAS, домашнем сервере или личном компьютере. Здесь описаны установка, настройка, развёртывание ИИ-сервиса, повседневная работа, системные настройки и обслуживание. Об устройстве системы и алгоритмах — в разделе Архитектура.

Wanmory — открытая частная фототека с ИИ для размещения на своём сервере. Система состоит из четырёх контейнеров: бэкенда на Go (server), сервиса ИИ-инференса на Python (ml), базы данных PostgreSQL + pgvector (postgres) и mdns, который объявляет локальный домен. Все фото, метаданные, векторы и очередь задач хранятся локально, без зависимости от облачных сервисов.

• Работа с фото: хронология по месяцам, альбомы и умные альбомы, разбор серий и похожих снимков, карта путешествий, слайд-шоу.
• Возможности ИИ: обнаружение и группировка лиц, поиск на естественном языке (Chinese-CLIP), распознавание текста (PP-OCR), эстетическая оценка (выбор ИИ).
• Несколько участников: отдельные учётные записи, право удаления по принципу владения, история входов.

Способ 1: скрипт установки (рекомендуется)

На 64-битной машине с установленным Docker выполните:

curl -fsSL https://wanmory.com/install.sh | bash

Скрипт по порядку делает следующее:

• Проверка окружения: архитектура CPU (amd64 / arm64) и 64-битное пользовательское окружение, наличие Docker и Docker Compose v2, свободная память и место на диске.
• Интерактивная настройка: каталог установки (по умолчанию ~/wanmory), порт (по умолчанию 8080, проверяется занятость), локальный домен (по умолчанию wanmory.local), пароль базы данных (по умолчанию случайный) и расположение базы (по умолчанию том Docker pgdata, можно указать каталог на локальном диске), часовой пояс (введите город или регион для поиска, например shanghai, tokyo или 北京; при нескольких совпадениях выберите номер).
• Места хранения: каталог данных (миниатюры, превью и загруженные фото, по умолчанию ./data) и каталог моделей ИИ (по умолчанию ./models).
• Вопросы и вывод скрипта — на английском, чтобы корректно отображаться в любом терминале NAS.
• Существующие папки с фото: добавляйте сколько нужно, для каждой выбирая подключение только для чтения (рекомендуется) или для чтения и записи.
• Создаёт .env (права 600); если указаны папки с фото, создаёт также docker-compose.override.yml, который Docker Compose подхватывает автоматически.
• Скачивает официальный docker-compose.yml (если GitHub недоступен — с Gitee), проверяет конфигурацию, загружает образы, запускает сервисы и, когда всё готово, выводит адрес.

# Пример: установка без вопросов в /opt/wanmory на порт 9000 с подключением папок с фото NAS
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

Способ 2: ручная установка

1. 1
   Создайте каталог и скачайте файл Compose

   Создайте каталог для файла Compose, данных и моделей и скачайте официальный docker-compose.yml:

   bashКопировать

   mkdir -p ~/wanmory && cd ~/wanmory
   curl -fsSLO https://raw.githubusercontent.com/i-dj/wanmory/main/docker/docker-compose.yml

2. 2
   (Необязательно) Создайте .env

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

   .envКопировать

   WANMORY_DB_PASSWORD=замените-на-случайную-строку
   WANMORY_PORT=8080
   WANMORY_TZ=Europe/Moscow
   WANMORY_VERSION=latest

3. 3
   Запустите сервисы

   При первом запуске загружаются образы и автоматически выполняются миграции базы данных:

   bashКопировать

   docker compose up -d
   docker compose ps        # убедитесь, что все четыре сервиса running / healthy

4. 4
   Откройте и настройте

   Откройте в браузере http://wanmory.local:8080 (или http://<IP хоста>:8080), создайте учётную запись администратора по подсказкам и загрузите модели в «Системные настройки → ИИ». После загрузки моделей существующие фото автоматически встают в очередь ИИ.

Официальный файл Compose описывает четыре сервиса: базу данных postgres, бэкенд server, объявление локального домена mdns и встроенный ИИ-сервис ml. Назначение каждого параметра указано прямо в файле:

# Официальный файл Compose для Wanmory: выполните docker compose up -d в каталоге этого файла
# Переменные вида ${VAR:-значение} читаются из .env в том же каталоге; если не заданы — берётся значение по умолчанию
services:
  # ── База данных: PostgreSQL 17 + pgvector ────────────────────────
  # Хранит метаданные фото, людей, альбомы, настройки, очередь задач и векторы (индекс HNSW)
  # Порт не публикуется; доступна только во внутренней сети Compose
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # в рабочей среде обязательно смените в .env
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # по умолчанию именованный том pgdata; с WANMORY_DB_DIR — этот каталог. Включите в резервные копии
    healthcheck:                             # server ждёт эту проверку и стартует, когда база готова
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── Бэкенд: программа на Go со встроенным веб-приложением ────────
  # Отвечает за API, загрузки (tus), планирование задач, миниатюры и права; при запуске выполняет миграции БД
  server:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    environment:
      DATABASE_URL: postgres://wanmory:${WANMORY_DB_PASSWORD:-wanmory}@postgres:5432/wanmory
      WANMORY_ML_URL: http://ml:3003         # адрес встроенного ИИ-сервиса; удалённый задаётся в «Настройках ИИ»
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # часовой пояс, если в EXIF его нет
      WANMORY_MDNS: "off"                    # в сети bridge контейнер не получает мультикаст; домен объявляет сервис mdns ниже
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # порт, который показывает веб-приложение; должен совпадать с пробросом
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # начальный локальный домен; после смены в веб-настройках действует настройка
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # порт хоста:порт контейнера
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ — загруженные оригиналы, thumbs/ — миниатюры и превью 1440 px
      # Существующие папки с фото подключаются подкаталогами /photos, сколько угодно; :ro — только чтение; сканируются каждые 15 минут
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/camera:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── Объявление локального домена (mDNS) ──────────────────────────
  # Тот же образ, что и server, запускает только подкоманду mdns; объявляет wanmory.local (можно сменить в веб-приложении)
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # для отправки и приёма мультикаста в локальной сети нужна сеть хоста
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # периодически запрашивает у server текущий домен
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # объявляется, пока server недоступен
    depends_on:
      - server
    restart: unless-stopped
  # ── Встроенный ИИ-сервис: FastAPI + ONNX Runtime, только CPU ─────
  # Без состояния; получает превью от server и возвращает лица, векторы и текст; порт не публикуется
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # модели сохраняются, пересоздание контейнера не требует повторной загрузки
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # без автозагрузки; администратор сначала подтверждает лицензии и место на диске в веб-приложении
    restart: unless-stopped
volumes:
  pgdata:

.env (переменные Compose)

Эти переменные используются в docker-compose.yml; запишите их в .env в том же каталоге, чтобы они вступили в силу:

Контейнер server (необязательно)

DATABASE_URL, WANMORY_ML_URL, WANMORY_MDNS и WANMORY_HTTP_PUBLIC_PORT уже заданы в файле Compose с пояснениями. Следующих переменных в стандартном файле нет; при необходимости добавьте их в environment сервиса server:

Фото, которые уже лежат на NAS или внешнем диске, загружать не нужно. Подключите папку подкаталогом /photos внутри контейнера: она сканируется каждые 15 минут, новые файлы импортируются на месте (без копирования и перемещения), а затем, как и загруженные фото, проходят чтение метаданных, создание миниатюр и обработку ИИ.

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro — только для чтения
      - /media/usb/camera:/photos/usb:ro
      - /home/me/Pictures:/photos/pictures    # чтение и запись

После изменения выполните docker compose up -d. Первое сканирование начнётся примерно через 20 секунд после перезапуска контейнера.

• Рекомендуется подключать только для чтения (:ro): система ничего не пишет в такие папки. Удаление фото в приложении лишь переносит его в «Недавно удалённые», окончательное удаление никогда не стирает исходный файл, и при следующих сканированиях он не импортируется снова. В папках с правом записи окончательное удаление стирает и исходный файл.
• Файлы с одинаковым содержимым импортируются один раз (сверка по контрольной сумме SHA-1), включая уже загруженные файлы и дубликаты в разных папках.
• Скрытые каталоги и системные папки NAS (.xxx, @eaDir, #recycle и т. п.) пропускаются автоматически.
• Фото из подключённых папок не принадлежат ни одному участнику; удалять их могут только администраторы.

Сервис mdns работает в режиме сети хоста и объявляет домен доступа в локальной сети (по умолчанию wanmory.local). macOS, iOS, iPadOS и Windows 10 и новее открывают http://wanmory.local:8080 без настройки роутера. Домен меняется в «Системные настройки → Домен доступа» и должен оканчиваться на .local.

Веб-загрузка использует протокол с докачкой tus (/api/uploads/) с блоками по 16 МБ. За обратным прокси снимите ограничение на размер запроса и отключите буферизацию запросов. Пример для Nginx:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/uploads/ {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 0;          # без ограничения размера (не меньше 20m)
    proxy_request_buffering off;     # передавать потоком, не сохраняя на диск прокси
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

ИИ-сервис — HTTP-сервис без состояния: он получает от бэкенда превью размером 1440 пикселей и возвращает лица, векторы и распознанный текст. Он не обращается к базе данных и не сохраняет файлы. Бэкенд поддерживает два режима, которые переключаются в «Системные настройки → ИИ → Режим работы ИИ»:

Когда ИИ-сервис недоступен, задачи ИИ остаются в очереди и перестают забираться, не расходуя повторы; когда сервис вернётся, обработка продолжится сама. Просмотр, загрузка и прочее при этом работают.

Способ 1: напрямую на Mac или машине с GPU (рекомендуется)

При прямом запуске доступно аппаратное ускорение: на Apple Silicon модели лиц используют CoreML, а Chinese-CLIP — MPS; на GPU NVIDIA Chinese-CLIP работает через CUDA в половинной точности (около 1,9 ГБ видеопамяти / памяти). Сначала установите uv.

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # установить зависимости PyTorch (семантический поиск с ускорением на GPU)
# Сгенерируйте токен доступа; бэкенд и ИИ-сервис используют одно значение
export WANMORY_ML_TOKEN=$(openssl rand -hex 24)
echo $WANMORY_ML_TOKEN
WANMORY_FACE_MODEL_PRELOAD=1 uv run --extra torch python -m wanmory_ml
# По умолчанию слушает 0.0.0.0:3003; меняется через WANMORY_ML_HOST / WANMORY_ML_PORT

Способ 2: образ Docker на другой машине

Для более мощной машины x86 без подходящего GPU; образ использует только процессор:

docker run -d --name wanmory-ml --restart unless-stopped \
  -p 3003:3003 \
  -e WANMORY_ML_TOKEN=<токен-доступа> \
  -v $PWD/models:/models \
  ghcr.io/i-dj/wanmory-ml:latest

Включение удалённого сервиса в бэкенде

1. 1
   Откройте настройки ИИ

   Войдите как администратор, откройте «Системные настройки → ИИ → Режим работы ИИ» и выберите «Удалённый сервис».

2. 2
   Укажите адрес и токен

   Адрес вида http://192.168.1.20:3003, токен — значение, сгенерированное на предыдущем шаге. Перед сохранением соединение проверяется, показываются задержка и версия сервиса.

3. 3
   Проверьте уровень и модели

   После подключения уровень «Авто» пересчитывается по оборудованию удалённой машины; загрузите нужные модели в разделе «Уровень моделей».

Уровень определяет, какие модели используются для лиц и семантического поиска. В режиме «Авто» система рекомендует уровень по оборудованию машины с ИИ-сервисом: при наличии подходящего GPU — «Высокая точность»; только с процессором и памятью меньше 6 ГБ — «Лёгкий», иначе — «Сбалансированный».

• Распознавание текста использует PP-OCRv6 (RapidOCR); его модели ставятся вместе с зависимостями и отдельно не загружаются.
• После смены уровня лица на всех фото обнаруживаются заново, а семантические векторы пересчитываются новыми моделями; пока это идёт, поиск работает по старым векторам, а люди с именами сохраняются.
• Модели загружаются в подключённый каталог ./models; неиспользуемые можно удалить, чтобы освободить место (используемую модель удалить нельзя).
• Модели лиц InsightFace разрешены только для некоммерческого использования; перед коммерческим использованием замените их или получите лицензию.

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

   При первом входе система видит, что учётных записей нет, и предлагает создать администратора. Администраторы могут добавлять участников и менять системные настройки.

2. 2
   Загрузите модели

   Откройте «Системные настройки → ИИ», подтвердите уровень моделей и загрузите их. Пока модели не готовы, задачи ИИ ждут в очереди.

3. 3
   Импортируйте фото

   Загрузите через веб-приложение или подключите фото с NAS, как описано в разделе Подключение папок с фото.

4. 4
   Добавьте участников

   В «Системные настройки → Участники» создайте учётные записи для других людей и выберите роль «Участник» или «Администратор».

• Веб-загрузка принимает фото, видео, HEIC, RAW (например, DNG) и другое, с выбором нескольких файлов; загрузка идёт блоками по протоколу tus и продолжается после обрыва сети или перезагрузки страницы.
• Загруженные файлы раскладываются по годам и месяцам в каталоге загрузок (по умолчанию data/upload). Каталог меняется в «Системные настройки → Каталог загрузок» и влияет только на новые загрузки.
• После импорта по порядку выполняются: чтение метаданных (ExifTool) → миниатюры и превью 1440 пикселей (libvips / FFmpeg) → семантические векторы, лица и текст (ИИ-сервис) → обратное геокодирование.
• Индикатор фоновых задач вверху боковой панели показывает в штуках фото прогресс и оставшееся время для «Импорт фото» и «Распознавание ИИ».

Сведения о людях (имена, объединения) общие для всех участников; число фото, обложки и страницы людей считаются по фото, которые видит конкретный участник, а скрытые фото видит только владелец.

• Участники: при добавлении задаются имя, начальный пароль (не короче 4 символов) и роль; пароль участника можно сбросить, а самого участника — удалить.
• История входов: записываются время, устройство и IP каждого входа, местоположение оценивается по IP без интернета (ip2region), хранятся последние полгода. Видна только администраторам.
• В разделе «Моя учётная запись» каждый участник может сменить пароль и аватар и посмотреть устройства, на которых выполнен вход.

Вверху карточки в реальном времени показывается состояние ИИ (работает или причина паузы). Изменения применяются сразу, без перезапуска.

«Системные настройки → Обновление системы» показывает текущие версии бэкенда и ИИ-сервиса и сообщает о новых. Для обновления выполните в каталоге с docker-compose.yml:

docker compose pull && docker compose up -d

Миграции базы данных выполняются автоматически при запуске server. Если версия закреплена через WANMORY_VERSION, сначала измените тег в .env.

Резервировать нужно три вида данных:

# Выгрузить базу данных
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# Восстановить в новую установку (сначала docker compose up -d postgres)
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

Если участник забыл пароль, администратор сбрасывает его в «Системные настройки → Участники». Если пароль забыл сам администратор, выполните на хосте с приложением, в каталоге с docker-compose.yml:

docker compose exec server wanmory reset-password            # показать учётные записи и выбрать
docker compose exec server wanmory reset-password <имя>       # указать учётную запись сразу

• Команда выводит все учётные записи (имя, роль, дата создания, последний вход); выберите номер и дважды введите новый пароль.
• После сброса учётная запись выходит из системы на всех устройствах; фото и альбомы не затрагиваются.
• Сделать это можно только на хосте, в веб-приложении такой возможности нет. Без Docker запустите wanmory reset-password с теми же переменными окружения, что и сервер, например DATABASE_URL.

Журналы сервисов: docker compose logs -f server и docker compose logs -f ml. Если проблема не решается, напишите нам на странице Сообщить о проблеме, указав версию и приложив нужные журналы.

Запустите скрипт удаления на хосте, где работает Wanmory:

curl -fsSL https://wanmory.com/uninstall.sh | bash

Скрипт сначала читает .env в каталоге установки и показывает контейнеры, базу данных, каталог данных, модели ИИ и занимаемое ими место, а также подключённые папки с фото. Затем останавливает и удаляет контейнеры и сеть и по каждому пункту спрашивает, удалять ли его (по умолчанию всё сохраняется):

• Подключённые папки с фото (NAS, внешние диски) никогда не удаляются.
• Для удаления базы данных или каталога данных нужно подтвердить действие вводом DELETE.
• Если удалить только контейнеры и сохранить данные, повторный запуск install.sh в том же каталоге вернёт всё как было; если удаляете .env, но оставляете базу данных, сначала запишите указанный в нём WANMORY_DB_PASSWORD.