ΣύνδεσηΚλείστε μια ενημέρωση

Κεφάλαιο 2.1

Αρχιτεκτονική

Τι διαχειρίζεται κάθε υπηρεσία στο chart του Nexus και ποια συστήματα αποθήκευσης βρίσκονται από κάτω της, καθώς και οι κανόνες που τα συνδέουν μεταξύ τους, από την ταυτότητα μεταξύ υπηρεσιών έως τη διαδρομή που ακολουθεί κάθε κλήση μοντέλου.

Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

19 λεπτά ανάγνωσης

Όταν ο Tomás Reilly ολοκλήρωσε την πρώτη εγκατάσταση στην Harrow Port Authority, η εντολή kubectl -n nexus get pods έδειξε δέκα Deployments και επτά StatefulSets, συν τρία CronJobs. Τα Jobs μετεγκατάστασης (migration) που δημιούργησαν τη βάση δεδομένων είχαν ήδη εξαφανιστεί, επειδή το καθένα διαγράφει τον εαυτό του μόλις ολοκληρωθεί επιτυχώς. Αυτή η λίστα είναι ολόκληρη η πλατφόρμα. Μάθετέ την, γιατί οι περισσότερες ερωτήσεις που αφορούν την καθημερινή λειτουργία ξεκινούν με το «ποιο από αυτά έχει στην κατοχή του εκείνο;»

Αυτό το κεφάλαιο απαντά σε αυτό το ερώτημα για κάθε τμήμα, ακολουθεί ένα αίτημα καθώς περνά μέσα από αυτά και στη συνέχεια καλύπτει τους κανόνες στους οποίους υπακούν όλα. Το υπόλοιπο του Μέρους 2 βασίζεται σε αυτή την εικόνα.

Οι υπηρεσίες και τι διαχειρίζεται η καθεμία

Το chart είναι ένα Helm chart, το nexus, έκδοση 1.0.0-alpha.1, για Kubernetes 1.33 ή νεότερη έκδοση. Κάθε φόρτος εργασίας (workload) εκτελείται κάτω από το δικό του ServiceAccount, ως χρήστης non-root, με όλες τις δυνατότητες (capabilities) του Linux αφαιρεμένες. Οι κλήσεις προς τις υπηρεσίες που φυλάσσουν την ταυτότητα και τα κλειδιά εκτελούνται μέσω αμοιβαίου TLS (Transport Layer Security), και το δημόσιο API (application programming interface) μοιράζεται μια διεργασία με τον δρομολογητή AI (artificial intelligence).

Στοιχείο Deployment και Service Θύρα Service Τι έχει στην κατοχή του
Κονσόλα nexus-alpha 3000 Τις σελίδες που βλέπουν οι χρήστες· σερβίρει HTML (Hypertext Markup Language) στον κεντρικό υπολογιστή (host) της κονσόλας
BFF (backend for frontend) nexus-alpha-bff 8080 Τα δεδομένα της ίδιας της κονσόλας, το μενού που λαμβάνει κάθε άτομο, το μητρώο εκδόσεων
Έλεγχος ταυτότητας nexus-auth 9101 (αμοιβαίο TLS στην 8443) Άτομα, οργανισμούς, συνεδρίες, διακριτικά (tokens), κλειδιά API, τη δεξαμενή κλειδιών μοντέλων του οργανισμού
Πύλη nexus-gateway 9092, WebSocket 8093 Ο δρομολογητής παρόχων AI και το δημόσιο API edge για REST (representational state transfer) και MCP (Model Context Protocol)
Ενορχηστρωτής nexus-orchestrator 8080 Αποστολή UNO: αποδοχή κάθε εργασίας και τοποθέτησή της στην ουρά
Ροές εργασιών nexus-workflows 8081 Εκτέλεση UNO: ο εργάτης (worker) που εκτελεί τις εργασίες που βρίσκονται στην ουρά
GraphRAG nexus-graphrag 8090, WebSocket 8091 Μνήμη: το γράφημα γνώσης και η ανάκτηση δεδομένων από αυτό
Probitas nexus-probitas 9151 (HTTPS) Πειστήρια: αρχεία διακυβέρνησης και το σφραγισμένο καθολικό (ledger)
Μηχανή δεξιοτήτων (Skills engine) nexus-skills-engine 8095 Τη βιβλιοθήκη δεξιοτήτων· εύρεση και εκτέλεση δεξιοτήτων
Κλειδιά nexus-keys 8080 (HTTPS, αμοιβαίο TLS) Κλειδιά ανά οργανισμό στο OpenBao, θεματοφυλακή, την ταυτότητα της εγκατάστασης
Πρόσθετα (Plugins) nexus-plugins 9111 Το μητρώο προσθέτων και τις εγγραφές καταλόγου· απενεργοποιημένο από προεπιλογή
Επεξεργασία αρχείων nexus-fileprocess 9109 Ανάγνωση μεταφορτωμένων εγγράφων και εικόνων· απενεργοποιημένη από προεπιλογή

Τα πρώτα δέκα είναι υποχρεωτικά. Τα δύο τελευταία είναι προαιρετικά και ενεργοποιούνται με τα components.plugins.enabled και components.fileprocess.enabled όπου τα χρησιμοποιεί μια εγκατάσταση Enterprise ή ένα πακέτο τομέα (domain pack). Μία ακόμη προαιρετική υπηρεσία, η nexus-alive στη θύρα 8080, έχει τον δικό της διακόπτη, τον components.alive.enabled, και είναι επίσης απενεργοποιημένη από προεπιλογή. Τα αντίγραφα (replicas) και οι πόροι για το καθένα βρίσκονται κάτω από το components.<name>.

Η κονσόλα αποτελείται από σελίδες που αποδίδονται από τον διακομιστή (server-rendered) χωρίς βάση δεδομένων. Επικοινωνεί με το BFF και με το nexus-auth εντός του συμπλέγματος (cluster), ποτέ βγαίνοντας έξω μέσω του δημόσιου κεντρικού υπολογιστή auth και επιστρέφοντας μέσα. Αρνείται να εκκινήσει χωρίς την έκδοσή της (edition), την οποία το chart περνά ως NEXUS_EDITION από τη μοναδική τιμή edition. Κάθε μέλος ενός οργανισμού εργάζεται σε αυτήν ανάλογα με τον ρόλο του. Οι σελίδες διαχείρισης προορίζονται για ιδιοκτήτες και διαχειριστές, και ένα μέλος που ανοίγει μία από αυτές βλέπει τη σελίδα «Not an administrator».

Το BFF είναι το ήμισυ του διακομιστή της κονσόλας και είναι κατασκευασμένο ως πρόσθετο (plugin) της πλατφόρμας, καταχωρισμένο ως το προϊόν Nexus Alpha. Διατηρεί τους πίνακες της ίδιας της κονσόλας σε μια ξεχωριστή βάση δεδομένων, την nexus_alpha, και αποφασίζει ποιες ομάδες μενού βλέπει ένα άτομο. Όταν η κονσόλα χρειάζεται να γίνει κάποια εργασία, το BFF τη ζητά από την υπηρεσία που την έχει στην κατοχή της.

Το nexus-auth είναι γραμμένο σε Go και είναι η μόνη υπηρεσία που εκδίδει διακριτικά (tokens). Τα διακριτικά πρόσβασης (access tokens) διαρκούν 15 λεπτά και τα διακριτικά ανανέωσης (refresh tokens) 12 ώρες από προεπιλογή (auth.accessTokenTTL, auth.refreshTokenTTL). Περιορίζει κάθε συνδεδεμένο άτομο σε 5.000 αιτήματα το λεπτό πριν απαντήσει με 429 (auth.rateLimitPerMinute). Εκτελεί δύο ακροατές (listeners): τον απλό στη θύρα κοντέινερ 8080 στον οποίο φτάνει το δημόσιο Ingress, και έναν με αμοιβαίο TLS στην 8443 τον οποίο πρέπει να χρησιμοποιεί κάθε καλών εντός του συμπλέγματος. Εμπιστεύεται το X-Forwarded-For μόνο από τα άλματα (hops) στο proxy.trustedCIDRs, μια λίστα ευρών Classless Inter-Domain Routing (CIDR), η οποία έχει ως προεπιλογή το 10.42.0.0/16, το δίκτυο pod του k3s. Εάν ο ελεγκτής ingress σας εκτελείται αλλού, αλλάξτε το. Διαφορετικά, κάθε σύνδεση θα φαίνεται σαν να προήλθε από τον ελεγκτή.

Το gateway έχει δύο εργασίες που μοιράζονται μία διεργασία. Εντός του συμπλέγματος είναι ο AI Provider Router (το τηλεφωνικό κέντρο AI στο Μέρος 1 και στις σελίδες της κονσόλας), ο μοναδικός κάτοχος των διαπιστευτηρίων μοντέλων ενός οργανισμού (περισσότερα γι' αυτό παρακάτω). Στο άκρο (edge) είναι αυτό στο οποίο φτάνει το api.<domain>: πελάτες REST και πελάτες MCP, των οποίων τα διακριτικά φέρουν το κοινό (audience) https://<hosts.api>/mcp και προέρχονται από τον διακομιστή εξουσιοδότησης OAuth 2.1 στον κεντρικό υπολογιστή auth (το OAuth είναι το ανοιχτό πρότυπο για εξουσιοδότηση με ανάθεση).

Το orchestrator και το workflows μαζί αποτελούν το UNO, τη μηχανή ροής εργασιών. Όλη η επεξεργασία εκτελείται μέσω αυτών. Το orchestrator δέχεται μια εργασία στο POST /api/v1/dispatch, απαντά με 202 δίνοντας jobId, runId και traceId, και την τοποθετεί στην ουρά. Δεν υπάρχει διαδρομή ενσωματωμένης (inline) εκτέλεσης: ένας πελάτης κάνει πάντα τακτικά ερωτήματα (polling) στο GET /api/v1/dispatch/{jobId} ή δέχεται μια κλήση επιστροφής (callback). Ο εργάτης του workflows τραβάει εργασίες από την ουρά, τέσσερις κάθε φορά ανά αντίγραφο (replica) από προεπιλογή (workflows.concurrency), και έχει ακριβώς μία διαδρομή HTTP, την GET /health.

Το Probitas είναι η υπηρεσία πειστηρίων. Σερβίρει το ίδιο TLS, από ένα πιστοποιητικό που εκδίδει το chart, και διατηρεί τους πίνακές του στο σχήμα (schema) trust με έναν ξεχωριστό ρόλο για το καθολικό (ledger). Οι δυνατότητες διακυβέρνησής του ενεργοποιούνται από το probitas.flags. Αρκετές έρχονται σε κατάσταση λειτουργίας shadow: η ετυμηγορία υπολογίζεται και καταγράφεται, και τίποτα δεν αποκλείεται μέχρι να αλλάξετε τη σημαία (flag).

Το nexus-keys είναι η υπηρεσία κλειδιών της πλατφόρμας, γραμμένη σε Go. Διατηρεί ένα κλειδί ανά οργανισμό σε έναν χώρο αποθήκευσης κλειδιών OpenBao και τα εναλλάσσει (rotates) κάθε βράδυ. Οι νυχτερινές εργασίες του καταστρέφουν επίσης κλειδιά των οποίων η ημερομηνία διατήρησης έχει παρέλθει και εξάγουν τις αποδείξεις του σε έναν δικό του τόμο (volume). Η διαγραφή του κλειδιού ενός οργανισμού καθιστά τα δεδομένα που είναι κλειδωμένα κάτω από αυτό οριστικά μη αναγνώσιμα. Εκδίδει επίσης την ταυτότητα εγκατάστασης κατά την πρώτη αρχικοποίηση (bootstrap), κάτω από το keys.installationName, και αυτό το όνομα είναι μόνιμο. Επιλέξτε το προσεκτικά: το chart αρνείται ένα κενό όνομα (INSTALLATION_NAME_MISSING) και αρνείται το όνομα που υπάρχει στις δικές του ενδεικτικές τιμές (INSTALLATION_NAME_EXAMPLE).

Αυτή η εγκατάσταση (Community)
Αυτή η εγκατάσταση (Community)
Η σελίδα μιας εγκατάστασης Community δείχνει την έκδοσή της και την υγεία των μηχανών της. Αναφέρει ξεκάθαρα ότι δεν απαιτείται άδεια χρήσης. Τα τμήματα Enterprise της σελίδας εμφανίζονται ως προεπισκοπήσεις (teasers).

Τρεις δημόσιοι κεντρικοί υπολογιστές (hosts)

Το chart δημοσιεύει ακριβώς τρία ονόματα κεντρικών υπολογιστών (host names), τα οποία μαζί αποτελούν την ταυτότητα της εγκατάστασης. Κάθε υπηρεσία αρνείται να εκκινήσει χωρίς αυτά.

Ingress Τιμή Host Backend
nexus-console hosts.console nexus-alpha, θύρα 3000
nexus-api hosts.api nexus-gateway, θύρα 9092
nexus-auth hosts.auth nexus-auth, θύρα 9101

Τα παραδείγματα σε αυτό το βιβλίο χρησιμοποιούν τα console.harrow.example, api.harrow.example και auth.harrow.example. Τα Ingresses είναι απλά αντικείμενα networking.k8s.io/v1 με έναν κανόνα το καθένα, στη διαδρομή /. Το TLS στο άκρο (edge) ακολουθεί το tls.mode: existing (ένα Secret που δημιουργήσατε εσείς, το οποίο κατονομάζεται στο tls.existingSecret), cert-manager (ένας ClusterIssuer που εκτελείτε εσείς, ο οποίος κατονομάζεται στο tls.clusterIssuer) ή none (το TLS τερματίζεται μπροστά από το σύμπλεγμα). Το chart δεν προσθέτει καμία δική του ανακατεύθυνση, επομένως μια πρόκληση (challenge) HTTP του ACME (Automated Certificate Management Environment) φτάνει στον επιλυτή (solver) σας αμετάβλητη. Το Κεφάλαιο 2.11, Παραλλαγές: εξωτερικοί χώροι αποθήκευσης, TLS και ingress, καλύπτει κάθε λειτουργία.

Τίποτα άλλο δεν εκτίθεται. Οι χώροι αποθήκευσης δεδομένων, το OpenBao και κάθε εσωτερική υπηρεσία ακούν μόνο εντός του χώρου ονομάτων (namespace).

Τρεις οριζόντιες ζώνες. Η επάνω ζώνη είναι το "Edge" με τρία πλαίσια Ingress με τις ετικέτες console, api και auth, καθένα από τα οποία δείχνει προς τα κάτω στο αντίστοιχο Service του (nexus-alpha :3000, nexus-gateway :9092, nexus-auth :9101). Η μεσαία ζώνη είναι το "Platform services": ένα πλαίσιο για το nexus-alpha-bff· το nexus-orchestrator δίπλα στο nexus-workflows, ομαδοποιημένα και με την ετικέτα UNO· έπειτα τα nexus-graphrag, nexus-probitas, nexus-skills-engine, nexus-keys· και δύο πλαίσια με διακεκομμένη γραμμή για τα προαιρετικά nexus-plugins και nexus-fileprocess. Η κάτω ζώνη είναι το "Data tier" με ένα πλαίσιο ανά χώρο αποθήκευσης (PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS), και ένα ξεχωριστό οριοθετημένο πλαίσιο με την ετικέτα "Key store" που περιέχει τα openbao και openbao-unsealer, προσβάσιμο μόνο από το nexus-keys.
Τα στοιχεία μιας εγκατάστασης Nexus και οι χώροι αποθήκευσης κάτω από αυτά.

Ένα αίτημα, από την αρχή έως το τέλος

Δείτε τι συμβαίνει όταν η Aoife Brennan, επικεφαλής IT στην Harrow, ανοίγει την κονσόλα και κάνει στον βοηθό μια ερώτηση σχετικά με το πρόγραμμα ελλιμενισμού αυτού του μήνα.

  1. Το πρόγραμμα περιήγησής της φορτώνει το https://console.harrow.example. Το Ingress nexus-console το στέλνει στο nexus-alpha στη θύρα 3000.
  2. Συνδέεται με το passkey της. Οι σελίδες σύνδεσης επικοινωνούν με το nexus-auth μέσω του auth.harrow.example, και το nexus-auth εκδίδει γι' αυτήν ένα διακριτικό πρόσβασης (access token) που φέρει τον χρήστη της, τον οργανισμό της και, όταν η συνεδρία της διαθέτει, την επιχειρηματική της μονάδα.
  3. Ο διακομιστής της κονσόλας καλεί το BFF, το οποίο ελέγχει το διακριτικό της και ρωτά το nexus-auth εάν ο οργανισμός της κατέχει το προϊόν και εάν ο ρόλος της γίνεται δεκτός. Απαντά με τις ομάδες μενού που επιτρέπεται να δει.
  4. Η ερώτησή της πηγαίνει από το BFF στη διαδρομή αποστολής του orchestrator, με τον οργανισμό και τον χρήστη της να λαμβάνονται από το επαληθευμένο διακριτικό. Το orchestrator απαντά με 202 και τοποθετεί την εργασία σε μια ουρά στο Valkey.
  5. Ένας εργάτης του workflows αναλαμβάνει την εργασία. Η δεξιότητα που εκτελεί επιλύεται από τη μηχανή δεξιοτήτων, και η ανάκτηση από τα έγγραφα της Harrow πηγαίνει στο GraphRAG, το οποίο διαβάζει τα Neo4j, Qdrant και το δικό του σχήμα PostgreSQL.
  6. Η κλήση του μοντέλου πηγαίνει στον AI Provider Router στο /internal/ai/chat. Ο δρομολογητής επιλέγει τον πάροχο και το μοντέλο από τη δεξαμενή κλειδιών και την πολιτική δρομολόγησης της ίδιας της Harrow, πραγματοποιεί την κλήση με το κλειδί της Harrow και επιστρέφει την ολοκλήρωση (completion).
  7. Το αποτέλεσμα καταλήγει στη γραμμή εκτέλεσης της εργασίας. Το BFF το διαβάζει και η κονσόλα εμφανίζει την απάντηση, μαζί με τις παραπομπές της.

Τα άλματα (hops) από υπηρεσία σε υπηρεσία φέρουν προβαλλόμενα διακριτικά υπηρεσίας (projected service tokens), εκείνα προς τα nexus-auth, nexus-keys και Probitas εκτελούνται μέσω TLS από την αρχή πιστοποίησης της ίδιας της εγκατάστασης, και κάθε πρόσβαση σε δεδομένα στα βήματα 4 έως 6 περιορίζεται αυστηρά (fenced) στον οργανισμό της Harrow μέσα στην ίδια τη βάση δεδομένων. Οι παρακάτω ενότητες εξηγούν και τα δύο.

Μια ακολουθία από αριστερά προς τα δεξιά. Ένα πλαίσιο προγράμματος περιήγησης (browser) στέλνει "1 page" στο Ingress console, και έπειτα στο nexus-alpha. Ένα πλευρικό βέλος "2 sign-in" πηγαίνει από το πρόγραμμα περιήγησης μέσω του Ingress auth στο nexus-auth. Το nexus-alpha στέλνει "3 menu" στο nexus-alpha-bff, το οποίο κάνει έλεγχο με το nexus-auth. Το nexus-alpha-bff στέλνει "4 dispatch, 202" στο nexus-orchestrator, το οποίο γράφει σε ένα εικονίδιο ουράς Valkey. Το nexus-workflows τραβάει το "5 job" από την ουρά και καλεί τα nexus-skills-engine και nexus-graphrag (με τους τρεις χώρους αποθήκευσής του σχεδιασμένους κάτω από το GraphRAG). Το nexus-workflows στέλνει "6 chat" στο nexus-gateway, με την ετικέτα "AI Provider Router: organisation key pool", το οποίο στέλνει ένα μονό βέλος έξω από τα όρια του συμπλέγματος προς το "model provider". Ένα διάστικτο βέλος επιστροφής "7 result on run row" επιστρέφει στο nexus-alpha-bff.
Μία ερώτηση στον βοηθό, από το πρόγραμμα περιήγησης στον πάροχο του μοντέλου και πίσω.

Το επίπεδο δεδομένων

Το Nexus διαθέτει το δικό του υπογεγραμμένο αντίγραφο για κάθε χώρο αποθήκευσης, με την προσφορά πηγαίου κώδικα για τον καθένα μέσα στο πακέτο. Ο καθένας επιλέχθηκε τόσο για την άδεια χρήσης του όσο και για τη λειτουργία του.

Χώρος αποθήκευσης Έκδοση Άδεια χρήσης Γιατί βρίσκεται εκεί Θύρα Προεπιλεγμένος τόμος
PostgreSQL με PostGIS και pgvector PostgreSQL 16, PostGIS 3, pgvector 0.8 Άδεια χρήσης PostgreSQL· PostGIS GPL-2.0-or-later Το σύστημα καταγραφής (system of record) για κάθε υπηρεσία· PostGIS για δεδομένα χαρτών· pgvector για διανύσματα που διατηρούνται δίπλα στις γραμμές 5432 50 GiB
Valkey 8.1 BSD-3-Clause Οι ουρές εργασιών του UNO και οι βραχύβιες κρυφές μνήμες (caches), όπως η κρυφή μνήμη κλειδιών API του nexus-auth 6379 5 GiB
Neo4j Community Edition 5.26 GPL-3.0 Το γράφημα γνώσης που κατασκευάζει και διασχίζει το GraphRAG 7687 (Bolt) 20 GiB
Qdrant 1.15 Apache-2.0 Διανυσματική αναζήτηση για το GraphRAG και τη μηχανή δεξιοτήτων 6333 (HTTP), 6334 (απομακρυσμένες κλήσεις διαδικασιών gRPC) 10 GiB
SeaweedFS 4.48 Apache-2.0 Αποθήκευση αντικειμένων (object storage) για αρχεία, συμβατή με το Amazon Simple Storage Service (S3) 8333 50 GiB
OpenBao 2.6 MPL-2.0 Ο χώρος αποθήκευσης κλειδιών και ο μηχανισμός αποσφράγισής του, για το nexus-keys 8200 5 GiB και 1 GiB

Ορισμένες επιλογές αντικατέστησαν κάτι πιο οικείο. Το Valkey παίρνει τη θέση του Redis 7.4, του οποίου τις τρέχουσες άδειες χρήσης αρνείται η έκδοση. Το MinIO έχει άδεια AGPL-3.0, επομένως ο χώρος αποθήκευσης αντικειμένων είναι το SeaweedFS. Το GraphRAG επικοινωνεί με το Neo4j Community Edition μέσω του Bolt, ενός πρωτοκόλλου δικτύου, και οι υπηρεσίες επικοινωνούν με το PostGIS μέσω του πρωτοκόλλου PostgreSQL, επομένως η άδεια GPL παραμένει σε καθένα από αυτά. Το OpenBao είναι η διακλάδωση (fork) του Vault από το Linux Foundation πριν από την αλλαγή της άδειας χρήσης του Vault.

Κάθε χώρος αποθήκευσης εκτελείται με ενεργοποιημένο τον έλεγχο ταυτότητας και με παραγόμενα διαπιστευτήρια: έναν κωδικό πρόσβασης για το Valkey, ένα κλειδί API για το Qdrant, κλειδιά πρόσβασης για το SeaweedFS.

Καθένας από τους πέντε χώρους αποθήκευσης κάτω από το dataTier εκτελείται εντός του συμπλέγματος (mode: in-cluster, η προεπιλογή) ή είναι κάποιος που ήδη λειτουργείτε εσείς (mode: external, με external.host και ένα Secret που κατονομάζεται από το external.existingSecret). Για μια εξωτερική PostgreSQL, ορίστε το sslmode σε verify-full ή verify-ca, και τοποθετήστε το πιστοποιητικό της αρχής πιστοποίησης (CA) του διακομιστή σε εκείνο το Secret· το κεφάλαιο 2.11, Παραλλαγές: εξωτερικοί χώροι αποθήκευσης, TLS και 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

Το ζεύγος OpenBao αποτελεί την εξαίρεση: εκτελείται πάντα εντός της εγκατάστασης, επειδή το Job θεματοφυλακής το αρχικοποιεί εκεί.

Ταυτότητα μεταξύ υπηρεσιών

Το Nexus εκτελείται χωρίς πλέγμα υπηρεσιών (service mesh). Το αμοιβαίο TLS προέρχεται από μια τοπική αρχή πιστοποίησης (CA) την οποία δημιουργεί το chart μέσω του cert-manager, το οποίο πρέπει να εγκατασταθεί πρώτο (έχει δοκιμαστεί η έκδοση v1.21.3).

Ένας αυτο-υπογεγραμμένος (self-signed) Issuer δημιουργεί ένα πιστοποιητικό CA, το nexus-local-ca, ECDSA (Elliptic Curve Digital Signature Algorithm) P-256, με ισχύ δέκα ετών. Ένας δεύτερος Issuer υπογράφει με αυτήν τη CA. Κάθε φόρτος εργασίας (workload) που καλεί έναν διακομιστή TLS εντός της εγκατάστασης λαμβάνει το δικό του πιστοποιητικό πελάτη, με όνομα <service-account>-client-tls, το οποίο ισχύει για 90 ημέρες και ανανεώνεται 15 ημέρες πριν από τη λήξη του. Το μοναδικό του όνομα είναι ένα ενιαίο αναγνωριστικό πόρου (URI) στη μορφή ταυτότητας SPIFFE:

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

Κάθε φόρτος εργασίας βρίσκει το δημόσιο πιστοποιητικό της CA ως ca.crt μέσα στο δικό του Secret πιστοποιητικού. Κανένα pod δεν προσαρτά (mounts) το κλειδί της CA, και δεν χρειάζεστε το trust-manager.

Τρεις υπηρεσίες επαληθεύουν τους καλούντες μέσω πιστοποιητικού. Το nexus-auth το κάνει στον δεύτερο ακροατή του, στη θύρα 8443, και κάθε καλών εντός του συμπλέγματος καλεί αυτόν. Το nexus-keys το κάνει στον μοναδικό του ακροατή. Το Probitas σερβίρει TLS από το δικό του πιστοποιητικό, το nexus-probitas-tls, το οποίο ξαναδιαβάζει όταν το cert-manager το ανανεώνει. Κανένα από αυτά δεν εμπιστεύεται μια κεφαλίδα X-Forwarded-Client-Cert.

Κάθε φόρτος εργασίας λαμβάνει επίσης διακριτικά (tokens) Kubernetes διάρκειας μίας ώρας στο /var/run/secrets/nexus, ένα ανά υπηρεσία που καλεί, με εκείνη την υπηρεσία ως κοινό (audience). Το ConfigMap nexus-service-identities αντιστοιχίζει κάθε <namespace>/<service-account> σε ένα όνομα υπηρεσίας ή προσθέτου, και ένας φόρτος εργασίας που λείπει από αυτό δεν έχει ταυτότητα και απορρίπτεται. Το orchestrator και το Probitas ελέγχουν αυτά τα διακριτικά με το Kubernetes API. Από τις εκτελούμενες υπηρεσίες, μόνο αυτές οι δύο κατέχουν το system:auth-delegator ή έχουν προσαρτημένο ένα διακριτικό API· ο μοναδικός άλλος φόρτος εργασίας με διακριτικό είναι το Job θεματοφυλακής που εκτελείται κατά την εγκατάσταση.

Η πολιτική δικτύου (Network policy) κλείνει ό,τι δεν κλείνει η ταυτότητα. Το chart ξεκινά από την προεπιλεγμένη άρνηση (default deny) και στη συνέχεια επιτρέπει την κίνηση μεταξύ των pods της ίδιας της εγκατάστασης, του DNS (Domain Name System), του χώρου ονομάτων του ελεγκτή ingress (networkPolicy.ingressNamespace, kube-system από προεπιλογή) προς τα τρία δημόσια Services, και του διακομιστή API για τους δύο ελεγκτές διακριτικών. Τα pods του OpenBao φέρουν διαφορετική ετικέτα (label) από την υπόλοιπη πλατφόρμα, επομένως ο ανοιχτός κανόνας εντός του χώρου ονομάτων δεν φτάνει σε αυτά: μόνο το nexus-keys, τα Jobs του και το Job θεματοφυλακής περνούν, στη θύρα 8200. Οτιδήποτε άλλο πρέπει να προσεγγίσει ένας φόρτος εργασίας εκτός του χώρου ονομάτων, όπως ο αναμεταδότης αλληλογραφίας (mail relay) σας, μπαίνει στο networkPolicy.externalEgressCIDRs, το οποίο είναι κενό από προεπιλογή.

Μεταβάσεις (migrations) και το καθολικό σχήματος

Οι μετεγκαταστάσεις (migrations) εκτελούνται ως Helm hooks, στα post-install και pre-upgrade. Ένα post-install hook εκτελείται αφού δημιουργηθούν τα Deployments της έκδοσης (release). Έτσι, σε μια πρώτη εγκατάσταση, οι υπηρεσίες ξεκινούν ενώ τα σχήματά τους δεν υπάρχουν ακόμη, και θα έμπαιναν σε βρόχο συνεχών καταρρεύσεων (crash-loop) απέναντι σε μια βάση δεδομένων χωρίς ρόλο, χωρίς κωδικό πρόσβασης και χωρίς πίνακες. Το Nexus το αποφεύγει αυτό με ένα καθολικό (ledger).

Τα hooks εκτελούνται με σειρά βαρύτητας (weight), και το Helm περιμένει κάθε Job πριν ξεκινήσει η επόμενη βαρύτητα:

Βαρύτητα Hook Τι κάνει
-30 nexus-migrations-env και προαπαιτούμενα Δημιουργεί το αποκλειστικό για hooks Secret με τα διαπιστευτήρια του μηχανισμού μετεγκατάστασης (migrator), και οτιδήποτε διαβάζει το Job θεματοφυλακής
-20 nexus-db-bootstrap Δημιουργεί τις βάσεις δεδομένων nexus και nexus_alpha, τον ρόλο του migrator, τον ρόλο χρόνου εκτέλεσης (runtime role) κάθε υπηρεσίας, τις επεκτάσεις και το καθολικό
-15 nexus-openbao-custody-init Αρχικοποιεί τον χώρο αποθήκευσης κλειδιών και τον μηχανισμό αποσφράγισης και εκδίδει την ταυτότητα της εγκατάστασης
-12 nexus-graphrag-migrations Το σχήμα του GraphRAG, το οποίο έχει στην κατοχή του αντικείμενα στα οποία αναφέρεται η γραμμή βάσης (baseline) του nexus-auth
-10 nexus-auth-migrations Το σχήμα ταυτότητας
-5 Μετεγκαταστάσεις των orchestrator, gateway και Probitas Τα σχήματά τους· το Probitas ελέγχει πρώτα ότι υπάρχουν οι πίνακες auth
0 nexus-alpha-bff-migrations Η βάση δεδομένων της ίδιας της κονσόλας

Κάθε Job μετεγκατάστασης έχει backoffLimit: 0, επομένως μια αποτυχημένη μετεγκατάσταση οδηγεί σε αποτυχία της εγκατάστασης.

Το καθολικό είναι ένας πίνακας, ο nexus_release.schema_applied, με μία γραμμή ανά αλυσίδα (chain) και σύνοψη εικόνας (image digest). Κάθε hook γράφει τη γραμμή του μόνο αφού επιστρέψει ο εκτελεστής μετεγκατάστασής του. Κάθε Deployment που χρησιμοποιεί PostgreSQL φέρει ένα κοντέινερ αρχικοποίησης (init container), το wait-for-schema, το οποίο διαβάζει αυτόν τον πίνακα ως ένας ρόλος που δεν επιτρέπεται να διαβάσει τίποτα άλλο (nexus_ledger_reader) και περιμένει μέχρι κάθε αλυσίδα από την οποία εξαρτάται να εμφανίσει μια γραμμή για την εικόνα αυτής της έκδοσης. Τότε ξεκινά η υπηρεσία. Ο εργάτης του workflows περιμένει την αλυσίδα του orchestrator, εφόσον μοιράζεται αυτήν τη βάση δεδομένων, και η μηχανή δεξιοτήτων περιμένει μόνο την αρχικοποίηση (bootstrap).

Κάνει ερωτήματα (polls) κάθε 3 δευτερόλεπτα (schemaWait.intervalSeconds) και εγκαταλείπει μετά από 1.800 (schemaWait.timeoutSeconds) με μια γραμμή που κατονομάζει τις αλυσίδες που εξακολουθούν να λείπουν. Το κοντέινερ της ίδιας της υπηρεσίας δεν ξεκινά ποτέ απέναντι σε λάθος σχήμα.

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

Αυτός είναι ο λόγος για τον οποίο δεν πρέπει ποτέ να εκτελείτε το helm install --wait. Με το --wait, το Helm περιμένει τα Deployments πριν εκτελέσει τα post-install hooks, και τα Deployments περιμένουν τα hooks. Κανένα από τα δύο δεν προχωρά. Εγκαταστήστε χωρίς αυτό και περιμένετε μετά· το κεφάλαιο 2.6, Εγκατάσταση του Community στο Kubernetes, δίνει την ακριβή εντολή.

Απομόνωση σε τρεις άξονες

Κάθε ανάγνωση, εγγραφή, κλήση εργαλείου και αποστολή δεξιότητας στο Nexus περιορίζεται ως προς την εμβέλεια (scoped) σε τρεις άξονες.

Άξονας Πεδίο Τι διαχωρίζει
Μισθωτής (Tenant) organization_id Έναν οργανισμό από έναν άλλον, ένα αυστηρό όριο
Ιδιοκτήτης (Owner) owner_user_id Τα στοιχεία ενός ατόμου από εκείνα όλων των άλλων, ακόμη και εντός του ίδιου οργανισμού
Μονάδα (Unit) business_unit_id Μια υποδιαίρεση ενός οργανισμού, προαιρετικό

Ο άξονας του ιδιοκτήτη εκπλήσσει τους ανθρώπους. Ένα γραμματοκιβώτιο ή ένα προσωπικό σημειωματάριο είναι ιδιωτικό για τον ιδιοκτήτη του ακόμη και απέναντι σε συναδέλφους στην ίδια μονάδα με τον ίδιο ρόλο. Ένας διαχειριστής ορίζει πολιτικές και δεν διαβάζει περιεχόμενο.

Οι άξονες προέρχονται από το επαληθευμένο αίτημα και από πουθενά αλλού. Καμία μεταβλητή περιβάλλοντος, κεφαλίδα, παράμετρος ερωτήματος ή τμήμα διαδρομής δεν μπορεί να τους ορίσει. Ένα σώμα αιτήματος που κατονομάζει έναν οργανισμό απορρίπτεται με TENANT_NOT_A_PARAMETER. Μια επιφάνεια που δεν μπορεί να δηλώσει σε ποιον μισθωτή, ιδιοκτήτη και μονάδα ανήκει μια γραμμή αρνείται με 403 SCOPE_PREDICATE_MISSING, και το σώμα παραθέτει ποιοι άξονες επιλύθηκαν και ποιοι όχι. Δεν καταφεύγει ποτέ σε μια ευρύτερη ανάγνωση.

Αυτό ισχύει σε δύο σημεία ταυτόχρονα.

Στη βάση δεδομένων. Κάθε υπηρεσία συνδέεται με τους δικούς της ρόλους χρόνου εκτέλεσης: nexus_auth, auth_app και auth_platform για την υπηρεσία ταυτότητας, nexus_probitas και nexus_probitas_ledger για το Probitas, και nexus_gateway, nexus_graphrag, nexus_skills, orchestrator_app, workflows_app και τους υπόλοιπους για τις άλλες. Κανένας δεν είναι superuser ούτε έχει BYPASSRLS. Κανένας δεν έχει στην κατοχή του ούτε τους πίνακες που χρησιμοποιεί, επομένως κάθε πολιτική ασφάλειας επιπέδου γραμμής (RLS - row-level security) εφαρμόζεται σε αυτόν. Οι ρόλοι μοιράζονται μια ομάδα, την nexus_runtime, η οποία εκχωρεί δικαίωμα σύνδεσης και χρήσης σχήματος και απολύτως κανένα δικαίωμα σε πίνακες· σε κάθε υπηρεσία εκχωρούνται οι δικοί της πίνακες από τις δικές της μετεγκαταστάσεις. Οι ρυθμίσεις μισθωτή που διαβάζουν οι πολιτικές RLS μπορούν να οριστούν μόνο μέσω της συνάρτησης bind_scope κάθε υπηρεσίας, η οποία εκτελείται ως ο ιδιοκτήτης της. Η αρχικοποίηση (bootstrap) ανακαλεί το set_config από όλους τους άλλους, και το orchestrator και το Probitas αρνούνται να ξεκινήσουν εάν ο ρόλος χρόνου εκτέλεσής τους θα μπορούσε να το καλέσει απευθείας (το Probitas το ονομάζει αυτό DB_ROLE_SETS_SCOPE_DIRECTLY). Οι μόνες συνδέσεις superuser σε ολόκληρη την εγκατάσταση ανήκουν στο Job αρχικοποίησης και στο βήμα προετοιμασίας (provisioning) του BFF.

Στη κοινόχρηστη θεμελιώδη δομή ερωτημάτων περιορισμένης εμβέλειας (scoped-query primitive). Κάθε αποθετήριο στην πλατφόρμα και κάθε πρόσθετο που κατασκευάζεται πάνω στο SDK (software development kit) κληρονομεί έναν φράχτη (fence) που κατασκευάζει το κατηγόρημα (predicate) SQL από μια επιλυμένη εμβέλεια. Η συνάρτηση εμβέλειάς του λαμβάνει την επαληθευμένη ταυτότητα και δεν έχει παράμετρο οργανισμού, επομένως ένας καλών δεν μπορεί να περάσει μία, και καμία διαδρομή δεν μπορεί να εξαιρεθεί.

Υπάρχει ακριβώς μία διέλευση του ορίου του μισθωτή, και είναι στενή: μια καταγεγραμμένη έγκριση (grant). Δύο άτομα στον οργανισμό που κατέχει τις γραμμές καταγράφουν ποιος οργανισμός επιτρέπεται να διαβάσει ποιους πίνακες, και μέχρι πότε. Κάθε ανάγνωση εκτελείται σε μια συναλλαγή μόνο για ανάγνωση και καταγράφεται και στους δύο μισθωτές. Οι ιδιοκτήτες και οι διαχειριστές δεν διαβάζουν ποτέ διαγώνια μεταξύ οργανισμών, και ο αναγνώστης δεν μπορεί να διευρύνει μια έγκριση.

Η διαδρομή του AI

Οι καλούντες εκφράζουν επιθυμίες. Ο AI Provider Router κατέχει το διαπιστευτήριο και κάνει την τελική επιλογή.

Κάθε κλήση μοντέλου στο Nexus περνά μέσα από τις διαδρομές /internal/ai/* του δρομολογητή, και ο δρομολογητής δέχεται μόνο κατονομαζόμενους καλούντες. Το chart ορίζει τρεις λίστες στο gateway:

Διαδρομές Ποιος επιτρέπεται να καλέσει
Συνομιλία και ροή συνομιλίας (chat streaming) nexus-orchestrator, nexus-workflows, nexus-skills-engine
Ενσωματώσεις (Embeddings) και επανακατάταξη (rerank) nexus-graphrag, nexus-skills-engine, nexus-workflows
Οτιδήποτε άλλο, συμπεριλαμβανομένης της εκτέλεσης εργαλείων nexus-orchestrator, nexus-workflows

Μια κλήση χωρίς ταυτότητα καλούντος απορρίπτεται με 403 MISSING_CALLER_IDENTITY, και ένας καλών που δεν βρίσκεται στη λίστα με 403 UNAUTHORIZED_CALLER. Τα πρόσθετα (plugins) δεν βρίσκονται σε καμία λίστα, και αυτό είναι σκόπιμο: οι κλήσεις μοντέλων ενός προσθέτου πραγματοποιούνται εκ μέρους του, μέσω της αποστολής UNO.

Αυτό που μπορεί να στείλει ένας καλών είναι μια επιθυμία: έναν προτιμώμενο πάροχο και μοντέλο, συν ένα προφίλ δυνατοτήτων όπως ένα ελάχιστο μήκος περιβάλλοντος (context length) ή χρήση εργαλείων. Ο δρομολογητής ικανοποιεί μια επιθυμία μόνο όταν ο οργανισμός έχει ενεργοποιήσει αυτόν τον πάροχο και του έχει δώσει διαπιστευτήρια· διαφορετικά, κάνει αντικατάσταση, πρώτα εντός του ίδιου παρόχου και στη συνέχεια μεταξύ των άλλων παρόχων του οργανισμού. Ένα προφίλ δυνατοτήτων λειτουργεί μόνο ως φίλτρο, και μια απαίτηση εντοπιότητας δεδομένων (data-residency) μέσα σε αυτό είναι απαράβατη. Όταν τίποτα δεν ταιριάζει, δεν υπάρχει εφεδρικό μοντέλο: ο καλών λαμβάνει 422 MODEL_CAPABILITY_UNAVAILABLE ή 422 NO_PROVIDER_FOR_ROLE, με μια συμβολοσειρά αποκατάστασης την οποία η κονσόλα εμφανίζει σε έναν διαχειριστή.

Τα κλειδιά ανήκουν στον οργανισμό. Οι διαχειριστές κάθε οργανισμού τοποθετούν τα δικά τους κλειδιά παρόχων στη δεξαμενή του από την κονσόλα, και ο δρομολογητής τα επιλύει τη στιγμή της κλήσης. Κανένα κλειδί μοντέλου δεν αποτελεί τιμή του chart και κανένα δεν συνοδεύει το Nexus. Ένας οργανισμός χωρίς κλειδί δεν λαμβάνει απαντήσεις AI, και η κονσόλα το αναφέρει ξεκάθαρα· τίποτα δεν καλύπτει το κενό από κάπου αλλού.

Δύο τιμές του chart διαμορφώνουν τον δρομολογητή. Το ai.localProvider.baseUrl ονομάζει έναν διακομιστή μοντέλων συμβατό με το OpenAI που εκτελείτε εσείς, ο οποίος δρομολογείται όπως κάθε άλλος πάροχος. Το ai.installationHosts καταγράφει τους διακομιστές μοντέλων σας σε ιδιωτικά ονόματα, τους οποίους ο δρομολογητής υπολογίζει ως εντός της εγκατάστασης. Το GraphRAG δημιουργεί επίσης ενσωματώσεις (embeddings) μέσω του δρομολογητή, ως ο οργανισμός στον οποίο ανήκει το περιεχόμενο. Το προεπιλεγμένο μοντέλο ενσωμάτωσης εκτελείται στο σύμπλεγμα (cluster) χωρίς κάρτα γραφικών· οι φιλοξενούμενες ενσωματώσεις είναι επιλογή του κάθε οργανισμού.

Καμία τηλεμετρία

Τίποτα δεν φεύγει από μια εγκατάσταση εκτός αν το στείλετε εσείς. Η τιμή telemetry.enabled του chart μπορεί να είναι μόνο false· το σχήμα (schema) απορρίπτει οτιδήποτε άλλο. Η αναφορά του ίδιου του επιπέδου δεδομένων είναι επίσης απενεργοποιημένη: η αναφορά χρήσης του Neo4j και η τηλεμετρία του Qdrant είναι απενεργοποιημένες στο chart.

Με το networkPolicy.enabled ενεργοποιημένο, που είναι η προεπιλογή, κανένα pod δεν μπορεί να συνδεθεί στο διαδίκτυο εκτός αν καταγράψετε τον προορισμό στο networkPolicy.externalEgressCIDRs. Ένας φιλοξενούμενος πάροχος μοντέλων είναι ένας τέτοιος προορισμός, όπως και ο διακομιστής αναμετάδοσης αλληλογραφίας (mail relay) σας.

Ο ίδιος κανόνας άλλαξε μία προεπιλογή που θα παρατηρήσετε. Το CAPTCHA του nexus-auth για τις εγγραφές χρειάζεται μια υπηρεσία διαδικτύου, οπότε σε μια εγκατάσταση είναι απενεργοποιημένο, και η εγγραφή ενός αγνώστου αναμένει την έγκριση ενός διαχειριστή (403 SIGNUP_REQUIRES_APPROVAL). Ο έλεγχος που αποκλείει εγγραφές από δίκτυα φιλοξενίας (hosting networks) είναι επίσης απενεργοποιημένος, επειδή χρειάζεται αδειοδοτημένες βάσεις δεδομένων που το Nexus δεν διαθέτει. Χάνετε αυτόν τον έλεγχο.

Πώς λειτουργεί η εγκατάσταση
Πώς λειτουργεί η εγκατάσταση
Στο Enterprise, η σελίδα εύρυθμης λειτουργίας (health page) δείχνει το σύμπλεγμα κάτω από το Nexus: πόσο απασχολημένο είναι κάθε μέρος και πόση χωρητικότητα απομένει, με κάθε προειδοποίηση δίπλα στο τι πρέπει να κάνετε γι' αυτήν.