ВходЗапазете среща

Глава 2.25

Разработване за всяко издание

Какво се променя, когато едно разширение трябва да работи във всяко издание, в изолирана от интернет среда (air-gapped), в пакет за Nexus Edge или под собствената марка на клиента. Обхваща лицензионната граница за модулите Enterprise и подписаната офлайн доставка, с матрица на това какво трябва да се направи по различен начин за всяка целева среда.

Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

17 минути за четене

В Corrán Orbital доставяме на повече места, отколкото повечето екипи някога ще доставят. Нашите собствени инженери работят с Enterprise на земята. Един спътник, CORR-3, изпълнява мисионен пакет върху Nexus Edge. Двама клиенти работят с Community на един сървър, един работи с изолирана Enterprise инсталация, която никога не вижда интернет, а за един застраховател сме изградили пакет върху собствената му инсталация. Кодът отдолу е до голяма степен един и същ, а разликите са основно в това къде му е позволено да отиде и как стига дотам.

Тази глава разглежда последователно всяка цел: спрямо какво изграждате, какво нямате право да променяте и как резултатът достига до клиента. Матрица в края обобщава всичко на една страница. Глава 2.18, Моделът за разширения, обяснява по какво се различават уменията, плъгините, пакетите и модулите. Глава 2.2, Изданията отвътре, описва самите издания.

Community и отвореното ядро

Community е отвореното ядро, под Apache License, Version 2.0. Можете да го разклоните и да доставяте промени по него. Файлът NOTICE, който го придружава, съдържа едно нещо, което си струва да знаете, преди да брандирате каквото и да било: лицензът не предоставя право за използване на имената или търговските марки на Adverant извън посочването на произхода на произведението.

Разширявате Community по същия начин, по който разширявате Enterprise. Plugin SDK (комплект за разработка на софтуер) е един и същ пакет и в двете издания и нито шаблонът за пълна услуга, нито 22-те проверки за съответствие се променят; глава 2.21, Plugin SDK, разглежда това. Уменията също работят. Community получава целия създател и библиотека на Skills Engine, с версии и тестове, докато канареечните издания и одобрението от двама души остават в Enterprise.

Изграждане в Community
Изграждане в Community
Изграждане на плъгин за резервации на един сървър с Community. Обърнете внимание на пропуска за достъп, който достига до Propose чрез GitHub и не предлага Elevate, както и на тийзъра вдясно, изброяващ какво добавя Enterprise.

Страниците за разработчици в Community предлагат същите златни пътеки с три разлики, които ще усетите веднага:

  1. Кодът Ви се намира в GitHub, а не в собствените хранилища на инсталацията. Златната пътека за плъгини създава хранилище в GitHub и пространство за разработка от същия фиксиран шаблон, който използва Enterprise; екран DV18 показва как тя създава room-bookings.
  2. Златните пътеки за домейн пакети и за платформата са в Enterprise. В Community изграждате плъгини и умения, както и лещи и работни потоци върху това, което изпълнявате.
  3. Пропуските в Community спират под нивото Elevate. На един сървър няма продукционна среда, до която да се достига от IDE (интегрирана среда за разработка), и администрирате сървъра директно. Опит от IDE се отказва с PASS_TIER_REQUIRED.

Пространството за разработка в Community на малък сървър е скромно. Нашето имаше 2 ядра и 8 GiB памет, беше затворено с изключение на декларираното в манифеста и приключи след 7 дни неактивност.

Принос обратно

Skills Engine също е под Apache-2.0 и приема приноси по обичайния начин. Разклонете хранилището, създайте клон от main, направете промяната с нейните тестове и изпълнете проверките, преди да отворите заявка за изтегляне (pull request):

git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheck

Принос, който променя поведението, изисква тест, който се проваля без него. Това не е въпрос на вътрешен стил: собствените правила за тестване на SDK изискват всеки нов тест да бъде показано, че се проваля върху кода преди промяната, а рецензентите изискват доказателство.

Модули Enterprise и лицензионната граница

Enterprise е Community плюс лицензирани модули. Лицензираният модул е отделен артефакт, който услуга на Community зарежда при стартиране, и именно чрез него функциите на Enterprise, както и всеки затворен модул, който изграждате за клиенти на Enterprise, се присъединяват към отвореното ядро.

Правилото, което прави това възможно, е лицензната граница. Затворен модул може да достига изданието Community само чрез един пакет, @adverant/nexus-spi, интерфейса за доставчици на услуги. Той е под Apache-2.0 и съдържа интерфейси плюс проверките на типове, с които хостът и модулът се проверяват взаимно, без друга логика по време на изпълнение. Свързването през границата е интерфейс или мрежов протокол, никога изходен код.

Експорт Какво представлява
RouteModule Лицензиран модул за маршрути: id, featureGroup, bodies и register(app, ctx), който монтира своите рутери в приложението на хоста
SpiApp Частта от HTTP приложението на хоста, до която един модул се докосва: use
SpiContext Какво предоставя хостът на модула: продуктовата проверка и защитата на обхвата, четеца на лиценза, пула за заявки с обхват, схемата на услугата, адресите нагоре по веригата и клиентите на платформата
SpiRuntime Стойностите от Plugin SDK, които хостът предоставя на модула, така че модулът никога да не импортира сам средата за изпълнение на SDK
SpiPlane Какво добавя лицензираната равнина освен маршрути, например четенията за екрани, които обслужва
ScreenModule Лицензирана група екрани на конзолата: group, featureGroup, routes, screens и menu
GrantCheck (featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }>

HTTP рамката и типът екран на конзолата са параметри на типа, така че интерфейсът не обвързва нито едното, нито другото. Ето скелета на модул за маршрути с тип обработчик на 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> е групата функции от матрицата на изданията, която модулът обслужва. Всеки лицензиран маршрут се изпълнява зад ctx.requireScope, продуктовата проверка и защитата на обхвата на хоста, а модулът също проверява собственото си право, преди да отговори. Модул без право отказва с LICENCE_LOCKED и показва тийзъра на функцията, никога нейните данни. Вашият модул също никога не импортира средата за изпълнение на Plugin SDK, защото SDK е пакет на Community, който границата не допуска. Хостът му предоставя стойностите от SDK, които той извиква. Преди да зареди какъвто и да е модул, хостът инсталира SpiHost в globalThis под Symbol.for(SPI_HOST_KEY), съдържащ средата за изпълнение на SDK и собствения комплект маршрути на приложението. Това трябва да стане първо: модул, компилиран в един пакет, се изпълнява като цяло и извикване на register би дошло твърде късно за код, който чете стойностите от SDK по време на зареждане. За типовете @adverant/nexus-spi/sdk/<module> преекспортира декларациите на SDK, включени непроменени от едно издание на SDK и фиксирани с контролна сума, така че проверката на типовете на Вашия модул се извършва спрямо същите тела на откази и клиенти, които използва плъгин.

Модулът за екрани следва още едно правило: един модул на група функции, така че група, чиито екрани принадлежат към две групи функции, се доставя като два модула и само един от тях съдържа реда в менюто.

Какво отказва проверката на лицензната граница

Проверката на лицензната граница на Adverant държи всеки модул на Enterprise в рамките на границата и си струва да прилагате същото правило към собствените си затворени модули. Конфигурацията ѝ е един файл:

{
  "communityScopes": ["@adverant/", "@adverant-nexus/"],
  "allowedCommunityPackages": ["@adverant/nexus-spi"],
  "enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
  "communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
  "allowedCommunityGoModules": []
}

Всяко от следните е констатация със своя файл и ред:

  • всеки импорт на пакет в обхват на Community, който не е разрешеният интерфейс или пакет на Enterprise, включително динамичните импорти;
  • всеки спецификатор, път за импорт в Go или URL адрес на зависимост, който посочва хранилище на Community, освен ако не е Go модул, изброен в allowedCommunityGoModules;
  • относителен импорт, който излиза извън хранилището;
  • зависимост в package.json, която е път file:, link:, portal: или workspace: извън хранилището, или Git URL адрес към хранилище на Community;
  • replace в go.mod, който сочи извън хранилището.

Тя завършва с код 0 при чист резултат и 1 при констатации. Код 2 означава, че е отказала, защото конфигурацията ѝ е била грешна или не е сканирала нищо. Интерфейсният пакет не се публикува в регистър. Вие държите фиксирано байт по байт копие на изградения пакет в хранилището си като локален пакет file:, с фиксиране SHA256SUMS и проверка в конвейера, която отказва копие, което се различава. Тъй като копието е в хранилището, проверката го приема.

Две големи полета едно до друго. Лявото поле е обозначено с „Community (Apache-2.0)“ и съдържа по-малки полета за „Services“, „Plugin SDK“ и „@adverant/nexus-spi“. Дясното поле е обозначено с „Enterprise module (closed)“ и съдържа „RouteModule“, „ScreenModule“ и „GrantCheck“. Една плътна стрелка пресича линията от дясното поле само към „@adverant/nexus-spi“ и е обозначена с „compile against“. Две пунктирани стрелки от дясното поле към „Services“ и „Plugin SDK“ са зачеркнати и обозначени с „licence-line gate: finding“.
Лицензната граница между Community и модул на Enterprise.

Компилации за отделните издания

Ако Вашето разширение се доставя на клиенти и в двете издания, изграждате го веднъж за всяко издание, като всяко изграждане става в собствено композирано дърво. Композирането на дърво означава да се вземат само файловете, които принадлежат на това издание. Собственият експорт на Adverant прави това от списък на границите, в който всеки проследяван файл се разпределя по правила, при които печели първото съвпадение: правилото посочва възможност и изданието на файла следва от нивото на тази възможност в матрицата на изданията, или посочва клас файлове, който не се доставя в нито едно издание, с обосновка. Файловете само за изграждане се доставят в дървото на Enterprise и, когато са отбелязани, и в дървото на Community. Веригата от миграции на модула е данни на инсталатора и се доставя в дървото на всяко издание.

След това изпълнете цялото изграждане от чисто състояние във всяко композирано дърво. Това означава и трите команди, всеки път:

npm ci
npm test
npm run build

Научихме това по скъпия начин: дърво на Enterprise премина тестовете си, докато дървото на Community се провали при продукционното си изграждане, защото тип, от който то се нуждаеше, се намираше само във файл на Enterprise. Успешните тестове в едно дърво не Ви казват нищо за другото. Тестовете на дадено издание могат да импортират само това, което съдържа дървото на това издание, а експортът отказва тест, който излиза извън него.

Експортът също записва лиценза на всяко издание. Файловете на Community носят SPDX (Software Package Data Exchange) идентификатора Apache-2.0; файловете на Enterprise носят LicenseRef-Adverant-Enterprise, а техният package.json гласи UNLICENSED. Не редактирайте тези полета ръчно: експортът ги презаписва, а копие, което вече не съответства на фиксирания си лицензен текст, се отказва.

Team: само в облака

Team е Community плюс набора Team и работи само в облака на Adverant. Няма самостоятелно хостван Team. Наборът Team добавя шест възможности върху Community, сред които консолидираният работен панел, споделените бележници, администрирането на библиотеката с умения и операциите с работни потоци с промотиране между среди.

За разработчика „само в облака“ означава едно нещо: клиент на Team получава Вашия плъгин като подписано издание чрез каталога, никога от Вашите собствени сървъри. Изграждате го така, както го изгражда външен издател, на клъстер на издател.

Клъстер на издател
Клъстер на издател
Собствен виртуален клъстер на издател в облака на Adverant, само с примерни данни. Проследете потока на живо в горната част: IDE достига до клъстера и примерните данни на издателя, подписано издание преминава през преглед към каталога и няма път до нито един клиент.

Клъстерът на издател е виртуален клъстер в облака на Adverant с квота, определена от Adverant. Той съдържа само примерни данни и няма маршрут до нито един клиент. Искането за маскирано копие на данните на клиент там се отказва с TENANT_BOUNDARY; клиентът може да сподели с Вас резултати от тестове, никога своите данни. Вашият пропуск за него никога не достига до клиент. Когато изданието е готово, то се подписва и преглежда от Adverant, преди да бъде включено в каталога. След това всеки клиент избира дали да го инсталира и му предоставя само това, което манифестът му декларира, единица по единица. Извикване на нещо, което манифестът не е декларирал, се отказва от страна на клиента с CONNECTION_SCOPE_EXCEEDED, а единственият начин да се добави е ново издание, което клиентът преглежда.

Клиенти с изолирана среда (air-gapped)

Един от нашите клиенти работи с Nexus там, където нищо не влиза и не излиза по мрежа. Неговата инсталация е описана в глава 2.10, Изолирана инсталация. За нас това означаваше да доставим плъгина си на подписан носител, а инструментът за това е nexus-airgap от комплекта за суверенна доставка @adverant/nexus-sovereign.

Запечатаният пакет е един подписан, самодостатъчен tar архив. Той може да съдържа образи и миграции, предварително подписани умения и тегла на модели, както и SBOM (спецификация на софтуерните компоненти) с лицензите на всичко вътре. Манифестът му изброява всеки файл с неговия SHA-256 и е подписан с Ed25519. Изграждането на такъв пакет от код изглежда така:

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 е Вашият ключ за подписване на издания. Командата nexus-airgap bundle прави същото от командния ред. След това операторът на клиента го проверява преди всичко друго:

nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgap

Проверката изчислява наново хеша на всеки файл спрямо манифеста, отхвърля всеки файл, който манифестът не изброява, изисква доверен подписващ с Ed25519 и отказва всеки пакет, чийто списък с разрешени мрежови адреси не е празен. Файл, променен след подписването, се проваля с BUNDLE_INTEGRITY_VIOLATION. Кажете на оператора да спре дотук и да Ви се обади; съществува превключвател за нестрог режим и той никога не трябва да го използва.

Три правила осигуриха нашата доставка:

  1. Довереният ключ пътува отделно от пакета. Изпращаме публичния ключ и SHA-256 на пакета по различен път от носителя, така че пакетът да не може да гарантира сам за себе си.
  2. Нищо в пакета не може да се нуждае от мрежата при инсталиране. Никакво изтегляне на пакети, никакво изтегляне на модели, никакво обръщение за лиценз. Ако плъгинът се нуждае от модел, собственият сървър за модели на клиента го предоставя чрез AI (изкуствен интелект) Provider Router.
  3. След проверката операторът въвежда изданието през собствените канали за издания на инсталацията, точно както би направил свързан клиент. Пакетът е начинът, по който пристигат байтовете, а не начин за заобикаляне на проверките за промотиране.

Работата в изолирана среда е по-бавна и това не може да се поправи от наша страна. Един грешен байт струва нов комплект носители и още едно пътуване, затова проверяваме пакета сами на чиста машина със същата команда, преди той да напусне сградата.

Пакети за мисии на Nexus Edge

Nexus Edge е по-компактна версия на Nexus, която работи на спътници и дронове, на мисионни компютри, отделени от полетния компютър. Тя е допълнителен модул с лиценз за платформа или флот. Това, което се променя от една мисия към следващата, е мисионният пакет, и изграждането на тези пакети е голяма част от моята работа.

Мисионният пакет съдържа това, от което полезният товар се нуждае за една мисия. Наред с моделите и адаптерите си той съдържа онтологията с начален граф, стъпките на агентите, правилата за известяване, приоритетите за това какво се изтегля първо, таблица за разпределение, която указва кой компютър какво изпълнява, деградиралите стъпки, до които платформата може да премине при отказ на компютър, и тестовите случаи, които пакетът трябва да премине на борда.

Изграждане на мисионен пакет
Изграждане на мисионен пакет
Изграждане на Maritime watch 1.5 от 1.4. Обърнете внимание на тестовите случаи на борда (48, всички трябва да преминат) и на таблицата за разпределение, която указва какво се изпълнява на всяка от двете GPU (графичен процесор) платки и на CPU (централен процесор) платката при всяка деградирала стъпка.

Пакетите се изграждат и подписват на земята. Някои практически правила от нашите изграждания:

  • Поддържайте големите части стабилни. Maritime watch 1.5 добави адаптер за откриване на кораби и две правила за известяване; езиковият модел и онтологията не се промениха, така че пакетът беше 412 MB вместо 9.8 GB. Каналът нагоре е тесен, а базовите модели се зареждат преди изстрелването.
  • Използвайте един модел за вграждания за цялото семейство мисии както на земята, така и на полезния товар, за да могат промените в графа, които се изтеглят, да се обединяват с наземния граф.
  • Полезният товар никога не изпраща команда към полетните системи. Той изпраща типизирани заявки чрез супервайзора към полетния компютър, който отговаря на всяка от тях с обяснение на причината.
  • Всеки тип хардуер изисква собствена проверка на пакета. Инсталирането на пакет, който не е проверен за хардуера на дадено устройство, се отказва с PACK_NOT_CHECKED_FOR_HARDWARE.
Подписване и изпращане на пакет
Подписване и изпращане на пакет
Пускане на Maritime watch 1.5 към CORR-3. Необходими са два от три подписа, така че един откраднат ключ не може да пусне пакет, а планът показва, че пакетът се активира едва след като неговите 48 теста преминат на борда.

Пускането изисква два от три подписа. Нашият и този на Adverant са обичайната двойка, а третият е офлайн ключ, който съхраняваме в сейф за случаите, когато някой от другите два бъде изгубен. Пакетът се качва в неактивния слот, проверява се, изпълнява тестовите си случаи на реалните платки и се активира само ако всички преминат, като брояч не позволява повторното инсталиране на по-стар пакет. Ако тест не премине, платформата остава на предишния пакет, а отказът се изтегля при следващото преминаване. Внедряваме на една платформа наведнъж, всяка след седмица без проблеми. Пакетите остават валидни, докато платформата е извън връзка, така че спътник без връзка продължава да работи с пакета, който има.

На превозни средства и плавателни съдове Edge може да работи на k3s. Космическият апарат използва супервайзор с подписани образи или статични двоични файлове и фиксирана таблица за разпределение вместо Kubernetes и затова таблицата за разпределение пътува в пакета.

Витрини със собствена марка (white-label)

Допълнителният модул Storefront / white-label позволява на клиента да постави собствената си марка и домейн върху това, което виждат неговите потребители, със собствени екрани за вход, и да приема плащания чрез собствените си платежни шлюзове. Данните за картите никога не достигат до Nexus.

Плъгин, изграден за white-label клиент, никога не трябва да показва Adverant. Манифестът съдържа всичко, свързано с марката, а платформата определя останалото от собствената марка на организацията, а не от нещо, твърдо зададено във Вашия код:

{
  "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> е собственият домейн на клиента и passkeyRpId трябва да съвпада с него, защото ключовете за достъп (passkeys) са обвързани с домейна, на който човек влиза. Уеб приложение на собствен произход удостоверява потребителите чрез помощните функции за вход на SDK, чиито два публични маршрута са единствените незащитени /api маршрути, които проверката на обхвата приема, и то само когато манифестът ги декларира auth: public с allowAnonymous: true. Извикванията от фронтенда минават през прокси сървъра с разрешен списък на бекенда за фронтенда, никога директно към адреса на услуга. Администраторът на клиента конфигурира плащанията – от шлюзовете до брандираната страница за плащане. Вашият плъгин не го прави.

Матрицата

Цел на изграждането Изгражда се спрямо Какво правите различно Как достига до клиента
Community Plugin SDK, Skills Engine Код в GitHub; без пакет за домейн или пътища на платформата; без Elevate Клиентът го инсталира; не е необходим преглед за каталога
Enterprise (Вашата собствена инсталация) Plugin SDK, Skills Engine, шаблони за пакети Среди за разработка, клонове на данни, маскирани копия със собственика на данните; пакети и изгледи Повишаване от тестова среда към пилотно звено, след това навсякъде
Enterprise модул (затворен) Само @adverant/nexus-spi Правило за лицензната граница; проверка на правата за собствена група функции; LICENCE_LOCKED, когато няма право Зарежда се от услуга на Community при стартиране, на лицензирани инсталации
И двете издания Plugin SDK Съставете дървото на всяко издание; npm ci, тестове и продукционно изграждане във всяко По едно издание за всяка версия на продукта
Team Plugin SDK на клъстер на издател Само примерни данни; само в облака Подписано издание, преглед от Adverant, каталог
Изолирана среда (air-gapped) Plugin SDK, @adverant/nexus-sovereign Запечатан пакет; ключът и контролната сума се изпращат отделно; нищо не се изтегля при инсталиране Подписан носител, проверен, след това каналите за издания на инсталацията
Nexus Edge Съдържание на мисионния пакет Таблица за разпределение, деградирали стъпки, тестове на борда, хардуерни проверки Два от три подписа, неактивен слот, активиране след преминаване на тестовете
Собствена марка (White-label) Plugin SDK domains и branding в манифеста; никъде името Adverant Както при Enterprise, на собствения домейн на клиента

Каквато и да е целта, внедряването става само чрез каналите за издания на инсталацията. Глава 2.28, Издаване на Вашето разширение, описва тези канали. Глава 2.27, Сценарии за изграждане, съдържа рецепта за всеки ред по-горе.