Version 1.0.0-alpha.1senaste
Kapitel 2.25
Bygga för varje utgåva
Vad som ändras när ett tillägg måste fungera i varje utgåva, på en luftgapad plats, på en Nexus Edge-nyttolast eller bakom en kunds eget varumärke. Omfattar licensgränsen för Enterprise-moduler och signerad offlineleverans, med en matris över vad som ska göras annorlunda för varje mål.
Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

På Corrán Orbital levererar vi till fler platser än vad de flesta team kommer att göra. Våra egna ingenjörer kör Enterprise på marken. En satellit, CORR-3, kör ett uppdragspaket på Nexus Edge. Två kunder kör Community på en enskild server, en kör en luftgapad Enterprise-installation som aldrig ser internet, och vi har byggt ett paket åt ett försäkringsbolag på deras egen installation. Koden under ytan är i stort sett densamma, och skillnaderna handlar mest om var den får köras och hur den tar sig dit.
Det här kapitlet går igenom varje mål i tur och ordning: vad ni bygger mot, vad ni inte får röra och hur resultatet når kunden. En matris i slutet samlar allt på en sida. Kapitel 2.18, Utökningsmodellen, förklarar hur färdigheter, insticksprogram, paket och moduler skiljer sig åt. Kapitel 2.2, Utgåvorna under huven, beskriver själva utgåvorna.
Community och den öppna kärnan
Community är den öppna kärnan, under Apache License, Version 2.0. Ni kan förgrena den och leverera ändringar till den. Filen NOTICE som följer med säger en sak som är värd att känna till innan ni sätter ert varumärke på något: licensen ger inte rätt att använda Adverants namn eller varumärken utöver att ange var arbetet kommer ifrån.
Ni utökar Community på samma sätt som ni utökar Enterprise. Plugin SDK (programvaruutvecklingskit) är samma paket i båda utgåvorna, och varken fullservicemallen eller de 22 efterlevnadsgrindarna ändras; kapitel 2.21, Plugin SDK, behandlar detta. Färdigheter fungerar också. Community får hela skaparen och biblioteket i Skills Engine, med versioner och tester, medan kanarieutgåvor och godkännande av två personer förblir hos Enterprise.
Utvecklarsidorna i Community erbjuder samma gyllene vägar med tre skillnader som ni märker direkt:
- Er kod ligger i GitHub i stället för i installationens egna arkiv. Den gyllene vägen för insticksprogram skapar ett GitHub-arkiv och en utvecklingsmiljö utifrån samma låsta mall som Enterprise använder; skärm DV18 visar hur den skapar
room-bookings. - De gyllene vägarna för domänpaket och plattform tillhör Enterprise. I Community bygger ni insticksprogram och färdigheter, samt linser och arbetsflöden ovanpå det ni kör.
- Community-pass stannar under nivån Elevate. På en enskild server finns ingen produktionsmiljö att nå från en IDE (integrerad utvecklingsmiljö), och ni administrerar servern direkt. Ett försök från en IDE nekas med
PASS_TIER_REQUIRED.
En utvecklingsmiljö för Community på en liten server är blygsam. Vår hade 2 kärnor och 8 GiB minne, var stängd förutom det som manifestet deklarerar och avslutades efter 7 inaktiva dagar.
Bidra tillbaka
Skills Engine är också licensierad under Apache-2.0 och tar emot bidrag på vanligt sätt. Förgrena arkivet, skapa en gren från main, gör ändringen med tillhörande tester och kör kontrollerna innan ni öppnar en pull-begäran:
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheckEtt bidrag som ändrar beteendet kräver ett test som misslyckas utan det. Det är inte en intern stilregel: SDK:ts egna testregler säger att varje nytt test måste visas misslyckas i trädet före ändringen, och granskare ber om bevis på detta.
Enterprise-moduler och licensgränsen
Enterprise är Community plus licensierade moduler. En licensierad modul är en separat artefakt som en Community-tjänst läser in när den startar, och det är så Enterprise-funktioner, och alla slutna moduler ni bygger för Enterprise-kunder, kopplas till den öppna kärnan.
Regeln som får detta att fungera är licensgränsen. En sluten modul får nå Community-utgåvan genom ett enda paket, @adverant/nexus-spi, gränssnittet för tjänsteleverantörer. Det är licensierat under Apache-2.0 och innehåller gränssnitt samt de typvakter som en värd och en modul använder för att kontrollera varandra, utan någon annan körningslogik. Koppling över gränsen sker via ett gränssnitt eller ett nätverksprotokoll, aldrig via källkod.
| Export | Vad det är |
|---|---|
RouteModule |
En licensierad ruttmodul: id, featureGroup, bodies och register(app, ctx), som monterar sina routrar på värdens applikation |
SpiApp |
Den del av värdens HTTP-applikation som en modul berör: use |
SpiContext |
Vad värden lämnar över till en modul: produktgrinden och omfångsvakten, licensläsaren, poolen för omfångsbegränsade frågor, tjänstens schema, uppströmsadresserna och plattformsklienterna |
SpiRuntime |
Värdena från Plugin SDK som en värd lämnar över till en modul, så att modulen aldrig själv importerar SDK:ts körningsmiljö |
SpiPlane |
Vad ett licensierat plan lägger till utöver rutter, såsom de skärmläsningar det betjänar |
ScreenModule |
En konsols licensierade skärmgrupp: group, featureGroup, routes, screens och menu |
GrantCheck |
(featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }> |
HTTP-ramverket och konsolens skärmtyp är typparametrar, så gränssnittet binder ingendera. Här är skelettet för en ruttmodul, med en hanterartyp för 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> är funktionsgruppen i utgåvematrisen som modulen betjänar. Varje licensierad rutt körs bakom ctx.requireScope, värdens produktgrind och omfångsvakt, och modulen kontrollerar även sin egen tilldelning innan den svarar. En modul som saknar berättigande nekar med LICENCE_LOCKED och ritar upp funktionens förhandsvisning, aldrig dess data. Er modul importerar heller aldrig körningsmiljön för Plugin SDK, eftersom SDK:t är ett Community-paket som gränsen inte tillåter. Värden lämnar över de SDK-värden som modulen anropar. Innan värden läser in någon modul installerar den en SpiHost på globalThis under Symbol.for(SPI_HOST_KEY), som innehåller SDK-körningsmiljön och applikationens eget ruttytyg. Det måste ske först: en modul som kompilerats till ett enda paket utvärderas som en helhet, och ett register-anrop skulle komma för sent för kod som läser SDK-värdena medan den läses in. För typer återexporterar @adverant/nexus-spi/sdk/<module> SDK:ts deklarationer, inkluderade oförändrade från en SDK-utgåva och låsta med kontrollsumma, så att er modul typkontrolleras mot samma nekandekroppar och klienter som ett insticksprogram använder.
En skärmmodul följer ytterligare en regel: en modul per funktionsgrupp, så en grupp vars skärmar tillhör två funktionsgrupper levereras som två moduler, och bara en av dem bär menyraden.
Vad licensgränsgrinden nekar
Adverants licensgränsgrind håller varje Enterprise-modul på rätt sida av gränsen, och det är värt att hålla era egna slutna moduler till samma regel. Dess konfiguration består av en enda fil:
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}Var och en av dessa ger en träff med angivande av fil och rad:
- varje import av ett paket under ett Community-omfång som inte är det tillåtna gränssnittet eller ett Enterprise-paket, inklusive dynamiska importer;
- varje specificerare, Go-importsökväg eller beroende-URL som namnger ett Community-arkiv, såvida det inte är en Go-modul som listas i
allowedCommunityGoModules; - en relativ import som klättrar ut ur arkivet;
- ett
package.json-beroende som är enfile:-,link:-,portal:- ellerworkspace:-sökväg utanför arkivet, eller en Git-URL till ett Community-arkiv; - en
go.modreplacesom pekar utanför arkivet.
Den avslutar med kod 0 när allt är rent och 1 vid träffar. Avslutningskod 2 betyder att den nekade, eftersom konfigurationen var felaktig eller för att den inte skannade någonting. Gränssnittspaketet publiceras inte till något register. Ni har med er en bytelåst kopia av det byggda paketet inuti ert arkiv som ett lokalt file:-paket, med en SHA256SUMS-låsning och en kontroll i er pipeline som nekar en kopia som avviker. Eftersom kopian finns inuti arkivet godkänner grinden den.
Byggen för olika utgåvor
Om er utökning levereras till kunder på båda utgåvorna bygger ni den en gång per utgåva, och varje bygge sker i sitt eget sammansatta träd. Att sätta samman ett träd innebär att man bara tar med de filer som tillhör den utgåvan. Adverants egen export gör detta utifrån en gränslista där varje spårad fil tilldelas enligt regeln att första träffen vinner: en regel namnger en kapabilitet och filens utgåva följer av den kapabilitetens nivå i utgåvematrisen, eller så namnger den en klass av filer som inte levereras i någon av utgåvorna, med en angiven orsak. Filer som enbart används vid bygge levereras i Enterprise-trädet och, när de är markerade, även i Community-trädet. En moduls migreringskedja är installationsdata och levereras i varje utgåvas träd.
Kör sedan hela bygget från grunden i varje sammansatt träd. Det innebär alla tre kommandon, varje gång:
npm ci
npm test
npm run buildVi lärde oss detta den dyra vägen: ett Enterprise-träd klarade sina tester medan Community-trädet misslyckades i sitt produktionsbygge, eftersom en typ det behövde bara fanns i en Enterprise-fil. Att testerna går igenom i det ena trädet säger ingenting om det andra. En utgåvas tester får bara importera det som finns i den utgåvans träd, och exporten nekar ett test som sträcker sig utanför det.
Exporten skriver också varje utgåvas licens. Community-filer bär SPDX-identifieraren (Software Package Data Exchange) Apache-2.0; Enterprise-filer bär LicenseRef-Adverant-Enterprise och deras package.json anger UNLICENSED. Redigera inte dessa fält för hand: exporten skriver om dem, och en kopia som inte längre stämmer överens med sin låsta licenstext nekas.
Team: endast moln
Team är Community plus Team-uppsättningen, och det körs endast i Adverant-molnet. Det finns inget Team för egen drift. Team-uppsättningen lägger till sex kapabiliteter ovanpå Community, däribland den samlade arbetspanelen, delade anteckningsböcker, administration av färdighetsbibliotek samt arbetsflödesdrift med befordran mellan miljöer.
För en utvecklare innebär endast molndrift en sak: en Team-kund får ert insticksprogram som en signerad utgåva via katalogen, aldrig från era egna servrar. Ni bygger det på samma sätt som en extern utgivare bygger, på ett utgivarkluster.
Ett utgivarkluster är ett virtuellt kluster i Adverant-molnet med en kvot som fastställts av Adverant. Det innehåller enbart exempeldata och har ingen rutt till någon kund. Att be om en maskerad kopia av en kunds data där nekas med TENANT_BOUNDARY; en kund kan dela testresultat med er, men aldrig sina data. Ert pass där når aldrig in till en kund. När utgåvan är klar signeras och granskas den av Adverant innan den listas i katalogen. Varje kund väljer sedan om de vill installera den och beviljar den endast det som dess manifest deklarerar, enhet för enhet. Ett anrop till något som manifestet inte deklarerat nekas hos kunden med CONNECTION_SCOPE_EXCEEDED, och det enda sättet att lägga till det är genom en ny utgåva som kunden granskar.
Luftgapade kunder
En av våra kunder kör Nexus där ingenting går in eller ut över ett nätverk. Deras installation beskrivs i kapitel 2.10, Luftgapad installation. För oss innebar det att leverera vårt insticksprogram på signerade medier, och verktyget för detta är nexus-airgap, från det suveräna leveranspaketet @adverant/nexus-sovereign.
Ett förseglat paket är en enda signerad, fristående tarball-fil. Det kan innehålla avbildningar och migreringar, försignerade färdigheter och modellvikter, samt en SBOM (programvaruförteckning) med licenserna för allt innehåll. Dess manifest listar varje fil med dess SHA-256 och är signerat med Ed25519. Att bygga ett från kod ser ut så här:
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 är er signeringsnyckel för utgåvor. Kommandot nexus-airgap bundle gör samma sak från kommandoraden. Kundens operatör kontrollerar det sedan före allt annat:
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgapVerifieringen beräknar om hashen för varje fil mot manifestet, avvisar alla filer som manifestet inte listar, kräver en betrodd Ed25519-undertecknare och nekar alla paket vars tillåtelselista för nätverk inte är tom. En fil som ändrats efter signering misslyckas med BUNDLE_INTEGRITY_VIOLATION. Be operatören att stanna där och ringa er; det finns en icke-strikt växel, och de bör aldrig använda den.
Tre regler bar vår leverans:
- Den betrodda nyckeln färdas separat från paketet. Vi skickar den publika nyckeln och paketets SHA-256 via en annan väg än mediet, så att ett paket inte kan gå i god för sig självt.
- Ingenting i paketet får kräva nätverket vid installation. Ingen pakethämtning, ingen modellnedladdning, inget licensanrop. Om insticksprogrammet behöver en modell tillhandahåller kundens egen modellserver den genom AI (artificiell intelligens) Provider Router.
- Efter verifieringen tar operatören in utgåvan genom installationens egna utgåvekanaler, precis som en uppkopplad kund skulle göra. Paketet är sättet som byten anländer på, inte en genväg förbi befordringsgrindarna.
Luftgapat arbete är långsammare, och det går inte att åtgärda från vår sida. En felaktig byte kostar en ny uppsättning medier och ännu en resa, så vi verifierar paketet själva på en ren maskin med samma kommando innan det lämnar byggnaden.
Nexus Edge-uppdragspaket
Nexus Edge är ett mindre Nexus som körs på satelliter och drönare, på uppdragsdatorer som hålls åtskilda från flygdatorn. Det är ett tillägg med en licens per plattform eller flotta. Det som ändras från ett uppdrag till nästa är uppdragspaketet, och att bygga sådana är en stor del av mitt jobb.
Ett uppdragspaket bär det som nyttolasten behöver för ett uppdrag. Utöver sina modeller och adaptrar innehåller det ontologin med en startgraf, agentsteg, larmregler, prioriteringarna för vad som skickas ner först, en placeringstabell som anger vilken dator som kör vad, de degraderade steg som plattformen kan falla tillbaka till när en dator går sönder, samt de testfall det måste klara ombord.
Paket byggs och signeras på marken. Några praktiska regler från våra byggen:
- Håll de stora delarna stabila. Maritime watch 1.5 lade till en adapter för fartygssökning och två larmregler; språkmodellen och ontologin ändrades inte, så paketet blev 412 MB i stället för 9.8 GB. Upplänken är smal och basmodeller läses in före uppskjutning.
- Använd en och samma inbäddningsmodell för hela uppdragsfamiljen på såväl marken som i nyttolasten, så att de grafändringar som skickas ner kan slås samman med markgrafen.
- Nyttolasten skickar aldrig ett kommando till flygsystemen. Den skickar typade förfrågningar via övervakaren till flygdatorn, som besvarar var och en med en orsak.
- Varje hårdvarutyp kräver en egen kontroll av paketet. Att installera ett paket som inte har kontrollerats för en enhets hårdvara nekas med
PACK_NOT_CHECKED_FOR_HARDWARE.
En utgåva kräver två av tre signaturer. Vår och Adverants är det vanliga paret, och den tredje är en offlinenyckel som vi förvarar i ett kassaskåp ifall en av de andra två skulle förloras. Paketet laddas upp till den inaktiva platsen, verifieras, kör sina testfall på de faktiska korten och aktiveras endast om alla godkänns, med en räknare som förhindrar att ett äldre paket installeras på nytt. Om ett test misslyckas stannar plattformen kvar på det föregående paketet och felet skickas ner vid nästa passage. Vi rullar ut en plattform i taget, var och en efter en felfri vecka. Paket förblir giltiga medan en plattform är utan kontakt, så en satellit utan länk fortsätter att arbeta med det paket den har.
På fordon och fartyg kan Edge köras på k3s. En rymdfarkost kör en övervakare med signerade avbildningar eller statiska binärfiler och en fast placeringstabell i stället för Kubernetes, och det är därför placeringstabellen följer med inuti paketet.
White-label-butiker
Tillägget Storefront / white-label låter en kund sätta sitt eget varumärke och sin egen domän på det som deras användare ser, med egna inloggningsskärmar, och ta betalt via sina egna betalväxlar. Kortuppgifter rör aldrig Nexus.
Ett insticksprogram som byggts för en white-label-kund får aldrig visa Adverant. Manifestet bär allt som är varumärkesspecifikt, och plattformen löser ut resten från organisationens eget varumärke i stället för från något som är hårdkodat i er kod:
{
"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> är kundens egen domän, och passkeyRpId måste matcha den, eftersom lösenordsnycklar är bundna till den domän en person loggar in på. En webbapplikation på sitt eget ursprung loggar in personer genom SDK:ts inloggningshjälpare, vars två publika rutter är de enda oskyddade /api-rutter som omfångsgrinden accepterar, och endast när manifestet deklarerar dem som auth: public med allowAnonymous: true. Frontend-anrop går genom backend-proxyn med tillåtelselista för frontend, aldrig direkt till en tjänsteadress. Kundens administratör konfigurerar betalningssidan, från betalväxlar till den varumärkesanpassade kassan. Ert insticksprogram gör det inte.
Matrisen
| Byggmål | Bygg mot | Vad ni gör annorlunda | Hur det når kunden |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Kod i GitHub; inga domänpaket- eller plattformsvägar; ingen Elevate | Kunden installerar det; ingen kataloggranskning behövs |
| Enterprise (er egen installation) | Plugin SDK, Skills Engine, paketmallar | Utvecklingsmiljöer, datagrenar, maskerade kopior hos dataägaren; paket och linser | Befordran från staging till en pilotenhet, sedan överallt |
| Enterprise-modul (sluten) | Endast @adverant/nexus-spi |
Licensgränsregel; tilldelningskontroll på den egna funktionsgruppen; LICENCE_LOCKED när berättigande saknas |
Läses in av en Community-tjänst vid start, på licensierade installationer |
| Båda utgåvorna | Plugin SDK | Sätt samman varje utgåvas träd; npm ci, tester och produktionsbygge i vardera |
En version per utgåva |
| Team | Plugin SDK på ett utgivarkluster | Endast exempeldata; endast moln | Signerad utgåva, granskning av Adverant, katalog |
| Luftgapad | Plugin SDK, @adverant/nexus-sovereign |
Förseglat paket; nyckel och kontrollsumma skickas separat; ingenting hämtas vid installation | Signerade medier, verifierade, därefter installationens utgåvekanaler |
| Nexus Edge | Innehåll i uppdragspaket | Placeringstabell, degraderade steg, tester ombord, hårdvarukontroller | Två av tre signaturer, inaktiv plats, aktiveras efter godkända tester |
| White label | Plugin SDK | domains och branding i manifestet; inget Adverant-namn någonstans |
Som för Enterprise, på kundens egen domän |
Oavsett mål sker driftsättning enbart genom installationens utgåvekanaler. Kapitel 2.28, Släppa er utökning, behandlar dessa kanaler. Kapitel 2.27, Byggscenarier, har ett recept för varje rad ovan.



