Yabanin オフ ライン(エアギャップ)バンドル — ビルドと検証
ネットワークに接続されたマシンで自己完結型の Yabanin バンドルを作り、ネットワークが一切ないマシンで検証・インストールする方法です。バンドルが使うのは、make release-artifacts と docker build がすでに生成する成果物だけです。バイナリと SHA256SUMS、SBOM、NOTICE 草案、任意の cosign 署名、保存済みコンテナイメージです。Kubernetes ベースのエアギャップ導入は、install-guide.md と airgap-checklist.md で別途扱います。このドキュメントは、最小の Docker/compose の経路です。
バンドルの内容
| ファイル | 生成元 | 用途 |
|---|---|---|
dist/release/yabanin-* | make release-artifacts | 静的サービスバイナリ(-trimpath、スタンプ済みのバージョン/コミット) |
dist/release/SHA256SUMS | make release-artifacts | すべてのバイナリに対する sha256 |
dist/release/SHA256SUMS.sig | make release-artifacts(COSIGN_KEY が設定されている場合のみ) | SHA256SUMS に対する cosign 鍵ペア署名(R078 D-B の署名対象) |
dist/release/yabanin-release.pub | make release-artifacts( 署名時) | COSIGN_KEY に対応する公開鍵。自動的にエクスポートされる(公開物のみ) |
dist/release/sbom.spdx.json または dist/release/*.buildinfo + sbom.source | make release-artifacts | SBOM(syft SPDX)。syft がインストールされていない場合のフォールバックは go version -m のビルドマニフェスト。sbom.source は、どの経路で生成したかを記録する |
dist/release/THIRD-PARTY-NOTICES.md(+ NOTICE、NOTICE-litellm.txt) | scripts/release/notice_bundle.sh 経由の make release-artifacts | ライセンス棚卸しから作る配布用 NOTICE 草案。ライセンス識別子と、「全文は埋め込んでいない」という明示的な免責。レビュアーが配布前に全文を添付する |
dist/release/UNSIGNED-RELEASE-DISCLOSURE.md | make release-artifacts(未署名の場合のみ) | 未署名リリースに必要な、リリースノート用の開示フラグメント(D-D) |
images/*.tar + images/sbom-<image>.spdx.json | scripts/airgap/build_bundle.sh | イメージごとの SBOM を付けて保存したイメージ(syft。syft がない場合は、正直な buildinfo/UNAVAILABLE フォールバックマーカー。syft の出力は決して偽装しない) |
images/image-digests.txt(+ .sig) | scripts/airgap/build_bundle.sh | イメージごとに記録したレジストリダイジェスト。COSIGN_KEY が設定されている場合は、それらに対する cosign 鍵ペア署名(オフラインで検証可能。R078 D-B の対象) |
images.tar.gz | docker save | ハードニング済み Yabanin イメージ + pgvector/pgvector:pg16 + redis:7-alpine |
manifest.sha256 | sha256sum | バンドル内のすべてのファイルに対するチェックサム(イメージ、SBOM、ダイジェスト、NOTICE 資料 — インストール前の改ざんチェック) |
compose/airgap-compose.yml | deploy/onprem/airgap-compose.yml | build: がなく、レジストリ参照もない最小 compose |
秘密情報はバンドルに決して入れません。COSIGN_KEY も .env もパスワードも入れません。同梱するのは公開鍵だけです。
前提条件
ネットワークに接続されたビルドマシンで必要なもの:
goとmake(make release-artifacts用)。docker(イメージのビルド +docker save)。cosign— 任意ですが、署名付きバンドルには必須です。インストールされていない場合、make release-artifactsは署名をスキップし、リリースノート用にUNSIGNED-RELEASE-DISCLOSURE.mdを書き、strict モードは失敗します(下記を参照)。syft— 任意です。インストールされていない場合、SBOM はgo version -mのビルドマニフェスト(バイナリごとの.buildinfo。sbom.sourceに記録)にフォールバックします。これは正直なビルドメタデータですが、完全な SPDX SBOM ではありません。COSIGN_KEY— 署名用の秘密鍵のパス(オーナー鍵ペア、決定 D-A)。対応する公開鍵は、署名時にdist/release/yabanin-release.pubへ自動的にエクスポートされます。
strict モード(R078、オーナー決定 D-D)
RELEASE_STRICT=1 にすると、セットが不完全になる場合、両方の生成側が失敗します(exit 1、「incomplete release artifacts/bundle」)。不完全になる条件は、syft がない、COSIGN_KEY がない、NOTICE 草案用のライセンス監査がない、イメージごとの SBOM がない、または cosign が失敗することです(以前は build_bundle.sh 内の || true で握りつぶされていました)。
strict モードで未署名のまま出荷する唯一の方法は、明示的なオーナー上書きです。
RELEASE_STRICT=1 RELEASE_ALLOW_UNSIGNED=true make release-artifacts
上書きは、スクリプトの出力と UNSIGNED-RELEASE-DISCLOSURE.md にそのまま記録され、リリースノートに含めなければなりません。これは 2026-10-31 リリースで承認された経路です(開示付きで未署名のまま出荷します)。このリリースのあと、上書きなしの strict モードが必須です。検証側にも同じ規則が適用されます。strict 検証は、RELEASE_ALLOW_UNSIGNED=true が設定されていない限り、未署名または不完全なバンドルで FAIL します。許可したことは出力に表示されます。
執筆時点のリポジトリ作成環境では、cosign と syft はインストールされていません。完全な SPDX SBOM 付きの署名済みリリースを作る前に、インストールする前提条件として扱ってください。これらがなくても、バンドルはハッシュで検証できます。airgap-verify.sh は署名ステージを隠さず、SKIP(未署名)として報告します。--strict では FAIL になります。