Nessie a shuiteáil

Reáchtáil Nessie ar an mbonneagar a roghnaíonn tú, ó mheaisín amháin go scamall bainistithe.

Cad a theastaíonn roimh thosú

Is monarepo pnpm de sheirbhísí Node é Nessie, agus dhá bhuanda statach ina theannta. Is cuma cén bealach a rithtear é, ní mór na ceithre rud seo a bheith ann ar dtús.

• PostgreSQL le pgvector. Níl sé roghnach, agus ní féidir aon rud eile a chur ina áit. Ritheann na migrations CREATE EXTENSION vector agus cruthaíonn siad colúin vector(1024). Sa táirgeadh úsáidtear pgvector/pgvector:pg17.
• Node 22 agus pnpm. Tógann gach Dockerfile i infrastructure/docker/ ar node:22-slim, agus sonraíonn an stór an bainisteoir pacáiste sa package.json sa fhréamh (pnpm@10.22.0).
• Críochphointe samhla le comhoiriúnacht OpenAI agus eochair di. Gabhann gníomhairí agus leabuithe araon tríd. Tá cur síos ar “Tátal a chumrú” thíos.
• Stóráil réad S3-chomhoiriúnach, i ngach imscaradh nach é an fhorbairt áitiúil é. Diúltaítear d’uaslódálacha ar dhiosca áitiúil lasmuigh den mhód local, agus is teip tosaithe é an diúltú sin seachas tosú i riocht laghdaithe. Pléitear é faoi “Ar mheaisín amháin nó sa scamall bainistithe” thíos.

Tá Docker agus reverse proxy de dhíth don chonair coimeádáin a dtuairiscítear níos faide anonn, agus fearann agus TLS do rud ar bith atá inrochtana ón idirlíon.

Ní luaitear an méid crua-earraí — an lárphróiseálaí, an cuimhne agus an diosca is gá do líon áirithe daoine — in aon áit sa stór, mar sin ní luaitear é sa leathanach seo ach oiread.

Na comhpháirteanna agus an bealach a nascann siad

Is íomhá amháin atá san API agus san oibrí. Tá an dá phacáiste ceangailte go dlúth lena chéile, agus mar sin tógann Dockerfile.app an fhoireann iomlán aon uair amháin, agus athraíonn coimeádán an oibrí an t-ordú go node worker/dist/index.js. Sa mhód local níl aon choimeádán oibrí ann: ritheann an API an t-oibrí laistigh dá phróiseas féin.

Níl Redis ann. Tá an scuaine tascanna agus an t-iompar fíor-ama beirt bunaithe ar Postgres, de chinneadh agus ní de dhearmad. Scriosann an crann Google Cloud a mhodúil Pub/Sub agus Redis ar an gcúis chéanna.

Calafoirt

Sa fhorbairt áitiúil tá an API ar 5454 agus an riarthóir ar 5455 de réir réamhshocraithe. Is féidir le cóip oibre den stór péire dá chuid féin a ghlacadh trí NESSIE_API_PORT agus NESSIE_ADMIN_PORT a shocrú, sa timpeallacht nó in .env an stórais; léann gach uirlis sa stór, na sraitheanna tástála brabhsálaí ina measc, an dá luach chéanna. Roghnaigh an péire sula dtosaíonn tú agus coinnigh é: má bhogann tú seirbhís atá ag rith go calafort eile, bíonn an riarthóir ag labhairt leis an API mícheart.

Tá an táirgeadh difriúil, agus ní athraíonn an riail sin é. Éisteann coimeádán an API go hinmheánach ar 5554 (le NESSIE_API_PORT) agus an athsheachadán brú ar 5556, beirt taobh thiar den reverse proxy.

Á rith ar mheaisín amháin, le haghaidh forbartha

Seolann an stór comhad Compose nach bhfuil ann ach bunachar sonraí, agus is sin uile a theastaíonn don lúb áitiúil.

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

Foilsíonn an coimeádán sin Postgres ar 55432, agus is nessie an t-ainm ar an úsáideoir, ar an bpasfhocal agus ar an mbunachar sonraí araon. Cuirtear an teaghrán nasctha i .env ag fréamh an stóir — léann script forbartha an API é — agus ansin cuirtear na migrations i bhfeidhm agus tógtar an t-oibrí uair amháin, mar i mód áitiúil lódálann an API an t-oibrí óna dist tógtha:

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

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

Ritheann pnpm dev an API agus an riarthóir ag an am céanna, le hathlódáil te, ar 5454 agus 5455. Seiceáiltear gur fhreagair an API ar GET /api/health.

Postgres, agus an riachtanas pgvector

Cruthaíonn na migrations trí shíntí féin — vector, pg_trgm agus pgcrypto — mar sin caithfidh an ról a ritheann iad cead a bheith aige síntí a chruthú. Ar Postgres bainistithe is é sin an rud is cóir a sheiceáil roimh rud ar bith eile.

Is cuid den scéim é leithead an vector, ní socrú. Is colúin vector(N) iad thoughts.embedding, thought_recalls.query_embedding agus knowledge_page_chunks.embedding, agus luaitear N uair amháin mar EMBEDDING_DIMENSIONS in packages/schemas/src/embedding.ts — 1024 faoi láthair, leithead dúchasach an mhúnla leabaithe a úsáidtear sa táirgeadh. Seolann gach iarratas leabaithe an leithead sin, agus teipeann go glórach ar sholáthraí a fhreagródh ar leithead eile, seachas vectóirí a scríobh nach nglacfadh an bunachar sonraí leo. Chun bogadh go múnla leabaithe de leithead eile, caithfear an tairiseach sin a athrú, migration a scríobh a athchineálann na trí cholún, agus athleabú a dhéanamh: ní féidir vectóirí de leithead éagsúil a thiontú, mar sin ní ghearrann an migration iad ach cuireann sé ar neamhní iad.

Má reáchtáiltear Nessie taobh le feidhmchláir eile ar líonra Docker roinnte, is cóir ainm ar leith a thabhairt do choimeádán a bhunachair sonraí. Is nessie-postgres ainm seirbhíse Compose an tionscadail, agus ní postgres riamh, mar bíonn ainm na seirbhíse ina ailias DNS ar an líonra roinnte, agus má bhíonn imbhuailt ann rothlaíonn postgres:5432 idir dhá bhunachar sonraí.

Cumraíocht

Tá an chumraíocht ama rite ina sraitheanna: comhad nessie.config.json feistithe san API agus san oibrí le léamh-amháin, agus athróga comhshaoil os a chionn. Is é ConfigEnvMap in packages/config an mheaitseáil idir an dá cheann, agus is é sin an liosta údarásach.

Roghnaíonn NESSIE_MODE cruth an imscartha: local (an réamhshocrú, agus conair na forbartha), hosted nó selfHosted — is é sin a shocraíonn suiteáil féin-óstáilte. Díchumasaíonn sé logáil isteach forbartha agus éilíonn sé liosta ceadaithe CORS.

Seo na socruithe nach dtosóidh imscaradh selfHosted, nó nach n-oibreoidh sé, gan iad:

Tá infrastructure/compose/.env.prod.example ar an gcruth beacht ar fad acu, leis na bloic roghnacha — stóráil réad, stóras rúnda, SSO, post nasctha — curtha i dtrácht san áit cheart. Is é docs/deployment/configuration.md an catalóg iomlán, lena n-áirítear gach socrú roghnach.

Imscaradh le Docker Compose

Cóipeáiltear .env.prod.example go .env in aice le docker-compose.prod.yml agus líontar isteach é, ansin cuirtear an bunachar sonraí ar siúl, tógtar, cuirtear na migrations i bhfeidhm agus tosaítear. Tá an t-ordú tábhachtach: ritheann na migrations agus na seeds i gcoinne bunachair sonraí atá suas cheana, sula bhfreastalaíonn aon tseirbhís.

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

Ritheann na Dockerfiles táirgthe lint ar gach pacáiste sula dtógtar é, agus mar sin is teip tógála é teip lint.

Ní roghnach an chéim reconcile

Socraíonn reconcile rialacha polasaí réamhshocraithe gach eagraíochta agus cuireann sé le deontais uirlisí cosanta MCP agus Personal Assistant atá ar iarraidh. Ba ghnách leis an API é seo a dhéanamh ag tosú ar gach macasamhail; anois ceanglaíonn sé, éisteann sé, agus ní dhéanann sé tada eile. Mar sin, gan an chéim seo ní bhíonn rialacha polasaí ag an gcéad eagraíocht, agus diúltaítear gach ceangal gníomhaire. Tá sé idempotent, mar sin is saor é a rith ar gach scaoileadh — agus caithfidh uasghrádú a cuireadh i bhfeidhm de láimh é a rith freisin.

An chéad chuntas úinéara

Ní bhíonn úsáideoirí ar bith ag suiteáil nua selfHosted, mar sin cruthaíonn an API comhartha tosaithe aon-uaire agus logálann sé URL socraithe. Stóráiltear an comhartha i Postgres seachas i bpróiseas, ionas go n-aontaíonn gach macasamhail air.

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

Oscail https://<your-admin-host>/bootstrap?token=<token> agus cruthaigh cuntas an úinéara. Éagann an comhartha tar éis 15 nóiméad; atosaigh seirbhís an API chun ceann nua a chruthú.

Má chumraítear SSO, níl aon chéim tosaithe ann ar chor ar bith. Cuirtear an mód tosaithe ar leataobh an nóiméad a chumasaítear soláthraí seachtrach fíordheimhnithe — ar shlí eile bheadh sé ag glacadh seilbh ar an scáileán logála isteach — agus an chéad duine a logálann isteach trí SSO, cruthaíonn sé an fhoireann réamhshocraithe agus bíonn sé ina úinéir uirthi.

Tátal a chumrú

Tá comhoiriúnacht OpenAI ag an gcomhrá. Is é NESSIE_MODEL_BASE_URL an críochphointe, NESSIE_MODEL_API_KEY an eochair iompair, agus ainmníonn NESSIE_MODEL_PROVIDER an t-oiriúnóir. Tiomsaíonn Nessie oiriúnóirí do openai, kimi agus deepseek, agus baineann sé amach aon rud eile tríd an nascóir ginearálta comhoiriúnach le OpenAI. Socraíonn NESSIE_MODEL_NAME an tsamhail réamhshocraithe don imscaradh, ach bíonn tosaíocht níos airde ag roghnú samhla an ghníomhaire aonair ós a chionn.

Tá leabuithe á dtreorú ar leithligh, mar b’fhéidir nach dtabharfaidh an soláthraí comhrá seirbhís leabaithe dóibh ar chor ar bith — níl críochphointe leabaithe ag DeepSeek, mar shampla. Oidhreann gach réimse NESSIE_EMBEDDING_* nach socraítear an soláthraí comhrá, mar sin leabaíonn imscaradh nach socraíonn ceann acu iad tríd an gcríochphointe comhrá. Socraítear NESSIE_EMBEDDING_PROVIDER, NESSIE_EMBEDDING_MODEL agus, ar sheachfhreastalaí a dhíríonn de réir seirbhíse, an chuid seirbhíse, nuair nach féidir leis an soláthraí comhrá leabú. Má dhéantar é seo mícheart, teipeann go ciúin seachas go glórach: titeann athghairm cuimhne agus cuardach an bhunachair eolais ar chainéal lexical agus leanann siad ar aghaidh, agus logáiltear kb_search: query embedding failed de réir a chéile.

Níl cuntasaíocht chaiteachais Nessie — leabhar comharthaí in aghaidh na heagraíochta agus geata an bhuiséid — ag brath ar an gcríochphointe a phointeáiltear chuige, agus oibríonn sé mar an gcéanna cibé an bhfuil aitheantas glaonna sínithe cumraithe nó nach bhfuil.

Logáil isteach

Fíordheimhníonn Nessie daoine trí UnlikeOtherAI, a bhainistíonn struchtúr na heagraíochta agus na foirne freisin. Ní thaispeánann leathanach logála isteach an riarthóra ach cnaipe amháin, “Login / Register”.

Is sreabhadh cumraíochta-JWT atá sa chomhtháthú seachas OIDC caighdeánach: freastalaíonn an API ar dhoiciméad cumraíochta RS256 sínithe ag GET /api/auth/sso/config, agus an JWKS comhfhreagrach ag GET /.well-known/jwks.json, beirt ar óstach an API. Is seicheamh aon-uaire é a shocrú — gintear péire eochracha RSA-2048 agus socraítear UOA_CONFIG_JWT_PRIVATE_KEY_B64, UOA_CONFIG_JWT_KID, UOA_DOMAIN, UOA_CONFIG_URL, UOA_JWKS_URL, UOA_REDIRECT_URL agus UOA_CONTACT_EMAIL; cliceáiltear ar an gcnaipe uair amháin, rud a ardaíonn iarratas comhtháthaithe; ceadaítear é, rud a sheolann nasc aon-uaire chuig an seoladh teagmhála, nasc a iompraíonn an rúnda cliant; socraítear UOA_CLIENT_SECRET agus atosaítear an API. Ní mór go mbeadh an kid uathúil do gach fearann.

Fearann a chur os a chionn, le TLS

Freastalaíonn imscaradh ar thrí ainm: an suíomh poiblí, an riarthóir, agus an API. Níl bunús an riarthóra agus bunús an API ionann. Leabaítear VITE_API_BASE_URL sa bhuanda ag an tógáil ag Dockerfile.admin, mar sin caithfear gach déantán riarthóra tógtha — lena n-áirítear tógáil deisce a leabaíonn é — a thógáil i gcoinne bhunús an API. Má thógtar i gcoinne bhunús an riarthóra féin é, réitíonn /api/auth/providers ar bhlaosc HTML an riarthóra, agus fágtar an logáil isteach ina seasamh ag “Loading providers...”.

Críochnaíonn Caddy TLS ar an táirgeadh, agus faigheann sé teastais in-ainm-óstach de réir HTTP-01, agus ní theastaíonn plugin soláthraí DNS uaidh chuige sin. Treoraítear an seachfhreastalaí chuig na coimeádáin riarthóra agus suímh ar chalafort 80, agus chuig an API ar a chalafort inmheánach.

Socraítear NESSIE_API_TRUSTED_PROXY_HOPS go dtí líon na seachfhreastalaithe os comhair an API — 1 taobh thiar de sheachfhreastalaí amháin. Is é 0 an réamhshocrú, agus déanann sé neamhaird iomlán de X-Forwarded-For. Is cinneadh amháin é seo le dhá iarmhairt: is é a eochraíonn freisin teorainneacha rátaí fíordheimhnithe, mar sin má tá sé ró-íseal roinneann gach cliant buicéad an tseachfhreastalaí, agus má tá sé ró-ard is féidir le cliant a sheoladh féin a fhalsú. Is fearr earráid ar an taobh íseal, agus tomhas a dhéanamh air.

Is féidir gach eagraíocht agus foireann a fhreastalú ar a fho-fhearann féin, ach tá sé as ar bun de réir réamhshocraithe. Rialaítear é le NESSIE_TEAM_HOST_BASE_DOMAIN: murab é atá socraithe, ní dhírítear tionóntaí de réir óstainm ar chor ar bith, agus diúltaíonn an geata eisiúna teastas NESSIE_TLS_CHECK_KEY gach iarratas fad is nach bhfuil sé socraithe — agus is é sin an réamhshocrú ceart d’imscaradh nach n-úsáideann an ghné.

Seiceálacha sláinte

Ar SIGTERM, folmhaíonn an API seachas bás a fháil san áit ina bhfuil sé. Teorainníonn NESSIE_SHUTDOWN_TIMEOUT_MS an folmhú sin, agus is é 25 soicind an réamhshocrú. Caithfear é a choinneáil faoin tréimhse ghrásta a thugann an treoraire don choimeádán, nó maraíonn an rith an próiseas ar dtús, agus ní bhaineann an folmhú aon tairbhe as.

Uasghrádú

Is é uasghrádú prisma migrate deploy ar an mbunachar sonraí atá ann cheana, ansin na seeds, ansin reconcile. Na ceithre ordú céanna agus a bhí sa chéad imscaradh.

Tá an conair tástáilte don bhealach a ghlacann féin-óstálaí i ndáiríre, seachas i gcoinne bunachair sonraí úir: athchóiríonn CI íomhá a tógadh fiche imirce taobh thiar, imirceann sé go ceann reatha, bailíochtaíonn sé an scéim, agus rithfidh sé seiceáil smoke ar na táblaí croí. Is foinse uasghrádaithe chruthaithe aon scaoileadh laistigh den fhuinneog ar deireadh. Tá fillteáin imirce do-athraithe nuair a bhíonn siad geallta, agus teipeann an tógáil ar chéim lint má athainmnítear, uimhrítear arís, scriostar nó athraítear fillteán imirce, mar go bhfuil na ceithre rud sin ag briseadh migrate deploy do bhunachar sonraí a chláraigh an sean-sraith cheana.

Cuireann imirce amháin a theip gach imscaradh ina dhiaidh sin ar sos. Stopann migrate deploy ar an gcéad teip agus diúltaíonn sé gach imirce níos déanaí le P3009, agus fanann an suiteáil ar an sean-scaoileadh go dtí go nglanann duine é de láimh. Chaith táirgeadh an tionscadail féin lá ag diúltú d’imscaradh ar an mbealach seo. Chun é a ghlanadh ní mór a dhearbhú gur rolladh ar ais go fíor an imirce a theip — níor cheart aon cheann de na réada a chruthaíonn sí a bheith ann, agus ba cheart go mbeadh an rud a athraíonn sí ina chruth bunaidh fós — agus ansin ní mór é a réiteach mar rolladh ar ais. Ní iarrthóir é imirce a cuireadh i bhfeidhm go páirteach.

Níl cúltaca agus athchóiriú don imscaradh Docker Compose féin-óstáilte doiciméadaithe sa stór, mar sin ní thuairiscíonn an leathanach seo nós imeachta dó.

Meaisín amháin, nó scamall bainistithe

Is í an chonair Docker Compose ar aon óstach amháin an chonair fhíoraithe — is í a rithtear i dtáirgeadh an tionscadail féin, ar fhreastalaí amháin, leis an mbunachar sonraí, stóráil réad, an API, an t-oibrí, an riarthóir agus an suíomh mar choimeádáin taobh thiar de sheachfhreastalaí roinnte.

Athraíonn scálú thar aon mheaisín amháin trí thrí rud, agus iad uile curtha i bhfeidhm seachas molta. Taobh amuigh de mhód local ritheann Nessie an API agus an t-oibrí mar phróisis ar leith, agus mar go leor macasamhail de gach ceann, mar sin diúltaítear aon chumas a shuíonn go bhfuil diosca an mheaisín faoi úinéireacht phróiseas amháin: stóráil réad comhad (teip tosaithe), teamplaí timpeallachta feidhmithe leis an soláthraí docker (neamhéifeachtach, agus teipeann an soláthar go glórach), agus na huirlisí tógtha file_read, file_write agus file_glob (toradh uirlise teipthe ar féidir leis an ngníomhaire é a léamh). Luann gach diúltú an socrú, an mód, agus cad is féidir a úsáid ina ionad.

Don scamall bainistithe, tá crann Terraform sa stór in infrastructure/terraform/ a dhíríonn ar Google Cloud: an API mar sheirbhís Cloud Run le híoslion amháin — coinníonn sé cliant LISTEN Postgres leanúnach agus ritheann sé scuabanna cothabhála, mar sin ciallaíonn scálú go nialas go stopann an seachadadh fíor-ama — an t-oibrí mar pholl oibrí Cloud Run, mar ní cheanglaíonn sé calafort agus ní bheadh seirbhís réidh riamh; post imirce a ghatálann gach scaoileadh; Cloud SQL do PostgreSQL 17; agus buicéad GCS a rochtnaítear tríd an mbackend S3-chomhoiriúnach.

Tá an conair sin scríofa, ní siúlta. Deir an stór é sin go soiléir, agus deir an leathanach seo é freisin: níl aon tionscadal Google Cloud ann dó, níor pleanáladh ná níor cuireadh i bhfeidhm aon rud sa chrann i gcoinne tionscadail fhíor, níl an conair uaslódála ilchodaí go GCS tástáilte i gcoinne buicéid fhíor, níl cineál an phoill oibrí bailíochtaithe, agus is áit choinneála í líon na n-athsheachadán óstach sa chrann — ní tomhas é ach áit choinneála atá le tomhas a dhéanamh air. Ní léirítear an riarthóir ná an suíomh poiblí ann ar chor ar bith. Glactar leis mar phointe tosaigh atá le fíorú, ní mar imscaradh tacaithe.

Tá leathanach ar leith ann maidir le cá bhfuil sonraí an imscartha, cad a choinníonn an bogearraí agus cad nach gcoinníonn sé d’aon ghnó: Déanta san AE, agus cá bhfuil na sonraí.