Verze 1.0.0-alpha.1nejnovější
Kapitola 2.25
Sestavení pro jednotlivé edice
Co se mění, když musí jedno rozšíření fungovat v každé edici, v izolovaném (air-gapped) prostředí, v nákladu Nexus Edge nebo pod vlastní značkou zákazníka. Zahrnuje licenční hranici pro moduly Enterprise a podepsané offline doručení, včetně matice odlišných postupů pro každý cíl.
Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

Ve společnosti Corrán Orbital dodáváme na více míst, než bývá u většiny týmů obvyklé. Naši vlastní inženýři provozují Enterprise na zemi. Družice CORR-3 provozuje misijní balíček na Nexus Edge. Dva zákazníci provozují Community na jediném serveru, jeden provozuje izolovanou instalaci Enterprise, která se nikdy nepřipojí k internetu, a pro jednu pojišťovnu jsme vytvořili balíček na její vlastní instalaci. Kód pod tím je z velké části stejný a rozdíly se týkají hlavně toho, kam smí putovat a jak se tam dostane.
Tato kapitola postupně prochází jednotlivé cíle: proti čemu sestavujete, čeho se nesmíte dotknout a jak se výsledek dostane k zákazníkovi. Matice na konci to shrnuje na jedné stránce. Kapitola 2.18, Model rozšíření, vysvětluje, čím se liší dovednosti, pluginy, balíčky a moduly. Kapitola 2.2, Edice pod kapotou, popisuje samotné edice.
Edice Community a otevřené jádro
Community je otevřené jádro pod licencí Apache License, Version 2.0. Můžete si jej forknout a dodávat do něj změny. Soubor NOTICE, který jej doprovází, uvádí jednu věc, kterou je dobré znát dříve, než cokoli označíte svou značkou: licence neuděluje právo používat názvy ani ochranné známky společnosti Adverant nad rámec uvedení, odkud dílo pochází.
Community rozšiřujete stejně jako Enterprise. Plugin SDK (sada pro vývoj softwaru) je v obou edicích stejný balíček a nemění se ani šablona plné služby, ani 22 kontrol dodržování pravidel; pojednává o tom kapitola 2.21, Plugin SDK. Fungují i dovednosti. Community získává celý tvůrce a knihovnu Skills Engine včetně verzí a testů, zatímco kanárková vydání a schvalování dvěma osobami zůstávají v Enterprise.
Vývojářské stránky v Community nabízejí stejné zlaté cesty se třemi rozdíly, které pocítíte okamžitě:
- Váš kód je uložen na GitHubu, nikoli ve vlastních repozitářích instalace. Zlatá cesta pro pluginy vytvoří repozitář na GitHubu a vývojový prostor ze stejné připnuté šablony, jakou používá Enterprise; obrazovka DV18 ukazuje, jak vytváří
room-bookings. - Zlaté cesty pro doménové balíčky a platformu patří do Enterprise. V Community vytváříte pluginy a dovednosti a také pohledy a pracovní postupy nad tím, co provozujete.
- Propustky v Community končí pod úrovní Elevate. Na jediném serveru neexistuje žádné produkční prostředí, kam by se dalo dosáhnout z IDE (integrovaného vývojového prostředí), a server spravujete přímo. Pokus z IDE je odmítnut s
PASS_TIER_REQUIRED.
Vývojový prostor Community na malém serveru je skromný. Náš měl 2 jádra a 8 GiB paměti, byl uzavřený kromě toho, co deklaruje manifest, a ukončil se po 7 dnech nečinnosti.
Přispívání zpět
Skills Engine je rovněž pod licencí Apache-2.0 a přijímá příspěvky obvyklým způsobem. Forkněte repozitář, vytvořte větev z main, proveďte změnu včetně testů a před otevřením pull requestu spusťte kontroly:
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheckPříspěvek, který mění chování, potřebuje test, který bez něj selže. Nejde o firemní zvyklost: vlastní pravidla testování SDK stanoví, že u každého nového testu musí být prokázáno, že na stromu před změnou selže, a recenzenti si o důkaz říkají.
Moduly Enterprise a licenční hranice
Enterprise je Community plus licencované moduly. Licencovaný modul je samostatný artefakt, který služba Community načte při spuštění, a je to způsob, jakým se k otevřenému jádru připojují funkce Enterprise i jakýkoli uzavřený modul, který vytvoříte pro zákazníky Enterprise.
Pravidlem, díky kterému to funguje, je licenční hranice. Uzavřený modul smí přistupovat k edici Community pouze prostřednictvím jediného balíčku, @adverant/nexus-spi, rozhraní poskytovatele služeb. Je pod licencí Apache-2.0 a obsahuje rozhraní a typové strážce, kterými se hostitel a modul vzájemně ověřují, bez jakékoli další běhové logiky. Propojení přes hranici je rozhraní nebo síťový protokol, nikdy zdrojový kód.
| Export | Co to je |
|---|---|
RouteModule |
Licencovaný modul tras: id, featureGroup, bodies a register(app, ctx), který připojuje své routery k aplikaci hostitele |
SpiApp |
Část aplikace HTTP hostitele, které se modul dotýká: use |
SpiContext |
Co hostitel předává modulu: produktovou bránu a strážce rozsahu, čtečku licence, fond dotazů s rozsahem, schéma služby, upstreamové adresy a klienty platformy |
SpiRuntime |
Hodnoty SDK pro pluginy, které hostitel předává modulu, takže modul sám nikdy neimportuje běhové prostředí SDK |
SpiPlane |
Co licencovaná vrstva přidává kromě tras, například čtení pro obrazovky, která obsluhuje |
ScreenModule |
Licencovaná skupina obrazovek konzole: group, featureGroup, routes, screens a menu |
GrantCheck |
(featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }> |
HTTP framework a typ obrazovky konzole jsou typové parametry, takže rozhraní neváže ani jedno z nich. Zde je kostra modulu tras s typem obslužné rutiny 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> je skupina funkcí matice edic, kterou modul obsluhuje. Každá licencovaná trasa běží za ctx.requireScope, produktovou bránou a strážcem rozsahu hostitele, a modul navíc před odpovědí ověřuje vlastní oprávnění. Modul, který oprávnění nemá, odmítne s LICENCE_LOCKED a zobrazí upoutávku funkce, nikdy její data. Váš modul také nikdy neimportuje běhové prostředí SDK pro pluginy, protože SDK je balíček Community, který hranice nepropustí. Hostitel mu předá hodnoty SDK, které volá. Před načtením jakéhokoli modulu hostitel nainstaluje SpiHost na globalThis pod Symbol.for(SPI_HOST_KEY), obsahující běhové prostředí SDK a vlastní sadu tras aplikace. Musí se to stát nejdříve: modul zkompilovaný do jednoho balíku se vyhodnocuje jako celek a volání register by přišlo příliš pozdě pro kód, který čte hodnoty SDK během načítání. Pro typy @adverant/nexus-spi/sdk/<module> znovu exportuje deklarace SDK, převzaté beze změn z jednoho vydání SDK a připnuté kontrolním součtem, takže typová kontrola vašeho modulu probíhá proti stejným tělům odmítnutí a klientům, jaké používá plugin.
Modul obrazovek se řídí ještě jedním pravidlem: jeden modul na skupinu funkcí, takže skupina, jejíž obrazovky patří do dvou skupin funkcí, se dodává jako dva moduly a řádek nabídky nese jen jeden z nich.
Co odmítá kontrola licenční hranice
Kontrola licenční hranice společnosti Adverant drží každý modul Enterprise v mezích hranice a vyplatí se podřídit stejnému pravidlu i vaše vlastní uzavřené moduly. Její konfigurace je jeden soubor:
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}Každá z následujících položek je nález se souborem a řádkem:
- jakýkoli import balíčku v rozsahu Community, který není povoleným rozhraním ani balíčkem Enterprise, včetně dynamických importů;
- jakýkoli specifikátor, importní cesta Go nebo URL závislosti, které jmenují repozitář Community, pokud nejde o modul Go uvedený v
allowedCommunityGoModules; - relativní import, který vystupuje mimo repozitář;
- závislost v
package.json, která je cestoufile:,link:,portal:neboworkspace:mimo repozitář, nebo Git URL na repozitář Community; replacevgo.mod, který ukazuje mimo repozitář.
Při čistém výsledku skončí s kódem 0 a při nálezech s kódem 1. Kód 2 znamená, že odmítla, protože její konfigurace byla chybná nebo nic neprohledala. Balíček rozhraní se nepublikuje do registru. Ve svém repozitáři uchováváte bajtově připnutou kopii sestaveného balíčku jako lokální balíček file:, s připnutím SHA256SUMS a kontrolou v pipeline, která odmítne odlišnou kopii. Protože je kopie uvnitř repozitáře, kontrola ji přijme.
Sestavení pro edice
Pokud se vaše rozšíření dodává zákazníkům v obou edicích, sestavujete jej jednou pro každou edici a každé sestavení probíhá ve vlastním složeném stromu. Složení stromu znamená převzít pouze soubory, které do dané edice patří. Vlastní export společnosti Adverant to provádí podle seznamu hranic, v němž je každý sledovaný soubor přiřazen pravidly, kde platí první shoda: pravidlo jmenuje schopnost a edice souboru vyplývá z úrovně této schopnosti v matici edic, nebo jmenuje třídu souborů, která se nedodává v žádné edici, s uvedením důvodu. Soubory určené pouze pro sestavení se dodávají ve stromu Enterprise a, jsou-li tak označeny, také ve stromu Community. Řetězec migrací modulu jsou data instalátoru a dodává se ve stromu každé edice.
Poté spusťte celé sestavení od čistého stavu v každém složeném stromu. To znamená všechny tři příkazy, pokaždé:
npm ci
npm test
npm run buildNaučili jsme se to draze: strom Enterprise prošel testy, zatímco strom Community neprošel produkčním sestavením, protože typ, který potřeboval, existoval pouze v souboru Enterprise. To, že testy projdou v jednom stromu, nic neříká o tom druhém. Testy edice smí importovat jen to, co obsahuje strom dané edice, a export odmítne test, který sahá mimo něj.
Export také zapisuje licenci každé edice. Soubory Community nesou identifikátor SPDX (Software Package Data Exchange) Apache-2.0; soubory Enterprise nesou LicenseRef-Adverant-Enterprise a jejich package.json uvádí UNLICENSED. Tato pole neupravujte ručně: export je přepíše a kopie, která již neodpovídá připnutému textu licence, je odmítnuta.
Team: pouze v cloudu
Team je Community plus sada Team a běží pouze v Adverant cloud. Neexistuje žádná samostatně hostovaná edice Team. Sada Team přidává k Community šest schopností, mezi nimi konsolidovaný pracovní panel, sdílené poznámkové bloky, správu knihovny dovedností a provoz pracovních postupů s povyšováním mezi prostředími.
Pro tvůrce znamená výhradně cloudový provoz jedinou věc: zákazník Team získá váš plugin jako podepsané vydání prostřednictvím katalogu, nikdy z vašich vlastních serverů. Sestavujete jej tak, jak sestavuje externí vydavatel, na clusteru vydavatele.
Cluster vydavatele je virtuální cluster v Adverant cloud s kvótou stanovenou společností Adverant. Obsahuje pouze vzorová data a nemá žádnou cestu k žádnému zákazníkovi. Žádost o maskovanou kopii dat zákazníka je zde odmítnuta s TENANT_BOUNDARY; zákazník s vámi může sdílet výsledky testů, nikdy svá data. Vaše propustka k němu nikdy nedosahuje do prostředí zákazníka. Když je vydání připraveno, je podepsáno a zrevidováno společností Adverant, než je zařazeno do katalogu. Každý zákazník se pak rozhodne, zda jej nainstaluje, a udělí mu pouze to, co deklaruje jeho manifest, jednotku po jednotce. Volání čehokoli, co manifest nedeklaroval, je na straně zákazníka odmítnuto s CONNECTION_SCOPE_EXCEEDED a jediný způsob, jak to přidat, je nové vydání, které zákazník zreviduje.
Zákazníci v izolovaném (air-gapped) prostředí
Jeden z našich zákazníků provozuje Nexus tam, kde po síti nic nevstupuje ani nevystupuje. Jeho instalace je popsána v kapitole 2.10, Izolovaná instalace. Pro nás to znamenalo dodat náš plugin na podepsaných médiích a nástrojem k tomu je nexus-airgap ze sady pro suverénní doručování @adverant/nexus-sovereign.
Zapečetěný balík je jeden podepsaný, samostatný tarball. Může obsahovat image a migrace, předem podepsané dovednosti a váhy modelů a SBOM (soupis softwarových komponent) s licencemi všeho uvnitř. Jeho manifest uvádí každý soubor s jeho SHA-256 a je podepsán pomocí Ed25519. Sestavení z kódu vypadá takto:
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 je váš podpisový klíč pro vydání. Příkaz nexus-airgap bundle dělá totéž z příkazového řádku. Operátor zákazníka jej pak před čímkoli jiným ověří:
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgapOvěření znovu spočítá hash každého souboru proti manifestu, odmítne každý soubor, který manifest neuvádí, vyžaduje důvěryhodného podepisovatele Ed25519 a odmítne každý balík, jehož seznam povolených síťových přístupů není prázdný. Soubor změněný po podpisu selže s BUNDLE_INTEGRITY_VIOLATION. Řekněte operátorovi, aby se v tu chvíli zastavil a kontaktoval vás; existuje přepínač nestriktního režimu a ten by nikdy neměl použít.
Naše doručení stálo na třech pravidlech:
- Důvěryhodný klíč putuje odděleně od balíku. Veřejný klíč a SHA-256 balíku posíláme jinou cestou než média, takže balík nemůže ručit sám za sebe.
- Nic v balíku nesmí při instalaci potřebovat síť. Žádné stahování balíčků, žádné stahování modelů, žádné volání licenčního serveru. Pokud plugin potřebuje model, poskytne jej vlastní modelový server zákazníka prostřednictvím AI (umělá inteligence) Provider Router.
- Po ověření operátor přenese vydání do instalace jejími vlastními kanály pro vydání, přesně jako by to udělal připojený zákazník. Balík je způsob, jak bajty dorazí, nikoli způsob, jak obejít brány povýšení.
Práce v izolovaném prostředí je pomalejší a z naší strany to napravit nelze. Chybný bajt stojí novou sadu médií a další cestu, proto balík před odesláním z budovy sami ověřujeme stejným příkazem na čistém počítači.
Balíčky misí pro Nexus Edge
Nexus Edge je menší Nexus, který běží na satelitech a dronech, na misijních počítačích oddělených od letového počítače. Jde o doplněk s licencí pro každou platformu nebo flotilu. Mezi jednotlivými misemi se mění misijní balíček a jejich sestavování tvoří velkou část mé práce.
Misijní balíček obsahuje vše, co užitečné zatížení potřebuje pro jednu misi. Vedle svých modelů a adaptérů obsahuje ontologii s výchozím grafem, kroky agentů, pravidla upozornění, priority určující, co se stáhne jako první, tabulku umístění určující, který počítač co spouští, degradované kroky, na které může platforma přejít při selhání počítače, a testovací případy, které musí projít na palubě.
Balíčky se sestavují a podepisují na zemi. Několik praktických pravidel z našich sestavení:
- Velké části udržujte stabilní. Maritime watch 1.5 přidal adaptér pro vyhledávání lodí a dvě pravidla upozornění; jazykový model ani ontologie se nezměnily, takže balíček měl 412 MB místo 9.8 GB. Uplink je úzký a základní modely se nahrávají před startem.
- Pro celou rodinu misí používejte jeden embeddingový model, na zemi i v užitečném zatížení, aby se změny grafu, které přijdou dolů, mohly sloučit s pozemním grafem.
- Užitečné zatížení nikdy neposílá příkazy letovým systémům. Posílá typované požadavky přes supervizor letovému počítači, který na každý odpoví s uvedením důvodu.
- Každý typ hardwaru vyžaduje vlastní kontrolu balíčku. Instalace balíčku, který nebyl zkontrolován pro hardware daného zařízení, je odmítnuta s chybou
PACK_NOT_CHECKED_FOR_HARDWARE.
Vydání vyžaduje dva ze tří podpisů. Obvyklou dvojici tvoří náš podpis a podpis společnosti Adverant, třetím je offline klíč uložený v trezoru pro případ, že se jeden z ostatních dvou ztratí. Balíček se nahraje do nečinného slotu, ověří se, spustí své testovací případy na skutečných deskách a zapne se jen tehdy, když všechny projdou, přičemž čítač brání opětovné instalaci staršího balíčku. Pokud některý test selže, platforma zůstane na předchozím balíčku a informace o selhání přijde při dalším přeletu. Zavádíme po jedné platformě, každou po týdnu bez problémů. Balíčky zůstávají platné i v době, kdy je platforma mimo spojení, takže satelit bez spojení dál pracuje s balíčkem, který má.
Na vozidlech a plavidlech může Edge běžet na k3s. Kosmická loď místo Kubernetes používá supervizor s podepsanými obrazy nebo statickými binárními soubory a pevnou tabulkou umístění, a proto je tabulka umístění součástí balíčku.
White-label výlohy
Doplněk Storefront / white-label umožňuje zákazníkovi opatřit to, co vidí jeho uživatelé, vlastní značkou a doménou, s vlastními přihlašovacími obrazovkami, a přijímat platby přes vlastní platební brány. Údaje o kartách se Nexus nikdy nedotknou.
Plugin vytvořený pro zákazníka s white-label řešením nesmí nikdy zobrazit Adverant. Manifest obsahuje vše, co se týká značky, a platforma zbytek odvozuje z vlastní značky organizace, nikoli z čehokoli napevno zapsaného ve vašem kódu:
{
"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> je vlastní doména zákazníka a passkeyRpId se s ní musí shodovat, protože přístupové klíče (passkeys) jsou vázány na doménu, na které se uživatel přihlašuje. Webová aplikace na vlastním originu přihlašuje uživatele pomocí přihlašovacích pomocníků SDK, jejichž dvě veřejné trasy jsou jedinými nechráněnými trasami /api, které brána rozsahů přijme, a to pouze tehdy, když je manifest deklaruje jako auth: public s allowAnonymous: true. Volání z frontendu procházejí proxy se seznamem povolených adres backendu pro frontend, nikdy přímo na adresu služby. Platební stránku, od platebních bran po pokladnu s vlastní značkou, konfiguruje administrátor zákazníka. Váš plugin ne.
Matice
| Cíl sestavení | Sestavuje se proti | Co děláte jinak | Jak se dostane k zákazníkovi |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Kód na GitHubu; žádný doménový balíček ani platformní cesty; žádný Elevate | Zákazník jej nainstaluje sám; revize katalogu není potřeba |
| Enterprise (vaše vlastní instalace) | Plugin SDK, Skills Engine, šablony balíčků | Vývojové prostory, datové větve, maskované kopie s vlastníkem dat; balíčky a pohledy | Povýšení ze stagingu na pilotní jednotku, poté všude |
| Modul Enterprise (uzavřený) | Pouze @adverant/nexus-spi |
Pravidlo licenční hranice; kontrola oprávnění na vlastní skupině funkcí; LICENCE_LOCKED bez nároku |
Načítán službou Community při spuštění, na licencovaných instalacích |
| Obě edice | Plugin SDK | Sestavte strom každé edice; v každé npm ci, testy a produkční sestavení |
Jedno vydání pro každou edici |
| Team | Plugin SDK na clusteru vydavatele | Pouze ukázková data; pouze cloud | Podepsané vydání, revize Adverant, katalog |
| Izolované prostředí (air-gapped) | Plugin SDK, @adverant/nexus-sovereign |
Zapečetěný balík; klíč a kontrolní součet zaslány zvlášť; při instalaci se nic nestahuje | Podepsaná média, ověření, poté kanály vydání instalace |
| Nexus Edge | Obsah misijního balíčku | Tabulka umístění, degradované kroky, testy na palubě, kontroly hardwaru | Dva ze tří podpisů, nečinný slot, zapnutí po úspěšných testech |
| White-label | Plugin SDK | domains a branding v manifestu; nikde název Adverant |
Jako u Enterprise, na vlastní doméně zákazníka |
Bez ohledu na cíl se nasazuje pouze přes kanály vydání instalace. Těmto kanálům se věnuje kapitola 2.28, Vydání vašeho rozšíření. Kapitola 2.27, Scénáře sestavení, obsahuje postup pro každý řádek výše.



