--- title: "Переменные окружения" description: "Полная таблица переменных окружения инстанса: режим и порт, пространства и служебная БД, семантический поиск, Docker-образ." --- # Переменные окружения Notarium конфигурируется через переменные окружения. Дефолты рабочие — для локального запуска заполнять ничего не нужно: скопируйте `.env.example` в `.env`, при необходимости поправьте нужные строки. Docker-стек прокидывает `.env` в контейнер как есть (в образ значения не запекаются), поэтому один и тот же файл описывает и локальный, и продакшн-инстанс. ```bash cp .env.example .env # дефолты рабочие — правьте только то, что нужно ``` Ниже — полная справка. Часть переменных задаётся напрямую в `.env.example`, часть (тонкая настройка поиска) имеет дефолты в коде и в примере не выписана — они помечены отдельно. ## Ядро Базовые переменные: порт, режим аутентификации, расположение служебной БД и пространств. | Переменная | Назначение | Дефолт | Пример | |---|---|---|---| | `DATA_DIR` | Единственная ручка данных: корень, из которого выводится всё остальное — служебная БД, индексы, заметки, артефакты. Не задан → берётся рабочий дефолт. | `/data` (Docker); `~/.local/share/notarium` (host) | `DATA_DIR=/srv/notarium` | | `PORT` | Порт, который слушает бэкенд; один Fastify-листенер отдаёт `/api`, `/mcp` и статику SPA. | `3000` | `PORT=3000` | | `AUTH_MODE` | Режим аутентификации: `password` (логин + setup-экран первого запуска, требует служебную БД) или `none` (единственный all-access принципал для desktop/dev/доверенного интранета, без login-UI). | `password` | `AUTH_MODE=none` | | `META_DB_URL` | Служебная БД: идентичность, журнал ревизий, реестр пространств, аутентификация, проекты. По дефолту — sqlite под `DATA_DIR`, поэтому режим `password` работает без настройки. Опционально: задавайте, только чтобы перенести служебное состояние во внешний Postgres (общее состояние, HA). | `sqlite:/meta.db` | `META_DB_URL=postgres://user:pass@db:5432/notarium` | | `SPACES_ROOT` | Корень, где каждое пространство — это папка; включает создание пространств из UI в рантайме. Опционально: по дефолту это `/spaces`, задавайте, только если заметки лежат вне корня данных. | `/spaces` | `SPACES_ROOT=/mnt/notes` | | `SPACES_CONFIG` | Явная топология пространств: inline-JSON или путь к JSON-файлу. Перекрывает single-space-переменные. | не задан | `SPACES_CONFIG=/data/spaces.json` | | `ENGINE_DATA_DIR` | Где движок держит производные индексы — по файлу на пространство. Имя файла следует за именем папки пространства и при переименовании пространства не меняется. Удаление каталога → реиндекс при старте, индекс восстановим. Опционально: по дефолту `/engine`, задавайте, чтобы вынести индексы на другой диск. | `/engine` | `ENGINE_DATA_DIR=/mnt/ssd/engine` | | `JOBS_DATA_DIR` | Каталог задач: артефакты async-экспорта (производное, чистится по TTL) **и** загруженные файлы незавершённого импорта — эти живут ровно столько, сколько живёт их задача, и потому попадают в бэкап. Опционально: по дефолту `/jobs`, задавайте, чтобы вынести на другой диск. | `/jobs` | `JOBS_DATA_DIR=/mnt/ssd/jobs` | | `SPACE_IDLE_EVICT_SECONDS` | Выгрузка read-model простаивающего пространства. `0` — держать тёплым; пространства с живым SSE-соединением не выгружаются. | `0` | `SPACE_IDLE_EVICT_SECONDS=900` | | `SYNC_POLL_SECONDS` | Период опроса внешних изменений на диске (каждый опрос — полный рескан пространства). `0` — отключить опрос. Для неотслеживаемых mount'ов (сетевой том, in-memory) эффективный интервал сверху ограничен 60 с. | `120` | `SYNC_POLL_SECONDS=0` | | `PUBLIC_BASE_URL` | Канонический внешний адрес инстанса за reverse proxy — для OAuth-метаданных MCP-коннекторов. Без него адрес выводится из forwarded-заголовков прокси. | не задан | `PUBLIC_BASE_URL=https://notes.example.com` | | `TRUST_PROXY` | Список IP/CIDR **непосредственных** прокси через запятую — по нему выводится настоящий IP клиента для лимитов входа и допуска новых OAuth-клиентов. Не задан — безопасный дефолт: `X-Forwarded-For` на лимиты не влияет. Булевы значения, счётчики хопов, именованные диапазоны и всеадресные диапазоны (`/0`) отклоняются при старте. | не задан | `TRUST_PROXY=172.18.0.0/16` | > [!note] Служебная БД против файлов > На диске лежат две разные вещи. `SPACES_ROOT` — это **Markdown-истина** (ваши заметки, по папке на пространство). `META_DB_URL` — служебная БД: то, что из файлов не выводится (пользователи, доступы, история версий). Подробнее — в разделе [Self-host](/docs/self-hosting/). ## Single-space (bare-host, без Docker) Для запуска одного пространства без `SPACES_CONFIG` и без `SPACES_ROOT` (например, локальный bare-run без Docker). | Переменная | Назначение | Дефолт | Пример | |---|---|---|---| | `ENGINE` | Движок одного пространства. Единственное значение — `notarium`; можно не задавать. | `notarium` | `ENGINE=notarium` | | `NOTES_DIR` | Абсолютный путь к папке заметок одного пространства (single-space режим). | не задан | `NOTES_DIR=/home/me/notes` | ## Семантический поиск Лексический полнотекстовый поиск (FTS) работает всегда и без настройки. Семантический (векторный) и гибридный поиск — **включается по желанию**: тяжёлый нативный стек (`onnxruntime` + `sqlite-vec`, ~660 МБ на диске) плюс модель эмбеддингов bge-m3 (~600 МБ на диске, сотни МБ RAM). Переменные ниже имеют дефолты в коде и в `.env.example` не выписаны. | Переменная | Назначение | Дефолт | Пример | |---|---|---|---| | `VECTOR_SEARCH` | `on`/`off` — включает семантику и гибридное слияние. При отсутствии нативного стека `on` откатывается на полнотекстовый поиск — без ошибки. | `on` (код), `off` (published-образ) | `VECTOR_SEARCH=on` | | `EMBED_MODEL` | Id модели эмбеддингов (transformers.js/ONNX). Задаётся **вместе** с `EMBED_DIMENSIONS`. | `Xenova/bge-m3` | `EMBED_MODEL=Xenova/multilingual-e5-small` | | `EMBED_DIMENSIONS` | Ширина вектора; **обязана** совпадать с моделью (bge-m3 — 1024, e5-small — 384). Несовпадение fail-closed: заметка остаётся FTS-only. | `1024` | `EMBED_DIMENSIONS=384` | | `EMBED_DTYPE` | Квантизация модели: `fp32` / `fp16` / `q8` / `q4`. | `q8` | `EMBED_DTYPE=fp16` | | `EMBED_THREADS` | Число ONNX intra-op потоков на воркер фонового индексирования (пул из `EMBED_WORKERS` воркеров). | `1` на воркер (fallback без пула — половина ядер) | `EMBED_THREADS=2` | | `EMBED_WORKERS` | Размер пула `worker_threads` эмбеддинга = параллелизм фонового индексирования по ядрам. Каждый воркер держит свою копию модели (влияет на RAM). | `max(1, min(ядра−2, 4))` | `EMBED_WORKERS=8` | | `EMBED_QUERY_PREFIX` / `EMBED_PASSAGE_PREFIX` | Префиксы для асимметричных моделей (e5). Для симметричной bge-m3 **не задавать** — иначе качество незаметно просядет. | не заданы | `EMBED_QUERY_PREFIX="query: "` | | `EMBED_CPU_MEM_ARENA` | `on`/`off`. `off` удерживает потребление на постоянном уровне ~1.9 ГБ RAM для bge-m3 — против OOM на тесной swapless-машине (с `on` арена может доползти до нескольких ГБ). | `on` | `EMBED_CPU_MEM_ARENA=off` | | `GRAPH_BOOST` | `on`/`off` — третий RRF-канал (буст по связям, 1-hop wikilink). Инертен при `VECTOR_SEARCH=off`. | `off` | `GRAPH_BOOST=on` | > [!warning] Два независимых переключателя > Чтобы семантика заработала локально, нужны **оба**: нативный стек **установлен** (`make deps-vector`; дефолтный `make deps` его не ставит, published-образ несёт всегда) **и** `VECTOR_SEARCH=on`. Если стека нет — `on` откатывается на лексический полнотекстовый поиск, без ошибки. Подробнее — в разделе [Поиск](/docs/concepts/search/) и [Настройка поиска](/docs/self-hosting/search-setup/). ## Бэкап и восстановление Встроенные команды `backup`, `backup verify` и `restore` работают без настройки. Переменные ниже нужны, только когда корень контейнера смонтирован на чтение или данных заметно больше типового. Подробнее — [Бэкап и восстановление](/docs/self-hosting/backup/). | Переменная | Назначение | Дефолт | Пример | |---|---|---|---| | `NOTARIUM_BACKUP_TMPDIR` | Каталог под промежуточные файлы бэкапа, проверки и восстановления. Задавайте, если корень контейнера read-only или под `/tmp` не хватает места: потоковому бэкапу может временно понадобиться архив плюс два развёрнутых стейджа. | `/tmp` | `NOTARIUM_BACKUP_TMPDIR=/mnt/scratch` | | `NOTARIUM_BACKUP_MAX_BYTES` | Потолок объёма — и сжатого входа, и развёрнутой полезной нагрузки. Защита от zip-бомбы; поднимают только доверенные крупные инсталляции. | 64 ГиБ | `NOTARIUM_BACKUP_MAX_BYTES=137438953472` | | `NOTARIUM_BACKUP_MAX_ENTRIES` | Потолок числа записей в архиве. | `1000000` | `NOTARIUM_BACKUP_MAX_ENTRIES=2000000` | | `NOTARIUM_BACKUP_MAX_METADATA_BYTES` | Отдельный потолок памяти под имена, служебные структуры ZIP и `manifest.json`. | 32 МиБ | `NOTARIUM_BACKUP_MAX_METADATA_BYTES=67108864` | ## Docker и сборка | Переменная | Назначение | Дефолт | Пример | |---|---|---|---| | `IMAGE` / `TAG` | Ссылка на образ для `docker compose` / `make up`. Основной путь установки — публичный образ `docouno/notarium:latest`; переопределите координату, чтобы взять свой реестр или конкретный тег. | `docouno/notarium:latest` | `IMAGE=docouno/notarium` `TAG=latest` | | `GIT_SHA` / `BUILD_TIME` | Build-args сборки; инлайнятся в `GET /api/about` и вкладку **Settings → About**. Без них — `null`. | пусто | `GIT_SHA=$(git rev-parse --short HEAD)` | > [!important] Образ и сборка из исходников > `docouno/notarium:latest` — публичный образ и основной путь установки; `IMAGE` / `TAG` задают, какой образ подтянет `docker compose` / `make up`. Если образ ещё не подтянулся из реестра — соберите из исходников основного репозитория: `make up` (поведение идентично). ## Смотрите также - [Конфигурация self-host](/docs/self-hosting/configuration/) — установка, тома, продакшн-конфигурация. - [Поиск](/docs/concepts/search/) — лексика, семантика, гибридное слияние и откат на полнотекстовый поиск без ошибки. - [Справочник горячих клавиш](/docs/reference/keyboard-shortcuts/) — раскладки и пресеты.