Versjon 1.0.0-alpha.1nyeste
Kapittel 2.25
Bygge for hver utgave
Hva som endres når én utvidelse må fungere i hver utgave, på et luftgapet anlegg, på en Nexus Edge-nyttelast eller bak en kundes eget merke. Dekker lisensgrensen for Enterprise-moduler og signert frakoblet levering, med en matrise over hva som må gjøres annerledes for hvert mål.
Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

Hos Corrán Orbital leverer vi til flere steder enn de fleste team gjør. Våre egne ingeniører kjører Enterprise på bakken. En satellitt, CORR-3, kjører en oppdragspakke på Nexus Edge. To kunder kjører Community på én enkelt server, én kjører en luftgapet Enterprise-installasjon som aldri ser internett, og vi har bygget en pakke for et forsikringsselskap på deres egen installasjon. Koden under er stort sett den samme, og forskjellene handler mest om hvor den har lov til å gå og hvordan den kommer dit.
Dette kapittelet går gjennom hvert mål etter tur: hva du bygger mot, hva du ikke har lov til å røre, og hvordan resultatet når kunden. En matrise til slutt samler alt på én side. Kapittel 2.18, Utvidelsesmodellen, forklarer hvordan ferdigheter, programtillegg, pakker og moduler skiller seg fra hverandre. Kapittel 2.2, Utgavene under panseret, beskriver selve utgavene.
Community og den åpne kjernen
Community er den åpne kjernen, under Apache License, Version 2.0. Du kan forgrene den og levere endringer til den. NOTICE-filen som følger med den, sier én ting som er verdt å vite før du setter ditt eget merke på noe: lisensen gir ikke rett til bruk av Adverants navn eller varemerker utover det å oppgi hvor arbeidet kom fra.
Du utvider Community på samme måte som du utvider Enterprise. Plugin SDK (programvareutviklingssett) er den samme pakken på begge utgavene, og verken fulltjenestemalen eller de 22 etterlevelsesportene endres; kapittel 2.21, Plugin SDK, dekker dette. Ferdigheter fungerer også. Community får hele oppretteren og biblioteket i Skills Engine, med versjoner og tester, mens kanariutgivelser og topersonsgodkjenning forblir i Enterprise.
Utviklersidene på Community tilbyr de samme gylne stiene med tre forskjeller du vil merke med en gang:
- Koden din lever i GitHub fremfor i installasjonens egne kodelagre. Den gylne stien for programtillegg oppretter et GitHub-kodelager og et utviklingsområde fra den samme låste malen som Enterprise bruker; skjermbilde DV18 viser at den oppretter
room-bookings. - De gylne stiene for domenepakker og plattform tilhører Enterprise. På Community bygger du programtillegg og ferdigheter, pluss linser og arbeidsflyter på det du kjører.
- Community-pass stopper under Elevate-nivået. På én server er det ingen produksjon å nå fra et IDE (integrert utviklingsmiljø), og du administrerer serveren direkte. Et forsøk fra IDE-et avvises med
PASS_TIER_REQUIRED.
Et Community-utviklingsområde på en liten server er beskjedent. Vårt hadde 2 kjerner og 8 GiB minne, stengt bortsett fra det manifestet deklarerer, og det ble avsluttet etter 7 inaktive dager.
Bidra tilbake
Skills Engine er også under Apache-2.0, og tar imot bidrag på vanlig måte. Forgren kodelageret, opprett en gren fra main, gjør endringen med tilhørende tester, og kjør kontrollene før du åpner en flettingsforespørsel:
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheckEt bidrag som endrer atferd, trenger en test som feiler uten det. Dette er ikke husstil: SDK-ets egne testregler sier at hver ny test må vises å feile på treet før endringen, og fagfeller ber om beviset.
Enterprise-moduler og lisensgrensen
Enterprise er Community pluss lisensierte moduler. En lisensiert modul er en separat artefakt som en Community-tjeneste laster inn når den starter, og det er slik Enterprise-funksjoner, og enhver lukket modul du bygger for Enterprise-kunder, kobles til den åpne kjernen.
Regelen som får dette til å fungere, er lisensgrensen. En lukket modul kan nå Community-utgaven gjennom kun én pakke, @adverant/nexus-spi, tjenesteleverandørgrensesnittet. Den er under Apache-2.0 og inneholder grensesnitt pluss typevaktene en vert og en modul bruker for å kontrollere hverandre, uten annen kjøretidslogikk. Kobling over grensen skjer via et grensesnitt eller en nettverksprotokoll, aldri kildekode.
| Eksport | Hva det er |
|---|---|
RouteModule |
En lisensiert rutemodul: id, featureGroup, bodies og register(app, ctx), som monterer ruterne sine på vertens app |
SpiApp |
Delen av vertens HTTP-app som en modul berører: use |
SpiContext |
Hva verten gir en modul: produktporten og omfangsvakten, lisensleseren, den omfangsbegrensede spørrepoolen, tjenestens skjema, oppstrømsadressene og plattformklientene |
SpiRuntime |
Plugin SDK-verdiene en vert gir en modul, slik at modulen aldri selv importerer SDK-ets kjøretidsmiljø |
SpiPlane |
Hva et lisensiert plan legger til utover ruter, slik som skjermlesningene det betjener |
ScreenModule |
En konsolls lisensierte skjermgruppe: group, featureGroup, routes, screens og menu |
GrantCheck |
(featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }> |
HTTP-rammeverket og konsollens skjermtype er typeparametere, så grensesnittet binder ingen av dem. Her er skjelettet til en rutemodul, med en Express-håndteringstype:
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> er funksjonsgruppen i utgavematrisen som modulen betjener. Hver lisensiert rute kjører bak ctx.requireScope, vertens produktport og omfangsvakt, og modulen sjekker også sin egen tildeling før den svarer. En modul som ikke har rettigheter, avviser med LICENCE_LOCKED og tegner funksjonens forhåndsvisning, aldri dataene dens. Modulen din importerer heller aldri kjøretidsmiljøet til programtilleggets SDK, fordi SDK-et er en Community-pakke som grensen ikke tillater. Verten gir den SDK-verdiene den kaller. Før den laster inn noen modul, installerer verten en SpiHost på globalThis under Symbol.for(SPI_HOST_KEY), som holder SDK-kjøretidsmiljøet og appens eget rutesett. Dette må skje først: en modul kompilert til én bunt evalueres som en helhet, og et register-kall ville komme for sent for kode som leser SDK-verdiene mens den lastes inn. For typer re-eksporterer @adverant/nexus-spi/sdk/<module> SDK-ets deklarasjoner, levert uendret fra én SDK-utgivelse og låst med sjekksum, slik at modulen din typesjekker mot de samme avvisningskroppene og klientene som et programtillegg bruker.
En skjermmodul følger én regel til: én modul per funksjonsgruppe, slik at en gruppe der skjermene tilhører to funksjonsgrupper, leveres som to moduler, og bare én av dem bærer menyraden.
Hva lisensgrenseporten avviser
Adverants lisensgrenseport holder hver Enterprise-modul til grensen, og det er verdt å holde dine egne lukkede moduler til samme regel. Konfigurasjonen dens er én fil:
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}Hver av disse er et funn med fil og linje:
- enhver import av en pakke under et Community-omfang som ikke er det tillatte grensesnittet eller en Enterprise-pakke, inkludert dynamiske importer;
- enhver spesifikator, Go-importsti eller avhengighets-URL som navngir et Community-kodelager, med mindre det er en Go-modul oppført i
allowedCommunityGoModules; - en relativ import som klatrer ut av kodelageret;
- en
package.json-avhengighet som er enfile:-,link:-,portal:- ellerworkspace:-sti utenfor kodelageret, eller en Git-URL til et Community-kodelager; - en
go.modreplacesom peker utenfor kodelageret.
Den avslutter med 0 når alt er rent, og 1 ved funn. Avslutningskode 2 betyr at den avviste fordi konfigurasjonen var ugyldig eller den ikke skannet noe. Grensesnittpakken er ikke publisert i et register. Du har med en byte-låst kopi av den bygde pakken inne i kodelageret ditt som en lokal file:-pakke, med en SHA256SUMS-låsing og en sjekk i leveringskjeden din som avviser en kopi som avviker. Fordi kopien ligger inne i kodelageret, godtar porten den.
Utgavebygg
Hvis utvidelsen din leveres til kunder på begge utgavene, bygger du den én gang per utgave, og hvert bygg skjer i sitt eget sammensatte tre. Å sette sammen et tre betyr å ta kun de filene som tilhører den utgaven. Adverants egen eksport gjør dette fra en grenseliste der hver sporet fil tilordnes etter regler der første treff vinner: en regel navngir en kapabilitet, og filens utgave følger av denne kapabilitetens nivå i utgavematrisen, eller den navngir en klasse filer som ikke leveres i noen av utgavene, med en begrunnelse. Filer som kun brukes ved bygging, leveres i Enterprise-treet og, når de er merket, også i Community-treet. En moduls migreringskjede er installasjonsdata og leveres i treet til hver utgave.
Kjør deretter hele bygget fra bunnen av i hvert sammensatte tre. Det betyr alle tre kommandoene, hver gang:
npm ci
npm test
npm run buildVi lærte dette på den dyre måten: et Enterprise-tre besto testene sine mens Community-treet feilet i produksjonsbygget sitt, fordi en type det trengte, kun fantes i en Enterprise-fil. Tester som består i ett tre, forteller deg ingenting om det andre. En utgaves tester kan kun importere det som finnes i denne utgavens tre, og eksporten avviser en test som strekker seg utenfor det.
Eksporten skriver også hver utgaves lisens. Community-filer bærer SPDX-identifikatoren (Software Package Data Exchange) Apache-2.0; Enterprise-filer bærer LicenseRef-Adverant-Enterprise og deres package.json sier UNLICENSED. Ikke rediger disse feltene manuelt: eksporten skriver dem på nytt, og en kopi som ikke lenger samsvarer med den låste lisensteksten sin, blir avvist.
Team: kun i skyen
Team er Community pluss Team-settet, og det kjører kun i Adverant-skyen. Det finnes ingen selvdriftet Team. Team-settet legger til seks kapabiliteter på toppen av Community, blant annet det konsoliderte arbeidspanelet, delte notatbøker, administrasjon av ferdighetsbibliotek og arbeidsflytoperasjoner med promotering mellom miljøer.
For en utvikler betyr kun i skyen én ting: en Team-kunde får programtillegget ditt som en signert utgivelse gjennom katalogen, aldri fra dine egne servere. Du bygger det på samme måte som en ekstern utgiver bygger, på en utgiverklynge.
En utgiverklynge er en virtuell klynge i Adverant-skyen med en kvote satt av Adverant. Den inneholder kun eksempeldata og har ingen rute til noen kunde. Å be om en maskert kopi av en kundes data der blir avvist med TENANT_BOUNDARY; en kunde kan dele testresultater med deg, aldri dataene sine. Passet ditt på den når aldri inn til en kunde. Når utgivelsen er klar, signeres og gjennomgås den av Adverant før den oppføres i katalogen. Hver kunde velger deretter om de vil installere den og gir den kun det manifestet deklarerer, enhet for enhet. Et kall til noe manifestet ikke deklarerte, avvises hos kunden med CONNECTION_SCOPE_EXCEEDED, og den eneste måten å legge det til på er en ny utgivelse som kunden gjennomgår.
Luftgapede kunder
Én av kundene våre kjører Nexus der ingenting går inn eller ut over et nettverk. Installasjonen deres er beskrevet i kapittel 2.10, Luftgapet installasjon. For oss betydde det å levere programtillegget vårt på signerte medier, og verktøyet for det er nexus-airgap, fra det suverene leveringssettet @adverant/nexus-sovereign.
En forseglet bunt er én signert, selvstendig tarball. Den kan inneholde avbildninger og migreringer, forhåndssignerte ferdigheter og modellvekter, og en SBOM (programvare-stykliste) med lisensene til alt inni. Manifestet lister opp hver fil med dens SHA-256 og er signert med Ed25519. Å bygge en fra kode ser slik ut:
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 er signeringsnøkkelen din for utgivelser. Kommandoen nexus-airgap bundle gjør det samme fra kommandolinjen. Kundens operatør sjekker den deretter før noe annet:
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgapVerifisering beregner hash på nytt for hver fil mot manifestet, avviser enhver fil som manifestet ikke lister opp, krever en klarert Ed25519-signatar, og avviser enhver bunt der nettverkets tillatelsesliste ikke er tom. En fil som er endret etter signering, feiler med BUNDLE_INTEGRITY_VIOLATION. Be operatøren om å stoppe der og ringe deg; det finnes en ikke-streng bryter, og de bør aldri bruke den.
Tre regler bar leveransen vår:
- Den klarerte nøkkelen reiser separat fra bunten. Vi sender den offentlige nøkkelen og buntens SHA-256 via en annen rute enn mediene, slik at en bunt ikke kan gå god for seg selv.
- Ingenting i bunten kan kreve nettverket ved installasjon. Ingen pakkehenting, ingen modellnedlasting, intet lisenskall. Hvis programtillegget trenger en modell, leverer kundens egen modellserver den gjennom AI (kunstig intelligens) Provider Router.
- Etter verifisering tar operatøren utgivelsen inn gjennom installasjonens egne utgivelseskanaler, nøyaktig slik en tilkoblet kunde ville gjort. Bunten er måten bytene ankommer på, ikke en snarvei rundt promoteringsportene.
Luftgapet arbeid går saktere, og det kan ikke løses fra vår side. Én feil byte koster et nytt sett med medier og en ny tur, så vi verifiserer bunten selv på en ren maskin med samme kommando før den forlater bygningen.
Nexus Edge-oppdragspakker
Nexus Edge er en mindre Nexus som kjører på satellitter og droner, på oppdragsdatamaskiner som holdes adskilt fra flydatamaskinen. Det er et tillegg med en lisens per plattform eller flåte. Det som endrer seg fra ett oppdrag til det neste, er oppdragspakken, og å bygge disse er en god del av jobben min.
En oppdragspakke bærer det nyttelasten trenger for ett oppdrag. Ved siden av modeller og adaptere inneholder den ontologien med en startgraf, agenttrinn, varslingsregler, prioriteringene for hva som sendes ned først, en plasseringstabell som sier hvilken datamaskin som kjører hva, de degraderte trinnene plattformen kan falle tilbake til når en datamaskin svikter, og testtilfellene den må bestå om bord.
Pakker bygges og signeres på bakken. Noen praktiske regler fra byggene våre:
- Hold de store delene stabile. Maritime watch 1.5 la til en skipsfinneradapter og to varslingsregler; språkmodellen og ontologien ble ikke endret, så pakken var 412 MB i stedet for 9.8 GB. Opplinken er smal, og grunnmodeller lastes inn før oppskyting.
- Bruk én innbyggingsmodell for hele oppdragsfamilien både på bakken og i nyttelasten, slik at grafendringene som kommer ned, kan flettes med bakkegrafen.
- Nyttelasten sender aldri en kommando til flysystemene. Den sender typede forespørsler gjennom overvåkeren til flydatamaskinen, som svarer på hver enkelt med en begrunnelse.
- Hver maskinvaretype trenger sin egen kontroll av pakken. Installasjon av en pakke som ikke er kontrollert for en enhets maskinvare, avvises med
PACK_NOT_CHECKED_FOR_HARDWARE.
Utgivelse krever to av tre signaturer. Vår og Adverants er det vanlige paret, og den tredje er en frakoblet nøkkel vi oppbevarer i en safe i tilfelle én av de to andre går tapt. Pakken går opp til det inaktive sporet, verifiseres, kjører testtilfellene sine på de faktiske kortene, og slås kun på hvis alle består, med en teller som hindrer at en eldre pakke installeres på nytt. Hvis en test feiler, blir plattformen værende på den forrige pakken, og feilen sendes ned ved neste passering. Vi ruller ut én plattform om gangen, hver etter en feilfri uke. Pakker forblir gyldige mens en plattform er uten kontakt, slik at en satellitt uten forbindelse fortsetter å arbeide på pakken den har.
På kjøretøy og fartøyer kan Edge kjøre på k3s. Et romfartøy kjører en overvåker med signerte avbildninger eller statiske binærfiler og en fast plasseringstabell i stedet for Kubernetes, og det er derfor plasseringstabellen følger med inne i pakken.
White-label-butikkfronter
Tillegget Storefront / white-label lar en kunde sette sitt eget merke og domene på det brukerne deres ser, med egne påloggingsskjermer, og ta imot betalinger gjennom sine egne betalingsløsninger. Kortdetaljer berører aldri Nexus.
Et programtillegg bygget for en white-label-kunde må aldri vise Adverant. Manifestet bærer alt merkespesifikt, og plattformen løser resten fra organisasjonens eget merke fremfor fra noe som er hardkodet i koden din:
{
"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> er kundens eget domene, og passkeyRpId må samsvare med det, fordi passnøkler er bundet til domenet en person logger på. En nettapp på sin egen opprinnelse logger folk på gjennom SDK-ets påloggingshjelpere, der de to offentlige rutene er de eneste ubeskyttede /api-rutene omfangsporten godtar, og kun når manifestet deklarerer dem auth: public med allowAnonymous: true. Frontend-kall går gjennom backend-for-frontend-mellomtjeneren med tillatelsesliste, aldri direkte til en tjenesteadresse. Kundens administrator konfigurerer betalingssiden, fra betalingsløsninger til den merkede kassen. Programtillegget ditt gjør det ikke.
Matrisen
| Byggmål | Bygg mot | Hva du gjør annerledes | Hvordan det når kunden |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Kode i GitHub; ingen domenepakke- eller plattformstier; ingen Elevate | Kunden installerer det; ingen katalogvurdering nødvendig |
| Enterprise (din egen installasjon) | Plugin SDK, Skills Engine, pakkemaler | Utviklingsområder, datagrener, maskerte kopier hos dataeieren; pakker og linser | Promotering fra testmiljø til en pilotenhet, deretter overalt |
| Enterprise-modul (lukket) | Kun @adverant/nexus-spi |
Lisensgrenseregel; tildelingssjekk på sin egen funksjonsgruppe; LICENCE_LOCKED når ikke berettiget |
Lastes inn av en Community-tjeneste ved oppstart, på lisensierte installasjoner |
| Begge utgaver | Plugin SDK | Sett sammen treet for hver utgave; npm ci, tester og produksjonsbygg i hver |
Én utgivelse per utgave |
| Team | Plugin SDK på en utgiverklynge | Kun eksempeldata; kun i skyen | Signert utgivelse, Adverant-vurdering, katalog |
| Luftgapet | Plugin SDK, @adverant/nexus-sovereign |
Forseglet bunt; nøkkel og sjekksum sendt separat; ingenting hentes ved installasjon | Signerte medier, verifisert, deretter installasjonens utgivelseskanaler |
| Nexus Edge | Innhold i oppdragspakke | Plasseringstabell, degraderte trinn, tester om bord, maskinvarekontroller | To av tre signaturer, inaktivt spor, slås på etter at tester er bestått |
| Egen merkevare | Plugin SDK | domains og branding i manifestet; intet Adverant-navn noe sted |
Som for Enterprise, på kundens eget domene |
Uansett mål skjer utrulling kun gjennom installasjonens utgivelseskanaler. Kapittel 2.28, Utgivelse av utvidelsen din, dekker disse kanalene. Kapittel 2.27, Byggscenarier, har en oppskrift for hver rad ovenfor.



