Skip to main content

Panduan pemasangan Yabanin di premis sendiri / jurang udara

Untuk laluan luar talian Docker/compose sahaja (binaan bundle, pengesahan checksum/tandatangan/SBOM, docker load, compose minimum tanpa rangkaian) lihat offline-bundle.md.

Prasyarat​

  • Kubernetes 1.28+ (atau serasi: OpenShift 4.14+, Rancher).
  • 3 nod pekerja, 16GB RAM setiap satu, 4 vCPU setiap satu.
  • Nod GPU (pilihan, untuk model tempatan: vLLM/Ollama). Operator NVIDIA disyorkan.
  • StorageClass yang menyokong ReadWriteOnce.
  • Trafik keluar DISEKAT pada peringkat rangkaian (keperluan jurang udara).
  • kubectl, helm 3.12+, docker (atau ctr) pada hos lompat dengan bundle jurang udara.

Langkah 1 — Salin bundle jurang udara​

Pindahkan yabanin-airgap-<tag>.tar.gz ke hos lompat (USB, scp melalui pautan peribadi).

Langkah 2 — Muat imej ke dalam registri luar talian​

scripts/airgap/load_bundle.sh yabanin-airgap-<tag>.tar.gz localhost:5000
# load_bundle.sh extracts the bundle, verifies manifest.sha256 (fails closed on
# any mismatch BEFORE docker load) and pushes every image to the registry.

Langkah 3 — Pasang (rahsia diberikan kepada helm, bukan dicipta terlebih dahulu)​

Carta menjana setiap Secret sendiri (<release>-secrets, -kek, -license); mencipta Secret terlebih dahulu dengan nama yang sama menyebabkan helm install gagal pada sumber yang bercanggah. Berikan nilai melalui --set/-f sebaliknya:

kubectl create namespace yabanin
helm install yabanin deploy/helm/yabanin-onprem \
-f deploy/helm/yabanin-onprem/values-airgap.yaml \
--set image.repository=localhost:5000/yabanin \
--set image.tag=<tag> \
--set secrets.pg_password=$(openssl rand -hex 16) \
--set secrets.cache_hmac_secret=$(openssl rand -hex 32) \
--set secrets.encryption_key=$(openssl rand -hex 32) \
--set secrets.session_key=$(openssl rand -hex 32) \
--set secrets.kek=$(openssl rand -hex 32) \
--set secrets.license=<vendor-issued-license-token>

Nota (disahkan secara langsung, R056-05):

  • secrets.pg_uri boleh kekal kosong — cangkuk migrate membina DSN pemilik daripada secrets.pg_password dan perkhidmatan postgres yang dibundel. Berikan secrets.pg_uri hanya apabila menggunakan postgres LUARAN (bundled.postgres=false).
  • secrets.cache_hmac_secret DIPERLUKAN apabila Redis dikonfigurasi (carta di premis sendiri sentiasa mengkonfigurasi Redis yang dibundel) dan mesti HEX — nilai bukan heks menyebabkan gerbang keluar dengan invalid cache_hmac_secret: cache signer: invalid hex secret.
  • Job migrate post-install berjalan secara automatik: ia menunggu postgres, menjalankan bootstrap peranan IMP-88 yabanin_app (idempoten; SQL tidak boleh dihantar dalam migrasi kerana pg_dump tidak boleh membawa peranan kluster) dan menggunakan migrasi dengan YABANIN_REGION ditetapkan. Job yang sama berjalan sebagai post-upgrade. Jika helm install melaporkan kegagalan cangkuk, semak kubectl -n yabanin get jobs sebelum menyahpepijat pod — perkhidmatan hanya bermula terhadap skema yang telah dimigrasikan.

Langkah 4 — Sahkan​

kubectl -n yabanin rollout status deploy/yabanin-gateway
kubectl -n yabanin port-forward svc/yabanin-gateway 18082:8082 &
curl -sf http://127.0.0.1:18082/healthz # expect {"redis":"up","status":"ok"}
curl -sf http://127.0.0.1:18082/healthz/license # licensed install: {"active":true,...}

(Perkhidmatan gerbang ialah ClusterIP; gunakan port-forward, atau tetapkan service.type kepada NodePort/LoadBalancer jika titik masuk luaran diperlukan.)

Langkah 5 — Dayakan model tempatan (pilihan)​

kubectl -n yabanin exec -it yabanin-postgres-0 -- \
psql -U yabanin -d yabanin -c \
"UPDATE models_registry SET enabled=true WHERE provider='vllm';"

Pemberat mesti dimuatkan terlebih dahulu pada PVC vLLM oleh pembeli (tiada muat turun dalam mod jurang udara); lihat permintaan pertama jurang udara.

Penyelesaian Masalah​

GejalaPembetulan
license invalid signaturekunci awam pembekal tidak sepadan — keluarkan semula token untuk binaan ini
ImagePullBackOffjalankan load_bundle.sh; sahkan image.repository menunjuk ke registri luar talian (image.registry BUKAN nilai carta)
invalid cache_hmac_secret ... invalid hextetapkan secrets.cache_hmac_secret HEX (openssl rand -hex 32)
role "yabanin_app" does not existcangkuk bootstrap post-install tidak selesai — semak Job migrate; cangkuk adalah idempoten, jalankan semula helm upgrade
OOMKillednaikkan gateway.resources.limits.memory; semak konsumer yang berulang panas
connection refused :5432statefulset postgres belum sedia — semak PVC terikat
Ralat RLS row-level securitymigrasi berjalan tanpa rantau — cangkuk menetapkan YABANIN_REGION; jalankan semula secara manual: YABANIN_REGION=onprem yabanin-migrate (rantau ialah pemboleh ubah persekitaran, bukan bendera)