Zaloguj sięUmów spotkanie

Rozdział 2.1

Architektura

Za co odpowiada każda usługa w pakiecie chart systemu Nexus i jakie magazyny danych znajdują się pod nią, a następnie reguły, które łączą je w całość – od tożsamości między usługami po ścieżkę, którą pokonuje każde wywołanie modelu.

Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Czas czytania: 19 min

Gdy Tomás Reilly zakończył pierwszą instalację w Harrow Port Authority, polecenie kubectl -n nexus get pods wykazało dziesięć obiektów Deployment i siedem obiektów StatefulSet oraz trzy obiekty CronJob. Zadania Job migracji, które zbudowały bazę danych, już zniknęły, ponieważ każde z nich usuwa się automatycznie po pomyślnym zakończeniu. Ta lista obejmuje całą platformę. Warto ją poznać, ponieważ większość pytań w fazie utrzymania (day-two) zaczyna się od „który z tych elementów odpowiada za tamto?”.

Ten rozdział odpowiada na to pytanie w odniesieniu do każdego elementu, śledzi przepływ jednego żądania przez nie, a następnie omawia reguły, którym wszystkie podlegają. Pozostała część Części 2 opiera się na tym obrazie.

Usługi i za co odpowiada każda z nich

Pakiet to jeden chart Helm, nexus, w wersji 1.0.0-alpha.1, przeznaczony dla Kubernetes 1.33 lub nowszego. Każde obciążenie działa w ramach własnego konta ServiceAccount, jako użytkownik inny niż root, z odebranymi wszystkimi uprawnieniami (capabilities) systemu Linux. Wywołania kierowane do usług chroniących tożsamość i klucze odbywają się przez obustronny protokół TLS (Transport Layer Security), a publiczny interfejs API (application programming interface) współdzieli proces z routerem AI (artificial intelligence).

Komponent Deployment i Service Port usługi Za co odpowiada
Konsola nexus-alpha 3000 Strony widoczne dla użytkowników; serwuje kod HTML (Hypertext Markup Language) pod adresem hosta konsoli
BFF (backend dla frontendu) nexus-alpha-bff 8080 Własne dane konsoli, menu otrzymywane przez każdą osobę, rejestr wydań
Uwierzytelnianie nexus-auth 9101 (obustronny TLS na porcie 8443) Osoby, organizacje, sesje, tokeny, klucze API, pula kluczy modeli organizacji
Brama (Gateway) nexus-gateway 9092, WebSocket 8093 AI Provider Router oraz brzegowy publiczny interfejs API dla standardów REST (representational state transfer) i MCP (Model Context Protocol)
Orkiestrator nexus-orchestrator 8080 Dyspozytor UNO: przyjmowanie każdego zadania i umieszczanie go w kolejce
Przepływy pracy (Workflows) nexus-workflows 8081 Wykonanie UNO: proces roboczy uruchamiający zadania z kolejki
GraphRAG nexus-graphrag 8090, WebSocket 8091 Pamięć: graf wiedzy i wyszukiwanie w nim
Probitas nexus-probitas 9151 (HTTPS) Dowody: rekordy ładu korporacyjnego (governance) i zapieczętowana księga (ledger)
Silnik umiejętności (Skills engine) nexus-skills-engine 8095 Biblioteka umiejętności; wyszukiwanie i uruchamianie umiejętności
Klucze (Keys) nexus-keys 8080 (HTTPS, obustronny TLS) Klucze poszczególnych organizacji w OpenBao, piecza nad kluczami (custody), tożsamość instalacji
Wtyczki (Plugins) nexus-plugins 9111 Rejestr wtyczek i rekordy katalogowe; domyślnie wyłączone
Przetwarzanie plików nexus-fileprocess 9109 Odczytywanie przesłanych dokumentów i obrazów; domyślnie wyłączone

Pierwsze dziesięć elementów jest wymaganych. Dwa ostatnie są opcjonalne i włącza się je za pomocą parametrów components.plugins.enabled oraz components.fileprocess.enabled, gdy korzysta z nich instalacja Enterprise lub pakiet domenowy. Jeszcze jedna opcjonalna usługa, nexus-alive na porcie 8080, ma własny przełącznik components.alive.enabled i również jest domyślnie wyłączona. Liczba replik i zasoby dla każdego elementu znajdują się w sekcji components.<name>.

Konsola to strony renderowane po stronie serwera, nieposiadające własnej bazy danych. Komunikuje się ona z usługą BFF oraz z usługą nexus-auth wewnątrz klastra, nigdy nie wychodząc na zewnątrz przez publiczny host uwierzytelniania i z powrotem. Odmawia uruchomienia bez określonej edycji, którą chart przekazuje jako NEXUS_EDITION na podstawie pojedynczej wartości edition. Każdy członek organizacji pracuje w niej zgodnie ze swoją rolą. Strony administracyjne są przeznaczone dla właścicieli i administratorów, a zwykły członek, który spróbuje taką stronę otworzyć, zobaczy komunikat „Not an administrator” (Brak uprawnień administratora).

BFF to serwerowa część konsoli, zbudowana jako wtyczka platformy i zarejestrowana jako produkt Nexus Alpha. Przechowuje własne tabele konsoli w osobnej bazie danych nexus_alpha i decyduje, które grupy menu widzi dana osoba. Gdy konsola potrzebuje wykonania jakiegoś zadania, BFF zwraca się do usługi, która za nie odpowiada.

nexus-auth to usługa napisana w języku Go, będąca jedynym komponentem generującym tokeny. Tokeny dostępu są domyślnie ważne przez 15 minut, a tokeny odświeżania przez 12 godzin (auth.accessTokenTTL, auth.refreshTokenTTL). Usługa ogranicza każdą zalogowaną osobę do 5000 żądań na minutę, po czym zwraca kod 429 (auth.rateLimitPerMinute). Uruchamia dwa procesy nasłuchujące (listeners): zwykły na porcie kontenera 8080, do którego dociera publiczny obiekt Ingress, oraz wymagający obustronnego TLS na porcie 8443, z którego musi korzystać każdy obiekt wywołujący wewnątrz klastra. Ufa nagłówkowi X-Forwarded-For tylko z przeskoków (hops) wymienionych w proxy.trustedCIDRs – liście zakresów CIDR (Classless Inter-Domain Routing), która domyślnie ma wartość 10.42.0.0/16, czyli sieci podów k3s. Jeśli kontroler ingress działa w innym miejscu, należy zmienić tę wartość. W przeciwnym razie każde logowanie będzie wyglądać tak, jakby pochodziło z kontrolera.

Brama (Gateway) realizuje dwa zadania współdzielące jeden proces. Wewnątrz klastra pełni funkcję AI Provider Router (centrali przełączającej AI opisanej w Części 1 i widocznej na stronach konsoli), będąc jedynym dysponentem danych uwierzytelniających do modeli danej organizacji (więcej na ten temat poniżej). Na brzegu sieci jest tym, do czego dociera ruch z api.<domain>: klientami REST oraz klientami MCP, których tokeny zawierają odbiorcę (audience) https://<hosts.api>/mcp i pochodzą z serwera autoryzacji OAuth 2.1 na hoście uwierzytelniania (OAuth to otwarty standard delegowanej autoryzacji).

Orkiestrator i przepływy pracy (workflows) tworzą razem UNO – silnik przepływów pracy. Przez nie przechodzą wszystkie operacje obliczeniowe. Orkiestrator przyjmuje zadanie pod adresem POST /api/v1/dispatch, odpowiada kodem 202 wraz z parametrami jobId, runId oraz traceId, a następnie umieszcza je w kolejce. Nie ma ścieżki wykonania w trybie bezpośrednim (inline): klient zawsze odpytuje adres GET /api/v1/dispatch/{jobId} lub odbiera wywołanie zwrotne (callback). Proces roboczy workflows pobiera zadania z kolejki – domyślnie po cztery naraz na każdą replikę (workflows.concurrency) – i ma dokładnie jedną trasę HTTP: GET /health.

Probitas to usługa obsługi dowodów. Samodzielnie obsługuje protokół TLS w oparciu o certyfikat wystawiony przez chart i przechowuje swoje tabele w schemacie trust z osobną rolą dla księgi (ledger). Jej funkcje ładu korporacyjnego (governance) są przełączane za pomocą parametru probitas.flags. Kilka z nich jest dostarczanych w trybie shadow: werdykt jest obliczany i zapisywany, ale nic nie jest blokowane, dopóki nie zmieni się tej flagi.

nexus-keys to usługa kluczy platformy napisana w języku Go. Przechowuje ona po jednym kluczu na organizację w magazynie kluczy OpenBao i dokonuje ich rotacji co noc. Jej nocne zadania niszczą również klucze, których termin przechowywania minął, oraz eksportują potwierdzenia do własnego wolumenu. Usunięcie klucza organizacji sprawia, że dane zaszyfrowane przy jego użyciu stają się bezpowrotnie nieczytelne. Usługa ta generuje również tożsamość instalacji podczas pierwszego rozruchu (bootstrap) pod kluczem keys.installationName, a nazwa ta jest stała. Należy wybrać ją rozważnie: chart odrzuca pustą nazwę (INSTALLATION_NAME_MISSING) oraz nazwę występującą w jego własnych przykładowych wartościach (INSTALLATION_NAME_EXAMPLE).

Ta instalacja (Community)
Ta instalacja (Community)
Strona własna instalacji w wersji Community pokazuje jej wersję oraz stan silników. Informuje wprost, że żadna licencja nie jest wymagana. Części strony dotyczące wersji Enterprise są wyświetlane jako zapowiedzi (teasers).

Trzy hosty publiczne

Chart publikuje dokładnie trzy nazwy hostów, które razem tworzą tożsamość instalacji. Każda usługa odmawia uruchomienia bez nich.

Ingress Wartość hosta Backend
nexus-console hosts.console nexus-alpha, port 3000
nexus-api hosts.api nexus-gateway, port 9092
nexus-auth hosts.auth nexus-auth, port 9101

Przykłady w tej książce wykorzystują adresy console.harrow.example, api.harrow.example oraz auth.harrow.example. Obiekty Ingress to zwykłe obiekty networking.k8s.io/v1, z których każdy zawiera jedną regułę ze ścieżką /. Obsługa protokołu TLS na brzegu sieci zależy od parametru tls.mode: existing (utworzony przez Państwa obiekt Secret o nazwie wskazanej w tls.existingSecret), cert-manager (utrzymywany przez Państwa obiekt ClusterIssuer o nazwie wskazanej w tls.clusterIssuer) lub none (połączenie TLS kończy się przed klastrem). Chart nie dodaje własnego przekierowania, dzięki czemu wyzwanie HTTP protokołu ACME (Automated Certificate Management Environment) dociera do mechanizmu weryfikującego (solver) w niezmienionej postaci. Każdy z tych trybów omówiono w Rozdziale 2.11, Warianty: zewnętrzne magazyny danych, TLS i ingress.

Nic innego nie jest udostępniane na zewnątrz. Magazyny danych, OpenBao oraz wszystkie usługi wewnętrzne nasłuchują wyłącznie wewnątrz przestrzeni nazw (namespace).

Trzy poziome pasma. Górne pasmo to „Edge” z trzema blokami Ingress oznaczonymi jako console, api oraz auth, z których każdy wskazuje w dół na swoją usługę Service (nexus-alpha :3000, nexus-gateway :9092, nexus-auth :9101). Środkowe pasmo to „Platform services”: blok dla nexus-alpha-bff; nexus-orchestrator obok nexus-workflows, zgrupowane i oznaczone jako UNO; następnie nexus-graphrag, nexus-probitas, nexus-skills-engine, nexus-keys; oraz dwa bloki obrysowane linią przerywaną dla opcjonalnych usług nexus-plugins i nexus-fileprocess. Dolne pasmo to „Data tier” z jednym blokiem na każdy magazyn danych (PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS) oraz osobnym, odgrodzonym blokiem oznaczonym jako „Key store”, mieszczącym openbao i openbao-unsealer, dostępnym wyłącznie dla usługi nexus-keys.
Komponenty instalacji Nexus oraz znajdujące się pod nimi magazyny danych.

Żądanie, od początku do końca

Oto co się dzieje, gdy Aoife Brennan, szefowa działu IT w Harrow, otwiera konsolę i zadaje asystentowi pytanie dotyczące harmonogramu miejsc postojowych dla statków na bieżący miesiąc.

  1. Jej przeglądarka wczytuje adres https://console.harrow.example. Obiekt Ingress nexus-console przesyła żądanie do usługi nexus-alpha na porcie 3000.
  2. Loguje się ona za pomocą swojego klucza dostępu (passkey). Strony logowania komunikują się z nexus-auth przez auth.harrow.example, a usługa nexus-auth generuje dla niej token dostępu zawierający identyfikator użytkownika, organizację oraz – jeśli sesja ją obejmuje – jednostkę biznesową.
  3. Serwer konsoli wywołuje usługę BFF, która weryfikuje token i pyta usługę nexus-auth, czy dana organizacja posiada ten produkt oraz czy rola użytkowniczki jest dopuszczona. W odpowiedzi zwracane są grupy menu, które może ona zobaczyć.
  4. Jej pytanie trafia z BFF do trasy dyspozytora w orkiestratorze wraz z informacją o organizacji i użytkowniku pobraną ze zweryfikowanego tokena. Orkiestrator odpowiada kodem 202 i umieszcza zadanie w kolejce w bazie Valkey.
  5. Proces roboczy workflows pobiera zadanie. Uruchamiana przez niego umiejętność jest rozwiązywana przez silnik umiejętności, a wyszukiwanie w dokumentach Harrow trafia do usługi GraphRAG, która odczytuje dane z baz Neo4j, Qdrant oraz swojego schematu w PostgreSQL.
  6. Wywołanie modelu trafia do komponentu AI Provider Router pod adresem /internal/ai/chat. Router wybiera dostawcę i model z własnej puli kluczy oraz polityki routingu organizacji Harrow, wykonuje wywołanie przy użyciu klucza Harrow i zwraca wygenerowaną odpowiedź (completion).
  7. Wynik trafia do wiersza przebiegu zadania. Usługa BFF odczytuje go, a konsola wyświetla odpowiedź wraz z cytowaniami.

Przeskoki między usługami przenoszą rzutowane (projected) tokeny usług, połączenia z usługami nexus-auth, nexus-keys oraz Probitas odbywają się przez protokół TLS z wykorzystaniem własnego urzędu certyfikacji instalacji, a każdy dostęp do danych w krokach od 4 do 6 jest w samej bazie danych odgrodzony i ograniczony do organizacji Harrow. Poniższe sekcje wyjaśniają oba te mechanizmy.

Sekwencja od lewej do prawej. Blok przeglądarki wysyła „1 page” do Ingress console, a następnie do nexus-alpha. Boczna strzałka „2 sign-in” biegnie od przeglądarki przez Ingress auth do nexus-auth. Usługa nexus-alpha wysyła „3 menu” do nexus-alpha-bff, która weryfikuje dane w nexus-auth. Usługa nexus-alpha-bff wysyła „4 dispatch, 202” do nexus-orchestrator, która zapisuje dane w ikonie kolejki Valkey. Usługa nexus-workflows pobiera „5 job” z kolejki oraz wywołuje nexus-skills-engine i nexus-graphrag (jej trzy magazyny danych są narysowane pod GraphRAG). Usługa nexus-workflows wysyła „6 chat” do nexus-gateway, oznaczonej jako „AI Provider Router: organisation key pool”, od której pojedyncza strzałka wychodzi poza granicę klastra do „model provider”. Kropkowana strzałka powrotna „7 result on run row” wraca do nexus-alpha-bff.
Jedno pytanie do asystenta – od przeglądarki do dostawcy modelu i z powrotem.

Warstwa danych

Nexus dostarcza własną, podpisaną kopię każdego magazynu danych wraz z ofertą kodu źródłowego dla każdego z nich w pakiecie. Każdy magazyn został wybrany zarówno ze względu na swoją licencję, jak i funkcjonalność.

Magazyn Wersja Licencja Dlaczego został użyty Port Domyślny wolumen
PostgreSQL z rozszerzeniami PostGIS i pgvector PostgreSQL 16, PostGIS 3, pgvector 0.8 Licencja PostgreSQL; PostGIS GPL-2.0-or-later Główny system ewidencji (system of record) dla każdej usługi; PostGIS dla danych mapowych; pgvector dla wektorów przechowywanych obok wierszy 5432 50 GiB
Valkey 8.1 BSD-3-Clause Kolejki zadań UNO oraz krótkotrwałe pamięci podręczne, takie jak pamięć podręczna kluczy API w usłudze nexus-auth 6379 5 GiB
Neo4j Community Edition 5.26 GPL-3.0 Graf wiedzy budowany i przeszukiwany przez usługę GraphRAG 7687 (Bolt) 20 GiB
Qdrant 1.15 Apache-2.0 Wyszukiwanie wektorowe dla usługi GraphRAG oraz silnika umiejętności 6333 (HTTP), 6334 (zdalne wywołania procedur gRPC) 10 GiB
SeaweedFS 4.48 Apache-2.0 Obiektowa pamięć masowa dla plików, zgodna z Amazon Simple Storage Service (S3) 8333 50 GiB
OpenBao 2.6 MPL-2.0 Magazyn kluczy i jego proces odpieczętowania (unsealer) dla usługi nexus-keys 8200 5 GiB i 1 GiB

Niektóre wybory zastąpiły bardziej znane rozwiązania. Valkey zastępuje bazę Redis 7.4, której obecne licencje są odrzucane przez to wydanie. MinIO jest objęte licencją AGPL-3.0, dlatego magazynem obiektów jest SeaweedFS. Usługa GraphRAG łączy się z Neo4j Community Edition przez protokół sieciowy Bolt, a usługi łączą się z PostGIS przez protokół PostgreSQL, dzięki czemu licencja GPL pozostaje po stronie każdego z tych komponentów. OpenBao to rozwijany przez Linux Foundation fork systemu Vault sprzed zmiany jego licencji.

Każdy magazyn działa z włączonym uwierzytelnianiem i wygenerowanymi danymi logowania: hasłem dla Valkey, kluczem API dla Qdrant oraz kluczami dostępu dla SeaweedFS.

Każdy z pięciu magazynów w sekcji dataTier działa wewnątrz klastra (mode: in-cluster, ustawienie domyślne) lub jest już przez Państwa utrzymywany zewnętrznie (mode: external, z parametrem external.host oraz obiektem Secret wskazanym przez external.existingSecret). W przypadku zewnętrznej bazy PostgreSQL należy ustawić parametr sslmode na wartość verify-full lub verify-ca i umieścić certyfikat urzędu certyfikacji (CA) serwera w tym obiekcie Secret; szczegóły znajdują się w rozdziale 2.11, Warianty: zewnętrzne magazyny danych, TLS i ingress.

# 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

Wyjątkiem jest para komponentów OpenBao: zawsze działa ona wewnątrz instalacji, ponieważ zadanie Job odpowiedzialne za pieczę nad kluczami (custody) inicjalizuje ją w tym miejscu.

Tożsamość między usługami

Nexus działa bez siatki usług (service mesh). Obustronny TLS pochodzi z lokalnego urzędu certyfikacji (CA), który chart tworzy za pośrednictwem narzędzia cert-manager; należy je zainstalować wcześniej (przetestowano wersję v1.21.3).

Samopodpisany obiekt Issuer tworzy jeden certyfikat CA, nexus-local-ca, wykorzystujący algorytm ECDSA (Elliptic Curve Digital Signature Algorithm) P-256 i ważny przez dziesięć lat. Drugi obiekt Issuer podpisuje certyfikaty za pomocą tego CA. Każde obciążenie wywołujące serwer TLS wewnątrz instalacji otrzymuje własny certyfikat klienta o nazwie <service-account>-client-tls, ważny przez 90 dni i odnawiany na 15 dni przed wygaśnięciem. Jego jedyną nazwą jest identyfikator URI (uniform resource identifier) w formacie tożsamości SPIFFE:

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

Każde obciążenie znajduje publiczny certyfikat CA jako ca.crt we własnym obiekcie Secret certyfikatu. Żaden pod nie montuje klucza prywatnego CA i nie jest potrzebne narzędzie trust-manager.

Trzy usługi weryfikują obiekty wywołujące na podstawie certyfikatu. Usługa nexus-auth robi to na swoim drugim procesie nasłuchującym, na porcie 8443, z którym łączy się każdy obiekt wywołujący wewnątrz klastra. Usługa nexus-keys robi to na swoim jedynym procesie nasłuchującym. Usługa Probitas obsługuje protokół TLS z własnego certyfikatu nexus-probitas-tls, który wczytuje ponownie po jego odnowieniu przez cert-manager. Żadna z tych usług nie ufa nagłówkowi X-Forwarded-Client-Cert.

Każde obciążenie otrzymuje również jednogodzinne tokeny Kubernetes w ścieżce /var/run/secrets/nexus – po jednym dla każdej wywoływanej usługi, z tą usługą wskazaną jako odbiorca (audience). Obiekt ConfigMap nexus-service-identities mapuje każdy <namespace>/<service-account> na nazwę usługi lub wtyczki, a obciążenie, którego w nim brakuje, nie ma tożsamości i spotyka się z odmową. Orkiestrator oraz usługa Probitas weryfikują te tokeny za pomocą interfejsu API Kubernetes. Spośród działających usług tylko te dwie posiadają uprawnienie system:auth-delegator lub mają zamontowany token API; jedynym innym obciążeniem posiadającym token jest zadanie Job pieczy nad kluczami (custody) uruchamiane podczas instalacji.

Polityka sieciowa (NetworkPolicy) zamyka ruch, którego nie ogranicza warstwa tożsamości. Chart zaczyna od domyślnej blokady (default deny), a następnie dopuszcza ruch między własnymi podami instalacji, usługą DNS (Domain Name System), przestrzenią nazw kontrolera ingress (networkPolicy.ingressNamespace, domyślnie kube-system) do trzech publicznych obiektów Service oraz do serwera API dla dwóch komponentów weryfikujących tokeny. Pody OpenBao posiadają inną etykietę niż reszta platformy, dzięki czemu otwarta reguła ruchu wewnątrz przestrzeni nazw ich nie obejmuje: docierają do nich wyłącznie usługa nexus-keys, jej zadania Job oraz zadanie Job pieczy nad kluczami (custody) na porcie 8200. Wszystko inne, z czym obciążenie musi połączyć się poza przestrzenią nazw, np. Państwa serwer przekazywania poczty (mail relay), należy wpisać w parametrze networkPolicy.externalEgressCIDRs, który domyślnie jest pusty.

Migracje i rejestr schematów

Migracje są uruchamiane jako haki (hooks) Helm w fazach post-install oraz pre-upgrade. Hak post-install uruchamia się po utworzeniu obiektów Deployment danego wydania. Oznacza to, że podczas pierwszej instalacji usługi uruchamiają się, gdy ich schematy jeszcze nie istnieją, przez co wpadałyby w pętlę awarii (crash-loop), próbując połączyć się z bazą danych bez ról, bez haseł i bez tabel. Nexus zapobiega temu za pomocą księgi (ledger).

Haki uruchamiają się w kolejności wag, a Helm czeka na zakończenie każdego zadania Job przed rozpoczęciem kolejnej wagi:

Waga Hak Co robi
-30 nexus-migrations-env i wymagania wstępne Tworzy przeznaczony wyłącznie dla haków obiekt Secret z danymi logowania migratora oraz wszystkie elementy odczytywane przez zadanie Job pieczy nad kluczami (custody)
-20 nexus-db-bootstrap Tworzy bazy danych nexus i nexus_alpha, rolę migratora, rolę wykonawczą (runtime role) każdej usługi, rozszerzenia oraz księgę (ledger)
-15 nexus-openbao-custody-init Inicjalizuje magazyn kluczy oraz proces odpieczętowania (unsealer) i generuje tożsamość instalacji
-12 nexus-graphrag-migrations Schemat usługi GraphRAG, do którego należą obiekty przywoływane przez bazowy schemat usługi nexus-auth
-10 nexus-auth-migrations Schemat tożsamości
-5 Migracje orkiestratora, bramy (gateway) oraz usługi Probitas Ich schematy; usługa Probitas sprawdza najpierw, czy istnieją tabele uwierzytelniania
0 nexus-alpha-bff-migrations Własna baza danych konsoli

Każde zadanie Job migracji ma ustawienie backoffLimit: 0, więc nieudana migracja powoduje niepowodzenie całej instalacji.

Księga (ledger) to jedna tabela, nexus_release.schema_applied, zawierająca po jednym wierszu na każdy łańcuch migracji i skrót (digest) obrazu. Każdy hak zapisuje swój wiersz dopiero po zakończeniu działania swojego procesu wykonującego migrację. Każdy obiekt Deployment korzystający z bazy PostgreSQL zawiera kontener inicjujący wait-for-schema, który odczytuje tę tabelę przy użyciu roli niemającej uprawnień do odczytu niczego innego (nexus_ledger_reader) i czeka, aż każdy łańcuch, od którego zależy dana usługa, wykaże wiersz odpowiadający obrazowi bieżącego wydania. Dopiero wtedy usługa się uruchamia. Proces roboczy workflows czeka na łańcuch orkiestratora, ponieważ współdzieli z nim tę bazę danych, natomiast silnik umiejętności czeka wyłącznie na rozruch (bootstrap).

Odpytuje on bazę co 3 sekundy (schemaWait.intervalSeconds) i rezygnuje po 1800 sekundach (schemaWait.timeoutSeconds), wypisując wiersz z nazwami wciąż brakujących łańcuchów. Właściwy kontener usługi nigdy nie uruchamia się w oparciu o niewłaściwy schemat.

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

Właśnie dlatego nigdy nie wolno uruchamiać polecenia helm install --wait. Przy użyciu flagi --wait Helm czeka na gotowość obiektów Deployment przed uruchomieniem haków post-install, natomiast obiekty Deployment czekają na wykonanie haków. Żaden z elementów nie rusza z miejsca. Należy przeprowadzić instalację bez tej flagi i zaczekać na gotowość po jej zakończeniu; dokładne polecenie podano w rozdziale 2.6, Instalacja wersji Community w środowisku Kubernetes.

Izolacja na trzech osiach

Każdy odczyt, zapis, wywołanie narzędzia i uruchomienie umiejętności w systemie Nexus ma zakres ograniczony w trzech osiach.

Oś Pole Co rozdziela
Dzierżawca (Tenant) organization_id Jedną organizację od drugiej – twarda granica
Właściciel (Owner) owner_user_id Zasoby jednej osoby od zasobów wszystkich pozostałych osób, nawet wewnątrz tej samej organizacji
Jednostka (Unit) business_unit_id Jednostka podrzędna w ramach organizacji, opcjonalnie

Oś właściciela często zaskakuje użytkowników. Skrzynka pocztowa lub osobisty notatnik są prywatne dla ich właściciela nawet przed współpracownikami z tej samej jednostki i o tej samej roli. Administrator ustala polityki, ale nie odczytuje treści.

Wartości osi pochodzą z uwierzytelnionego żądania i z żadnego innego miejsca. Żadna zmienna środowiskowa, nagłówek, parametr zapytania ani segment ścieżki nie mogą ich ustawić. Treść żądania wskazująca nazwę organizacji jest odrzucana z kodem TENANT_NOT_A_PARAMETER. Warstwa dostępu, która nie jest w stanie określić, do którego dzierżawcy, właściciela i jednostki należy dany wiersz, odmawia dostępu z kodem 403 SCOPE_PREDICATE_MISSING, a treść odpowiedzi wymienia osie, które udało się rozwiązać, oraz te, których nie rozwiązano. System nigdy nie przechodzi awaryjnie do szerszego odczytu.

Zasada ta obowiązuje jednocześnie w dwóch miejscach.

W bazie danych. Każda usługa łączy się przy użyciu własnych ról wykonawczych (runtime roles): nexus_auth, auth_app oraz auth_platform dla usługi tożsamości, nexus_probitas i nexus_probitas_ledger dla usługi Probitas, a także nexus_gateway, nexus_graphrag, nexus_skills, orchestrator_app, workflows_app i pozostałych dla reszty usług. Żadna z nich nie jest superużytkownikiem ani nie posiada uprawnienia BYPASSRLS. Żadna nie jest też właścicielem tabel, z których korzysta, dzięki czemu obowiązuje ją każda polityka zabezpieczeń na poziomie wiersza (RLS – row-level security). Role te współdzielą grupę nexus_runtime, która przyznaje prawo do połączenia i używania schematu, ale nie daje żadnych praw do tabel; każda usługa otrzymuje uprawnienia do własnych tabel w ramach swoich migracji. Ustawienia dzierżawcy odczytywane przez polityki RLS mogą być definiowane wyłącznie za pośrednictwem funkcji bind_scope danej usługi, która uruchamia się z uprawnieniami jej właściciela. Zadanie rozruchu (bootstrap) odbiera uprawnienie set_config wszystkim pozostałym podmiotom, a orkiestrator i usługa Probitas odmawiają uruchomienia, jeśli ich rola wykonawcza mogłaby wywołać tę funkcję bezpośrednio (Probitas oznacza ten błąd jako DB_ROLE_SETS_SCOPE_DIRECTLY). Jedyne połączenia z uprawnieniami superużytkownika w całej instalacji należą do zadania Job rozruchu oraz kroku aprowizacji w usłudze BFF.

We współdzielonym prymitywie zapytań o ograniczonym zakresie. Każde repozytorium na platformie oraz każda wtyczka zbudowana w oparciu o pakiet SDK (software development kit) dziedziczy jedną barierę ochronną, która buduje predykat SQL na podstawie rozwiązanego zakresu. Jej funkcja zakresu przyjmuje zweryfikowaną tożsamość i nie posiada parametru organizacji, dzięki czemu obiekt wywołujący nie może go przekazać, a żadna trasa nie może pominąć tego mechanizmu.

Istnieje dokładnie jeden przypadek przekroczenia granicy dzierżawcy i jest on ściśle ograniczony: zarejestrowane upoważnienie (grant). Dwie osoby w organizacji posiadającej wiersze rejestrują informację o tym, która organizacja może odczytywać które tabele i do kiedy. Każdy odczyt odbywa się w transakcji tylko do odczytu i jest rejestrowany w dziennikach obu dzierżawców. Właściciele i administratorzy nigdy nie odczytują danych między organizacjami, a podmiot odczytujący nie może rozszerzyć upoważnienia.

Ścieżka AI

Obiekty wywołujące wyrażają życzenia. AI Provider Router jest dysponentem danych uwierzytelniających i podejmuje ostateczną decyzję.

Każde wywołanie modelu w systemie Nexus przechodzi przez trasy /internal/ai/* routera, a router dopuszcza wyłącznie wskazane z nazwy obiekty wywołujące. Chart definiuje trzy listy w bramie (gateway):

Trasy Kto może wywoływać
Czat i strumieniowanie czatu nexus-orchestrator, nexus-workflows, nexus-skills-engine
Osadzenia (embeddings) i zmiana rankingu (rerank) nexus-graphrag, nexus-skills-engine, nexus-workflows
Wszystko inne, w tym wykonywanie narzędzi nexus-orchestrator, nexus-workflows

Wywołanie bez tożsamości obiektu wywołującego jest odrzucane z kodem 403 MISSING_CALLER_IDENTITY, a obiekt wywołujący spoza listy – z kodem 403 UNAUTHORIZED_CALLER. Wtyczek nie ma na żadnej liście i jest to celowe: wywołania modeli przez wtyczkę odbywają się w jej imieniu za pośrednictwem dyspozytora UNO.

To, co obiekt wywołujący może przesłać, to życzenie: preferowany dostawca i model oraz profil możliwości, taki jak minimalna długość kontekstu czy obsługa narzędzi. Router spełnia życzenie tylko wtedy, gdy organizacja ma włączonego tego dostawcę wraz z przypisanymi danymi uwierzytelniającymi; w przeciwnym razie dokonuje podstawienia – najpierw w obrębie tego samego dostawcy, a następnie spośród innych dostawców danej organizacji. Profil możliwości służy wyłącznie do filtrowania, a zawarty w nim wymóg dotyczący rezydencji danych (data residency) jest bezwzględny. Gdy żaden model nie pasuje, nie ma modelu awaryjnego: obiekt wywołujący otrzymuje kod 422 MODEL_CAPABILITY_UNAVAILABLE lub 422 NO_PROVIDER_FOR_ROLE wraz z komunikatem naprawczym, który konsola wyświetla administratorowi.

Klucze należą do organizacji. Administratorzy każdej organizacji dodają własne klucze dostawców do jej puli z poziomu konsoli, a router rozwiązuje je w momencie wywołania. Żaden klucz modelu nie jest wartością w charcie i żaden nie jest dostarczany wraz z systemem Nexus. Organizacja nieposiadająca klucza nie otrzymuje odpowiedzi AI, o czym konsola informuje wprost; brak ten nie jest uzupełniany z żadnego innego źródła.

Dwie wartości pakietu chart kształtują działanie routera. ai.localProvider.baseUrl wskazuje utrzymywany przez Państwa serwer modeli zgodny z OpenAI, do którego ruch jest kierowany jak do każdego innego dostawcy. ai.installationHosts zawiera listę Państwa serwerów modeli pod prywatnymi nazwami, które router traktuje jako znajdujące się wewnątrz instalacji. GraphRAG również generuje osadzenia (embeddings) za pośrednictwem tego routera, działając jako organizacja, do której należy dana treść. Domyślny model osadzeń działa w klastrze bez karty graficznej; korzystanie z hostowanych osadzeń to indywidualny wybór każdej organizacji.

Brak telemetrii

Nic nie opuszcza instalacji, dopóki sami Państwo tego nie wyślą. Wartość telemetry.enabled w pakiecie chart może wynosić wyłącznie false; schemat odrzuca jakąkolwiek inną wartość. Własne raportowanie warstwy danych jest również wyłączone: raporty użycia Neo4j oraz telemetria Qdrant są w pakiecie chart dezaktywowane.

Gdy opcja networkPolicy.enabled jest włączona – co stanowi ustawienie domyślne – żaden pod nie może połączyć się z internetem, o ile nie wskażą Państwo miejsca docelowego w networkPolicy.externalEgressCIDRs. Jednym z takich miejsc docelowych jest hostowany dostawca modeli, a innym Państwa serwer przekazywania poczty (mail relay).

Ta sama reguła zmieniła jedno ustawienie domyślne, co z pewnością Państwo zauważą. Mechanizm CAPTCHA w usłudze nexus-auth podczas rejestracji wymaga dostępu do usługi internetowej, dlatego w instalacji jest on wyłączony, a rejestracja nieznanego użytkownika oczekuje na zatwierdzenie przez administratora (403 SIGNUP_REQUIRES_APPROVAL). Filtr blokujący rejestracje z sieci hostingowych również jest wyłączony, ponieważ wymaga licencjonowanych baz danych, których Nexus nie dostarcza. Tracą Państwo to zabezpieczenie.

Stan instalacji
Stan instalacji
W wersji Enterprise strona stanu systemu pokazuje klaster, na którym działa Nexus: jak bardzo obciążona jest każda z części oraz ile zasobów pozostało, a obok każdego ostrzeżenia znajduje się informacja, co należy z nim zrobić.