Kirjaudu sisäänVaraa esittely

Luku 2.1

Arkkitehtuuri

Mitä kukin Nexus-kaavion palvelu omistaa ja mitkä tietovarastot ovat sen alla, sekä säännöt, jotka pitävät ne yhdessä aina palveluiden välisestä identiteetistä polkuun, jonka jokainen mallikutsu kulkee.

Tämä sivu on käännetty tekoälyllä englanninkielisestä alkuperäistekstistä. Jos jokin kohta on epäselvä, englanninkielinen sivu on ensisijainen lähde. Lue tämä sivu englanniksi

19 minuutin lukuaika

Kun Tomás Reilly sai ensimmäisen asennuksen valmiiksi Harrow Port Authoritylla, kubectl -n nexus get pods näytti kymmenen Deployment-resurssia ja seitsemän StatefulSet-resurssia sekä kolme CronJob-työtä. Tietokannan rakentaneet migraatio-Jobit olivat jo poistuneet, sillä jokainen niistä poistaa itsensä onnistuessaan. Tuo listaus on koko alusta. Opetelkaa se, sillä useimmat käyttöönoton jälkeiset kysymykset alkavat sanoin ”mikä näistä omistaa tuon?”

Tämä luku vastaa siihen jokaisen osan kohdalla, seuraa yhtä pyyntöä niiden läpi ja käy sitten läpi säännöt, joita ne kaikki noudattavat. Osan 2 loppuosa rakentuu tämän kokonaiskuvan päälle.

Palvelut ja mitä kukin niistä omistaa

Chart on yksi Helm-chart, nexus, versio 1.0.0-alpha.1, joka on tarkoitettu Kubernetes-versiolle 1.33 tai uudemmalle. Jokainen työkuorma ajetaan oman ServiceAccount-tilinsä alla, muuna kuin pääkäyttäjänä (non-root), kaikki Linux-valtuudet (capabilities) pudotettuina. Kutsut identiteettiä ja avaimia vartioiviin palveluihin kulkevat molemminpuolisen TLS-yhteyden (Transport Layer Security) yli, ja julkinen API (ohjelmointirajapinta, application programming interface) jakaa prosessin tekoälyreitittimen (AI, artificial intelligence) kanssa.

Komponentti Deployment ja Service Palveluportti Mitä se omistaa
Konsoli nexus-alpha 3000 Sivut, jotka käyttäjät näkevät; tarjoilee HTML-koodia (Hypertext Markup Language) konsoliverkkotunnuksessa
BFF (käyttöliittymäkohtainen taustapalvelu) nexus-alpha-bff 8080 Konsolin omat tiedot, kunkin käyttäjän saama valikko, julkaisurekisteri
Todennus nexus-auth 9101 (molemminpuolinen TLS portissa 8443) Henkilöt, organisaatiot, istunnot, poletit, API-avaimet, organisaation malliavainvaranto
Yhdyskäytävä nexus-gateway 9092, WebSocket 8093 AI Provider Router sekä julkinen API-reuna REST- (representational state transfer) ja MCP-kutsuille (Model Context Protocol)
Orkestroija nexus-orchestrator 8080 UNO-lähetys: jokaisen työn vastaanottaminen ja asettaminen jonoon
Työnkulut nexus-workflows 8081 UNO-suoritus: työntekijäprosessi, joka ajaa jonossa olevat työt
GraphRAG nexus-graphrag 8090, WebSocket 8091 Muisti: tietograafi ja siihen kohdistuva tiedonhaku
Probitas nexus-probitas 9151 (HTTPS) Todisteet: hallintotietueet ja sinetöity tilikirja
Taitomoottori nexus-skills-engine 8095 Taitokirjasto; taitojen etsiminen ja suorittaminen
Avaimet nexus-keys 8080 (HTTPS, molemminpuolinen TLS) Organisaatiokohtaiset avaimet OpenBaossa, säilytys, asennusidentiteetti
Lisäosat nexus-plugins 9111 Lisäosarekisteri ja luettelotietueet; oletuksena pois päältä
Tiedostojen käsittely nexus-fileprocess 9109 Ladattujen asiakirjojen ja kuvien lukeminen; oletuksena pois päältä

Kymmenen ensimmäistä ovat pakollisia. Kaksi viimeistä ovat valinnaisia, ja ne kytketään päälle asetuksilla components.plugins.enabled ja components.fileprocess.enabled silloin, kun Enterprise-asennus tai toimialapaketti käyttää niitä. Vielä yhdellä valinnaisella palvelulla, nexus-alive portissa 8080, on oma kytkimensä, components.alive.enabled, ja sekin on oletuksena pois päältä. Kunkin replikat ja resurssit sijaitsevat kohdassa components.<name>.

Konsoli koostuu palvelimella hahmonnetuista sivuista ilman tietokantaa. Se keskustelee BFF:n ja klusterin sisäisen nexus-auth-palvelun kanssa, eikä koskaan ulos julkisen todennuspalvelimen kautta ja takaisin sisään. Se kieltäytyy käynnistymästä ilman versiotaan (edition), jonka Helm-kaavio (chart) välittää arvona NEXUS_EDITION yhdestä edition-arvosta. Jokainen organisaation jäsen työskentelee siinä roolinsa mukaisesti. Hallintasivut ovat omistajille ja pääkäyttäjille, ja jäsen, joka avaa sellaisen, saa ”Not an administrator” -sivun.

BFF on konsolin palvelinpuoli, ja se on rakennettu alustan lisäosaksi, joka on rekisteröity Nexus Alpha -tuotteeksi. Se pitää konsolin omia tauluja erillisessä tietokannassa, nexus_alpha, ja päättää, mitkä valikkoryhmät käyttäjä näkee. Kun konsoli tarvitsee suorittaa työtä, BFF pyytää sitä palvelulta, joka sen omistaa.

nexus-auth on kirjoitettu Go-kielellä, ja se on ainoa palvelu, joka luo poletteja. Käyttöpoletit ovat oletuksena voimassa 15 minuuttia ja virkistyspoletit 12 tuntia (auth.accessTokenTTL, auth.refreshTokenTTL). Se rajoittaa jokaisen kirjautuneen käyttäjän 5,000 pyyntöön minuutissa ennen kuin se vastaa tilakoodilla 429 (auth.rateLimitPerMinute). Se ajaa kahta kuuntelijaa: tavallista konttiportissa 8080, johon julkinen Ingress yhdistää, ja molemminpuolista TLS-kuuntelijaa portissa 8443, jota jokaisen klusterin sisäisen kutsujan on käytettävä. Se luottaa X-Forwarded-For-otsikkoon vain niistä hypyistä, jotka ovat kohdassa proxy.trustedCIDRs, joka on luettelo CIDR-osoiteavaruuksista (Classless Inter-Domain Routing) ja jonka oletusarvo on 10.42.0.0/16, k3s-pod-verkko. Jos ingress-ohjaimenne ajetaan muualla, muuttakaa se. Muussa tapauksessa jokainen kirjautuminen näyttää tulevan ohjaimelta.

Yhdyskäytävällä on kaksi tehtävää, jotka jakavat yhden prosessin. Klusterin sisällä se on AI Provider Router (tekoälyn kytkentäkeskus osassa 1 ja konsolin sivuilla), joka on organisaation mallivaltuuksien ainoa haltija (siitä lisää alla). Reunalla se on kohde, johon api.<domain> yhdistää: REST-asiakkaat ja MCP-asiakkaat, joiden poletit kantavat kohdeyleisöä https://<hosts.api>/mcp ja tulevat OAuth 2.1 -valtuutuspalvelimelta todennusosoitteessa (OAuth on avoin standardi delegoidulle valtuutukselle).

Orkestroija ja työnkulut muodostavat yhdessä UNOn, työnkulkumoottorin. Kaikki laskenta kulkee niiden kautta. Orkestroija ottaa työn vastaan reitillä POST /api/v1/dispatch, vastaa tilakoodilla 202 sekä arvoilla jobId, runId ja traceId, ja asettaa sen jonoon. Suoraa suorituspolkua (inline) ei ole: asiakas kysyy aina tilaa reitiltä GET /api/v1/dispatch/{jobId} tai vastaanottaa takaisinkutsun. Työnkulkujen työntekijäprosessi hakee töitä jonosta, oletuksena neljä kerrallaan replikaa kohden (workflows.concurrency), ja sillä on täsmälleen yksi HTTP-reitti, GET /health.

Probitas on todistepalvelu. Se tarjoilee itse TLS-yhteyden kaavion myöntämästä varmenteesta ja pitää taulunsa trust-skeemassa, jossa tilikirjalle on erillinen rooli. Sen hallintaominaisuuksia ohjataan kytkimellä probitas.flags. Useat niistä toimitetaan shadow-tilassa: päätös lasketaan ja kirjataan, eikä mitään estetä ennen kuin muutatte lippua.

nexus-keys on Go-kielellä kirjoitettu alustan avainpalvelu. Se säilyttää organisaatiokohtaista avainta OpenBao-avainsäilössä ja kierrättää ne joka yö. Sen yölliset ajot myös tuhoavat avaimet, joiden säilytyspäivä on koittanut, ja vievät kuittauksensa omaan tallennusosiinsa. Organisaation avaimen poistaminen tekee sillä lukitusta datasta pysyvästi lukukelvotonta. Se myös luo asennusidentiteetin ensimmäisen alustuksen yhteydessä kohdassa keys.installationName, ja tuo nimi on pysyvä. Valitkaa se huolellisesti: kaavio hylkää tyhjän nimen (INSTALLATION_NAME_MISSING) ja hylkää omissa esimerkkiarvoissaan olevan nimen (INSTALLATION_NAME_EXAMPLE).

Tämä asennus (Community)
Tämä asennus (Community)
Community-asennuksen oma sivu näyttää sen version ja moottorin tilan. Siinä sanotaan selkeästi, ettei lisenssiä tarvita. Sivun Enterprise-osat näytetään esittelyinä.

Kolme julkista verkko-osoitetta

Kaavio julkaisee täsmälleen kolme verkkotunnusta (host name), jotka yhdessä muodostavat asennusidentiteetin. Jokainen palvelu kieltäytyy käynnistymästä ilman niitä.

Ingress Host-arvo Taustapalvelu
nexus-console hosts.console nexus-alpha, portti 3000
nexus-api hosts.api nexus-gateway, portti 9092
nexus-auth hosts.auth nexus-auth, portti 9101

Tämän kirjan esimerkit käyttävät arvoja console.harrow.example, api.harrow.example ja auth.harrow.example. Ingress-resurssit ovat tavallisia networking.k8s.io/v1-objekteja, joissa kussakin on yksi sääntö, polku /. Reunan TLS noudattaa asetusta tls.mode: existing (luomanne Secret, joka on nimetty kohdassa tls.existingSecret), cert-manager (ajamanne ClusterIssuer, joka on nimetty kohdassa tls.clusterIssuer) tai none (TLS päättyy klusterin edessä). Kaavio ei lisää omaa uudelleenohjaustaan, joten ACME-protokollan (Automated Certificate Management Environment) HTTP-haaste saavuttaa ratkaisijanne muuttumattomana. Luku 2.11, Muunnelmat: ulkoiset tietovarastot, TLS ja ingress, käsittelee kunkin tilan.

Mitään muuta ei altisteta ulospäin. Tietovarastot, OpenBao ja jokainen sisäinen palvelu kuuntelevat vain nimiavaruuden sisällä.

Kolme vaakasuoraa kaistaa. Ylin kaista on "Edge", jossa on kolme Ingress-laatikkoa nimeltä console, api ja auth, joista jokainen osoittaa alas omaan Service-palveluunsa (nexus-alpha :3000, nexus-gateway :9092, nexus-auth :9101). Keskimmäinen kaista on "Platform services": laatikko palvelulle nexus-alpha-bff; nexus-orchestrator palvelun nexus-workflows vieressä, ryhmiteltynä ja nimettynä UNO; sitten nexus-graphrag, nexus-probitas, nexus-skills-engine, nexus-keys; sekä kaksi katkoviivalla piirrettyä laatikkoa valinnaisille palveluille nexus-plugins ja nexus-fileprocess. Alin kaista on "Data tier", jossa on yksi laatikko kutakin tietovarastoa kohden (PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS), sekä erillinen aidattu laatikko nimeltä "Key store", joka sisältää komponentit openbao ja openbao-unsealer, ja johon on yhteys vain palvelulla nexus-keys.
Nexus-asennuksen komponentit ja niiden alla olevat tietovarastot.

Pyyntö alusta loppuun

Näin tapahtuu, kun Aoife Brennan, Harrow'n IT-johtaja, avaa konsolin ja esittää avustajalle kysymyksen tämän kuukauden laituripaikka-aikataulusta.

  1. Hänen selaimensa lataa osoitteen https://console.harrow.example. nexus-console-Ingress lähettää sen palvelulle nexus-alpha porttiin 3000.
  2. Hän kirjautuu sisään avainkoodillaan (passkey). Kirjautumissivut keskustelevat palvelun nexus-auth kanssa osoitteen auth.harrow.example kautta, ja nexus-auth luo hänelle käyttöpoletin, joka sisältää hänen käyttäjänsä, organisaationsa ja, kun hänen istunnollaan sellainen on, liiketoimintayksikkönsä.
  3. Konsolin palvelin kutsuu BFF:ää, joka tarkistaa hänen polettinsa ja kysyy nexus-auth-palvelulta, onko hänen organisaatiollaan kyseinen tuote ja sallitaanko hänen roolinsa. Se vastaa valikkoryhmillä, jotka hän saa nähdä.
  4. Hänen kysymyksensä kulkee BFF:ltä orkestroijan lähetysreitille mukanaan hänen organisaationsa ja käyttäjänsä, jotka on otettu vahvistetusta poletista. Orkestroija vastaa tilakoodilla 202 ja laittaa työn jonoon Valkeyssa.
  5. Työnkulkujen työntekijäprosessi ottaa työn. Taitomoottori selvittää suoritettavan taidon, ja haku Harrow'n asiakirjoista menee GraphRAGille, joka lukee Neo4j:tä, Qdrant-kantaa ja omaa PostgreSQL-skeemaansa.
  6. Mallikutsu menee AI Provider Routerille osoitteeseen /internal/ai/chat. Reititin valitsee palveluntarjoajan ja mallin Harrow'n omasta avainvarannosta ja reitityskäytännöstä, tekee kutsun Harrow'n avaimella ja palauttaa vastauksen.
  7. Tulos päätyy työn ajoriville. BFF lukee sen ja konsoli piirtää vastauksen lähdeviitteineen.

Palvelusta palveluun kulkevat hypyt kantavat projisoituja palvelupoletteja, kutsut nexus-auth-, nexus-keys- ja Probitas-palveluihin kulkevat asennuksen oman varmentajan myöntämän TLS-yhteyden yli, ja jokainen tietojen haku vaiheissa 4–6 on rajattu Harrow'n organisaatioon itse tietokannassa. Alla olevat osiot selittävät molemmat.

Tapahtumasarja vasemmalta oikealle. Selainlaatikko lähettää pyynnön "1 page" Ingress console -kohteeseen ja sieltä edelleen palveluun nexus-alpha. Sivunuoli "2 sign-in" kulkee selaimesta Ingress auth -kohteen kautta palveluun nexus-auth. nexus-alpha lähettää pyynnön "3 menu" palveluun nexus-alpha-bff, joka tarkistaa asian palvelulta nexus-auth. nexus-alpha-bff lähettää pyynnön "4 dispatch, 202" palveluun nexus-orchestrator, joka kirjoittaa Valkey-jonokuvakkeeseen. nexus-workflows hakee tehtävän "5 job" jonosta ja kutsuu palveluita nexus-skills-engine ja nexus-graphrag (jonka kolme tietovarastoa on piirretty GraphRAG:n alle). nexus-workflows lähettää pyynnön "6 chat" palveluun nexus-gateway, joka on nimetty "AI Provider Router: organisation key pool", ja joka lähettää yhden nuolen klusterin rajan ulkopuolelle kohteeseen "model provider". Katkoviivalla piirretty paluunuoli "7 result on run row" palaa takaisin palveluun nexus-alpha-bff.
Yksi avustajakysymys selaimesta mallin tarjoajalle ja takaisin.

Datakerros

Nexus toimittaa oman allekirjoitetun kopionsa jokaisesta tietovarastosta, ja kunkin lähdekooditarjous on mukana paketissa. Jokainen niistä on valittu yhtä lailla lisenssinsä kuin toiminnallisuutensakin vuoksi.

Tietovarasto Versio Lisenssi Miksi se on mukana Portti Oletustallennusosa
PostgreSQL sekä PostGIS ja pgvector PostgreSQL 16, PostGIS 3, pgvector 0.8 PostgreSQL-lisenssi; PostGIS GPL-2.0-or-later Jokaisen palvelun pääjärjestelmä (system of record); PostGIS karttadataa varten; pgvector rivien rinnalla pidettäviä vektoreita varten 5432 50 GiB
Valkey 8.1 BSD-3-Clause UNO-työjonot ja lyhytikäiset välimuistit, kuten nexus-auth-palvelun API-avainvälimuisti 6379 5 GiB
Neo4j Community Edition 5.26 GPL-3.0 Tietämysgraafi, jonka GraphRAG rakentaa ja jota se käy läpi 7687 (Bolt) 20 GiB
Qdrant 1.15 Apache-2.0 Vektorihaku GraphRAGille ja taitomoottorille 6333 (HTTP), 6334 (gRPC-etäproseduurikutsut) 10 GiB
SeaweedFS 4.48 Apache-2.0 Objektitallennustila tiedostoille, yhteensopiva Amazon Simple Storage Servicen (S3) kanssa 8333 50 GiB
OpenBao 2.6 MPL-2.0 Avainsäilö ja sen avaaja nexus-keys-palvelua varten 8200 5 GiB ja 1 GiB

Jotkin valinnat korvasivat jotain tutumpaa. Valkey korvaa Redis 7.4:n, jonka nykyiset lisenssit julkaisu hylkää. MinIO on AGPL-3.0, joten objektivarasto on SeaweedFS. GraphRAG käyttää Neo4j Community Editionia Bolt-verkkoprotokollan yli, ja palvelut käyttävät PostGISiä PostgreSQL-protokollan yli, joten GPL pysyy kummassakin niistä. OpenBao on Linux Foundationin haarautuma Vaultista ajalta ennen Vaultin lisenssimuutosta.

Jokaista tietovarastoa ajetaan todennus päällä ja luoduilla valtuuksilla: salasana Valkeylle, API-avain Qdrantille, käyttöavaimet SeaweedFS:lle.

Kukin kohdan dataTier alla olevista viidestä tietovarastosta ajetaan klusterissa (mode: in-cluster, oletusarvo) tai on sellainen, jota jo itse ylläpidätte (mode: external, asetuksella external.host ja kohdassa external.existingSecret nimetyllä Secret-resurssilla). Ulkoista PostgreSQL-tietokantaa varten asettakaa sslmode arvoon verify-full tai verify-ca ja laittakaa palvelimen varmentajan (CA, certificate authority) varmenne kyseiseen Secret-resurssiin; luvussa 2.11, Muunnelmat: ulkoiset tietovarastot, TLS ja ingress, on tarkemmat tiedot.

# harrow-values.yaml (Helm values): Harrow's own PostgreSQL, every other store in the cluster
dataTier:
  postgres:
    mode: external
    sslmode: verify-full
    external:
      host: pg.harrow.example
      existingSecret: harrow-postgres

OpenBao-pari on poikkeus: sitä ajetaan aina asennuksen sisällä, koska säilytys-Job (custody Job) alustaa sen siellä.

Palveluiden välinen identiteetti

Nexus toimii ilman palveluverkkoa (service mesh). Molemminpuolinen TLS tulee paikalliselta varmentajalta (CA, certificate authority), jonka kaavio luo cert-managerin kautta; cert-manager on asennettava ensin (v1.21.3 on testattu).

Itse allekirjoitettu Issuer tekee yhden CA-varmenteen, nexus-local-ca, ECDSA (Elliptic Curve Digital Signature Algorithm) P-256, joka on voimassa kymmenen vuotta. Toinen Issuer allekirjoittaa tällä CA:lla. Jokainen työkuorma, joka kutsuu TLS-palvelinta asennuksen sisällä, saa oman asiakasvarmenteensa nimeltä <service-account>-client-tls, joka on voimassa 90 päivää ja uusitaan 15 päivää ennen vanhenemista. Sen ainoa nimi on URI-tunniste (uniform resource identifier) SPIFFE-identiteettimuodossa:

spiffe://cluster.local/ns/<namespace>/sa/<service-account>

Jokainen työkuorma löytää CA:n julkisen varmenteen nimellä ca.crt omasta varmenne-Secretistään. Mikään pod ei liitä CA:n avainta, ettekä tarvitse trust-manageria.

Kolme palvelua vahvistaa kutsujat varmenteen perusteella. nexus-auth tekee sen toisessa kuuntelijassaan, portissa 8443, ja jokainen klusterin sisäinen kutsuja ottaa yhteyden siihen. nexus-keys tekee sen ainoassa kuuntelijassaan. Probitas tarjoilee TLS-yhteyden omasta varmenteestaan, nexus-probitas-tls, jonka se lukee uudelleen, kun cert-manager uusii sen. Yksikään niistä ei luota X-Forwarded-Client-Cert-otsikkoon.

Jokainen työkuorma saa myös tunnin voimassa olevat Kubernetes-poletit sijaintiin /var/run/secrets/nexus, yhden kutakin kutsumaansa palvelua kohden, kyseinen palvelu kohdeyleisönään. ConfigMap nexus-service-identities yhdistää jokaisen <namespace>/<service-account>-arvon palvelun tai lisäosan nimeen, ja siitä puuttuvalla työkuormalla ei ole identiteettiä ja se hylätään. Orkestroija ja Probitas tarkistavat nämä poletit Kubernetes API:lla. Käynnissä olevista palveluista vain nämä kaksi pitävät hallussaan oikeutta system:auth-delegator tai niillä on API-poletti liitettynä; ainoa muu työkuorma, jolla on poletti, on asennuksen yhteydessä ajettava säilytys-Job.

Verkkokäytäntö (NetworkPolicy) sulkee sen, mitä identiteetti ei sulje. Kaavio lähtee oletusarvoisesta estosta (default deny) ja sallii sitten liikenteen asennuksen omien podien välillä, DNS:n (Domain Name System), ingress-ohjaimen nimiavaruuden (networkPolicy.ingressNamespace, oletuksena kube-system) kolmeen julkiseen Service-resurssiin sekä API-palvelimen kahdelle poletin tarkistajalle. OpenBao-podeilla on eri tunniste (label) kuin muulla alustalla, joten avoin nimiavaruuden sisäinen sääntö ei yllä niihin: vain nexus-keys, sen Job-työt ja säilytys-Job pääsevät läpi porttiin 8200. Kaikki muu, mihin työkuorman on saatava yhteys nimiavaruuden ulkopuolella, kuten sähköpostivälittäjänne, laitetaan kohtaan networkPolicy.externalEgressCIDRs, joka on oletuksena tyhjä.

Migraatiot ja skeemakirjanpito

Migraatiot ajetaan Helm-koukkuina (hooks) vaiheissa post-install ja pre-upgrade. Post-install-koukku ajetaan sen jälkeen, kun julkaisun Deployment-resurssit on luotu. Ensimmäisessä asennuksessa palvelut siis käynnistyvät, kun niiden skeemoja ei vielä ole olemassa, ja ne joutuisivat kaatumissilmukkaan (crash-loop) vasten tietokantaa, jossa ei ole roolia, salasanaa eikä tauluja. Nexus välttää tämän tilikirjan (ledger) avulla.

Koukut ajetaan painojärjestyksessä, ja Helm odottaa jokaista Job-työtä ennen kuin seuraava painoarvo alkaa:

Painoarvo Koukku Mitä se tekee
-30 nexus-migrations-env ja esivaatimukset Luo vain koukuille tarkoitetun Secret-resurssin migraattorin valtuuksilla sekä kaiken, mitä säilytys-Job lukee
-20 nexus-db-bootstrap Luo nexus- ja nexus_alpha-tietokannat, migraattoriroolin, jokaisen palvelun ajonaikaisen roolin, laajennukset ja tilikirjan
-15 nexus-openbao-custody-init Alustaa avainsäilön ja avaajan sekä luo asennusidentiteetin
-12 nexus-graphrag-migrations GraphRAGin skeema, joka omistaa objektit, joihin nexus-auth-palvelun perustaso viittaa
-10 nexus-auth-migrations Identiteettiskeema
-5 orkestroijan, yhdyskäytävän ja Probitaksen migraatiot Niiden skeemat; Probitas tarkistaa ensin, että auth-taulut ovat olemassa
0 nexus-alpha-bff-migrations Konsolin oma tietokanta

Jokaisella migraatio-Jobilla on backoffLimit: 0, joten epäonnistunut migraatio keskeyttää asennuksen virheeseen.

Tilikirja on yksi taulu, nexus_release.schema_applied, jossa on rivi kutakin ketjua ja levykuvan tiivistettä (image digest) kohden. Jokainen koukku kirjoittaa rivinsä vasta sen jälkeen, kun sen migraatioajuri on palannut. Jokaisessa PostgreSQL:ää käyttävässä Deployment-resurssissa on alustuskontti (init container), wait-for-schema, joka lukee tuota taulua roolina, jolla ei ole oikeutta lukea mitään muuta (nexus_ledger_reader), ja odottaa, kunnes jokainen ketju, josta se on riippuvainen, näyttää rivin tämän julkaisun levykuvalle. Sen jälkeen palvelu käynnistyy. Työnkulkujen työntekijäprosessi odottaa orkestroijan ketjua, koska se jakaa kyseisen tietokannan, ja taitomoottori odottaa vain alustusta (bootstrap).

Se tekee kyselyn 3 sekunnin välein (schemaWait.intervalSeconds) ja luovuttaa 1 800 sekunnin jälkeen (schemaWait.timeoutSeconds) tulostaen rivin, jossa mainitaan vielä puuttuvat ketjut. Palvelun oma kontti ei koskaan käynnisty väärää skeemaa vasten.

kubectl -n nexus logs deploy/nexus-gateway -c wait-for-schema

Tästä syystä teidän ei pidä koskaan ajaa komentoa helm install --wait. Valitsimella --wait Helm odottaa Deployment-resursseja ennen kuin se ajaa post-install-koukut, ja Deployment-resurssit puolestaan odottavat koukkuja. Kumpikaan ei etene. Asentakaa ilman sitä ja odottakaa sen jälkeen; luku 2.6, Community-version asentaminen Kubernetesiin, antaa tarkan komennon.

Eristäminen kolmella akselilla

Jokainen luku, kirjoitus, työkalukutsu ja taidon lähetys Nexuksessa rajataan kolmella akselilla.

Akseli Kenttä Mitä se erottaa
Vuokraaja (Tenant) organization_id Yhden organisaation toisesta, ehdoton raja
Omistaja owner_user_id Yhden henkilön asiat kaikkien muiden asioista, myös saman organisaation sisällä
Yksikkö business_unit_id Organisaation alaosasto, valinnainen

Omistaja-akseli yllättää monet. Postilaatikko tai henkilökohtainen muistikirja on omistajalleen yksityinen jopa samassa yksikössä ja samassa roolissa toimivilta kollegoilta. Pääkäyttäjä asettaa käytännöt eikä lue sisältöä.

Akselit tulevat todennetusta pyynnöstä eivätkä mistään muualta. Mikään ympäristömuuttuja, otsake, kyselyparametri tai polun osa ei voi asettaa niitä. Pyynnön runko, joka nimeää organisaation, hylätään virheellä TENANT_NOT_A_PARAMETER. Rajapinta, joka ei pysty ilmoittamaan, mille vuokraajalle, omistajalle ja yksikölle rivi kuuluu, kieltäytyy tilakoodilla 403 SCOPE_PREDICATE_MISSING, ja runko luettelee, mitkä akselit selvisivät ja mitkä eivät. Se ei koskaan palaa käyttämään laajempaa lukua.

Tämä pätee kahdessa paikassa yhtä aikaa.

Tietokannassa. Jokainen palvelu yhdistää omilla ajonaikaisilla rooleillaan: nexus_auth, auth_app ja auth_platform identiteettipalvelulle, nexus_probitas ja nexus_probitas_ledger Probitakselle, sekä nexus_gateway, nexus_graphrag, nexus_skills, orchestrator_app, workflows_app ja loput muille. Yksikään niistä ei ole superuser eikä yhdelläkään ole BYPASSRLS-oikeutta. Yksikään ei myöskään omista käyttämiään tauluja, joten jokainen rivitason suojauskäytäntö (RLS, row-level security) koskee sitä. Roolit jakavat ryhmän, nexus_runtime, joka myöntää yhteyden ja skeeman käyttöoikeuden muttei lainkaan tauluoikeuksia; jokaiselle palvelulle myönnetään sen omat taulut sen omissa migraatioissa. Vuokraaja-asetukset, joita RLS-käytännöt lukevat, voidaan asettaa vain kunkin palvelun bind_scope-funktion kautta, joka ajetaan sen omistajana. Alustus (bootstrap) poistaa set_config-oikeuden kaikilta muilta, ja orkestroija sekä Probitas kieltäytyvät käynnistymästä, jos niiden ajonaikainen rooli voisi kutsua sitä suoraan (Probitas nimeää tämän virheellä DB_ROLE_SETS_SCOPE_DIRECTLY). Koko asennuksen ainoat superuser-yhteydet kuuluvat alustus-Jobille ja BFF:n provisiointivaiheelle.

Jaetussa rajatun kyselyn primitiivissä. Jokainen alustan tietovarasto (repository) ja jokainen SDK:n (ohjelmistokehityspaketti, software development kit) päälle rakennettu lisäosa perii yhden rajan, joka rakentaa SQL-predikaatin selvitetystä laajuudesta (scope). Sen laajuusfunktio ottaa vahvistetun identiteetin eikä sillä ole organisaatioparametria, joten kutsuja ei voi välittää sellaista sisään, eikä mikään reitti voi jättäytyä sen ulkopuolelle.

Vuokraajarajan ylityksiä on täsmälleen yksi, ja se on kapea: kirjattu valtuutus (grant). Kaksi henkilöä rivejä hallussaan pitävässä organisaatiossa kirjaa, mikä organisaatio saa lukea mitäkin tauluja ja mihin asti. Jokainen luku ajetaan vain luku -tapahtumassa (read-only transaction) ja kirjataan lokiin molemmissa vuokraajissa. Omistajat ja pääkäyttäjät eivät koskaan lue rajan yli, eikä lukija voi laajentaa valtuutusta.

Tekoälypolku

Kutsujat esittävät toiveita. AI Provider Router omistaa valtuustiedon ja tekee lopullisen valinnan.

Jokainen mallikutsu Nexuksessa kulkee reitittimen /internal/ai/*-reittien kautta, ja reititin päästää läpi vain nimetyt kutsujat. Kaavio asettaa yhdyskäytävälle kolme listaa:

Reitit Kuka saa kutsua
Keskustelu ja keskustelun suoratoisto nexus-orchestrator, nexus-workflows, nexus-skills-engine
Upotukset (embeddings) ja uudelleenjärjestely (rerank) nexus-graphrag, nexus-skills-engine, nexus-workflows
Kaikki muu, mukaan lukien työkalujen suoritus nexus-orchestrator, nexus-workflows

Kutsu ilman kutsujan identiteettiä hylätään tilakoodilla 403 MISSING_CALLER_IDENTITY, ja listalta puuttuva kutsuja tilakoodilla 403 UNAUTHORIZED_CALLER. Lisäosat eivät ole millään listalla, ja se on tarkoituksellista: lisäosan mallikutsut tapahtuvat sen puolesta UNO-lähetyksen kautta.

Se, mitä kutsuja voi lähettää, on toive: ensisijainen palveluntarjoaja ja malli sekä kyvykkyysprofiili, kuten vähimmäiskontekstipituus tai työkalujen käyttö. Reititin toteuttaa toiveen vain, kun organisaatiolla on kyseinen palveluntarjoaja käytössä ja valtuutettuna; muussa tapauksessa se korvaa sen ensin saman palveluntarjoajan sisällä ja sitten organisaation muiden palveluntarjoajien kesken. Kyvykkyysprofiili vain suodattaa, ja siinä oleva datan sijaintivaatimus (data residency) on ehdoton. Kun mikään ei sovi, varamallia ei ole: kutsuja saa tilakoodin 422 MODEL_CAPABILITY_UNAVAILABLE tai 422 NO_PROVIDER_FOR_ROLE sekä korjausohjeen, jonka konsoli näyttää pääkäyttäjälle.

Avaimet kuuluvat organisaatiolle. Kunkin organisaation pääkäyttäjät laittavat omat palveluntarjoaja-avaimensa sen varantoon konsolista käsin, ja reititin selvittää ne kutsun yhteydessä. Mikään malliavain ei ole kaavioarvo, eikä yhtäkään toimiteta Nexuksen mukana. Organisaatio, jolla ei ole avainta, ei saa tekoälyvastauksia, ja konsoli kertoo sen suoraan; mikään ei täytä aukkoa jostain muualta.

Kaksi chart-arvoa määrittävät reitittimen toimintaa. ai.localProvider.baseUrl nimeää ylläpitämäsi OpenAI-yhteensopivan mallipalvelimen, jonne liikenne reititetään kuten mille tahansa muullekin palveluntarjoajalle. ai.installationHosts luettelee yksityisillä nimillä varustetut mallipalvelimesi, jotka reititin katsoo osaksi asennusta. Myös GraphRAG luo upotukset reitittimen kautta sen organisaation nimissä, jonka sisällöstä on kyse. Oletusupotusmalli toimii klusterissa ilman näytönohjainta; ulkoisesti ylläpidetyt upotukset ovat kunkin organisaation oma valinta.

Ei telemetriaa

Asennuksesta ei poistu mitään, ellet itse lähetä sitä. Chartin arvo telemetry.enabled voi olla vain false; skeema hylkää kaiken muun. Myös tietokerroksen oma raportointi on poissa käytöstä: Neo4j:n käyttöraportti ja Qdrantin telemetria on poistettu käytöstä chartissa.

Kun networkPolicy.enabled on oletusarvoisesti käytössä, yksikään pod ei saa yhteyttä internetiin, ellet lisää kohdetta kohtaan networkPolicy.externalEgressCIDRs. Ulkoisesti ylläpidetty mallin tarjoaja on yksi tällainen kohde, samoin kuin sähköpostivälittimesi.

Sama sääntö muutti yhden oletusarvon, jonka tulet huomaamaan. nexus-auth-palvelun rekisteröitymisten CAPTCHA tarvitsee internet-palvelun, joten asennuksessa se on poissa käytöstä, ja tuntemattoman käyttäjän rekisteröityminen jää odottamaan järjestelmänvalvojan hyväksyntää (403 SIGNUP_REQUIRES_APPROVAL). Myös seulonta, joka estää rekisteröitymiset hosting-verkoista, on poissa käytöstä, koska se vaatii lisensoituja tietokantoja, joita Nexus ei toimita. Menetät kyseisen seulonnan.

Asennuksen tila
Asennuksen tila
Enterprise-versiossa tilasivu näyttää klusterin Nexus-järjestelmän alla: kuinka kuormitettu kukin osa on ja kuinka paljon kapasiteettia on jäljellä, sekä jokaisen varoituksen vieressä toimintaohjeet sen ratkaisemiseksi.