Skip to main content

Bundle luar talian (jurang udara) Yabanin — bina & sahkan

Cara menghasilkan bundle Yabanin yang serba lengkap pada mesin yang bersambung dan mengesahkan/memasangnya pada mesin tanpa sebarang rangkaian. Bundle hanya menggunakan artifak yang make release-artifacts dan docker build telah hasilkan: binari + SHA256SUMS, SBOM, draf NOTICE, tandatangan cosign pilihan, dan imej kontena yang disimpan. Pemasangan jurang udara berasaskan Kubernetes diliputi secara berasingan dalam install-guide.md dan airgap-checklist.md; dokumen ini ialah laluan Docker/compose yang minimum.

Kandungan bundle​

FileDihasilkan olehTujuan
dist/release/yabanin-*make release-artifactsbinari perkhidmatan statik (-trimpath, versi/commit yang dicop)
dist/release/SHA256SUMSmake release-artifactssha256 ke atas semua binari
dist/release/SHA256SUMS.sigmake release-artifacts (hanya apabila COSIGN_KEY ditetapkan)tandatangan pasangan kunci cosign ke atas SHA256SUMS (subjek penandatanganan R078 D-B)
dist/release/yabanin-release.pubmake release-artifacts (semasa menandatangani)kunci awam yang sepadan dengan COSIGN_KEY, dieksport secara automatik (bahan awam sahaja)
dist/release/sbom.spdx.json atau dist/release/*.buildinfo + sbom.sourcemake release-artifactsSBOM (syft SPDX), atau manifes binaan go version -m sebagai sandaran apabila syft tidak dipasang; sbom.source merekod laluan mana yang menghasilkannya
dist/release/THIRD-PARTY-NOTICES.md (+ NOTICE, NOTICE-litellm.txt)make release-artifacts melalui scripts/release/notice_bundle.shdraf NOTICE penghantaran daripada inventori lesen — pengecam lesen dengan penafian eksplisit "teks penuh tidak dibenamkan"; penyemak melampirkan teks penuh sebelum pengedaran
dist/release/UNSIGNED-RELEASE-DISCLOSURE.mdmake release-artifacts (hanya apabila tidak bertandatangan)fragmen pendedahan nota keluaran yang diperlukan bagi keluaran tidak bertandatangan (D-D)
images/*.tar + images/sbom-<image>.spdx.jsonscripts/airgap/build_bundle.shimej yang disimpan dengan SBOM per imej (syft; penanda sandaran buildinfo/UNAVAILABLE yang jujur apabila syft tiada — output syft tidak sekali-kali dipalsukan)
images/image-digests.txt (+ .sig)scripts/airgap/build_bundle.shdigest registri yang direkodkan bagi setiap imej dan, apabila COSIGN_KEY ditetapkan, tandatangan pasangan kunci cosign ke atasnya (boleh disahkan luar talian; subjek R078 D-B)
images.tar.gzdocker saveimej Yabanin yang dikeraskan + pgvector/pgvector:pg16 + redis:7-alpine
manifest.sha256sha256sumchecksum ke atas setiap file dalam bundle (imej, SBOM, digest, bahan NOTICE — semakan gangguan sebelum pemasangan)
compose/airgap-compose.ymldeploy/onprem/airgap-compose.ymlcompose minimum dengan tiada build: dan tiada rujukan registri

Rahsia tidak sekali-kali diletakkan dalam bundle: tiada COSIGN_KEY, tiada .env, tiada kata laluan. Hanya kunci awam yang dihantar.

Prasyarat​

Pada mesin binaan yang bersambung:

  • go dan make (untuk make release-artifacts);
  • docker (binaan imej + docker save);
  • cosign — pilihan tetapi diperlukan untuk bundle bertandatangan; jika tidak dipasang, make release-artifacts melangkau penandatanganan, menulis UNSIGNED-RELEASE-DISCLOSURE.md untuk nota keluaran, dan mod ketat gagal (lihat di bawah);
  • syft — pilihan; jika tidak dipasang, SBOM berundur kepada manifes binaan go version -m (.buildinfo bagi setiap binari, ditanda dalam sbom.source), iaitu metadata binaan yang jujur tetapi bukan SBOM SPDX yang penuh;
  • COSIGN_KEY — laluan kunci penandatanganan peribadi anda (pasangan kunci pemilik, keputusan D-A). Kunci awam yang sepadan dieksport ke dist/release/yabanin-release.pub secara automatik semasa menandatangani.

Mod ketat (R078, keputusan pemilik D-D)​

RELEASE_STRICT=1 menyebabkan kedua-dua pengeluar gagal (exit 1, "incomplete release artifacts/bundle") apabila himpunan itu tidak lengkap: tiada syft, tiada COSIGN_KEY, tiada audit lesen untuk draf NOTICE, SBOM per imej tiada, atau kegagalan cosign (sebelum ini ditelan oleh || true dalam build_bundle.sh).

Satu-satunya cara untuk menghantar tanpa tandatangan dalam mod ketat ialah penimpaan pemilik yang eksplisit:

RELEASE_STRICT=1 RELEASE_ALLOW_UNSIGNED=true make release-artifacts

Penimpaan itu direkodkan secara harfiah dalam output skrip dan dalam UNSIGNED-RELEASE-DISCLOSURE.md, yang mesti dimasukkan dalam nota keluaran. Ini ialah laluan yang diratifikasi untuk keluaran 2026-10-31 (dihantar tanpa tandatangan dengan pendedahan); selepas keluaran itu, mod ketat tanpa penimpaan adalah wajib. Pada sisi pengesahan, peraturan yang sama terpakai: pengesahan ketat GAGAL pada bundle yang tidak bertandatangan/tidak lengkap melainkan RELEASE_ALLOW_UNSIGNED=true ditetapkan, dan kebenaran itu dicetak dalam output.

Dalam persekitaran penulisan repositori pada masa penulisan, cosign dan syft tidak dipasang; anggap kedua-duanya sebagai prasyarat untuk dipasang sebelum menghasilkan keluaran bertandatangan dengan SBOM SPDX yang penuh. Tanpa keduanya, bundle masih boleh disahkan melalui cincang, dan airgap-verify.sh melaporkan peringkat tandatangan sebagai SKIP (tidak bertandatangan) dan bukannya menyembunyikannya — atau FAIL di bawah --strict.

Langkah 1 — Bina artifak keluaran (mesin bersambung)​

# Without signing (records UNSIGNED-RELEASE-DISCLOSURE.md for the notes):
make release-artifacts

# With signing (preferred for air-gap delivery; D-A owner key-pair):
COSIGN_KEY=/secure/path/cosign.key make release-artifacts
# dist/release/yabanin-release.pub is exported automatically; it used to be:
# cosign public-key --key /secure/path/cosign.key > dist/release/yabanin-release.pub

# Strict, unsigned via the ratified 2026-10-31 override (D-D):
RELEASE_STRICT=1 RELEASE_ALLOW_UNSIGNED=true make release-artifacts

# Strict and signed (mandatory after the 2026-10-31 release):
RELEASE_STRICT=1 COSIGN_KEY=/secure/path/cosign.key make release-artifacts

Sasaran itu juga mengeluarkan draf NOTICE (THIRD-PARTY-NOTICES.md daripada inventori make licenses-report melalui scripts/release/notice_bundle.sh; jalankan make licenses-report dahulu) dan menjalankan ujian asap pada setiap binari (checksum disahkan semula dalam direktori bersih, maklumat binaan dibaca, binari dilaksanakan terhadap konfigurasi tidak sah — kegagalan tempatan yang pantas, tiada rangkaian).

Nota: binari perkhidmatan tidak menyokong --help; semakan pantas "adakah ia berjalan" bagi binari itu ialah konfigurasi yang sengaja tidak sah, yang mesti keluar dengan kod bukan sifar (inilah tepatnya yang make release-artifacts lakukan secara dalaman).

Langkah 2 — Bina dan simpan imej (mesin bersambung)​

VERSION=$(git describe --tags --always)
docker build -f Dockerfile.hardened -t "yabanin:hardened-${VERSION}" .

# Pin third-party images by digest for reproducibility (record the digests you use):
docker pull pgvector/pgvector:pg16
docker pull redis:7-alpine

mkdir -p dist/offline
docker save "yabanin:hardened-${VERSION}" pgvector/pgvector:pg16 redis:7-alpine \
| gzip > "dist/offline/images-${VERSION}.tar.gz"

Langkah 3 — Himpun bundle (mesin bersambung)​

VERSION=$(git describe --tags --always)
B="dist/offline/yabanin-offline-${VERSION}"
mkdir -p "${B}/dist" "${B}/compose"
cp -R dist/release "${B}/dist/release"
cp "dist/offline/images-${VERSION}.tar.gz" "${B}/images.tar.gz"
cp deploy/onprem/airgap-compose.yml "${B}/compose/airgap-compose.yml"

cd "$B"
find . -type f ! -name manifest.sha256 -print0 | sort -z \
| xargs -0 sha256sum > manifest.sha256
cd - >/dev/null

tar -czf "dist/offline/yabanin-offline-${VERSION}.tar.gz" -C dist/offline "yabanin-offline-${VERSION}"

Pindahkan yabanin-offline-<version>.tar.gz ke mesin jurang udara melalui media yang diluluskan (USB, scp melalui pautan peribadi). Sebelum pemindahan, sahkan bundle tidak mengandungi bahan peribadi: grep -r "BEGIN PRIVATE" dist/offline/yabanin-offline-*/ mesti tidak memulangkan apa-apa.

Langkah 4 — Sahkan pada mesin jurang udara​

tar -xzf yabanin-offline-<version>.tar.gz
cd yabanin-offline-<version>

Checksum — semakan gangguan ke atas keseluruhan bundle:

sha256sum -c manifest.sha256

Tandatangan (hanya jika SHA256SUMS.sig dan yabanin-release.pub ada dalam bundle):

cosign verify-blob --key yabanin-release.pub \
--signature dist/release/SHA256SUMS.sig \
--insecure-ignore-tlog dist/release/SHA256SUMS
  1. --insecure-ignore-tlog melangkau carian log ketelusan yang memerlukan rangkaian (versi cosign yang lebih lama/lebih baharu menamakan bendera luar talian secara berbeza — semak cosign verify-blob --help; airgap-verify.sh memilih bendera yang betul secara automatik). Bagi bundle yang dibina oleh scripts/airgap/build_bundle.sh semakan yang sama terpakai pada images/image-digests.txt.sig (tandatangan ke atas digest imej yang direkodkan — subjek R078 D-B). Sesuatu ketidakpadanan tandatangan sentiasa gagal, dalam mod ketat mahupun tidak ketat.

Muat imej — operasi tempatan, tiada registri:

gunzip -k images.tar.gz
docker load -i images.tar

Jalankan imej dengan rangkaian dilumpuhkan — membuktikan imej itu sendiri tidak memerlukan sambungan. Binari bersatu tiada subperintah version (hanya gateway, admin, loggerd, mcp, migrate, dev, license, completion, help), jadi gunakan --help:

docker run --rm --pull=never --network none "yabanin:hardened-<version>" --help

Satu perintah untuk semua di atas:

scripts/release/airgap-verify.sh \
--artifacts dist/release \
--manifest manifest.sha256 \
--pubkey yabanin-release.pub \
--image-tar images.tar --image "yabanin:hardened-<version>" \
--compose compose/airgap-compose.yml
  1. Skrip mencetak satu baris PASS/SKIP/FAIL bagi setiap peringkat dan keluar dengan kod bukan sifar pada mana-mana FAIL. Langkauan adalah jujur (contohnya bundle tidak bertandatangan melaporkan SKIP signature, ia tidak dikira sebagai lulus). Setiap tindakan berkeupayaan rangkaian sama ada dielakkan (--pull=never, tiada curl/wget) atau dineutralkan (--network none). Tambah --strict (atau RELEASE_STRICT=1) untuk menjadikan himpunan yang tidak bertandatangan/tidak lengkap — tandatangan tiada, draf NOTICE, SBOM SPDX, SBOM per imej, digest imej tidak bertandatangan — sebagai FAIL; satu-satunya jalan keluar tanpa tandatangan ialah RELEASE_ALLOW_UNSIGNED=true, direkod secara harfiah dalam output dan bertujuan untuk keluaran 2026-10-31 tanpa tandatangan yang didedahkan (D-D).

Langkah 5 — Compose luar talian yang minimum​

Jangan gunakan deploy/quickstart/docker-compose.yml secara luar talian: ia mengandungi bahagian build: dan akan mencetuskan binaan/tarikan. compose/airgap-compose.yml yang dibundel (sumber: deploy/onprem/airgap-compose.yml) hanya merujuk imej yang telah dimuatkan:

name: yabanin-airgap
services:
postgres:
image: pgvector/pgvector:pg16 # loaded from images.tar
environment:
POSTGRES_USER: yabanin
POSTGRES_PASSWORD: replace-me # generate: openssl rand -hex 16
POSTGRES_DB: yabanin
healthcheck:
test: ["CMD-SHELL", "pg_isready -U yabanin -d yabanin"]
interval: 2s
timeout: 5s
retries: 30

redis:
image: redis:7-alpine # loaded from images.tar
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 2s
timeout: 5s
retries: 30

migrate:
image: yabanin:hardened-<version> # loaded from images.tar
command: ["migrate"]
restart: "no"
environment:
YABANIN_PG_URI: postgres://yabanin:replace-me@postgres:5432/yabanin?sslmode=disable
YABANIN_REGION: onprem
depends_on:
postgres:
condition: service_healthy

gateway:
image: yabanin:hardened-<version>
command: ["gateway"]
environment:
YABANIN_PG_URI: postgres://yabanin:replace-me@postgres:5432/yabanin?sslmode=disable
YABANIN_REGION: onprem
YABANIN_REDIS_ADDR: redis:6379
YABANIN_GATEWAY_LISTEN: ":8082"
ports:
- "127.0.0.1:8082:8082"
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy

Hidupkan dan semak kesihatan daripada hos — imej yang dikeraskan ialah distroless dan tiada shell/curl, jadi semakan kesihatan berada pada hos:

docker compose -f compose/airgap-compose.yml up -d
curl -fsS http://127.0.0.1:8082/healthz # expect {"status":"ok"}

airgap-verify.sh --compose compose/airgap-compose.yml menggagalkan peringkat compose jika file mengandungi build: atau merujuk imej yang tiada dalam stor docker tempatan (iaitu sesuatu akan ditarik).

Langkah 6 — Kemas kini​

  1. Pada mesin yang bersambung: kemas kini kod, bina semula artifak (make release-artifacts), bina semula imej dengan tag versi baharu, himpun yabanin-offline-<new-version>.tar.gz yang baharu (Langkah 1–3).
  2. Pindahkan, sahkan (Langkah 4), kemudian docker load imej baharu dan kemas kini tag image: dalam compose/airgap-compose.yml; docker compose up -d mencipta semula perkhidmatan.
  3. Simpan bundle sebelumnya dalam arkib untuk gulung balik.

Langkah 7 — Gulung balik​

gunzip -k images-<old-version>.tar.gz && docker load -i images-<old-version>.tar
# point compose image: tags back to yabanin:hardened-<old-version>
docker compose -f compose/airgap-compose.yml up -d

Gulung balik aplikasi ialah pada peringkat imej dan selamat. Migrasi pangkalan data hanya ke hadapan; menggulung balik merentasi migrasi memerlukan pemulihan Postgres daripada sandaran yang diambil sebelum naik taraf.

Batasan (baca sebelum meluluskan pemasangan)​

  • Tanpa cosign/COSIGN_KEY pada masa binaan, bundle tidak bertandatangan; airgap-verify.sh melaporkan SKIP signature (atau FAIL di bawah --strict, hanya boleh ditimpa oleh RELEASE_ALLOW_UNSIGNED=true yang direkod, D-D). UNSIGNED-RELEASE-DISCLOSURE.md dijana untuk nota keluaran. Keperluan perolehan yang mewajibkan provenans memerlukan varian bertandatangan.
  • Tanpa syft, SBOM ialah manifes binaan go version -m per binari, bukan JSON SPDX (ditanda dalam sbom.source); SBOM per imej berundur kepada ekstrak buildinfo yang jujur bagi imej Yabanin atau penanda sbom-*.UNAVAILABLE.txt yang eksplisit — output syft tidak sekali-kali dipalsukan, dan mod ketat menolak semua sandaran. Rekod varian sandaran dalam nota penghantaran.
  • THIRD-PARTY-NOTICES.md ialah draf yang dijana daripada inventori lesen: ia menyenaraikan pengecam lesen dan secara eksplisit tidak membenamkan teks lesen penuh; lampirkan teks dan bukti semakan berskop (standards/license-compliance.md) sebelum pengedaran.
  • images/image-digests.txt merekod digest registri; docker save/load tidak mengiranya semula, jadi semakan luar talian mengesahkan ikatan tandatangan pada senarai yang direkodkan serta manifest.sha256 ke atas tarball — kesepadanan tar→digest itu sendiri dipercayai daripada mesin binaan (yang bersambung).
  • Compose minimum hanya mendedahkan gerbang pada 127.0.0.1:8082 dan menggunakan kelayakan pemegang tempat — jana rahsia sebenar (openssl rand -hex 16) dan ikut panduan konfigurasi penuh dalam install-guide.md.
  • yabanin <version> tidak wujud sebagai subperintah; semakan jalan luar talian ialah --help (lihat Langkah 4.4). Menambah subperintah version dijejaki sebagai susulan RM-52.
  • scripts/airgap/build_bundle.sh mengautomatikkan Langkah 1–3 (tarik, simpan, SBOM per imej, perekodan digest, penandatanganan, manifes, pembungkusan); langkah manual di atas kekal sebagai laluan yang disemak bagi bundle tersuai. Pembungkusan install.sh daripada kad RM-53 asal masih belum dilaksanakan; airgap-verify.sh mengautomatikkan separuh pengesahan.