Орта айнымалылары
Notarium орта айнымалылары арқылы бапталады. Әдепкі мәндер жұмысқа дайын — жергілікті іске қосу үшін ештеңе толтырудың қажеті жоқ: .env.example файлын .env етіп көшіріп, қажет болса, керек жолдарды түзетіңіз. Docker стегі .env файлын контейнерге сол күйінде береді (мәндер образға сіңірілмейді), сондықтан бір ғана файл жергілікті дананы да, өнімдік (production) дананы да сипаттайды.
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:<DATA_DIR>/meta.db | META_DB_URL=postgres://user:pass@db:5432/notarium |
SPACES_ROOT | Әр кеңістік бір бума болатын түбір; UI-дан кеңістіктерді рантаймда жасауды қосады. Міндетті емес: әдепкіде <DATA_DIR>/spaces, жазбаларыңыз деректер түбірінен тыс жатса ғана орнатыңыз. | <DATA_DIR>/spaces | SPACES_ROOT=/mnt/notes |
SPACES_CONFIG | Кеңістіктердің айқын топологиясы: inline-JSON немесе JSON файлға жол. Single-space айнымалыларынан басым түседі. | берілмеген | SPACES_CONFIG=/data/spaces.json |
ENGINE_DATA_DIR | Қозғалтқыш туынды индекстерді сақтайтын жер — әр кеңістікке бір файл. Файл атауы кеңістік бумасының атауынан алынады және кеңістік қайта аталғанда өзгермейді. Каталогты жойсаңыз → іске қосылғанда қайта индекстеу, индекс қалпына келеді. Міндетті емес: әдепкіде <DATA_DIR>/engine, индекстерді басқа дискіге шығару үшін орнатыңыз. | <DATA_DIR>/engine | ENGINE_DATA_DIR=/mnt/ssd/engine |
JOBS_DATA_DIR | Тапсырмалар каталогы: async-экспорттың артефактілері (туынды, TTL бойынша тазаланады) және аяқталмаған импорттың жүктеп салынған файлдары — соңғылары дәл өз тапсырмасы тірі тұрғанша ғана сақталады, сондықтан сақтық көшірмеге кіреді. Міндетті емес: әдепкіде <DATA_DIR>/jobs, басқа дискіге шығару үшін орнатыңыз. | <DATA_DIR>/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 |
Дискіде екі түрлі нәрсе жатады. SPACES_ROOT — бұл Markdown-ақиқат (сіздің жазбаларыңыз, әр кеңістікке бір бума). META_DB_URL — қызметтік дерекқор: файлдардан шығарылмайтын нәрсе (пайдаланушылар, рұқсаттар, нұсқалар тарихы). Толығырақ — Өзіндік хостинг бөлімінде.
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 |
Семантика жергілікті ортада жұмыс істеуі үшін екеуі де керек: нативті стек орнатылған (make deps-vector; әдепкі make deps оны орнатпайды, published-образ әрдайым алып жүреді) және VECTOR_SEARCH=on. Стек болмаса — on лексикалық толық мәтіндік іздеуге қайтады, қатесіз. Толығырақ — Іздеу және Іздеуді баптау бөлімдерінде.
Сақтық көшірме және қалпына келтіру
Кіріктірілген backup, backup verify және restore командалары баптаусыз жұмыс істейді. Төмендегі айнымалылар контейнер түбірі оқуға ғана (read-only) тіркелгенде немесе деректер әдеттегіден әлдеқайда көп болғанда ғана керек. Толығырақ — Сақтық көшірме және қалпына келтіру.
| Айнымалы | Мақсаты | Әдепкі | Мысал |
|---|---|---|---|
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) |
docouno/notarium:latest — ашық образ және орнатудың негізгі жолы; IMAGE / TAG docker compose / make up қай образды тартатынын анықтайды. Егер образ реестрден әлі тартылмаса — негізгі репозиторийдің бастапқы кодынан құрастырыңыз: make up (әрекеті бірдей).
Тағы қараңыз
- Өзіндік хостинг конфигурациясы — орнату, томдар, өнімдік конфигурация.
- Іздеу — лексика, семантика, гибридті біріктіру және толық мәтіндік іздеуге қатесіз қайту.
- Пернелер тіркесімінің анықтамасы — орналасулар мен пресеттер.