Ugrás a fő tartalomra

Kubernetes

A Libre WebUI Helm chartot biztosít a helm/libre-webui könyvtárban.

Work Kubernetesen​

A Work natívan fut Kubernetesen — Docker daemon, CLI vagy socket nélkül. Telepítéskor így engedélyezze:

helm install libre-webui ./helm/libre-webui --set work.enabled=true

Ez beállítja a WORK_RUNTIME_BACKEND=kubernetes értéket, és létrehozza:

  • a külön sandbox-névteret (work.namespace, alapértelmezés szerint libre-webui-work), aktív sandboxonként egy Poddal és munkaterületenként egy PersistentVolumeClaimmel (work.workspaceSize, alapértelmezés szerint 5Gi — tényleges feladatonkénti kvóta; egy elnevezett házirend más értéket is megadhat);
  • a névtérre korlátozott Role és RoleBinding objektumokat, amelyek a ServiceAccount számára pontosan a pods (get/list/create/delete), pods/exec (get/create) és persistentvolumeclaims (get/list/create/delete) engedélyeket adják — titkok vagy clusterhatókör nélkül. Ezek teljesen kiváltják a Docker socketet: az API-szerver kikényszeríti, hogy a sandbox ne csatlakoztasson hostútvonalakat;
  • alapértelmezett tiltású NetworkPolicies szabályokat, amelyek csak a backend felől engednek bejövő forgalmat az előnézeti portra, a hálózattal rendelkező sandboxoknak pedig internetes kimenetet adnak a work.networkPolicy.blockedEgressCidrs tartományok kivételével (privát tartományok, egyes clusterek által használt CGNAT és link-local cloud metadata). Ellenőrizze a Pod- és szolgáltatás-CIDR-eket. A sandbox DNS-e csak a kube-system felé engedélyezett; a node-local DNS külön kivételt igényel.

A sandboxok nem root felhasználóként, csak olvasható rootfs-sel, capabilities nélkül, RuntimeDefault seccomppal és ServiceAccount-token nélkül futnak. A fájlok, parancsok, git és terminálok az API-szerveren keresztüli exec műveletet használják; az előnézet a Pod IP-jéről, aláírt same-origin proxyn keresztül érkezik, ezért a backendnek a clusteren belül kell futnia. Hostmappás munkaterület nem támogatott.

Két fontos megjegyzés: a NetworkPolicy csak akkor érvényesül, ha a CNI kikényszeríti (Calico, Cilium, újabb kind és a legtöbb felügyelt cluster). Mielőtt aktív elszigetelésként kezelné, ellenőrizze; a CI-készlet jelenti az érvényesítést. Soha ne csatlakoztassa a node konténer-runtime socketét a WebUI Podjához.

Telepítés​

helm install libre-webui oci://ghcr.io/libre-webui/charts/libre-webui

Az alapértelmezett chart tartós tárolással és beépített Ollamával telepíti a Librét. A 0.14.1 átmenet ellenőrzött többarchitektúrás digestre van rögzítve; a későbbi chartok a szemantikus appVersion image-et használják. Az image.tag vagy image.digest értéket csak tudatosan állítsa be. A nem üres image.tag elsőbbséget élvez az átmeneti digesttel szemben.

A solo profil replicaCount: 0 értékkel felfüggeszthető, replicaCount: 1 értékkel futtatható. A nagyobb értékeket és a HorizontalPodAutoscaler használatát elutasítja, mert az SQLite, a helyi fájlok és a folyamathoz kötött koordináció nem biztonságos több Poddal. Nulla értéknél létrejönnek a control plane erőforrásai, de forgalmat nem szolgál ki.

Több replikához használja a teljes team profilt: PostgreSQL/PGVector, S3-blobtárolás, Redis és külön tartós worker. A chart elutasítja a részleges megosztott/helyi keveréket. Induljon védett values fájlból:

replicaCount: 3

env:
  LIBRE_PLATFORM_MODE: team
  DATABASE_BACKEND: postgres
  DATABASE_SSL_MODE: verify-full
  POSTGRES_MIGRATION_MODE: apply
  POSTGRES_POOL_MAX: 10
  POSTGRES_CONNECT_TIMEOUT_MS: 5000
  POSTGRES_IDLE_TIMEOUT_MS: 30000
  POSTGRES_STATEMENT_TIMEOUT_MS: 30000
  POSTGRES_MIGRATION_LOCK_TIMEOUT_MS: 60000
  OLLAMA_TIMEOUT: 300000
  OLLAMA_LONG_OPERATION_TIMEOUT: 900000
  OLLAMA_MAX_CONTEXT: 32768
  BLOB_STORE_BACKEND: s3
  VECTOR_STORE_BACKEND: pgvector
  COORDINATION_BACKEND: redis
  JOB_WORKER_MODE: external
  STORAGE_ENCRYPTION_ACTIVE_KEY_ID: active
  S3_BUCKET: libre-blobs
  S3_REGION: us-east-1
  S3_BLOB_PREFIX: libre/blobs

worker:
  replicaCount: 1

secrets:
  databaseUrl: postgresql://libre:replace-me@postgres.example/libre
  redisUrl: rediss://redis.example:6379/0
  jwtSecret: '<one-stable-high-entropy-secret-for-every-replica>'
  encryptionKey: '<legacy-64-character-lowercase-hex-key>'
  storageEncryptionKeys: '{"legacy":"<legacy-64-character-lowercase-hex-key>","active":"<active-64-character-lowercase-hex-key>"}'
  s3AccessKeyId: replace-me
  s3SecretAccessKey: replace-me

A secrets.encryptionKey értékének pontosan egyeznie kell a legacy bejegyzéssel, a térképnek pedig tartalmaznia kell a STORAGE_ENCRYPTION_ACTIVE_KEY_ID kulcsot. A secrets.jwtSecret legyen stabil, nagy entrópiájú érték, amely minden alkalmazás- és worker-Podban azonos; nélküle a chart elutasítja a team profilt, hogy a munkamenetek ne függjenek Pod-helyi anyagtól. Felügyelt PostgreSQL esetén tartsa meg az ellenőrzött TLS-t, és ne adjon driverfüggő TLS-paramétereket a databaseUrl értékhez. A poolkorlát Podonként érvényes, ezért legalább (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX kapcsolatot és tartalékot biztosítson.

helm upgrade --install libre-webui \
  oci://ghcr.io/libre-webui/charts/libre-webui \
  --values /absolute/path/to/libre-team-values.yaml

Ne commitolja a fájlt, és ne adjon át titkokat a --set használatával. Használjon titkosított munkafolyamatot. A szolgáltatókat és a Work-Podokat egymástól függetlenül skálázza. work.enabled=true mellett a külső worker ugyanazt az image-et, StorageClass-t, work.env értéket, Ollama-végpontot, timeoutokat és kontextust kapja, mint az alkalmazás, mert az embeddings, a beszélgetések és a Work-hívások ott futnak.

Egy aktív team alkalmazás (pozitív replicaCount vagy autoscaling) legalább egy workert igényel; a chart a nullát elutasítja. Teljes felfüggesztéshez a replicaCount és worker.replicaCount értéket is állítsa nullára. Csak az alkalmazás nullázása leürítési/helyreállítási, csak workerrel működő mód: nincs webfelület, de a sor feldolgozása folytatódik.

Team frissítése és séma-kompatibilitás​

A Libre pontos sémaverziót követel, és nem támogat vegyes vagy leállásmentes adatbázis-frissítést. Az alkalmazás és a worker Recreate stratégiát használ, így az egyes Deploymenteken belül nincs átfedés, de a Kubernetes nem hangolja össze őket egyetlen határként. Frissítés előtt állítsa le az ingresst, fejezze be vagy szakítsa meg a feladatokat, skálázza mindkettőt nullára, készítsen ellenőrzött mentést, és győződjön meg a Podok leállásáról. Ezután frissítsen POSTGRES_MIGRATION_MODE=apply beállítással; egy folyamat advisory leader lockot tart, a többi vár és ellenőrzi a naplót. Visszagörgetéshez a mentést tiszta PostgreSQL/S3 célra állítsa vissza; soha ne futtasson régi binárist inkompatibilis sémán. Szándékos szolgáltatáskiesés lesz.

Helyi hozzáférés​

kubectl port-forward svc/libre-webui 8080:8080

Nyissa meg a http://localhost:8080 címet.

Külső Ollama​

Használjon meglévő Ollama-végpontot:

helm install libre-webui oci://ghcr.io/libre-webui/charts/libre-webui \
  --set ollama.bundled.enabled=false \
  --set ollama.external.enabled=true \
  --set ollama.external.url=http://my-ollama:11434

Titkok​

Állítson be stabil JWT-titkot és titkosítási kulcsot. Alapértelmezés szerint a chart a nem üres secrets.* értékekből létrehozza a <release>-libre-webui-secrets objektumot:

helm upgrade --install libre-webui \
  oci://ghcr.io/libre-webui/charts/libre-webui \
  --set-string secrets.jwtSecret="$(openssl rand -hex 64)" \
  --set-string secrets.encryptionKey="$(openssl rand -hex 32)"

Az üzemeltető által kezelt Secret használatához állítsa be a secrets.existingSecret értéket; a chart ekkor nem hoz létre újat, az alkalmazás és a worker a megnevezett objektumra hivatkozik:

secrets:
  existingSecret: libre-webui-runtime

Hozza létre a kiadás előtt. Kötelező a jwt-secret és encryption-key, team módban pedig a database-url, redis-url és storage-encryption-keys is. Opcionális a session-secret, s3-access-key-id, s3-secret-access-key és s3-session-token. A GitHub/Hugging Face OAuth a *-client-id/*-client-secret értékeket olvassa, amikor a nem üres secrets.githubClientId vagy secrets.huggingfaceClientId engedélyezi az integrációt. A chart nem ellenőrzi és nem másolja az értékeket; hiányzó kulcs megakadályozza a Pod indulását.

Automatizáláshoz részesítse előnyben a secrets.existingSecret használatát external-secrets vagy titkosított értékfájlok mellett. A --set látható lehet a folyamatlistában és a Helm-metaadatokban. A szolgáltatói hitelesítő adatokat tudatos chartbővítéssel vagy felhasználónként a WebUI-ban adja meg.

NetworkPolicies az alkalmazáshoz és a workerhez​

Az alkalmazás és a team worker bejövő házirendjeihez állítsa be a networkPolicy.enabled=true értéket:

networkPolicy:
  enabled: true

Az alkalmazás csak a HTTP-porton fogad bejövő forgalmat, a worker semmilyen porton. A házirendek nem korlátozzák a kimenő forgalmat: a folyamatoknak el kell érniük a PostgreSQL-t, Redist, S3-at, Ollamát, eszközöket és szolgáltatókat; ezek helyét az üzemeltető határozza meg.

Ez különálló a work.networkPolicy.enabled beállítástól, amely a Work namespace-ben alapértelmezett tiltást alkalmaz, és Work mellett alapból aktív. Mindkettő CNI-érvényesítést igényel; az objektumok renderelése önmagában nem bizonyít elszigetelést.

Tartós tárolás​

Az adat-PVC-t és az Ollamát tartós tárolón tartsa. A kötetről és a titkosítási kulcsról együtt készítsen mentést.

A Work-munkaterületek saját PVC-ket kapnak a sandbox-névtérben, nem az adat-PVC-t használják. A teljes helyreállításhoz az adatbázis (tulajdonjog, nevek, futások) és a PVC-k is szükségesek; együtt mentse őket.

Ingress​

Nyilvános hozzáféréshez állítson be HTTPS-t és pontos eredetet:

helm upgrade libre-webui \
  oci://ghcr.io/libre-webui/charts/libre-webui \
  --reuse-values \
  --set env.TRUST_PROXY=1 \
  --set-string env.CORS_ORIGIN=https://your-domain.example

A TRUST_PROXY a köztes hopok pontos száma, nem logikai érték. A biztonságos 0 alapérték figyelmen kívül hagyja a továbbított címeket. Az 1 csak egyetlen közvetlen ingressnél helyes; számoljon meg minden load balancert a rögzített láncban, és tartsa a Service-t azon kívül elérhetetlenül. Túl alacsony érték összecsoportosítja a klienseket és kimeríti a bejelentkezési korlátokat; túl magas érték megbízik a kliens által megadott címben. A chart 0–16 értéket fogad el, true értéket soha, és csak a HTTP-t kiszolgáló Podoknak adja át.

A chart nem teszi elérhetővé a BASE_URL vagy OAuth-callback értékeket. OAuth-telepítésnél bővítse a chartot vagy patch-elje a Deploymentet, az URL-eknek pedig meg kell egyezniük a nyilvános tartománnyal.

Erőforrás-tervezés​

Helyi Ollamánál a Podot elegendő memóriával/GPU-val rendelkező node-okra ütemezze. Ha külön Ollama-/inferencia-szolgáltatás áll rendelkezésre, a külső változat egyszerűbb.

Kapcsolódó dokumentáció​