Versiune 1.0.0-alpha.1cea mai recentă
Capitolul 2.25
Construirea pentru fiecare ediție
Ce se schimbă atunci când o extensie trebuie să funcționeze în fiecare ediție, pe un amplasament izolat de rețea (air-gapped), pe o încărcătură utilă Nexus Edge sau sub propria marcă a unui client. Acoperă linia de licențiere pentru modulele Enterprise și livrarea offline semnată, cu o matrice a ceea ce trebuie făcut diferit pentru fiecare destinație.
Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

La Corrán Orbital livrăm în mai multe locuri decât o vor face cele mai multe echipe. Propriii noștri ingineri rulează Enterprise la sol. Un satelit, CORR-3, rulează un pachet de misiune pe Nexus Edge. Doi clienți rulează Community pe un singur server, unul rulează o instalare Enterprise izolată (air-gapped) care nu vede niciodată internetul, iar noi am construit un pachet pentru un asigurător pe propria sa instalare. Codul de dedesubt este în mare parte același, iar diferențele țin în mare parte de locul în care are voie să ajungă și de modul în care ajunge acolo.
Acest capitol parcurge pe rând fiecare țintă: pe ce construiți, ce nu aveți voie să atingeți și cum ajunge rezultatul la client. O matrice de la final reunește totul pe o singură pagină. Capitolul 2.18, Modelul de extensii, explică prin ce diferă abilitățile, pluginurile, pachetele și modulele. Capitolul 2.2, Edițiile în detaliu, descrie edițiile propriu-zise.
Community și nucleul deschis
Community este nucleul deschis, sub licența Apache License, Version 2.0. Îl puteți bifurca (fork) și puteți livra modificări ale acestuia. Fișierul NOTICE care îl însoțește spune un lucru demn de știut înainte de a aplica vreo marcă: licența nu acordă dreptul de utilizare a numelor sau a mărcilor comerciale Adverant dincolo de indicarea provenienței lucrării.
Extindeți Community în același mod în care extindeți Enterprise. Plugin SDK (kit de dezvoltare software) este același pachet în ambele ediții, iar nici șablonul de serviciu complet, nici cele 22 de porți de conformitate nu se modifică; capitolul 2.21, Plugin SDK, tratează acest subiect. Și abilitățile funcționează. Community primește întregul creator și întreaga bibliotecă ale Skills Engine, cu versiuni și teste, în timp ce lansările canary și aprobarea de către două persoane rămân în Enterprise.
Paginile pentru dezvoltatori din Community oferă aceleași căi standard (golden paths), cu trei diferențe pe care le veți resimți imediat:
- Codul dumneavoastră se află în GitHub, nu în depozitele proprii ale instalării. Calea standard pentru pluginuri creează un depozit GitHub și un spațiu de dezvoltare pornind de la același șablon fixat pe care îl folosește Enterprise; ecranul DV18 o arată creând
room-bookings. - Căile standard pentru pachete de domeniu și pentru platformă sunt Enterprise. În Community construiți pluginuri și abilități, plus lentile și fluxuri de lucru peste ceea ce rulați.
- Permisele Community se opresc sub nivelul Elevate. Pe un singur server nu există un mediu de producție la care să ajungeți dintr-un IDE (mediu de dezvoltare integrat), iar serverul îl administrați direct. O încercare din IDE este refuzată cu
PASS_TIER_REQUIRED.
Un spațiu de dezvoltare Community pe un server mic este modest. Al nostru avea 2 nuclee și 8 GiB de memorie, era închis cu excepția a ceea ce declară manifestul și s-a încheiat după 7 zile de inactivitate.
Contribuții înapoi
Și Skills Engine este Apache-2.0 și acceptă contribuții în modul obișnuit. Bifurcați depozitul, creați o ramură din main, efectuați modificarea împreună cu testele aferente și rulați verificările înainte de a deschide un pull request:
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheckO contribuție care modifică comportamentul are nevoie de un test care eșuează în lipsa ei. Nu este o chestiune de stil intern: regulile de testare ale SDK-ului prevăd că pentru fiecare test nou trebuie demonstrat că eșuează pe arborele de dinaintea modificării, iar evaluatorii cer dovada.
Modulele Enterprise și linia de licențiere
Enterprise înseamnă Community plus module licențiate. Un modul licențiat este un artefact separat pe care un serviciu Community îl încarcă la pornire și reprezintă modul în care funcționalitățile Enterprise, precum și orice modul închis pe care îl construiți pentru clienții Enterprise, se atașează nucleului deschis.
Regula care face ca acest lucru să funcționeze este linia de licență. Un modul închis poate ajunge la ediția Community printr-un singur pachet, @adverant/nexus-spi, interfața furnizorului de servicii. Acesta este Apache-2.0 și conține interfețe plus verificările de tip pe care o gazdă și un modul le folosesc pentru a se verifica reciproc, fără nicio altă logică de execuție. Cuplarea peste linie se face printr-o interfață sau printr-un protocol de rețea, niciodată prin cod sursă.
| Export | Ce reprezintă |
|---|---|
RouteModule |
Un modul de rute licențiat: id, featureGroup, bodies și register(app, ctx), care își montează routerele pe aplicația gazdei |
SpiApp |
Partea aplicației HTTP a gazdei pe care o accesează un modul: use |
SpiContext |
Ce îi transmite gazda unui modul: poarta de produs și garda de domeniu, cititorul de licență, pool-ul de interogări delimitate, schema serviciului, adresele din amonte și clienții platformei |
SpiRuntime |
Valorile plugin SDK pe care o gazdă le transmite unui modul, astfel încât modulul să nu importe niciodată el însuși componenta de execuție a SDK-ului |
SpiPlane |
Ce adaugă un plan licențiat în afară de rute, cum ar fi citirile de ecran pe care le servește |
ScreenModule |
Grupul de ecrane licențiate al unei console: group, featureGroup, routes, screens și menu |
GrantCheck |
(featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }> |
Cadrul HTTP și tipul de ecran al consolei sunt parametri de tip, astfel încât interfața nu se leagă de niciunul dintre ele. Iată scheletul unui modul de rute, cu un tip de handler 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> este grupul de funcționalități din matricea edițiilor pe care îl servește modulul. Fiecare rută licențiată rulează în spatele ctx.requireScope, poarta de produs și garda de domeniu ale gazdei, iar modulul își verifică și propria autorizare înainte de a răspunde. Un modul care nu are drept de utilizare refuză cu LICENCE_LOCKED și afișează prezentarea funcționalității, niciodată datele acesteia. Nici modulul dumneavoastră nu importă vreodată componenta de execuție a plugin SDK, deoarece SDK-ul este un pachet Community pe care linia nu îl admite. Gazda îi transmite valorile SDK pe care le apelează. Înainte de a încărca orice modul, gazda instalează un SpiHost pe globalThis sub Symbol.for(SPI_HOST_KEY), care conține componenta de execuție a SDK-ului și propriul set de rute al aplicației. Acest lucru trebuie să se întâmple primul: un modul compilat într-un singur pachet se evaluează în întregime, iar un apel register ar veni prea târziu pentru codul care citește valorile SDK în timpul încărcării. Pentru tipuri, @adverant/nexus-spi/sdk/<module> reexportă declarațiile SDK-ului, preluate nemodificat dintr-o versiune SDK și fixate prin sumă de control, astfel încât modulul dumneavoastră este verificat din punct de vedere al tipurilor față de aceleași corpuri de refuz și aceiași clienți pe care îi folosește un plugin.
Un modul de ecran respectă încă o regulă: un modul pentru fiecare grup de funcționalități, astfel încât un grup ale cărui ecrane aparțin la două grupuri de funcționalități este livrat ca două module, iar doar unul dintre ele conține rândul de meniu.
Ce refuză poarta liniei de licență
Poarta liniei de licență a Adverant impune linia fiecărui modul Enterprise și merită să impuneți aceeași regulă propriilor module închise. Configurația sa este un singur fișier:
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}Fiecare dintre următoarele este o constatare, cu fișierul și linia aferente:
- orice import al unui pachet dintr-un domeniu Community care nu este interfața permisă sau un pachet Enterprise, inclusiv importurile dinamice;
- orice specificator, cale de import Go sau URL de dependență care numește un depozit Community, cu excepția cazului în care este un modul Go listat în
allowedCommunityGoModules; - un import relativ care iese din depozit;
- o dependență
package.jsoncare este o calefile:,link:,portal:sauworkspace:din afara depozitului ori un URL Git către un depozit Community; - un
go.modreplacecare indică în afara depozitului.
Se încheie cu codul 0 când nu există probleme și cu 1 când există constatări. Codul 2 înseamnă că a refuzat, deoarece configurația sa era greșită sau nu a scanat nimic. Pachetul de interfață nu este publicat într-un registru. Păstrați în depozit o copie a pachetului construit, fixată la nivel de octet, ca pachet file: local, cu o fixare SHA256SUMS și o verificare în pipeline care refuză o copie diferită. Deoarece copia se află în depozit, poarta o acceptă.
Versiuni compilate pe ediții
Dacă extensia dumneavoastră este livrată clienților din ambele ediții, o construiți o dată pentru fiecare ediție, iar fiecare construire are loc în propriul arbore compus. Compunerea unui arbore înseamnă preluarea doar a fișierelor care aparțin acelei ediții. Exportul propriu al Adverant face acest lucru pe baza unei liste de delimitare în care fiecare fișier urmărit este atribuit după reguli în care câștigă prima potrivire: o regulă numește o capabilitate, iar ediția fișierului decurge din nivelul acelei capabilități în matricea edițiilor, sau numește o clasă de fișiere care nu se livrează în nicio ediție, cu un motiv. Fișierele folosite doar la construire se livrează în arborele Enterprise și, atunci când sunt marcate, și în arborele Community. Lanțul de migrări al unui modul reprezintă date de instalare și se livrează în arborele fiecărei ediții.
Apoi rulați întreaga construire de la zero în fiecare arbore compus. Asta înseamnă toate cele trei comenzi, de fiecare dată:
npm ci
npm test
npm run buildAm învățat acest lucru pe calea cea scumpă: un arbore Enterprise și-a trecut testele, în timp ce arborele Community a eșuat la construirea de producție, deoarece un tip de care avea nevoie se afla doar într-un fișier Enterprise. Testele trecute într-un arbore nu vă spun nimic despre celălalt. Testele unei ediții pot importa doar ceea ce conține arborele acelei ediții, iar exportul refuză un test care iese din acesta.
Exportul scrie și licența fiecărei ediții. Fișierele Community poartă identificatorul SPDX (Software Package Data Exchange) Apache-2.0; fișierele Enterprise poartă LicenseRef-Adverant-Enterprise, iar package.json al acestora indică UNLICENSED. Nu editați manual aceste câmpuri: exportul le rescrie, iar o copie care nu mai corespunde textului de licență fixat este refuzată.
Team: exclusiv în cloud
Team înseamnă Community plus setul Team și rulează doar pe Adverant cloud. Nu există Team auto-găzduit. Setul Team adaugă șase capabilități peste Community, printre care panoul de lucru consolidat, caietele partajate, administrarea bibliotecii de abilități și operațiunile pentru fluxuri de lucru, cu promovare între medii.
Pentru un dezvoltator, „doar în cloud” înseamnă un singur lucru: un client Team primește pluginul dumneavoastră ca versiune semnată prin catalog, niciodată de pe propriile dumneavoastră servere. Îl construiți așa cum construiește un editor extern, pe un cluster de editor.
Un cluster de editor este un cluster virtual pe Adverant cloud, cu o cotă stabilită de Adverant. Conține doar date de exemplu și nu are nicio rută către vreun client. Solicitarea unei copii mascate a datelor unui client acolo este refuzată cu TENANT_BOUNDARY; un client vă poate partaja rezultatele testelor, niciodată datele sale. Permisul dumneavoastră pe acesta nu ajunge niciodată în mediul unui client. Când versiunea este gata, este semnată și evaluată de Adverant înainte de a fi listată în catalog. Fiecare client alege apoi dacă o instalează și îi acordă doar ceea ce declară manifestul, unitate cu unitate. Un apel către orice nu a fost declarat în manifest este refuzat la client cu CONNECTION_SCOPE_EXCEEDED, iar singura modalitate de a-l adăuga este o nouă versiune, pe care clientul o evaluează.
Clienți cu sisteme izolate de rețea (air-gapped)
Unul dintre clienții noștri rulează Nexus într-un mediu în care nimic nu intră și nu iese prin rețea. Instalarea sa este descrisă în capitolul 2.10, Instalare izolată (air-gapped). Pentru noi, aceasta a însemnat livrarea pluginului pe suport fizic semnat, iar instrumentul pentru aceasta este nexus-airgap, din kitul de livrare suverană @adverant/nexus-sovereign.
Un pachet sigilat este un singur tarball semnat și autonom. Poate conține imagini și migrări, abilități presemnate și ponderi de model, precum și un SBOM (listă de materiale software) cu licențele a tot ceea ce conține. Manifestul său listează fiecare fișier cu SHA-256 aferent și este semnat cu Ed25519. Construirea unuia din cod arată astfel:
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 este cheia dumneavoastră de semnare a versiunilor. Comanda nexus-airgap bundle face același lucru din linia de comandă. Operatorul clientului îl verifică apoi înainte de orice altceva:
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgapVerificarea recalculează hash-ul fiecărui fișier față de manifest, respinge orice fișier pe care manifestul nu îl listează, impune un semnatar Ed25519 de încredere și refuză orice pachet a cărui listă de permisiuni de rețea nu este goală. Un fișier modificat după semnare eșuează cu BUNDLE_INTEGRITY_VIOLATION. Spuneți-i operatorului să se oprească în acel punct și să vă contacteze; există un comutator non-strict, iar acesta nu ar trebui să îl folosească niciodată.
Trei reguli au susținut livrarea noastră:
- Cheia de încredere circulă separat de pachet. Trimitem cheia publică și SHA-256 al pachetului pe o altă cale decât suportul fizic, astfel încât un pachet să nu poată garanta pentru sine însuși.
- Nimic din pachet nu poate necesita rețeaua la instalare. Nicio descărcare de pachete, nicio descărcare de modele, niciun apel de licență. Dacă pluginul are nevoie de un model, serverul de modele propriu al clientului îl furnizează prin AI (inteligență artificială) Provider Router.
- După verificare, operatorul introduce versiunea prin canalele de lansare proprii ale instalării, exact așa cum ar face un client conectat. Pachetul este modul în care sosesc octeții, nu o cale de ocolire a porților de promovare.
Lucrul în medii izolate este mai lent, iar acest lucru nu se poate remedia din partea noastră. Un octet greșit costă un nou set de suporturi fizice și încă un drum, așa că verificăm noi înșine pachetul pe o mașină curată, cu aceeași comandă, înainte ca acesta să părăsească clădirea.
Pachete de misiune Nexus Edge
Nexus Edge este o versiune mai mică a Nexus care rulează pe sateliți și drone, pe calculatoare de misiune separate de calculatorul de zbor. Este un supliment cu o licență per platformă sau per flotă. Ceea ce se schimbă de la o misiune la alta este pachetul de misiune, iar construirea acestora reprezintă o bună parte din munca mea.
Un pachet de misiune conține ceea ce îi trebuie sarcinii utile pentru o misiune. Pe lângă modele și adaptoare, acesta include ontologia cu un graf inițial, pașii agenților, regulile de alertă, prioritățile privind ce se transmite primul la sol, un tabel de plasare care indică ce calculator rulează ce, pașii degradați la care platforma poate trece atunci când un calculator se defectează, precum și cazurile de test pe care trebuie să le treacă la bord.
Pachetele sunt construite și semnate la sol. Câteva reguli practice din construirile noastre:
- Păstrați stabile componentele mari. Maritime watch 1.5 a adăugat un adaptor de detectare a navelor și două reguli de alertă; modelul de limbaj și ontologia nu s-au schimbat, astfel încât pachetul a avut 412 MB în loc de 9.8 GB. Legătura ascendentă are o lățime de bandă redusă, iar modelele de bază se încarcă înainte de lansare.
- Folosiți un singur model de embedding pentru întreaga familie de misiuni, atât la sol, cât și pe sarcina utilă, astfel încât modificările grafului transmise la sol să poată fi îmbinate cu graful de la sol.
- Sarcina utilă nu trimite niciodată o comandă către sistemele de zbor. Ea trimite cereri tipizate, prin supervizor, către calculatorul de zbor, care răspunde la fiecare cu o justificare.
- Fiecare tip de hardware necesită propria verificare a pachetului. Instalarea unui pachet neverificat pentru hardware-ul unui dispozitiv este refuzată cu
PACK_NOT_CHECKED_FOR_HARDWARE.
Lansarea necesită două din trei semnături. A noastră și a Adverant sunt perechea obișnuită, iar a treia este o cheie offline pe care o păstrăm într-un seif pentru cazul în care una dintre celelalte două se pierde. Pachetul este încărcat în slotul inactiv, este verificat, își rulează cazurile de test pe plăcile reale și este activat doar dacă toate trec, cu un contor care împiedică reinstalarea unui pachet mai vechi. Dacă un test eșuează, platforma rămâne pe pachetul anterior, iar eșecul este transmis la sol la următoarea trecere. Distribuim pe câte o platformă pe rând, fiecare după o săptămână fără probleme. Pachetele rămân valabile cât timp o platformă nu are contact, astfel încât un satelit fără legătură continuă să funcționeze cu pachetul pe care îl are.
Pe vehicule și nave, Edge poate rula pe k3s. O navă spațială rulează un supervizor cu imagini semnate sau binare statice și un tabel de plasare fix în loc de Kubernetes, și de aceea tabelul de plasare călătorește în interiorul pachetului.
Vitrine digitale white-label
Suplimentul Storefront / white-label permite unui client să își aplice propria marcă și propriul domeniu asupra a ceea ce văd utilizatorii săi, cu propriile ecrane de autentificare, și să încaseze plăți prin propriile gateway-uri. Datele cardurilor nu ajung niciodată în Nexus.
Un plugin construit pentru un client white-label nu trebuie să afișeze niciodată Adverant. Manifestul conține tot ce ține de marcă, iar platforma determină restul din marca proprie a organizației, nu din ceva scris direct în codul dumneavoastră:
{
"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> este domeniul propriu al clientului, iar passkeyRpId trebuie să corespundă acestuia, deoarece cheile de acces (passkeys) sunt legate de domeniul pe care o persoană se autentifică. O aplicație web pe propria origine autentifică persoanele prin funcțiile auxiliare de autentificare ale SDK-ului, ale căror două rute publice sunt singurele rute /api neprotejate acceptate de poarta de domeniu, și doar atunci când manifestul le declară auth: public cu allowAnonymous: true. Apelurile din frontend trec prin proxy-ul cu listă de permisiuni al backend-ului pentru frontend, niciodată direct către adresa unui serviciu. Administratorul clientului configurează partea de plăți, de la gateway-uri până la pagina de plată cu marca proprie. Pluginul dumneavoastră nu face acest lucru.
Matricea
| Țintă de construire | Se construiește pe baza | Ce faceți diferit | Cum ajunge la client |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Cod în GitHub; fără pachet de domeniu sau căi de platformă; fără Elevate | Clientul îl instalează; nu este necesară revizuirea pentru catalog |
| Enterprise (propria dumneavoastră instalare) | Plugin SDK, Skills Engine, șabloane de pachete | Spații de dezvoltare, ramuri de date, copii mascate împreună cu proprietarul datelor; pachete și lentile | Promovare din staging către o unitate pilot, apoi peste tot |
| Modul Enterprise (închis) | Doar @adverant/nexus-spi |
Regula liniei de licență; verificarea drepturilor pe propriul grup de funcționalități; LICENCE_LOCKED atunci când nu există drept de utilizare |
Încărcat de un serviciu Community la pornire, pe instalările licențiate |
| Ambele ediții | Plugin SDK | Compuneți arborele fiecărei ediții; npm ci, teste și build de producție în fiecare |
O lansare per ediție |
| Team | Plugin SDK pe un cluster de editor | Doar date de exemplu; doar în cloud | Lansare semnată, revizuire Adverant, catalog |
| Izolat (air-gapped) | Plugin SDK, @adverant/nexus-sovereign |
Pachet sigilat; cheia și suma de control trimise separat; nimic descărcat la instalare | Suport semnat, verificat, apoi canalele de lansare ale instalării |
| Nexus Edge | Conținutul pachetului de misiune | Tabel de plasare, pași degradați, teste la bord, verificări hardware | Două din trei semnături, slot inactiv, activat după trecerea testelor |
| White-label | Plugin SDK | domains și branding în manifest; numele Adverant nu apare nicăieri |
Ca la Enterprise, pe domeniul propriu al clientului |
Indiferent de țintă, implementarea se face exclusiv prin canalele de lansare ale instalării. Capitolul 2.28, Lansarea extensiei dumneavoastră, descrie aceste canale. Capitolul 2.27, Scenarii de construire, conține o rețetă pentru fiecare rând de mai sus.



