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,helm3.12+,docker(atauctr) 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_uriboleh kekal kosong — cangkuk migrate membina DSN pemilik daripadasecrets.pg_passworddan perkhidmatan postgres yang dibundel. Berikansecrets.pg_urihanya apabila menggunakan postgres LUARAN (bundled.postgres=false).secrets.cache_hmac_secretDIPERLUKAN apabila Redis dikonfigurasi (carta di premis sendiri sentiasa mengkonfigurasi Redis yang dibundel) dan mesti HEX — nilai bukan heks menyebabkan gerbang keluar denganinvalid cache_hmac_secret: cache signer: invalid hex secret.- Job migrate
post-installberjalan secara automatik: ia menunggu postgres, menjalankan bootstrap peranan IMP-88yabanin_app(idempoten; SQL tidak boleh dihantar dalam migrasi kerana pg_dump tidak boleh membawa peranan kluster) dan menggunakan migrasi denganYABANIN_REGIONditetapkan. Job yang sama berjalan sebagaipost-upgrade. Jikahelm installmelaporkan kegagalan cangkuk, semakkubectl -n yabanin get jobssebelum 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
| Gejala | Pembetulan |
|---|---|
license invalid signature | kunci awam pembekal tidak sepadan — keluarkan semula token untuk binaan ini |
ImagePullBackOff | jalankan load_bundle.sh; sahkan image.repository menunjuk ke registri luar talian (image.registry BUKAN nilai carta) |
invalid cache_hmac_secret ... invalid hex | tetapkan secrets.cache_hmac_secret HEX (openssl rand -hex 32) |
role "yabanin_app" does not exist | cangkuk bootstrap post-install tidak selesai — semak Job migrate; cangkuk adalah idempoten, jalankan semula helm upgrade |
OOMKilled | naikkan gateway.resources.limits.memory; semak konsumer yang berulang panas |
connection refused :5432 | statefulset postgres belum sedia — semak PVC terikat |
Ralat RLS row-level security | migrasi berjalan tanpa rantau — cangkuk menetapkan YABANIN_REGION; jalankan semula secara manual: YABANIN_REGION=onprem yabanin-migrate (rantau ialah pemboleh ubah persekitaran, bukan bendera) |