Versione 1.0.0-alpha.1ultima
Capitolo 2.25
Sviluppare per ciascuna edizione
Cosa cambia quando un'unica estensione deve funzionare in ogni edizione, in un sito air-gapped, su un payload Nexus Edge o con il marchio del cliente. Copre il confine di licenza per i moduli Enterprise e la distribuzione offline firmata, con una matrice di ciò che occorre fare diversamente per ciascuna destinazione.
Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

In Corrán Orbital distribuiamo verso più destinazioni di quanto faccia la maggior parte dei team. I nostri ingegneri eseguono Enterprise a terra. Un satellite, CORR-3, esegue un pacchetto di missione su Nexus Edge. Due clienti eseguono Community su un singolo server, uno gestisce un'installazione Enterprise isolata (air-gapped) che non vede mai internet, e abbiamo creato un pacchetto per una compagnia assicurativa sulla propria installazione. Il codice sottostante è in gran parte lo stesso, e le differenze riguardano principalmente dove è consentito inviarlo e come ci arriva.
Questo capitolo esamina ciascuna destinazione a turno: su quale base si compila, cosa non è consentito toccare e come il risultato raggiunge il cliente. Una matrice alla fine riassume tutto in una pagina. Il Capitolo 2.18, Il modello di estensione, spiega in che modo differiscono skill, plugin, pacchetti e moduli. Il Capitolo 2.2, Le edizioni sotto il cofano, descrive le edizioni stesse.
Community e l'open core
Community è il nucleo open source, concesso sotto licenza Apache License, Version 2.0. È possibile effettuarne il fork e distribuire modifiche. Il file NOTICE che lo accompagna riporta un aspetto importante da conoscere prima di applicare qualsiasi marchio: la licenza non concede l'uso dei nomi o dei marchi registrati di Adverant, se non per indicare l'origine del lavoro.
Community si estende nello stesso modo in cui si estende Enterprise. Il Plugin SDK (software development kit) è lo stesso pacchetto in entrambe le edizioni, e né il modello di servizio completo né i 22 gate di conformità cambiano; l'argomento è trattato nel capitolo 2.21, Il Plugin SDK. Anche le skill funzionano allo stesso modo. Community dispone dell'intero generatore e della libreria dello Skills Engine, completi di versioni e test, mentre i rilasci canary e l'approvazione a due persone rimangono esclusivi di Enterprise.
Le pagine per gli sviluppatori su Community offrono gli stessi percorsi ottimali (golden path) con tre differenze che noterete immediatamente:
- Il codice risiede in GitHub anziché nei repository interni dell'installazione. Il percorso ottimale del plugin crea un repository GitHub e uno spazio di sviluppo a partire dallo stesso modello bloccato utilizzato da Enterprise; la schermata DV18 mostra la creazione di
room-bookings. - I percorsi ottimali per i pacchetti di dominio e per la piattaforma sono esclusivi di Enterprise. Su Community si creano plugin e skill, oltre a lenti e flussi di lavoro su ciò che si esegue.
- I pass di Community si fermano al di sotto del livello Elevate. Su un singolo server non c'è un ambiente di produzione da raggiungere tramite un IDE (integrated development environment) e il server viene amministrato direttamente. Un tentativo di accesso dall'IDE viene rifiutato con
PASS_TIER_REQUIRED.
Uno spazio di sviluppo Community su un server di piccole dimensioni è contenuto. Il nostro disponeva di 2 core e 8 GiB di memoria, era chiuso tranne per quanto dichiarato nel manifesto, ed è terminato dopo 7 giorni di inattività.
Contribuire al progetto
Anche lo Skills Engine è rilasciato sotto licenza Apache-2.0 e accetta contributi secondo la consueta procedura. Effettuate il fork del repository, create un branch da main, apportate la modifica con i relativi test ed eseguite i controlli prima di aprire una pull request:
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheckUn contributo che modifica il comportamento richiede un test che fallisca in assenza di tale modifica. Non si tratta di una convenzione interna: le stesse regole di test dell'SDK stabiliscono che ogni nuovo test deve dimostrare di fallire sull'albero del codice prima della modifica, e i revisori ne richiedono le prove.
Moduli Enterprise e il confine di licenza
Enterprise è costituito da Community più i moduli con licenza. Un modulo con licenza è un artefatto separato che un servizio Community carica all'avvio, ed è il modo in cui le funzionalità Enterprise, e qualsiasi modulo chiuso sviluppato per i clienti Enterprise, si collegano al nucleo open source.
La regola che permette questo funzionamento è la linea di licenza. Un modulo chiuso può comunicare con l'edizione Community esclusivamente attraverso un unico pacchetto, @adverant/nexus-spi, la Service Provider Interface. È rilasciato sotto licenza Apache-2.0 e contiene le interfacce e i type guard che un host e un modulo utilizzano per verificarsi a vicenda, senza alcun'altra logica di runtime. L'accoppiamento oltre la linea avviene tramite un'interfaccia o un protocollo di rete, mai tramite codice sorgente.
| Esportazione | Cos'è |
|---|---|
RouteModule |
Un modulo di route con licenza: id, featureGroup, bodies e register(app, ctx), che monta i propri router sull'applicazione dell'host |
SpiApp |
La parte dell'app HTTP dell'host toccata da un modulo: use |
SpiContext |
Ciò che l'host passa a un modulo: il gate di prodotto e la guardia di ambito, il lettore di licenza, il pool di query con ambito, lo schema del servizio, gli indirizzi upstream e i client della piattaforma |
SpiRuntime |
I valori del Plugin SDK che un host passa a un modulo, affinché il modulo non importi mai direttamente il runtime dell'SDK |
SpiPlane |
Ciò che un piano con licenza aggiunge oltre alle route, come le letture di schermata che serve |
ScreenModule |
Un gruppo di schermate con licenza di una console: group, featureGroup, routes, screens e menu |
GrantCheck |
(featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }> |
Il framework HTTP e il tipo di schermata della console sono parametri di tipo, pertanto l'interfaccia non vincola nessuno dei due. Ecco lo scheletro di un modulo di route, con un tipo di gestore Express:
import type { GrantCheck, RouteModule, SpiApp, SpiContext } from "@adverant/nexus-spi";
import { Router, type RequestHandler } from "express";
export function auditTrail(checkGrant: GrantCheck): RouteModule<RequestHandler> {
return {
id: "audit-trail",
featureGroup: "<feature-group>",
bodies: [],
register(app: SpiApp<RequestHandler>, ctx: SpiContext<RequestHandler>) {
const router = Router();
router.get("/api/audit-trail", ...ctx.requireScope, async (_req, res) => {
const verdict = await checkGrant("<feature-group>");
if (!verdict.entitled) {
res.status(403).json({
error: true,
code: verdict.code,
message: "This organisation's licence does not carry the audit trail.",
troubleshooting: ["An owner or administrator can turn it on with a licence from Adverant."],
});
return;
}
res.json({ entries: [] });
});
app.use(router);
},
};
}<feature-group> è il gruppo di funzionalità della matrice delle edizioni servito dal modulo. Ogni route con licenza viene eseguita dietro ctx.requireScope, il gate di prodotto e guardia di ambito dell'host, e anche il modulo verifica la propria concessione prima di rispondere. Un modulo privo di autorizzazione rifiuta con LICENCE_LOCKED e mostra l'anteprima della funzionalità, mai i relativi dati. Inoltre, il modulo non importa mai il runtime del Plugin SDK, poiché l'SDK è un pacchetto Community non ammesso oltre la linea di licenza. È l'host a fornirgli i valori dell'SDK che richiama. Prima di caricare qualsiasi modulo, l'host installa un SpiHost su globalThis sotto Symbol.for(SPI_HOST_KEY), contenente il runtime dell'SDK e il kit di route proprio dell'applicazione. Questa operazione deve avvenire per prima: un modulo compilato in un unico bundle viene valutato nel suo insieme e una chiamata a register arriverebbe troppo tardi per il codice che legge i valori dell'SDK durante il caricamento. Per quanto riguarda i tipi, @adverant/nexus-spi/sdk/<module> riesporta le dichiarazioni dell'SDK, integrate senza modifiche da una specifica release dell'SDK e bloccate tramite checksum, in modo che il modulo esegua il controllo dei tipi rispetto agli stessi corpi di rifiuto e agli stessi client utilizzati da un plugin.
Un modulo di schermata segue un'ulteriore regola: un modulo per ciascun gruppo di funzionalità; pertanto, un gruppo le cui schermate appartengono a due gruppi di funzionalità viene distribuito come due moduli distinti, e solo uno di essi contiene la riga di menu.
Cosa rifiuta il gate della linea di licenza
Il gate della linea di licenza di Adverant impone il rispetto della linea a ogni modulo Enterprise, ed è opportuno sottoporre anche i propri moduli chiusi alla medesima regola. La sua configurazione consiste in un unico file:
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}Ciascuno dei seguenti casi costituisce una violazione rilevata, completa di indicazione del file e della riga:
- qualsiasi importazione di un pacchetto sotto un ambito Community che non sia l'interfaccia consentita o un pacchetto Enterprise, incluse le importazioni dinamiche;
- qualsiasi specificatore, percorso di importazione Go o URL di dipendenza che faccia riferimento a un repository Community, a meno che non si tratti di un modulo Go elencato in
allowedCommunityGoModules; - un'importazione relativa che risale all'esterno del repository;
- una dipendenza
package.jsonche corrisponde a un percorsofile:,link:,portal:oworkspace:esterno al repository, oppure a un URL Git che punta a un repository Community; - un
go.modreplaceche punta all'esterno del repository.
Restituisce il codice di uscita 0 se non ci sono problemi e 1 in caso di violazioni rilevate. Il codice di uscita 2 indica un rifiuto dovuto a una configurazione errata o all'assenza di elementi analizzati. Il pacchetto dell'interfaccia non è pubblicato su un registro. È necessario mantenere una copia bloccata a livello di byte del pacchetto compilato all'interno del proprio repository come pacchetto file: locale, con un pin SHA256SUMS e un controllo nella pipeline che rifiuti qualsiasi copia difforme. Poiché la copia si trova all'interno del repository, il gate la accetta.
Build per le edizioni
Se l'estensione viene distribuita a clienti su entrambe le edizioni, è necessario compilarla una volta per ciascuna edizione, e ogni compilazione avviene nel proprio albero composto. Comporre un albero significa includere esclusivamente i file che appartengono a quella specifica edizione. Il sistema di esportazione di Adverant esegue questa operazione a partire da un elenco di confini in cui ogni file tracciato viene assegnato secondo regole basate sulla prima corrispondenza (first-match-wins): una regola indica una capacità e l'edizione del file deriva dal livello di tale capacità nella matrice delle edizioni, oppure indica una classe di file che non viene distribuita in nessuna delle due edizioni, specificandone il motivo. I file destinati esclusivamente alla compilazione vengono inclusi nell'albero Enterprise e, se contrassegnati, anche nell'albero Community. La catena di migrazione di un modulo costituisce dati dell'installatore e viene inclusa nell'albero di ogni edizione.
Successivamente, eseguite l'intera compilazione da zero in ciascun albero composto. Ciò significa eseguire tutti e tre i comandi, ogni volta:
npm ci
npm test
npm run buildLo abbiamo imparato a caro prezzo: un albero Enterprise ha superato i test mentre l'albero Community ha fallito la compilazione di produzione, poiché un tipo necessario risiedeva esclusivamente in un file Enterprise. Il superamento dei test in un albero non fornisce alcuna garanzia sull'altro. I test di un'edizione possono importare solo ciò che è contenuto nell'albero di quell'edizione, e il processo di esportazione rifiuta qualsiasi test che cerchi risorse al di fuori di esso.
Il processo di esportazione scrive inoltre la licenza di ciascuna edizione. I file Community riportano l'identificatore SPDX (Software Package Data Exchange) Apache-2.0; i file Enterprise riportano LicenseRef-Adverant-Enterprise e il loro campo package.json indica UNLICENSED. Non modificate manualmente questi campi: l'esportazione li sovrascrive e una copia che non corrisponde più al testo della licenza bloccato viene rifiutata.
Team: solo cloud
Team è costituito da Community più il set Team, e funziona esclusivamente sul cloud Adverant. Non esiste una versione self-hosted di Team. Il set Team aggiunge sei capacità rispetto a Community, tra cui il pannello di lavoro consolidato, i notebook condivisi, l'amministrazione della libreria delle skill e le operazioni sui flussi di lavoro con promozione tra ambienti.
Per uno sviluppatore, l'esclusività del cloud significa una sola cosa: un cliente Team riceve il plugin come release firmata attraverso il catalogo, mai dai vostri server. Lo si compila esattamente come fa un editore esterno, su un cluster editore.
Un cluster editore è un cluster virtuale sul cloud Adverant con una quota definita da Adverant. Contiene esclusivamente dati di esempio e non ha alcun instradamento verso i clienti. La richiesta di una copia mascherata dei dati di un cliente in questo ambiente viene rifiutata con TENANT_BOUNDARY; un cliente può condividere con voi i risultati dei test, ma mai i propri dati. Il vostro pass su questo cluster non raggiunge mai l'ambiente di un cliente. Quando la release è pronta, viene firmata e sottoposta a revisione da parte di Adverant prima di essere inserita nel catalogo. Ciascun cliente sceglie quindi se installarla e le concede solo quanto dichiarato nel manifesto, unità per unità. Una chiamata a qualsiasi risorsa non dichiarata nel manifesto viene rifiutata lato cliente con CONNECTION_SCOPE_EXCEEDED, e l'unico modo per aggiungerla consiste nel pubblicare una nuova release che il cliente dovrà esaminare.
Clienti air-gapped
Uno dei nostri clienti esegue Nexus in un ambiente in cui nessun dato entra o esce attraverso una rete. La loro installazione è descritta nel capitolo 2.10, Installazione isolata (air-gapped). Per noi questo ha significato distribuire il nostro plugin su supporti firmati, e lo strumento preposto a tale scopo è nexus-airgap, parte del kit di distribuzione sovrana @adverant/nexus-sovereign.
Un bundle sigillato è un unico archivio tarball autonomo e firmato. Può contenere immagini e migrazioni, skill pre-firmate e pesi dei modelli, oltre a una SBOM (software bill of materials) con le licenze di tutti gli elementi interni. Il suo manifesto elenca ogni file con il relativo hash SHA-256 ed è firmato con Ed25519. La compilazione a partire dal codice si presenta così:
import { SealedBundleExporter } from "@adverant/nexus-sovereign";
const { bundleDigest } = await new SealedBundleExporter().export(source, {
outPath: "./cold-chain-0.4.0.tar.gz",
profile: "airgap",
signerPrivateKeyPem,
});signerPrivateKeyPem è la vostra chiave di firma della release. Il comando nexus-airgap bundle esegue la stessa operazione dalla riga di comando. L'operatore del cliente procede quindi alla verifica prima di qualsiasi altra operazione:
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgapLa verifica ricalcola l'hash di ogni file confrontandolo con il manifesto, rifiuta qualsiasi file non elencato nel manifesto, richiede un firmatario Ed25519 attendibile e rifiuta qualsiasi bundle il cui elenco di indirizzi di rete consentiti (allow-list) non sia vuoto. Un file modificato dopo la firma genera un errore con BUNDLE_INTEGRITY_VIOLATION. Istruite l'operatore affinché si fermi immediatamente e vi contatti; esiste un'opzione non restrittiva, ma non dovrebbe mai essere utilizzata.
La nostra distribuzione si è basata su tre regole:
- La chiave attendibile viaggia separatamente dal bundle. Inviamo la chiave pubblica e l'hash SHA-256 del bundle attraverso un canale diverso rispetto al supporto fisico, in modo che un bundle non possa garantire per se stesso.
- Nessun elemento all'interno del bundle può richiedere l'accesso alla rete durante l'installazione. Nessun recupero di pacchetti, nessun download di modelli, nessuna chiamata di verifica della licenza. Se il plugin necessita di un modello, il server dei modelli interno del cliente lo fornisce attraverso l'AI (artificial intelligence) Provider Router.
- Dopo la verifica, l'operatore importa la release attraverso i canali di rilascio propri dell'installazione, esattamente come farebbe un cliente connesso alla rete. Il bundle rappresenta il mezzo con cui arrivano i byte, non una scorciatoia per aggirare i gate di promozione.
Il lavoro in ambienti isolati (air-gapped) è più lento e non c'è modo di evitarlo da parte nostra. Un singolo byte errato comporta la creazione di un nuovo set di supporti e un altro viaggio; pertanto, verifichiamo noi stessi il bundle su una macchina pulita utilizzando lo stesso comando prima che lasci l'edificio.
Pacchetti missione Nexus Edge
Nexus Edge è una versione ridotta di Nexus che viene eseguita su satelliti e droni, su computer di missione mantenuti separati dal computer di volo. È un componente aggiuntivo con una licenza per piattaforma o per flotta. Ciò che cambia da una missione all'altra è il pacchetto di missione, e la creazione di questi pacchetti costituisce buona parte del mio lavoro.
Un pacchetto di missione contiene ciò di cui il carico utile (payload) ha bisogno per una singola missione. Oltre ai modelli e agli adattatori, contiene l'ontologia con un grafo iniziale, i passaggi degli agenti, le regole di avviso, le priorità per i dati da trasmettere a terra per primi, una tabella di posizionamento che indica quale computer esegue cosa, i livelli di funzionamento degradato a cui la piattaforma può passare in caso di guasto di un computer e i casi di test che deve superare a bordo.
I pacchetti vengono compilati e firmati a terra. Ecco alcune regole pratiche derivate dalle nostre compilazioni:
- Mantenete stabili i componenti di grandi dimensioni. Maritime watch 1.5 ha aggiunto un adattatore per il rilevamento navale e due regole di avviso; il modello linguistico e l'ontologia non sono cambiati, quindi il pacchetto pesava 412 MB invece di 9.8 GB. Il collegamento in salita (uplink) ha una banda ridotta e i modelli di base vengono caricati prima del lancio.
- Utilizzate un unico modello di embedding per l'intera famiglia di missioni, sia a terra che sul carico utile, in modo che le modifiche al grafo trasmesse a terra possano fondersi con il grafo di terra.
- Il carico utile non invia mai un comando diretto ai sistemi di volo. Invia richieste tipizzate attraverso il supervisore al computer di volo, il quale risponde a ciascuna indicando una motivazione.
- Ogni tipo di hardware richiede una verifica specifica del pacchetto. L'installazione di un pacchetto non verificato per l'hardware di un determinato dispositivo viene rifiutata con
PACK_NOT_CHECKED_FOR_HARDWARE.
Il rilascio richiede due firme su tre. La nostra e quella di Adverant costituiscono la coppia abituale, mentre la terza è una chiave offline che conserviamo in una cassaforte nel caso in cui una delle altre due vada persa. Il pacchetto viene caricato nello slot inattivo, viene verificato, esegue i propri casi di test sulle schede reali e viene attivato solo se tutti i test vengono superati, con un contatore che impedisce la reinstallazione di un pacchetto più vecchio. Se un test fallisce, la piattaforma rimane sul pacchetto precedente e l'errore viene trasmesso a terra al passaggio successivo. Effettuiamo il rilascio su una piattaforma alla volta, procedendo con la successiva solo dopo una settimana senza anomalie. I pacchetti rimangono validi mentre una piattaforma è fuori contatto, pertanto un satellite privo di collegamento continua a operare con il pacchetto di cui dispone.
Su veicoli e imbarcazioni, Edge può essere eseguito su k3s. Un veicolo spaziale esegue un supervisore con immagini firmate o binari statici e una tabella di posizionamento fissa al posto di Kubernetes, ed è per questo motivo che la tabella di posizionamento viaggia all'interno del pacchetto.
Vetrine white-label
Il componente aggiuntivo Storefront / white-label consente a un cliente di applicare il proprio marchio e il proprio dominio a ciò che vedono gli utenti, con schermate di accesso personalizzate, e di accettare pagamenti tramite i propri gateway. I dati delle carte di pagamento non toccano mai Nexus.
Un plugin sviluppato per un cliente white-label non deve mai mostrare il nome Adverant. Il manifesto contiene tutti gli elementi specifici del marchio e la piattaforma risolve il resto a partire dal marchio proprio dell'organizzazione, anziché da valori cablati nel codice:
{
"domains": [
{ "primary": "<app-domain>", "aliases": ["www.<app-domain>"] }
],
"branding": {
"appName": "<app name>",
"tagline": "<one line>",
"primaryColor": "<hex>",
"accentColor": "<hex>",
"passkeyRpId": "<app-domain>",
"oauthClientRef": "brand:<plugin name>:google"
}
}<app-domain> è il dominio del cliente e passkeyRpId deve corrispondervi, poiché le passkey sono vincolate al dominio su cui una persona effettua l'accesso. Un'applicazione web sulla propria origine autentica gli utenti tramite gli helper di accesso dell'SDK, le cui due route pubbliche sono le uniche route /api non protette accettate dal gate di ambito, e solo quando il manifesto le dichiara auth: public con allowAnonymous: true. Le chiamate del frontend passano attraverso il proxy allow-list del backend per il frontend (BFF), mai direttamente verso l'indirizzo di un servizio. L'amministratore del cliente configura la parte relativa ai pagamenti, dai gateway fino alla pagina di pagamento con il proprio marchio. Il vostro plugin non se ne occupa.
La matrice
| Destinazione di compilazione | Base di compilazione | Cosa cambia nel processo | Come raggiunge il cliente |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Codice in GitHub; nessun percorso per pacchetti di dominio o piattaforma; nessun livello Elevate | Il cliente lo installa direttamente; nessuna revisione del catalogo necessaria |
| Enterprise (installazione propria) | Plugin SDK, Skills Engine, modelli di pacchetto | Spazi di sviluppo, branch di dati, copie mascherate con il proprietario dei dati; pacchetti e lenti | Promozione dallo staging a un'unità pilota, poi ovunque |
| Modulo Enterprise (chiuso) | Solo @adverant/nexus-spi |
Regola della linea di licenza; controllo delle concessioni sul proprio gruppo di funzionalità; LICENCE_LOCKED se non autorizzato |
Caricato da un servizio Community all'avvio, sulle installazioni con licenza |
| Entrambe le edizioni | Plugin SDK | Composizione dell'albero di ciascuna edizione; npm ci, test e compilazione di produzione in ciascuno |
Una release per edizione |
| Team | Plugin SDK su un cluster editore | Solo dati di esempio; solo cloud | Release firmata, revisione Adverant, catalogo |
| Isolata (air-gapped) | Plugin SDK, @adverant/nexus-sovereign |
Bundle sigillato; chiave e checksum inviati separatamente; nessun dato recuperato dalla rete all'installazione | Supporti firmati, verificati, poi tramite i canali di rilascio dell'installazione |
| Nexus Edge | Contenuti del pacchetto di missione | Tabella di posizionamento, livelli degradati, test a bordo, controlli hardware | Due firme su tre, slot inattivo, attivazione dopo il superamento dei test |
| White-label | Plugin SDK | domains e branding nel manifesto; nessun nome Adverant in alcun punto |
Come per Enterprise, sul dominio del cliente |
Qualunque sia la destinazione, la distribuzione avviene esclusivamente attraverso i canali di rilascio dell'installazione. Il Capitolo 2.28, Rilascio dell'estensione, illustra tali canali. Il Capitolo 2.27, Scenari di compilazione, fornisce una procedura dettagliata per ciascuna riga della tabella soprastante.



