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
| File | Dihasilkan oleh | Tujuan |
|---|---|---|
dist/release/yabanin-* | make release-artifacts | binari perkhidmatan statik (-trimpath, versi/commit yang dicop) |
dist/release/SHA256SUMS | make release-artifacts | sha256 ke atas semua binari |
dist/release/SHA256SUMS.sig | make release-artifacts (hanya apabila COSIGN_KEY ditetapkan) | tandatangan pasangan kunci cosign ke atas SHA256SUMS (subjek penandatanganan R078 D-B) |
dist/release/yabanin-release.pub | make 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.source | make release-artifacts | SBOM (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.sh | draf 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.md | make release-artifacts (hanya apabila tidak bertandatangan) | fragmen pendedahan nota keluaran yang diperlukan bagi keluaran tidak bertandatangan (D-D) |
images/*.tar + images/sbom-<image>.spdx.json | scripts/airgap/build_bundle.sh | imej 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.sh | digest 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.gz | docker save | imej Yabanin yang dikeraskan + pgvector/pgvector:pg16 + redis:7-alpine |
manifest.sha256 | sha256sum | checksum ke atas setiap file dalam bundle (imej, SBOM, digest, bahan NOTICE — semakan gangguan sebelum pemasangan) |
compose/airgap-compose.yml | deploy/onprem/airgap-compose.yml | compose 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:
godanmake(untukmake release-artifacts);docker(binaan imej +docker save);cosign— pilihan tetapi diperlukan untuk bundle bertandatangan; jika tidak dipasang,make release-artifactsmelangkau penandatanganan, menulisUNSIGNED-RELEASE-DISCLOSURE.mduntuk nota keluaran, dan mod ketat gagal (lihat di bawah);syft— pilihan; jika tidak dipasang, SBOM berundur kepada manifes binaango version -m(.buildinfobagi setiap binari, ditanda dalamsbom.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 kedist/release/yabanin-release.pubsecara 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
--insecure-ignore-tlogmelangkau carian log ketelusan yang memerlukan rangkaian (versi cosign yang lebih lama/lebih baharu menamakan bendera luar talian secara berbeza — semakcosign verify-blob --help;airgap-verify.shmemilih bendera yang betul secara automatik). Bagi bundle yang dibina olehscripts/airgap/build_bundle.shsemakan yang sama terpakai padaimages/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
- Skrip mencetak satu baris
PASS/SKIP/FAILbagi setiap peringkat dan keluar dengan kod bukan sifar pada mana-manaFAIL. Langkauan adalah jujur (contohnya bundle tidak bertandatangan melaporkanSKIP signature, ia tidak dikira sebagai lulus). Setiap tindakan berkeupayaan rangkaian sama ada dielakkan (--pull=never, tiada curl/wget) atau dineutralkan (--network none). Tambah--strict(atauRELEASE_STRICT=1) untuk menjadikan himpunan yang tidak bertandatangan/tidak lengkap — tandatangan tiada, draf NOTICE, SBOM SPDX, SBOM per imej, digest imej tidak bertandatangan — sebagaiFAIL; satu-satunya jalan keluar tanpa tandatangan ialahRELEASE_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
- Pada mesin yang bersambung: kemas kini kod, bina semula artifak
(
make release-artifacts), bina semula imej dengan tag versi baharu, himpunyabanin-offline-<new-version>.tar.gzyang baharu (Langkah 1–3). - Pindahkan, sahkan (Langkah 4), kemudian
docker loadimej baharu dan kemas kini tagimage:dalamcompose/airgap-compose.yml;docker compose up -dmencipta semula perkhidmatan. - 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_KEYpada masa binaan, bundle tidak bertandatangan;airgap-verify.shmelaporkanSKIP signature(atauFAILdi bawah--strict, hanya boleh ditimpa olehRELEASE_ALLOW_UNSIGNED=trueyang direkod, D-D).UNSIGNED-RELEASE-DISCLOSURE.mddijana untuk nota keluaran. Keperluan perolehan yang mewajibkan provenans memerlukan varian bertandatangan. - Tanpa
syft, SBOM ialah manifes binaango version -mper binari, bukan JSON SPDX (ditanda dalamsbom.source); SBOM per imej berundur kepada ekstrak buildinfo yang jujur bagi imej Yabanin atau penandasbom-*.UNAVAILABLE.txtyang eksplisit — output syft tidak sekali-kali dipalsukan, dan mod ketat menolak semua sandaran. Rekod varian sandaran dalam nota penghantaran. THIRD-PARTY-NOTICES.mdialah 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.txtmerekod digest registri;docker save/loadtidak mengiranya semula, jadi semakan luar talian mengesahkan ikatan tandatangan pada senarai yang direkodkan sertamanifest.sha256ke atas tarball — kesepadanan tar→digest itu sendiri dipercayai daripada mesin binaan (yang bersambung).- Compose minimum hanya mendedahkan gerbang pada
127.0.0.1:8082dan 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 subperintahversiondijejaki sebagai susulan RM-52.scripts/airgap/build_bundle.shmengautomatikkan 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. Pembungkusaninstall.shdaripada kad RM-53 asal masih belum dilaksanakan;airgap-verify.shmengautomatikkan separuh pengesahan.