Версія 1.0.0-alpha.1найновіша
Розділ 2.25
Збирання для кожної редакції
Що змінюється, коли одне розширення має працювати в кожній редакції, на ізольованому (air-gapped) майданчику, у складі корисного навантаження Nexus Edge або під власним брендом клієнта. Охоплює межі ліцензування для модулів Enterprise і підписане офлайн-доставлення, а також матрицю відмінностей для кожної цільової платформи.
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

У 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 пропонують ті самі «золоті шляхи» з трьома відмінностями, які ви відчуєте одразу:
- Ваш код зберігається в GitHub, а не у власних репозиторіях інсталяції. «Золотий шлях» плагіна створює репозиторій GitHub і середовище розробки з того самого зафіксованого шаблону, що використовує Enterprise; екран DV18 показує, як він створює
room-bookings. - «Золоті шляхи» доменного пакета та платформи належать до Enterprise. У Community ви створюєте плагіни та навички, а також лінзи та робочі процеси на основі того, що у вас працює.
- Пропуски 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 |
Значення 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 і показує тизер функції, ніколи не її дані. Ваш модуль також ніколи не імпортує середовище виконання 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; go.modreplace, що вказує за межі репозиторію.
Вона завершується з кодом 0, якщо порушень немає, і 1 за наявності знахідок. Код 2 означає, що вона відмовилася працювати, оскільки її конфігурація була хибною або вона нічого не просканувала. Пакет інтерфейсу не публікується в реєстрі. Ви зберігаєте побайтово зафіксовану копію зібраного пакета у своєму репозиторії як локальний пакет file: із фіксацією SHA256SUMS та перевіркою в конвеєрі, яка відхиляє копію, що відрізняється. Оскільки копія розміщена в репозиторії, перевірка її приймає.
Збірки для різних редакцій
Якщо ваше розширення постачається клієнтам обох редакцій, ви збираєте його окремо для кожної редакції, і кожне збирання відбувається у власному скомпонованому дереві. Компонування дерева означає взяття лише тих файлів, які належать до цієї редакції. Власний експорт 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 cloud. Самостійно розгорнутого Team не існує. Набір Team додає шість можливостей понад Community, серед них консолідовану робочу панель, спільні блокноти, адміністрування бібліотеки навичок і операції з робочими процесами з просуванням між середовищами.
Для розробника «лише хмара» означає одне: клієнт Team отримує ваш плагін як підписаний випуск через каталог, ніколи з ваших власних серверів. Ви збираєте його так, як це робить сторонній видавець, на кластері видавця.
Кластер видавця — це віртуальний кластер в Adverant cloud із квотою, встановленою 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. Скажіть оператору зупинитися на цьому й зв'язатися з вами; існує нестрогий перемикач, і його ніколи не слід використовувати.
Три правила забезпечили наше постачання:
- Довірений ключ передається окремо від пакета. Ми надсилаємо публічний ключ і SHA-256 пакета іншим шляхом, ніж носії, щоб пакет не міг засвідчувати сам себе.
- Ніщо в пакеті не повинно потребувати мережі під час встановлення. Жодного завантаження пакетів, жодного завантаження моделей, жодного звернення щодо ліцензії. Якщо плагіну потрібна модель, її надає власний сервер моделей клієнта через AI (штучний інтелект) Provider Router.
- Після перевірки оператор вводить випуск через власні канали випусків інсталяції, точно так, як це зробив би підключений клієнт. Пакет — це спосіб доставки байтів, а не обхід шлюзів просування.
Робота в ізольованому середовищі повільніша, і з нашого боку це не виправити. Хибний байт коштує нового комплекту носіїв і ще однієї поїздки, тому ми самі перевіряємо пакет на чистій машині тією самою командою, перш ніж він покине будівлю.
Пакети місій Nexus Edge
Nexus Edge — це компактніша версія Nexus, яка працює на супутниках і дронах, на місійних комп'ютерах, відокремлених від бортового комп'ютера керування польотом. Це доповнення з ліцензією на платформу або на парк. Від однієї місії до наступної змінюється місійний пакет, і створення таких пакетів — значна частина моєї роботи.
Місійний пакет містить те, що потрібно корисному навантаженню для однієї місії. Окрім моделей і адаптерів, він містить онтологію з початковим графом, кроки агентів, правила сповіщень, пріоритети щодо того, що передається на землю першим, таблицю розміщення, яка визначає, який комп'ютер що виконує, деградовані кроки, до яких платформа може перейти в разі збою комп'ютера, і тестові сценарії, які пакет має пройти на борту.
Пакети створюються й підписуються на землі. Кілька практичних правил із нашого досвіду збирання:
- Залишайте великі частини незмінними. У Maritime watch 1.5 додано адаптер пошуку суден і два правила сповіщень; мовна модель і онтологія не змінилися, тож пакет мав розмір 412 MB замість 9.8 GB. Канал висхідного зв'язку вузький, а базові моделі завантажуються до запуску.
- Використовуйте одну модель ембедингів для всього сімейства місій — як на землі, так і в корисному навантаженні, щоб зміни графа, які надходять на землю, можна було об'єднати з наземним графом.
- Корисне навантаження ніколи не надсилає команд системам керування польотом. Воно надсилає типізовані запити через супервізор до бортового комп'ютера, який відповідає на кожен із зазначенням причини.
- Для кожного типу апаратного забезпечення потрібна окрема перевірка пакета. Встановлення пакета, не перевіреного для апаратного забезпечення пристрою, відхиляється з
PACK_NOT_CHECKED_FOR_HARDWARE.
Для випуску потрібні два підписи з трьох. Зазвичай це наш підпис і підпис 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) прив'язані до домену, на якому користувач входить. Вебзастосунок на власному джерелі (origin) виконує вхід користувачів через допоміжні засоби входу SDK, два публічні маршрути яких є єдиними незахищеними маршрутами /api, які приймає шлюз областей доступу, і лише тоді, коли маніфест оголошує їх auth: public з allowAnonymous: true. Виклики з фронтенду проходять через проксі зі списком дозволених адрес backend for frontend і ніколи не надходять безпосередньо на адресу сервісу. Платіжну частину — від шлюзів до брендованої сторінки оформлення замовлення — налаштовує адміністратор клієнта. Ваш плагін цього не робить.
Матриця
| Ціль збирання | Збирання на основі | Що ви робите інакше | Як це потрапляє до клієнта |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Код у GitHub; без доменного пакета чи шляхів платформи; без Elevate | Клієнт встановлює його сам; перевірка каталогу не потрібна |
| Enterprise (ваша власна інсталяція) | Plugin SDK, Skills Engine, шаблони пакетів | Простори розробки, гілки даних, замасковані копії разом із власником даних; пакети й лінзи | Просування зі staging до пілотного підрозділу, потім — усюди |
| Модуль 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 «Сценарії збирання» наведено рецепт для кожного рядка вище.



