Versie 1.0.0-alpha.1nieuwste
Hoofdstuk 2.25
Bouwen voor elke editie
Wat er verandert wanneer één extensie moet werken in elke editie, op een air-gapped locatie, op een Nexus Edge-payload of achter het eigen merk van een klant. Behandelt de licentiegrens voor Enterprise-modules en ondertekende offline levering, met een matrix van wat u voor elk doel anders moet doen.
Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

Bij Corrán Orbital leveren we aan meer plaatsen dan de meeste teams ooit zullen doen. Onze eigen engineers draaien Enterprise op de grond. Een satelliet, CORR-3, draait een missiepakket op Nexus Edge. Twee klanten draaien Community op een enkele server, één draait een air-gapped Enterprise-installatie die nooit het internet ziet, en we hebben een pakket gebouwd voor een verzekeraar op hun eigen installatie. De onderliggende code is grotendeels hetzelfde, en de verschillen gaan vooral over waar de code naartoe mag en hoe die daar komt.
Dit hoofdstuk behandelt elk doel om de beurt: waartegen u bouwt, waar u niet aan mag komen en hoe het resultaat de klant bereikt. Een matrix aan het einde zet alles op één pagina. Hoofdstuk 2.18, Het uitbreidingsmodel, legt uit waarin vaardigheden, plug-ins, pakketten en modules van elkaar verschillen. Hoofdstuk 2.2, Edities onder de motorkap, beschrijft de edities zelf.
Community en de open core
Community is de open core, onder de Apache License, Version 2.0. U kunt deze forken en er wijzigingen aan leveren. Het NOTICE-bestand dat ermee meereist, vermeldt één ding dat goed is om te weten voordat u ergens uw merk op zet: de licentie verleent geen recht op gebruik van de namen of handelsmerken van Adverant, behalve om te vermelden waar het werk vandaan komt.
U breidt Community uit op dezelfde manier als Enterprise. De Plugin SDK (software development kit) is op beide edities hetzelfde pakket, en noch de full-service-template noch de 22 nalevingspoorten veranderen; hoofdstuk 2.21, De Plugin SDK, behandelt dit. Vaardigheden werken ook. Community krijgt de volledige maker en bibliotheek van de Skills Engine, met versies en tests, terwijl canary-releases en goedkeuring door twee personen bij Enterprise blijven.
De ontwikkelaarspagina's op Community bieden dezelfde golden paths, met drie verschillen die u meteen zult merken:
- Uw code staat in GitHub in plaats van in de eigen repositories van de installatie. Het golden path voor plug-ins maakt een GitHub-repository en een ontwikkelomgeving op basis van dezelfde vastgepinde template die Enterprise gebruikt; scherm DV18 laat zien hoe het
room-bookingsaanmaakt. - De golden paths voor domeinpakketten en het platform zijn voor Enterprise. Op Community bouwt u plug-ins en vaardigheden, plus lenzen en workflows op wat u draait.
- Community-passen stoppen onder het Elevate-niveau. Op één server is er geen productieomgeving om vanuit een IDE (integrated development environment) te bereiken, en beheert u de server rechtstreeks. Een poging vanuit de IDE wordt geweigerd met
PASS_TIER_REQUIRED.
Een Community-ontwikkelomgeving op een kleine server is bescheiden. De onze had 2 cores en 8 GiB geheugen, was gesloten behalve voor wat het manifest declareert, en werd na 7 inactieve dagen beëindigd.
Terugbijdragen
De Skills Engine valt ook onder Apache-2.0 en accepteert bijdragen op de gebruikelijke manier. Fork de repository, maak een branch vanaf main, breng de wijziging aan inclusief de bijbehorende tests, en voer de controles uit voordat u een pull request opent:
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheckEen bijdrage die het gedrag verandert, heeft een test nodig die zonder die bijdrage faalt. Dat is geen huisstijl: de eigen testregels van de SDK bepalen dat van elke nieuwe test moet worden aangetoond dat deze op de boom faalt vóór de wijziging, en reviewers vragen om het bewijs.
Enterprise-modules en de licentiegrens
Enterprise is Community plus gelicentieerde modules. Een gelicentieerde module is een afzonderlijk artefact dat een Community-service bij het starten laadt, en zo worden Enterprise-functies, en elke gesloten module die u voor Enterprise-klanten bouwt, aan de open core gekoppeld.
De regel die dit mogelijk maakt, is de licentiegrens. Een gesloten module mag de Community-editie slechts via één pakket bereiken: @adverant/nexus-spi, de service provider interface. Deze valt onder Apache-2.0 en bevat interfaces plus de type guards die een host en een module gebruiken om elkaar te controleren, zonder andere runtime-logica. Koppeling over de grens heen gebeurt via een interface of een netwerkprotocol, nooit via broncode.
| Export | Wat het is |
|---|---|
RouteModule |
Een gelicentieerde routemodule: id, featureGroup, bodies en register(app, ctx), die haar routers koppelt aan de app van de host |
SpiApp |
Het deel van de HTTP-app van de host dat door een module wordt aangesproken: use |
SpiContext |
Wat de host aan een module overhandigt: de productpoort en scopebewaker, de licentielezer, de scoped-query-pool, het schema van de service, de upstream-adressen en de platformclients |
SpiRuntime |
De waarden van de Plugin SDK die een host aan een module overhandigt, zodat de module nooit zelf de runtime van de SDK importeert |
SpiPlane |
Wat een gelicentieerd vlak toevoegt naast routes, zoals de schermuitlezingen die het bedient |
ScreenModule |
De gelicentieerde schermgroep van een console: group, featureGroup, routes, screens en menu |
GrantCheck |
(featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }> |
Het HTTP-framework en het schermtype van de console zijn typeparameters, zodat de interface geen van beide vastlegt. Hier is het raamwerk van een routemodule, met een Express-handlertype:
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> is de functiegroep uit de editiematrix die de module bedient. Elke gelicentieerde route draait achter ctx.requireScope, de productpoort en scopebewaker van de host, en de module controleert ook haar eigen toekenning voordat ze antwoordt. Een module die geen recht heeft, weigert met LICENCE_LOCKED en toont de teaser van de functie, nooit de gegevens ervan. Uw module importeert ook nooit de runtime van de Plugin SDK, omdat de SDK een Community-pakket is dat niet over de grens wordt toegelaten. De host overhandigt haar de SDK-waarden die ze aanroept. Voordat de host een module laadt, installeert deze een SpiHost op globalThis onder Symbol.for(SPI_HOST_KEY), met daarin de SDK-runtime en de eigen routekit van de app. Dit moet eerst gebeuren: een module die tot één bundel is gecompileerd, wordt als geheel geëvalueerd, en een aanroep van register zou te laat komen voor code die de SDK-waarden tijdens het laden uitleest. Voor typen exporteert @adverant/nexus-spi/sdk/<module> de declaraties van de SDK opnieuw, ongewijzigd meegeleverd vanuit één SDK-release en vastgepind met een checksum, zodat uw module typecontroles uitvoert tegen dezelfde weigeringsberichten en clients die een plug-in gebruikt.
Een schermmodule volgt nog één regel: één module per functiegroep, zodat een groep waarvan de schermen tot twee functiegroepen behoren als twee modules wordt geleverd, en slechts één daarvan de menurij bevat.
Wat de licentiegrens-poort weigert
De licentiegrens-poort van Adverant houdt elke Enterprise-module aan de grens, en het loont de moeite om uw eigen gesloten modules aan dezelfde regel te houden. De configuratie ervan bestaat uit één bestand:
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}Elk van de volgende punten levert een bevinding op met het bijbehorende bestand en regelnummer:
- elke import van een pakket onder een Community-scope dat niet de toegestane interface of een Enterprise-pakket is, inclusief dynamische imports;
- elke specifier, elk Go-importpad of elke dependency-URL die een Community-repository noemt, tenzij het een Go-module is die in
allowedCommunityGoModuleswordt vermeld; - een relatieve import die buiten de repository klimt;
- een
package.json-dependency die eenfile:-,link:-,portal:- ofworkspace:-pad buiten de repository is, of een Git-URL naar een Community-repository; - een
go.modreplacedie naar buiten de repository verwijst.
Het sluit af met 0 wanneer alles schoon is en met 1 bij bevindingen. Exitcode 2 betekent dat het heeft geweigerd, omdat de configuratie foutief was of omdat er niets is gescand. Het interfacepakket wordt niet naar een registry gepubliceerd. U neemt een op byte-niveau vastgepinde kopie van het gebouwde pakket mee in uw repository als een lokaal file:-pakket, met een SHA256SUMS-pin en een controle in uw pipeline die een afwijkende kopie weigert. Omdat de kopie zich binnen de repository bevindt, accepteert de poort deze.
Editie-builds
Als uw uitbreiding wordt geleverd aan klanten op beide edities, bouwt u deze één keer per editie, en vindt elke build plaats in zijn eigen samengestelde boom. Het samenstellen van een boom betekent dat alleen de bestanden worden meegenomen die bij die editie horen. De eigen export van Adverant doet dit aan de hand van een grenslijst waarin elk gevolgd bestand wordt toegewezen volgens 'first-match-wins'-regels: een regel noemt een mogelijkheid en de editie van het bestand volgt uit het niveau van die mogelijkheid in de editiematrix, of de regel noemt een klasse van bestanden die in geen van beide edities wordt geleverd, met een reden. Bestanden die alleen voor de build zijn, worden geleverd in de Enterprise-boom en, indien gemarkeerd, ook in de Community-boom. De migratieketen van een module bestaat uit installatiegegevens en wordt geleverd in de boom van elke editie.
Voer vervolgens in elke samengestelde boom de volledige build vanaf nul uit. Dat betekent alle drie de opdrachten, elke keer:
npm ci
npm test
npm run buildWe hebben dit op de dure manier geleerd: een Enterprise-boom slaagde voor zijn tests terwijl de Community-boom faalde bij zijn productiebuild, omdat een benodigd type alleen in een Enterprise-bestand stond. Tests die in de ene boom slagen, zeggen niets over de andere. De tests van een editie mogen alleen importeren wat de boom van die editie bevat, en de export weigert een test die daarbuiten reikt.
De export schrijft ook de licentie van elke editie. Community-bestanden dragen de SPDX-identifier (Software Package Data Exchange) Apache-2.0; Enterprise-bestanden dragen LicenseRef-Adverant-Enterprise en hun package.json vermeldt UNLICENSED. Bewerk die velden niet met de hand: de export overschrijft ze, en een kopie die niet langer overeenkomt met de vastgepinde licentietekst wordt geweigerd.
Team: alleen cloud
Team is Community plus de Team-set, en draait uitsluitend op de Adverant-cloud. Er is geen zelfgehoste Team. De Team-set voegt zes mogelijkheden toe boven op Community, waaronder het geconsolideerde werkpaneel, gedeelde notebooks, beheer van de vaardighedenbibliotheek en workflow-operaties met promotie tussen omgevingen.
Voor een bouwer betekent 'uitsluitend in de cloud' maar één ding: een Team-klant krijgt uw plug-in als een ondertekende release via de catalogus, nooit vanaf uw eigen servers. U bouwt deze zoals een externe uitgever dat doet, op een uitgeverscluster.
Een uitgeverscluster is een virtueel cluster op de Adverant-cloud met een door Adverant ingesteld quotum. Het bevat uitsluitend voorbeeldgegevens en heeft geen route naar welke klant dan ook. Daar vragen om een gemaskeerde kopie van de gegevens van een klant wordt geweigerd met TENANT_BOUNDARY; een klant kan testresultaten met u delen, nooit zijn gegevens. Uw pas op dit cluster reikt nooit tot bij een klant. Wanneer de release klaar is, wordt deze ondertekend en beoordeeld door Adverant voordat deze in de catalogus wordt opgenomen. Elke klant kiest vervolgens zelf of hij deze installeert en verleent alleen wat het manifest declareert, eenheid voor eenheid. Een aanroep naar iets wat het manifest niet heeft gedeclareerd, wordt aan de kant van de klant geweigerd met CONNECTION_SCOPE_EXCEEDED, en de enige manier om dit toe te voegen is een nieuwe release die door de klant wordt beoordeeld.
Air-gapped klanten
Eén van onze klanten draait Nexus op een plek waar niets via een netwerk in of uit gaat. Hun installatie wordt beschreven in hoofdstuk 2.10, Air-gapped installatie. Voor ons betekende dit dat we onze plug-in op ondertekende media moesten leveren, en de tool daarvoor is nexus-airgap, uit de sovereign delivery kit @adverant/nexus-sovereign.
Een verzegelde bundel is één ondertekende, op zichzelf staande tarball. Deze kan images en migraties bevatten, vooraf ondertekende vaardigheden en modelgewichten, en een SBOM (software bill of materials) met de licenties van alles wat erin zit. Het manifest vermeldt elk bestand met zijn SHA-256 en is ondertekend met Ed25519. Het bouwen ervan vanuit code ziet er als volgt uit:
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 is uw ondertekeningssleutel voor releases. De opdracht nexus-airgap bundle doet hetzelfde vanaf de opdrachtregel. De operator van de klant controleert de bundel vervolgens vóór al het andere:
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgapVerificatie berekent voor elk bestand opnieuw de hash aan de hand van het manifest, wijst elk bestand af dat niet in het manifest staat, vereist een vertrouwde Ed25519-ondertekenaar, en weigert elke bundel waarvan de netwerk-allowlist niet leeg is. Een bestand dat na ondertekening is gewijzigd, faalt met BUNDLE_INTEGRITY_VIOLATION. Zeg tegen de operator dat hij daar moet stoppen en u moet bellen; er bestaat een niet-strikte optie, en die mogen ze nooit gebruiken.
Drie regels bepaalden onze levering:
- De vertrouwde sleutel reist gescheiden van de bundel. We sturen de publieke sleutel en de SHA-256 van de bundel via een andere route dan de media, zodat een bundel niet voor zichzelf kan instaan.
- Niets in de bundel mag bij de installatie het netwerk nodig hebben. Geen pakket ophalen, geen model downloaden, geen licentie-aanroep. Als de plug-in een model nodig heeft, levert de eigen modelserver van de klant dat via de AI (artificial intelligence) Provider Router.
- Na verificatie brengt de operator de release binnen via de eigen releasekanalen van de installatie, precies zoals een verbonden klant zou doen. De bundel is de manier waarop de bytes aankomen, geen manier om de promotiepoorten te omzeilen.
Air-gapped werk gaat langzamer, en daar valt van onze kant niets aan te veranderen. Een verkeerde byte kost een nieuwe set media en nog een reis, dus verifiëren we de bundel zelf op een schone machine met dezelfde opdracht voordat deze het gebouw verlaat.
Nexus Edge-missiepakketten
Nexus Edge is een kleinere Nexus die draait op satellieten en drones, op missiecomputers die gescheiden worden gehouden van de vluchtcomputer. Het is een add-on met een licentie per platform of vloot. Wat van de ene missie op de andere verandert, is het missiepakket, en het bouwen daarvan is een flink deel van mijn werk.
Een missiepakket bevat wat de payload nodig heeft voor één missie. Naast de modellen en adapters bevat het de ontologie met een startgraaf, agentstappen, waarschuwingsregels, de prioriteiten voor wat als eerste naar beneden wordt gestuurd, een plaatsingstabel die aangeeft welke computer wat draait, de gedegradeerde stappen waarnaar het platform kan terugvallen wanneer een computer uitvalt, en de testcases waarvoor het aan boord moet slagen.
Pakketten worden op de grond gebouwd en ondertekend. Enkele praktische regels uit onze builds:
- Houd de grote onderdelen stabiel. Maritime watch 1.5 voegde een scheepszoeker-adapter en twee waarschuwingsregels toe; het taalmodel en de ontologie veranderden niet, waardoor het pakket 412 MB was in plaats van 9.8 GB. De uplink is smal, en basismodellen worden vóór de lancering geladen.
- Gebruik één embedding-model voor de hele missiefamilie, zowel op de grond als op de payload, zodat de graafwijzigingen die naar beneden komen kunnen worden samengevoegd met de grondgraaf.
- De payload stuurt nooit een opdracht naar de vluchtsystemen. Hij stuurt getypeerde verzoeken via de supervisor naar de vluchtcomputer, die elk verzoek met een reden beantwoordt.
- Elk hardwaretype heeft zijn eigen controle van het pakket nodig. Het installeren van een pakket dat niet is gecontroleerd voor de hardware van een apparaat, wordt geweigerd met
PACK_NOT_CHECKED_FOR_HARDWARE.
Vrijgave vereist twee van de drie handtekeningen. Die van ons en die van Adverant vormen het gebruikelijke paar, en de derde is een offlinesleutel die we in een kluis bewaren voor het geval één van de andere twee verloren gaat. Het pakket gaat omhoog naar het inactieve slot, wordt geverifieerd, voert zijn testcases uit op de echte borden, en wordt alleen ingeschakeld als ze allemaal slagen, met een teller die voorkomt dat een ouder pakket opnieuw wordt geïnstalleerd. Als een test faalt, blijft het platform op het vorige pakket en komt de fout bij de volgende passage naar beneden. We rollen één platform tegelijk uit, elk na een foutloze week. Pakketten blijven geldig terwijl een platform buiten bereik is, zodat een satelliet zonder verbinding blijft doorwerken op het pakket dat hij heeft.
Op voertuigen en vaartuigen kan Edge op k3s draaien. Een ruimtevaartuig draait een supervisor met ondertekende images of statische binaries en een vaste plaatsingstabel in plaats van Kubernetes, en daarom reist de plaatsingstabel mee in het pakket.
White-label-etalages
Met de add-on Storefront / white-label kan een klant zijn eigen merk en domein zetten op wat zijn gebruikers zien, met zijn eigen aanmeldschermen, en betalingen ontvangen via zijn eigen gateways. Kaartgegevens raken Nexus nooit.
Een plug-in die is gebouwd voor een white-label-klant mag nooit Adverant tonen. Het manifest bevat alles wat merkspecifiek is, en het platform haalt de rest op uit het eigen merk van de organisatie in plaats van uit iets wat hard in uw code is vastgelegd:
{
"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> is het eigen domein van de klant, en passkeyRpId moet daarmee overeenkomen, omdat passkeys gebonden zijn aan het domein waarop iemand zich aanmeldt. Een webapp op een eigen origin meldt mensen aan via de aanmeldhelpers van de SDK, waarvan de twee openbare routes de enige onbewaakte /api-routes zijn die de scopepoort accepteert, en alleen wanneer het manifest ze als auth: public declareert met allowAnonymous: true. Frontend-aanroepen lopen via de backend-for-frontend-allowlist-proxy, nooit rechtstreeks naar een serviceadres. De beheerder van de klant configureert de betalingskant, van gateways tot de checkout in eigen huisstijl. Uw plug-in doet dat niet.
De matrix
| Bouwdoel | Bouwen tegen | Wat u anders doet | Hoe het de klant bereikt |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Code in GitHub; geen domeinpakket- of platformpaden; geen Elevate | De klant installeert het; geen catalogusbeoordeling nodig |
| Enterprise (uw eigen installatie) | Plugin SDK, Skills Engine, pakket-templates | Ontwikkelomgevingen, datatakken, gemaskeerde kopieën met de data-eigenaar; pakketten en lenzen | Promotie van staging naar een piloteenheid, daarna overal |
| Enterprise-module (gesloten) | Alleen @adverant/nexus-spi |
Licentiegrens-regel; toekenningscontrole op de eigen functiegroep; LICENCE_LOCKED indien niet gerechtigd |
Geladen door een Community-service bij het starten, op gelicentieerde installaties |
| Beide edities | Plugin SDK | Boom van elke editie samenstellen; npm ci, tests en productiebuild in elk |
Eén release per editie |
| Team | Plugin SDK op een uitgeverscluster | Alleen voorbeeldgegevens; alleen cloud | Ondertekende release, beoordeling door Adverant, catalogus |
| Air-gapped | Plugin SDK, @adverant/nexus-sovereign |
Verzegelde bundel; sleutel en checksum apart verzonden; niets opgehaald bij installatie | Ondertekende media, geverifieerd, daarna de releasekanalen van de installatie |
| Nexus Edge | Inhoud missiepakket | Plaatsingstabel, gedegradeerde stappen, tests aan boord, hardwarecontroles | Twee van drie handtekeningen, inactief slot, ingeschakeld nadat tests slagen |
| White-label | Plugin SDK | domains en branding in het manifest; nergens de naam Adverant |
Zoals voor Enterprise, op het eigen domein van de klant |
Wat het doel ook is, uitrollen gebeurt uitsluitend via de releasekanalen van de installatie. Hoofdstuk 2.28, Uw uitbreiding vrijgeven, behandelt die kanalen. Hoofdstuk 2.27, Bouwscenario's, bevat een recept voor elke rij hierboven.



