バージョン 1.0.0-alpha.1最新
第 2.25 章
各エディション向けの構築
1つの拡張機能をすべてのエディション、エアギャップ環境、Nexus Edgeペイロード、または顧客の自社ブランド環境で動作させる必要がある場合に何が変わるかを解説します。Enterpriseモジュールのライセンス境界や署名付きオフライン配信を取り上げ、ターゲットごとに異なる対応をまとめたマトリックスを提供します。
このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

Corrán Orbitalでは、一般的なチームよりも多くの環境へ出荷しています。自社のエンジニアは地上でEnterpriseを稼働させています。人工衛星CORR-3は、Nexus Edge上でミッションパックを実行しています。2社の顧客は単一サーバー上でCommunityを稼働させており、1社はインターネットに一切接続しないエアギャップ環境のEnterpriseインストレーションを運用しています。さらに、ある保険会社向けには、同社のインストレーション上にパックを構築しました。基盤となるコードはほぼ共通しており、違いの大部分は「どこへの配置が許可されているか」および「どのようにそこへ届けるか」にあります。
この章では、それぞれのターゲットについて順番に見ていきます。対象とするビルド環境、触れることが許可されていない領域、そして成果物がどのように顧客へ届くのかを解説します。章末のマトリックスで、これらを1ページにまとめています。スキル、プラグイン、パック、モジュールの違いについては、第2.18章「拡張モデル」で説明しています。各エディション自体の詳細については、第2.2章「エディションの内部構造」で解説しています。
Communityとオープンコア
Communityは、Apache License, Version 2.0の下で提供されるオープンコアです。フォークして変更を加え、出荷することができます。同梱されているNOTICEファイルには、独自ブランドを付与する前に知っておくべき重要な点が1つ記載されています。それは、このライセンスは成果物の由来を示す目的以外でAdverantの名称や商標を使用する権利を許諾するものではない、という点です。
Communityの拡張方法は、Enterpriseを拡張する場合と同じです。Plugin SDK(ソフトウェア開発キット)は両エディションで同一のパッケージであり、フルサービステンプレートも22個の準拠ゲートも変わりません。これについては第2.21章「Plugin SDK」で解説しています。スキルも同様に機能します。カナリアリリースと2名承認はEnterprise限定ですが、Communityでもバージョン管理やテスト機能を備えたSkills Engineのクリエイターおよびライブラリ一式を利用できます。
Communityの開発者向けページでは同じゴールデンパスが提供されていますが、すぐに実感できる3つの違いがあります。
- コードは、インストレーション独自のリポジトリではなくGitHub上に配置されます。プラグインのゴールデンパスは、Enterpriseが使用するのと同じ固定テンプレートからGitHubリポジトリと開発スペースを作成します。画面DV18は、
room-bookingsを作成している様子を示しています。 - ドメインパックおよびプラットフォームのゴールデンパスはEnterprise専用です。Communityでは、プラグインとスキルに加え、稼働中の環境上でレンズやワークフローを構築します。
- CommunityのパスはElevateティアの手前で止まります。単一サーバー構成ではIDE(統合開発環境)から到達すべき本番環境が存在せず、サーバーは直接管理します。IDEからの試行は
PASS_TIER_REQUIREDで拒否されます。
小規模サーバー上のCommunity開発スペースは控えめな構成です。私たちが使用したものは2コア、メモリ8 GiBで、マニフェストで宣言されたもの以外は閉じられており、7日間のアイドル状態の後に終了しました。
コントリビューションの還元
Skills EngineもApache-2.0であり、通常の方法でコントリビューションを受け付けています。リポジトリをフォークし、mainからブランチを作成し、テストを含めて変更を加え、プルリクエストを作成する前にチェックを実行してください。
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheck動作を変更するコントリビューションには、その変更がなければ失敗するテストが必要です。これは単なる社内スタイルではありません。SDK自体のテスト規則により、すべての新しいテストは変更前のツリーで失敗することが示されなければならず、レビュアーはその証拠を求めます。
Enterpriseモジュールとライセンス境界
Enterpriseは、Communityにライセンス対象モジュールを加えたものです。ライセンス対象モジュールとは、Communityのサービスが起動時に読み込む個別のアーティファクトであり、Enterpriseの機能や、Enterprise顧客向けに構築されたクローズドモジュールをオープンコアに接続するための仕組みです。
これを機能させるルールがライセンス境界(ライセンスライン)です。クローズドモジュールは、サービスプロバイダーインターフェースである@adverant/nexus-spiという単一のパッケージを通じてのみ、Communityエディションに到達できます。これはApache-2.0であり、インターフェースと、ホストおよびモジュールが互いをチェックするために使用する型ガードのみを保持し、他のランタイムロジックは含みません。この境界を越える結合はインターフェースまたはネットワークプロトコルであり、ソースコードであってはなりません。
| エクスポート | その内容 |
|---|---|
RouteModule |
ライセンス対象のルートモジュール:id、featureGroup、bodies、および自身のルーターをホストのアプリにマウントするregister(app, ctx) |
SpiApp |
モジュールが触れるホストのHTTPアプリの部分:use |
SpiContext |
ホストがモジュールに渡すもの:プロダクトゲートとスコープガード、ライセンスリーダー、スコープ付きクエリプール、サービスのスキーマ、アップストリームアドレス、およびプラットフォームクライアント |
SpiRuntime |
モジュールがSDKのランタイム自体を直接インポートしないようにするために、ホストがモジュールに渡すPlugin 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はライセンス境界が許可しないCommunityパッケージであるため、モジュールがPlugin SDKのランタイムを直接インポートすることもありません。モジュールが呼び出すSDKの値はホストから渡されます。モジュールを読み込む前に、ホストはglobalThis上にSymbol.for(SPI_HOST_KEY)をキーとして、SDKランタイムとアプリ独自のルートキットを保持するSpiHostをインストールします。これは最初に行われる必要があります。1つのバンドルにコンパイルされたモジュールは全体として評価されるため、読み込み中にSDKの値を読み取るコードにとっては、registerの呼び出しでは遅すぎるためです。型については、@adverant/nexus-spi/sdk/<module>が1つのSDKリリースから変更なしでベンダリングされチェックサムで固定されたSDKの宣言を再エクスポートするため、モジュールはプラグインが使用するのと同じ拒否ボディおよびクライアントに対して型チェックを行うことができます。
画面モジュールはもう1つのルールに従います。それは「1つの機能グループにつき1つのモジュール」というルールです。そのため、画面が2つの機能グループに属するグループは2つのモジュールとして出荷され、そのうちの1つだけがメニュー行を保持します。
ライセンス境界ゲートが拒否するもの
Adverantのライセンス境界ゲートは、すべてのEnterpriseモジュールにこの境界を遵守させており、独自のクローズドモジュールにも同じルールを適用する価値があります。その設定は1つのファイルで行われます。
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}以下のそれぞれは、該当するファイルと行番号とともに検出項目(ファインディング)として報告されます。
- 許可されたインターフェースまたはEnterpriseパッケージではない、Communityスコープ下のパッケージのインポート(動的インポートを含む)。
- Communityリポジトリを指定する指定子(specifier)、Goインポートパス、または依存関係URL(ただし、
allowedCommunityGoModulesにリストされているGoモジュールを除く)。 - リポジトリの外へ遡る相対インポート。
- リポジトリ外の
file:、link:、portal:、またはworkspace:パスであるpackage.jsonの依存関係、あるいはCommunityリポジトリへのGit URL。 - リポジトリ外を指す
go.modのreplace。
問題がなければ終了コード0、検出項目がある場合は1で終了します。終了コード2は、設定が不正であるかスキャン対象がなかったために拒否されたことを意味します。インターフェースパッケージはレジストリには公開されません。ビルドされたパッケージのバイト単位で固定されたコピーを、ローカルのfile:パッケージとしてリポジトリ内に保持し、SHA256SUMSでピン留めした上で、異なるコピーを拒否するチェックをパイプラインに組み込みます。コピーはリポジトリ内にあるため、ゲートはこれを受け入れます。
エディション別のビルド
拡張機能を両方のエディションの顧客に出荷する場合、エディションごとに1回ずつビルドを行い、各ビルドはそれぞれ専用に構成されたツリー(composed tree)内で行われます。ツリーを構成するとは、そのエディションに属するファイルのみを抽出することを意味します。Adverant自身のエクスポート処理は、追跡対象のすべてのファイルが最初の一致優先(first-match-wins)ルールによって割り当てられる境界リストからこれを行います。ルールは機能(capability)を指定し、ファイルのエディションはその機能のエディションマトリックスにおけるティアに従うか、あるいは理由とともにどちらのエディションにも出荷しないファイルのクラスを指定します。ビルド専用ファイルはEnterpriseツリーに出荷され、マークされている場合はCommunityツリーにも出荷されます。モジュールのマイグレーションチェーンはインストーラーデータであり、すべてのエディションのツリーに出荷されます。
その後、構成された各ツリーでクリーンな状態からビルド全体を実行します。つまり、毎回以下の3つのコマンドすべてを実行します。
npm ci
npm test
npm run build私たちは高い代償を払ってこの教訓を得ました。必要な型がEnterpriseのファイルにしか存在しなかったために、Enterpriseツリーはテストに合格した一方で、Communityツリーは本番ビルドに失敗したのです。一方のツリーでテストが合格しても、もう一方のツリーについては何も保証されません。あるエディションのテストは、そのエディションのツリーが保持するもののみをインポートでき、エクスポート処理はツリーの外側にアクセスするテストを拒否します。
また、エクスポート処理は各エディションのライセンスも書き込みます。CommunityのファイルはSPDX(Software Package Data Exchange)識別子Apache-2.0を保持し、EnterpriseのファイルはLicenseRef-Adverant-Enterpriseを保持し、そのpackage.jsonにはUNLICENSEDと記載されます。これらのフィールドを手動で編集しないでください。エクスポート処理がこれらを書き換えるため、固定されたライセンステキストと一致しなくなったコピーは拒否されます。
Team:クラウド専用
TeamはCommunityにTeamセットを加えたもので、Adverantクラウド上でのみ稼働します。セルフホスト版のTeamは存在しません。Teamセットは、統合ワークパネル、共有ノートブック、スキルライブラリ管理、環境間のプロモーションを備えたワークフロー運用など、Communityの上に6つの機能を追加します。
ビルダーにとって、クラウド専用ということは1つのことを意味します。Teamの顧客は、あなたのプラグインを独自のサーバーからではなく、カタログを通じて署名付きリリースとして入手します。外部のパブリッシャーがビルドするのと同じ方法で、パブリッシャークラスター上でビルドを行います。
パブリッシャークラスターは、Adverantによってクォータが設定されたAdverantクラウド上の仮想クラスターです。サンプルデータのみを保持し、どの顧客へのルートも持ちません。そこで顧客データのマスクされたコピーを要求してもTENANT_BOUNDARYで拒否されます。顧客はテスト結果を共有することはできますが、データそのものを共有することは決してできません。そのクラスター上のパスが顧客環境に到達することはありません。リリースの準備ができると、カタログに掲載される前に署名され、Adverantによるレビューを受けます。その後、各顧客はそれをインストールするかどうかを選択し、マニフェストで宣言されているもののみをユニット単位で許可します。マニフェストで宣言されていないものへの呼び出しは顧客側でCONNECTION_SCOPE_EXCEEDEDにより拒否され、それを追加する唯一の方法は、顧客がレビューする新しいリリースを出すことです。
エアギャップ環境の顧客
私たちの顧客の1社は、ネットワークを介した入出力が一切ない環境でNexusを稼働させています。同社のインストレーションについては、第2.10章「エアギャップ環境へのインストール」で説明されています。私たちにとって、それは署名付きメディアでプラグインを出荷することを意味し、そのためのツールがソブリンデリバリーキット@adverant/nexus-sovereignに含まれるnexus-airgapです。
シールドバンドル(封緘バンドル)は、署名された自己完結型の単一tarballです。イメージやマイグレーション、事前署名されたスキルやモデルの重み、そして内部のあらゆる要素のライセンスを含む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で失敗します。その場合はそこで作業を止め、あなたに連絡するようオペレーターに伝えておいてください。非厳密(non-strict)スイッチも存在しますが、決して使用させてはなりません。
私たちのデリバリーは3つのルールに支えられていました。
- 信頼された鍵はバンドルとは別に送付します。バンドルが自分自身を保証できないようにするため、公開鍵とバンドルのSHA-256はメディアとは異なる経路で送信します。
- バンドル内のいかなる要素も、インストール時にネットワークを必要としてはなりません。パッケージのフェッチも、モデルのダウンロードも、ライセンスの呼び出しも行いません。プラグインがモデルを必要とする場合は、顧客自身のモデルサーバーがAI(人工知能)Provider Routerを通じてそれを提供します。
- 検証後、オペレーターは接続環境の顧客とまったく同じように、インストレーション自体のリリースチャネルを通じてリリースを取り込みます。バンドルはバイトデータを届ける手段であり、プロモーションゲートを回避する手段ではありません。
エアギャップ環境での作業は時間がかかり、私たちの側からそれを短縮する方法はありません。1バイトでも誤りがあれば、新しいメディア一式と再度の移動が必要になるため、出荷前にクリーンなマシン上で同じコマンドを使って自分たち自身でバンドルを検証しています。
Nexus Edgeミッションパック
Nexus Edgeは、人工衛星やドローン上で、フライトコンピューターとは分離されたミッションコンピューター上で稼働する小型のNexusです。プラットフォームまたはフリート単位のライセンスを持つアドオンです。ミッションごとに変わるのはミッションパックであり、それらをビルドすることは私の仕事の重要な部分を占めています。
ミッションパックには、1回のミッションでペイロードが必要とするものが格納されます。モデルやアダプターと並んで、初期グラフを含むオントロジー、エージェントのステップ、アラートルール、何を優先してダウンリンクするかの優先順位、どのコンピューターが何を実行するかを示す配置テーブル、コンピューター障害時にプラットフォームが段階的に機能を落とすための縮退ステップ、そして機上で合格しなければならないテストケースを保持します。
パックは地上でビルドされ、署名されます。私たちのビルドから得たいくつかの実践的なルールを紹介します。
- サイズの大きい部分は安定させておくこと。Maritime watch 1.5では船舶検出アダプターと2つのアラートルールを追加しましたが、言語モデルとオントロジーは変更しなかったため、パックのサイズは9.8 GBではなく412 MBで済みました。アップリンクの帯域は狭く、ベースモデルは打ち上げ前にロードされます。
- 地上とペイロードの双方で、ミッションファミリー全体に単一の埋め込みモデルを使用すること。これにより、ダウンリンクされたグラフの変更を地上のグラフとマージできます。
- ペイロードはフライトシステムに直接コマンドを送信してはなりません。スーパーバイザーを介してフライトコンピューターに型付きリクエストを送信し、フライトコンピューターはそれぞれに対して理由を添えて応答します。
- ハードウェアの種類ごとにパックの独自チェックが必要です。デバイスのハードウェア向けにチェックされていないパックのインストールは、
PACK_NOT_CHECKED_FOR_HARDWAREで拒否されます。
リリースには3つのうち2つの署名が必要です。通常は私たちとAdverantのペアを使用し、3つ目は他の2つのいずれかが失われた場合のために金庫に保管しているオフライン鍵です。パックはアイドルスロットにアップロードされ、検証され、実機のボード上でテストケースを実行し、すべて合格した場合にのみ有効化されます。古いパックが再インストールされるのを防ぐカウンターも備えています。テストに失敗した場合、プラットフォームは前のパックに留まり、失敗の詳細は次の通信パスでダウンリンクされます。私たちは1週間問題がないことを確認しながら、1プラットフォームずつロールアウトします。プラットフォームが通信圏外にある間もパックは有効なままであるため、リンクのない人工衛星も保持しているパックで稼働し続けます。
車両や船舶では、Edgeはk3s上で稼働できます。宇宙機では、Kubernetesの代わりに署名付きイメージまたは静的バイナリと固定の配置テーブルを持つスーパーバイザーを実行します。配置テーブルがパック内に同梱されて送られるのはそのためです。
ホワイトラベルのストアフロント
Storefront / ホワイトラベルアドオンを使用すると、顧客はユーザーに表示される画面に独自のブランドとドメインを設定し、独自のサインイン画面を用意し、独自のゲートウェイを通じて決済を受け付けることができます。カードの詳細情報がNexusに触れることは一切ありません。
ホワイトラベル顧客向けにビルドされたプラグインは、決して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はこれと一致しなければなりません。独自オリジン上のWebアプリは、SDKのサインインヘルパーを通じてユーザーをサインインさせます。その2つの公開ルートは、スコープゲートが受け入れる唯一の保護されていない/apiルートであり、マニフェストがそれらをallowAnonymous: trueとともにauth: publicと宣言している場合にのみ許可されます。フロントエンドの呼び出しはサービスのアドレスに直接向かうのではなく、BFF(Backend for Frontend)の許可リストプロキシを経由します。ゲートウェイからブランド化されたチェックアウトに至るまで、決済側の設定は顧客の管理者が行います。あなたのプラグインは関与しません。
マトリックス
| ビルドターゲット | ビルド対象(依存先) | 異なる点 | 顧客への到達方法 |
|---|---|---|---|
| Community | Plugin SDK、Skills Engine | コードはGitHub上。ドメインパックやプラットフォームパスなし。Elevateなし | 顧客がインストール。カタログレビューは不要 |
| Enterprise(自社インストレーション) | Plugin SDK、Skills Engine、パックテンプレート | 開発スペース、データブランチ、データ所有者の承認によるマスクされたコピー。パックとレンズ | ステージングからパイロットユニットへ、その後全体へプロモーション |
| Enterpriseモジュール(クローズド) | @adverant/nexus-spiのみ |
ライセンス境界ルール。自身の機能グループに対するグラントチェック。権限がない場合はLICENCE_LOCKED |
ライセンス付与されたインストレーション上で、起動時にCommunityサービスによって読み込まれる |
| 両エディション | プラグインSDK | 各エディションのツリーを構成。それぞれでnpm ci、テスト、本番ビルドを実行 |
エディションごとに1つのリリース |
| Team | パブリッシャークラスター上のPlugin SDK | サンプルデータのみ。クラウドのみ | 署名付きリリース、Adverantによるレビュー、カタログ |
| エアギャップ環境 | Plugin SDK、@adverant/nexus-sovereign |
シールドバンドル。鍵とチェックサムは別送。インストール時のフェッチなし | 署名付きメディア、検証、その後インストレーションのリリースチャネル |
| Nexus Edge | ミッションパックの内容 | 配置テーブル、縮退ステップ、機上テスト、ハードウェアチェック | 3つのうち2つの署名、アイドルスロット、テスト合格後に有効化 |
| ホワイトラベル | プラグインSDK | マニフェスト内のdomainsとbranding。いかなる場所にもAdverantの名称を出さない |
Enterpriseと同様(顧客自身のドメイン上) |
ターゲットが何であれ、デプロイはインストレーションのリリースチャネルを通じてのみ行われます。これらのチャネルについては、第2.28章「拡張機能のリリース」で解説しています。上記の各行に対応するレシピは、第2.27章「ビルドシナリオ」にあります。



