Wersja 1.0.0-alpha.1najnowsza
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

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).
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).
Żą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.
- Jej przeglądarka wczytuje adres
https://console.harrow.example. Obiekt Ingressnexus-consoleprzesyła żądanie do usługinexus-alphana porcie 3000. - Loguje się ona za pomocą swojego klucza dostępu (passkey). Strony logowania komunikują się z
nexus-authprzezauth.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ą. - 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ć.
- 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.
- 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.
- 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). - 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.
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-postgresWyją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-schemaWł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.

