--- title: "Орта айнымалылары" description: "Дананың орта айнымалыларының толық кестесі: режим мен порт, кеңістіктер мен қызметтік дерекқор, семантикалық іздеу, Docker образы." --- # Орта айнымалылары Notarium орта айнымалылары арқылы бапталады. Әдепкі мәндер жұмысқа дайын — жергілікті іске қосу үшін ештеңе толтырудың қажеті жоқ: `.env.example` файлын `.env` етіп көшіріп, қажет болса, керек жолдарды түзетіңіз. Docker стегі `.env` файлын контейнерге сол күйінде береді (мәндер образға сіңірілмейді), сондықтан бір ғана файл жергілікті дананы да, өнімдік (production) дананы да сипаттайды. ```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` (desktop/dev/сенімді интранет үшін жалғыз all-access субъект, login-UI жоқ). | `password` | `AUTH_MODE=none` | | `META_DB_URL` | Қызметтік дерекқор: бірегейлік, ревизиялар журналы, кеңістіктер тізілімі, аутентификация, жобалар. Әдепкіде — `DATA_DIR` астындағы sqlite, сондықтан `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` | Кері прокси артындағы дананың канондық сыртқы мекенжайы — MCP-коннекторлардың OAuth-метадеректері үшін. Онсыз мекенжай проксидің forwarded-тақырыптарынан шығарылады. | берілмеген | `PUBLIC_BASE_URL=https://notes.example.com` | | `TRUST_PROXY` | Дананың алдында **тікелей** тұрған проксилердің IP/CIDR тізімі, үтірмен бөлінген — сол арқылы кіру лимиттері мен жаңа OAuth-клиенттерді қабылдау үшін клиенттің шынайы IP-мекенжайы анықталады. Берілмесе — қауіпсіз әдепкі: `X-Forwarded-For` лимиттерге әсер етпейді. Логикалық мәндер, хоп сандары, атаулы ауқымдар және барлық мекенжайды қамтитын ауқымдар (`/0`) іске қосылғанда қабылданбайды. | берілмеген | `TRUST_PROXY=172.18.0.0/16` | > [!note] Қызметтік дерекқор vs файлдар > Дискіде екі түрлі нәрсе жатады. `SPACES_ROOT` — бұл **Markdown-ақиқат** (сіздің жазбаларыңыз, әр кеңістікке бір бума). `META_DB_URL` — қызметтік дерекқор: файлдардан шығарылмайтын нәрсе (пайдаланушылар, рұқсаттар, нұсқалар тарихы). Толығырақ — [Өзіндік хостинг](/docs/self-hosting/) бөлімінде. ## Single-space (bare-host, Docker-сіз) Бір кеңістікті `SPACES_CONFIG`-сіз және `SPACES_ROOT`-сыз іске қосу үшін (мысалы, Docker-сіз жергілікті bare-run). | Айнымалы | Мақсаты | Әдепкі | Мысал | |---|---|---|---| | `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 күйінде қалады. | `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` bge-m3 үшін тұтынуды ~1.9 ГБ RAM деңгейінде тұрақты ұстайды — тар, swapless машинадағы OOM-ға қарсы (`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` командалары баптаусыз жұмыс істейді. Төмендегі айнымалылар контейнер түбірі оқуға ғана (read-only) тіркелгенде немесе деректер әдеттегіден әлдеқайда көп болғанда ғана керек. Толығырақ — [Сақтық көшірме және қалпына келтіру](/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` (әрекеті бірдей). ## Тағы қараңыз - [Өзіндік хостинг конфигурациясы](/docs/self-hosting/configuration/) — орнату, томдар, өнімдік конфигурация. - [Іздеу](/docs/concepts/search/) — лексика, семантика, гибридті біріктіру және толық мәтіндік іздеуге қатесіз қайту. - [Пернелер тіркесімінің анықтамасы](/docs/reference/keyboard-shortcuts/) — орналасулар мен пресеттер.