Ana içeriğe geç

Kubernetes

Libre WebUI helm/libre-webui altında Helm chart’ı içerir.

Kubernetes’te Work​

Work, Docker daemonı, CLI’si veya socket’i olmadan yerel Kubernetes üzerinde çalışır:

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

Bu, WORK_RUNTIME_BACKEND=kubernetes ayarlar ve şunları oluşturur:

  • her çalışan kum havuzu için Pod ve görev çalışma alanı için PersistentVolumeClaim içeren özel ad alanı (work.namespace, varsayılan libre-webui-work; work.workspaceSize, varsayılan 5Gi, gerçek görev diski kotası ve adlandırılmış politika farklı boyut verebilir);
  • backend ServiceAccount’a yalnız o ad alanında pods (get/list/create/delete), pods/exec (get/create), persistentvolumeclaims (get/list/create/delete) veren Role ve RoleBinding — sır veya küme kapsamı yoktur. Bu Docker socket’ini tamamen değiştirir; ana bilgisayar yolu bağlanmasını API sunucusu engeller;
  • tüm kum havuzu trafiğini varsayılan reddeden, yalnız backend’den önizleme portuna girişi ve ağ etkin kum havuzlarına work.networkPolicy.blockedEgressCidrs dışındaki internet çıkışını veren NetworkPolicies. Özel, CGNAT ve metadata aralıkları varsayılan engellidir; kümenizin Pod/hizmet CIDR’lerini doğrulayın. DNS yalnız kube-system’e açıktır; node-local DNS özel istisna ister.

Kum havuzları root olmadan, salt okunur kök, tüm yetenekler kaldırılmış, seccomp RuntimeDefault ve ServiceAccount tokenı olmadan çalışır. Dosya, komut, Git ve terminal API exec alt kaynağını; önizleme Pod IP’sinden imzalı aynı kökenli proxy’yi kullanır, bu nedenle backend kümede çalışmalıdır. Ana bilgisayar klasörleri desteklenmez.

NetworkPolicy’nin uygulanması Calico, Cilium, yeni kind veya yönetilen küme gibi uygulayan CNI gerektirir; doğrulamadan yalıtım saymayın. WebUI Pod’una node kapsayıcı socket’i bağlamayın.

Kurulum​

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

Varsayılan chart kalıcı depolama ve paketli Ollama dağıtır. 0.14.1 geçişi doğrulanmış çok mimarili digest’e sabitlenmiştir; sonraki chart’lar eşleşen appVersion kullanır. Farklı image istiyorsanız image.tag veya image.digest açıkça ayarlayın; dolu image.tag geçiş digest’inden önceliklidir.

solo, bilinçli askıya alma için replicaCount: 0, normal çalışma için replicaCount: 1 kabul eder; SQLite, yerel dosya ve süreç içi koordinasyon nedeniyle daha büyüğünü ve HorizontalPodAutoscaler’ı reddeder. Sıfır replika denetim kaynaklarını kurar ancak trafik sunmaz.

Birden çok replika için PostgreSQL/PGVector, S3 uyumlu blob, Redis ve ayrı kalıcı worker içeren tam team kullanın; kısmi ortak/yerel karışım reddedilir:

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

secrets.encryptionKey, legacy ile tam eşleşmeli ve harita STORAGE_ENCRYPTION_ACTIVE_KEY_ID içermelidir. secrets.jwtSecret tüm uygulama/worker Pod’larında aynı kararlı yüksek entropili değer olmalıdır; chart olmadan team’i reddeder. Yönetilen PostgreSQL için doğrulanmış TLS kullanın, databaseUrl içine sürücü TLS parametresi eklemeyin. Havuz süreç başınadır; en az (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX ve işletim payı ayırın.

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

Dosyayı commit etmeyin, üretim sırlarını --set ile vermeyin; şifreli değer süreci kullanın. Model sağlayıcıları ve Work Pod’larını ayrı ölçekleyin. work.enabled=true iken worker uygulamayla aynı runtime image, StorageClass, work.env, Ollama ucu, zaman aşımı ve bağlamı alır; gömmeler, kalıcı sohbet ve Work çağrıları orada çalışır.

Etkin team en az bir dış worker ister; sıfır kurulumdan önce reddedilir. Tam askıya alma için hem replicaCount hem worker.replicaCount sıfır olmalıdır. Yalnız uygulamanın sıfırı, worker’ın kuyruğu sürdürdüğü bilinçli boşaltma/kurtarma modudur.

Team yükseltmeleri ve şema uyumluluğu​

Libre tam şema sürümü ister; karışık sürüm veya sıfır kesintili veritabanı yükseltmesi desteklenmez. Uygulama ve worker Recreate kullanır ama Kubernetes ikisini tek sınır olarak eşgüdümlemez. Önce yeni girişi durdurun, görevleri bitirin/iptal edin, iki eski Deployment’ı sıfıra indirin, doğrulanmış yedek alın ve tüm eski Pod’ların bittiğini doğrulayın. Sonra POSTGRES_MIGRATION_MODE=apply ile yükseltin; bir süreç advisory lock tutar, diğerleri aynı migration defterini bekleyip doğrular. Geri dönüş için önceki yedeği temiz PostgreSQL/S3 hedeflerine yükleyin; eski ikiliyi desteklemediği şemaya yöneltmeyin. Planlı kesinti bekleyin.

Yerel Erişim​

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

http://localhost:8080 açın.

Harici Ollama​

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

Sırlar​

Üretimde kararlı JWT ve şifreleme anahtarı ayarlayın. Varsayılan chart dolu secrets.* değerlerinden <release>-libre-webui-secrets oluşturur:

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)"

İşletmeci Secret’ı için secrets.existingSecret ayarlayın; chart Secret oluşturmaz, Pod’lar adlandırılmış nesneyi kullanır:

secrets:
  existingSecret: libre-webui-runtime

Kurulumdan önce oluşturun. jwt-secret, encryption-key; team ayrıca database-url, redis-url, storage-encryption-keys ister. İsteğe bağlı session-secret, s3-access-key-id, s3-secret-access-key, s3-session-token. GitHub/Hugging Face OAuth, dolu secrets.githubClientId veya secrets.huggingfaceClientId ile *-client-id/*-client-secret okuyabilir. Chart değerleri doğrulamaz veya kopyalamaz; eksik anahtar Pod’u başlatmaz.

Otomasyonda secrets.existingSecret ve external-secrets ya da şifreli Helm değerleri tercih edin. --set süreç incelemesinde ve sürüm metasında görünebilir. Sağlayıcı kimlik bilgilerini chart uzantısı veya kullanıcı ayarıyla ekleyin.

Uygulama ve worker NetworkPolicies​

networkPolicy.enabled=true uygulama ve team worker için giriş politikası oluşturur:

networkPolicy:
  enabled: true

Uygulama yalnız HTTP portunda giriş alır, worker hiçbir giriş almaz. Çıkış kısıtlanmaz; PostgreSQL, Redis, S3, Ollama, araç ve model uçlarına ulaşılmalıdır.

Bu, Work ad alanındaki varsayılan reddi yöneten work.networkPolicy.enabled ayarından ayrıdır. İkisi de NetworkPolicy’yi gerçekten uygulayan CNI ister.

Kalıcılık​

Libre WebUI ve Ollama PVC’lerini kalıcı depoda tutun. Veri birimini ve anahtarı birlikte yedekleyin.

Work çalışma alanları kum havuzu ad alanındaki kendi PVC’lerindedir, Libre veri PVC’sinde değil. Tam kurtarma veritabanını ve bu PVC’leri aynı politikayla yedeklemeyi gerektirir.

Ingress​

Genel erişim için HTTPS ve tam tarayıcı kökeni:

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

TRUST_PROXY boolean değil tam atlama sayısıdır. Güvenli varsayılan 0 iletilen adresleri yok sayar. Yalnız bir ingress proxy doğrudan bağlanıyorsa 1 kullanın; uzun sabit zincirde her güvenilir atlamayı sayın ve Service’i zincir dışında erişilmez tutun. Küçük sayı istemcileri proxy adresinde birleştirip giriş sınırını tüketir, büyük sayı istemcinin verdiği adrese güvenir. Chart yalnız 0–16 kabul eder, sınırsız true etmez ve yalnız HTTP uygulama Pod’larına yollar.

Chart BASE_URL veya OAuth callback değerlerini sunmaz. OAuth dağıtımları chart’ı genişletmeli ya da Deployment’ı yamamalı ve URL’ler genel etki alanıyla tam eşleşmelidir.

Kaynak Planlama​

Küme içi Ollama Pod’unu modeller için yeterli bellek ve GPU bulunan düğümlere zamanlayın. Kümede özel Ollama veya çıkarım hizmeti varsa harici Ollama genellikle daha basittir.

İlgili Belgeler​