Uppsetning Nessie

Keyrðu Nessie á innviðum sem þú velur, frá einni vél upp í stýrt skýjaumhverfi.

Það sem þú þarft áður en þú byrjar

Nessie er pnpm monorepo af Node-þjónustum auk tveggja kyrrstæðra pakka. Hvernig sem þú keyrir það þurfa sömu fjögur atriði að vera til fyrst.

• PostgreSQL með pgvector. Ekki valfrjálst og ekki hægt að skipta út. Gagnagrunnsbreytingarnar keyra CREATE EXTENSION vector og búa til vector(1024)-dálka. Framleiðslan keyrir pgvector/pgvector:pg17.
• Node 22 og pnpm. Sérhver Dockerfile í infrastructure/docker/ byggir á node:22-slim, og kóðasafnið festir pakkastjórann í rótar-package.json (pnpm@10.22.0).
• Endapunktur fyrir OpenAI-samhæft líkan og lykill að honum. Fulltrúar og innfellingar fara bæði í gegnum hann. Sjá „Stilling á gervigreindarlíkani“ hér að neðan.
• S3-samhæf hlutageymsla, fyrir hvaða uppsetningu sem er önnur en staðbundna þróunaruppsetningin. Upphleðslur á staðbundnum diski eru hafnaðar utan local-stillingar, og sú höfnun er villa við ræsingu frekar en skert ræsing — sjá „Ein vél eða stýrð skýjalausn“.

Docker og öfugur proxy þarf fyrir gámaleiðina sem lýst er neðar, og lén ásamt TLS fyrir allt sem er aðgengilegt af internetinu.

Vélbúnaðarstærð — lágmarksfjöldi örgjörva, minnis og disks fyrir tiltekinn fjölda fólks — kemur ekki fram neins staðar í kóðasafninu, svo þessi síða gerir það ekki heldur.

Þættirnir og hvernig þeir tengjast

API-þjónninn og vinnsluþjónninn eru ein mynd. Pakkarnir tveir eru þétt tengdir, svo Dockerfile.app byggir allt teymið einu sinni, og vinnslugámurinn yfirskrifar skipunina í node worker/dist/index.js. Í local-stillingu er enginn vinnslugámur: API-þjónninn keyrir vinnsluna innbyggða í sínu eigin ferli.

Enginn Redis. Bæði verkefnabiðröðin og rauntímaflutningurinn byggja á Postgres — af ákvörðun en ekki vanrækslu. Google Cloud-útfærslan eyðir Pub/Sub- og Redis-einingunum af sömu ástæðu.

Gáttir

Í staðbundinni þróun er API-ið sjálfgefið á 5454 og stjórnborðið á 5455. Hvert útcheckað eintak getur tekið sitt eigið par með því að stilla NESSIE_API_PORT og NESSIE_ADMIN_PORT, í umhverfinu eða í .env kóðasafnsins; öll verkfæri í kóðasafninu, þar á meðal prófunarsvíturnar í vafra, lesa sömu tvö gildin. Veldu parið áður en þú ræsir og haltu þig við það: ef keyrandi þjónusta er flutt á aðra gátt talar stjórnborðið við rangt API.

Framleiðsla er annað mál og breytist ekki við þá reglu. API-gámurinn hlustar innbyrðis á 5554 (fest með NESSIE_API_PORT) og ýtingarmiðlarinn á 5556, báðir á bak við öfugan proxy.

Keyrsla á einni vél, til þróunar

Kóðasafnið fylgir með Compose-skrá sem inniheldur aðeins gagnagrunn, og það er allt sem staðbundna lykkjan þarf.

pnpm install
docker compose -f infrastructure/compose/docker-compose.yml up -d postgres

Sá gámur birtir Postgres á 55432 með notandanafninu, lykilorðinu og gagnagrunninum öllu nefndu nessie. Settu tengistrenginn í .env í rót kóðasafnsins — þróunarhandrit API-þjónsins les hana — keyrðu síðan gagnagrunnsbreytingarnar og byggðu vinnsluþjóninn einu sinni, því í local-stillingu hleður API-þjónninn vinnslunni úr byggðri dist-möppu sinni:

DATABASE_URL=postgresql://nessie:nessie@localhost:55432/nessie

pnpm --filter @nessie/api prisma:migrate:deploy
pnpm --filter @nessie/worker build
pnpm dev

pnpm dev keyrir API-þjóninn og stjórnborðið hlið við hlið með endurhleðslu, á 5454 og 5455. Athugaðu hvort API-þjónninn svarar með GET /api/health.

Postgres og krafan um pgvector

Þrjár viðbætur eru búnar til af gagnagrunnsbreytingunum sjálfum — vector, pg_trgm og pgcrypto — svo hlutverkið sem keyrir þær verður að mega búa til viðbætur. Á stýrðum Postgres er það fyrsta sem þarf að athuga.

Breidd vigranna er hluti af gagnagrunnsskemanu, ekki stilling. thoughts.embedding, thought_recalls.query_embedding og knowledge_page_chunks.embedding eru vector(N)-dálkar, og N er skilgreint einu sinni sem EMBEDDING_DIMENSIONS í packages/schemas/src/embedding.ts — núna 1024, upprunaleg breidd innfellingarlíkansins sem framleiðslan notar. Sérhver innfellingarbeiðni sendir þá breidd, svo þjónusta sem myndi svara með annarri breidd mistekst hátt í stað þess að skrifa vigra sem gagnagrunnurinn hafnar. Að færa sig yfir á innfellingarlíkan með annarri breidd þýðir að breyta þeim fasta, skrifa gagnagrunnsbreytingu sem endurskilgreinir dálkana þrjá, og innfella aftur: vigrar af mismunandi breidd verða ekki umbreyttir, svo breytingin setur þá á NULL í stað þess að stytta þá.

Ef þú keyrir Nessie við hlið annarra forrita á sameiginlegu Docker-neti, gefðu gagnagrunnsgámnum þess sérstakt heiti. Compose-þjónusta verkefnisins heitir nessie-postgres og aldrei postgres, því þjónustuheitið verður DNS-samnefni á sameiginlega netinu, og árekstur veldur því að postgres:5432 skiptist til skiptis (round-robin) á milli tveggja gagnagrunna.

Stillingar

Keyrslustillingar eru lagskiptar: skráin nessie.config.json er tengd í API-þjóninn og vinnsluþjóninn í lesham, og umhverfisbreytur yfirskrifa hana. Tengingin milli þeirra er ConfigEnvMap í packages/config, sem er áreiðanlegi listinn.

NESSIE_MODE velur gerð uppsetningarinnar: local (sjálfgefið og þróunarleiðin), hosted eða selfHosted — sem sjálfshýst uppsetning stillir. Það slekkur á þróunarinnskráningu og krefst CORS-leyfislista.

Þetta eru stillingarnar sem selfHosted-uppsetning ræsist ekki með, eða virkar ekki án:

infrastructure/compose/.env.prod.example sýnir nákvæmlega form þeirra allra, með valfrjálsu blokkunum — hlutageymslu, leyndarmálahvelfingu, SSO og tengdum pósti — settum í athugasemdir á sínum stað. Heildarlistinn, þar á meðal sérhver valfrjáls stilling, er docs/deployment/configuration.md.

Uppsetning með Docker Compose

Afritaðu .env.prod.example í .env við hliðina á docker-compose.prod.yml og fylltu hana út, og ræstu síðan gagnagrunninn, byggðu, keyrðu breytingarnar og ræstu þjónustuna. Röðin skiptir máli: gagnagrunnsbreytingarnar og upphafsgögnin keyra á gagnagrunni sem er þegar uppi, áður en nokkur þjónusta svarar.

COMPOSE="docker compose -f infrastructure/compose/docker-compose.prod.yml"

bash infrastructure/compose/ensure-encryption-key-ring.sh infrastructure/compose/.env
$COMPOSE up -d nessie-postgres
$COMPOSE build nessie-api nessie-admin nessie-web
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api prisma:migrate:deploy
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api seed:connectors
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api seed:apps
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api reconcile
$COMPOSE up -d

Framleiðslu-Dockerfile-skrárnar keyra lint á hverjum pakka áður en þær byggja hann, svo villa í lint er byggingarvilla.

Samræmingarskrefið er ekki valfrjálst

reconcile sáir sjálfgefnum stefnureglum hverrar stofnunar og fyllir í tengdar MCP-heimildir og heimildir persónulega aðstoðarmannsins (Personal Assistant). API-þjónninn gerði þetta áður við ræsingu á hverri afritun; nú tengist hann, hlustar og gerir ekkert annað, svo án þessa skrefs hefur fyrsta stofnunin engar stefnureglur og hver tenging fulltrúa er hafnað. Það er óhætt að endurtaka það, svo það er ókeypis að keyra það við hverja útgáfu — og uppfærsla sem er sett upp handvirkt þarf líka að keyra það.

Fyrsti eigandi aðgangsins

Nýtt selfHosted-uppsetning hefur enga notendur, svo API-þjónninn býr til einnota ræsilykil og skráir slóð fyrir uppsetningu. Lykillinn lifir í Postgres en ekki í ferli, svo sérhver afritun er sammála um hann.

docker compose -f infrastructure/compose/docker-compose.prod.yml logs nessie-api 2>&1 | grep bootstrap

Opnaðu https://<your-admin-host>/bootstrap?token=<token> og búðu til eigandaaðganginn. Lykillinn rennur út eftir 15 mínútur; endurræstu API-þjónustuna til að búa til nýjan.

Ef þú setur upp SSO er enginn ræsiskref yfirleitt. Ræsistillingin er þögguð um leið og ytri auðkenningarþjónusta er virk — annars myndi hún taka innskráningarskjáinn — og fyrsta manneskjan sem skráir sig inn í gegnum SSO býr til sjálfgefna teymið og verður eigandi þess.

Stilling á gervigreindarlíkani

Spjallið er OpenAI-samhæft. NESSIE_MODEL_BASE_URL er endapunkturinn, NESSIE_MODEL_API_KEY er bearer-lykillinn og NESSIE_MODEL_PROVIDER nefnir millistykkið — Nessie hefur innbyggð millistykki fyrir openai, kimi og deepseek og nær í allt annað í gegnum almennan OpenAI-samhæfðan tengil. NESSIE_MODEL_NAME stillir sjálfgefið líkan uppsetningarinnar, sem líkanaval einstaks fulltrúa gengur framar.

Innfellingar fara um sérstaka leið, því spjallþjónustan þjónustar þær hugsanlega ekki yfirleitt — DeepSeek hefur til dæmis engan innfellingarendapunkt. Sérhvert NESSIE_EMBEDDING_*-svið sem er ekki stillt erfir spjallþjónustuna, svo uppsetning sem stillir ekkert þeirra býr til innfellingar í gegnum spjallendapunktinn. Stilltu NESSIE_EMBEDDING_PROVIDER, NESSIE_EMBEDDING_MODEL og, á proxy sem beinir eftir þjónustu, þjónustuhlutann, þegar spjallþjónustan getur ekki búið til innfellingar. Þetta fer hljóðlega úrskeiðis, ekki með látum: minnisendurheimt og leit í þekkingargrunninum falla niður á orðaleitarrás og halda áfram, og skrá kb_search: query embedding failed á leiðinni.

Eigið kostnaðarbókhald Nessie — tókenbókhaldið fyrir hverja stofnun og kostnaðarþakið — breytist ekki eftir því hvaða endapunkt þú bendir á, og virkar eins hvort sem undirrituð eignun á hverju kalli er stillt eða ekki.

Innskráning

Nessie auðkennir fólk í gegnum UnlikeOtherAI, sem stýrir líka skipulagi stofnana og teyma. Innskráningarsíða stjórnborðsins sýnir einn hnapp: „Innskrá / Nýskrá“.

Samþættingin er config-JWT-flæði en ekki hefðbundið OIDC: API-þjónninn býður undirritað RS256-stillingarskjal á GET /api/auth/sso/config og samsvarandi JWKS á GET /.well-known/jwks.json, bæði á API-hýsilinum. Að koma þessu upp er einskiptisröð — búðu til RSA-2048 lyklapar og stilltu UOA_CONFIG_JWT_PRIVATE_KEY_B64, UOA_CONFIG_JWT_KID, UOA_DOMAIN, UOA_CONFIG_URL, UOA_JWKS_URL, UOA_REDIRECT_URL og UOA_CONTACT_EMAIL; smelltu einu sinni á hnappinn, sem sendir inn beiðni um samþættingu; láttu samþykkja hana, sem sendir einnota hlekk á tengiliðsnetfangið með leyndarmálinu; stilltu UOA_CLIENT_SECRET og endurræstu API-þjóninn. kid verður að vera einstakt á hverju léni.

Að setja upp á léni, með TLS

Uppsetning þjónar þremur nöfnum: opinberu vefsíðunni, stjórnborðinu og API-inu. Upprunar stjórnborðsins og API-sins eru ekki skiptanlegir. Dockerfile.admin festir VITE_API_BASE_URL inn í pakkann við byggingu, svo sérhver byggður pakki stjórnborðsins — þar á meðal skjáborðssmíð sem felur hann í sér — verður að vera byggður gegn API-upprunanum. Sé hann byggður gegn eigin upprunanum leysist /api/auth/providers yfir í HTML-skelina og innskráningin situr föst á „Hleð innskráningarveitum...“.

Í framleiðslu lýkur TLS hjá Caddy, sem fær vottorð fyrir hvern hýsil í gegnum HTTP-01 og þarf ekki viðbót fyrir DNS-þjónustuaðila til þess. Beindu proxy-inum að stjórnborðs- og vefgámunum á gátt 80 og að API-inu á innri gátt þess.

Stilltu NESSIE_API_TRUSTED_PROXY_HOPS á fjölda proxy-a fyrir framan API-ið — 1 á bak við einn öfugan proxy. Sjálfgefið er 0, sem hunsar X-Forwarded-For alveg. Þetta er ein ákvörðun með tvennar afleiðingar: hún stjórnar líka hraðatakmörkunum á auðkenningu, svo of lágt gildi gefur öllum viðskiptavinum sömu takmörkunarfötu proxy-sins, og of hátt gildi gerir viðskiptavini kleift að falsa eigið vistfang. Skeikaðu lágt og mældu.

Að þjóna hverri stofnun og teymi á eigin undirléni er mögulegt og sjálfgefið óvirkt. Það er stýrt af NESSIE_TEAM_HOST_BASE_DOMAIN; sé það óstillt er leigjendum ekki beint eftir hýsilheiti yfirleitt, og útgáfuhliðið fyrir vottorð, NESSIE_TLS_CHECK_KEY, hafnar öllu meðan það er óstillt — sem er rétti sjálfgefni kosturinn fyrir uppsetningu sem notar ekki eiginleikann.

Heilsuathuganir

Við SIGTERM tæmir API-ið sig í stað þess að deyja þar sem það stendur. NESSIE_SHUTDOWN_TIMEOUT_MS takmarkar tæmingu og er sjálfgefið 25 sekúndur; haltu því undir þeim náðarfresti sem orkestrarinn gefur gámnum, annars drepur keyrslan ferlið fyrst og tæmingin gerir ekkert.

Uppfærsla

Uppfærsla er prisma migrate deploy gegn núverandi gagnagrunni, síðan upphafsgögnin, síðan reconcile. Sömu fjórar skipanir og við fyrstu uppsetningu.

Leiðin er prófuð fyrir þá leið sem sjálfshýsandi notandi fer í raun, frekar en gegn nýjum gagnagrunni: CI endurheimtir afrit sem tekið var tuttugu breytingum aftar, flytur það á núverandi haus, staðfestir skemað og keyrir reykpróf yfir kjarnatöflurnar. Sérhver útgáfa innan þessa síðasta glugga er sannreynd uppfærsluuppspretta. Gagnagrunnsbreytingamöppur eru óbreytanlegar þegar þær eru komnar í kóðasafnið, og lint-skref fellir bygginguna ef einni er endurnefnt, endurnúmeruð, eytt eða breytt, því öll fjögur brjóta migrate deploy fyrir gagnagrunn sem hefur þegar skráð gömlu röðina.

Ein mistókst breyting stöðvar allar útgáfur sem koma á eftir henni. migrate deploy stöðvast við fyrstu bilun og hafnar öllum síðari breytingum með P3009, svo uppsetningin er áfram á gömlu útgáfunni þar til einhver hreinsar það handvirkt. Framleiðsla verkefnisins eyddi einum degi í að hafna öllum útgáfum á þennan hátt. Að hreinsa hana þýðir að staðfesta að mistókst breytingin hafi raunverulega rúllast til baka — enginn af hlutunum sem hún býr til ætti að vera til, og það sem hún breytti ætti enn að vera í upprunalegri mynd — og aðeins þá merkja hana sem afturkallaða. Breyting sem var hálfkláruð er ekki frambjóðandi.

Afritun og endurheimt fyrir Compose-uppsetninguna á eigin vegum er ekki skjalfest í kóðasafninu, svo þessi síða lýsir ekki aðferð við það.

Ein vél eða stýrð skýjalausn

Uppsetningin á einni Docker Compose-vél hér að ofan er sú sem er sönnuð: það er það sem framleiðsla verkefnisins keyrir, á einum þjóni, með gagnagrunninn, hlutageymsluna, API-ið, vinnsluþjóninn, stjórnborðið og vefsíðuna sem gáma á bak við sameiginlegan öfugan proxy.

Að skala út fyrir eina vél breytir þremur hlutum, og allt er þvingað fram frekar en ráðlagt. Utan local-stillingar keyrir Nessie API-ið og vinnsluþjóninn sem aðskilin ferli og sem nokkur eintök af hvoru, svo sérhver geta sem gerir ráð fyrir að eitt ferli eigi disk vélarinnar er hafnað: skráargeymsla á disk (villa við ræsingu), keyrsluumhverfissniðmát með docker-veitunni (óvirk, og útvegun mistekst hátt) og innbyggðu verkfærin file_read, file_write og file_glob (mistekið verkfæraniðurstaða sem fulltrúinn getur lesið). Hver höfnun nefnir stillinguna, gerð uppsetningarinnar og hvað eigi að nota í staðinn.

Fyrir stýrða skýjalausn geymir kóðasafnið Terraform-tré í infrastructure/terraform/ sem beinist að Google Cloud: API-ið sem Cloud Run-þjónustu með lágmarki af einu eintaki — það heldur varanlegri Postgres LISTEN-tengingu og keyrir viðhaldsskoðanir, svo ef það er skalað niður í núll stöðvast rauntímaafhending — vinnsluþjóninn sem Cloud Run-vinnslulaug, því hann bindur enga gátt og Service yrði aldrei tilbúin, verk til flutnings sem hliðar öllum útgáfum, Cloud SQL fyrir PostgreSQL 17 og GCS-fötu sem næst í gegnum S3-samhæfða bakendann.

Sú leið er skrifuð, ekki prófuð. Kóðasafnið segir það umbúðalaust, og þessi síða gerir það líka: ekkert Google Cloud-verkefni er til fyrir hana, ekkert í trénu hefur verið skipulagt eða sett út gegn raunverulegu verkefni, upphleðsluleiðin um marga hluta í GCS hefur ekki verið prófuð gegn raunverulegri fötu, gerð vinnslulaugarinnar er óstaðfest, og fjöldi proxy-hoppa í henni er bráðabirgðagildi sem á að mæla frekar en mæling. Stjórnborðið og opinbera vefsíðan eru alls ekki líkön þar. Meðhöndlaðu hana sem upphafspunkt sem þú staðfestir, ekki studda uppsetningu.

Hvar gögn uppsetningar lifa, hvað hugbúnaðurinn geymir og hvað hann geymir viljandi ekki, er sérstök síða: Framleitt í ESB, og hvar gögnin þín eru.