Chuyển tới nội dung chính

Kubernetes

Libre WebUI cung cấp chart Helm trong helm/libre-webui.

Work trên Kubernetes​

Work chạy native trên Kubernetes—không có daemon, CLI hoặc socket Docker nào tham gia. Bật khi cài đặt:

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

Thao tác này chuyển backend sang WORK_RUNTIME_BACKEND=kubernetes và tạo:

  • namespace sandbox riêng (work.namespace, mặc định libre-webui-work) chứa một Pod cho mỗi sandbox đang chạy và một PersistentVolumeClaim cho mỗi không gian làm việc tác vụ (work.workspaceSize, mặc định 5Gi—hạn ngạch đĩa thực theo tác vụ; chính sách Work có tên có thể đặt kích thước khác cho tác vụ thuộc chính sách đó);
  • Role và RoleBinding theo phạm vi namespace cấp cho ServiceAccount của backend đúng quyền pods (get/list/create/delete), pods/exec (get/create) và persistentvolumeclaims (get/list/create/delete) trong namespace đó—không secrets, không phạm vi cluster. Quyền này thay thế hoàn toàn socket Docker: máy chủ API, không phải ứng dụng, đảm bảo đặc tả sandbox không thể gắn đường dẫn máy chủ;
  • NetworkPolicy mặc định từ chối mọi lưu lượng sandbox, chỉ cho ingress từ backend ở cổng xem trước và cấp egress Internet cho sandbox có mạng trừ work.networkPolicy.blockedEgressCidrs (mặc định gồm dải riêng, dải CGNAT mà một số cluster được quản lý dùng cho CIDR pod/dịch vụ và dải link-local metadata đám mây—hãy xác minh CIDR pod và dịch vụ của cluster đã được bao phủ). DNS sandbox chỉ được phép đến kube-system; cluster chạy DNS cục bộ theo node cần ngoại lệ DNS riêng.

Sandbox chạy không phải root với hệ thống tệp root chỉ đọc, bỏ mọi capability, seccomp RuntimeDefault và không có token ServiceAccount. Tệp, lệnh, git và terminal tương tác đi qua tài nguyên con exec của máy chủ API; bản xem trước được phục vụ từ IP Pod sandbox qua proxy cùng nguồn đã ký, yêu cầu backend chạy trong cluster (cấu trúc chart thông thường). Backend này không hỗ trợ không gian làm việc thư mục máy chủ.

Hai lưu ý cho nhà vận hành. Việc thực thi NetworkPolicy cần CNI có triển khai nó (Calico, Cilium, các bản kind gần đây và hầu hết mặc định của cluster được quản lý đều có)—hãy xác minh với cluster trước khi xem cách ly sandbox là đang hoạt động; bộ kiểm thử CI đầu cuối báo liệu cluster chạy nó có thực thi hay không. Không bao giờ gắn socket runtime container của node vào pod WebUI; backend Kubernetes tồn tại chính để điều đó không cần thiết.

Cài đặt​

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

Chart mặc định triển khai Libre WebUI với storage bền vững và dịch vụ Ollama đi kèm. Bản chuyển tiếp 0.14.1 được ghim vào digest image đa kiến trúc đã xác minh; các chart sau mặc định dùng image appVersion ngữ nghĩa tương ứng. Chỉ đặt rõ image.tag hoặc image.digest khi chủ ý dùng image khác. image.tag không rỗng được ưu tiên hơn digest chuyển tiếp.

Profile solo mặc định nhận replicaCount: 0 để tạm dừng có chủ ý hoặc replicaCount: 1 cho hoạt động bình thường. Nó từ chối giá trị lớn hơn và HorizontalPodAutoscaler vì SQLite, file local và điều phối trong process không an toàn phía sau nhiều Pod. Release không replica vẫn cấp resource control plane nhưng không phục vụ traffic Libre WebUI.

Với nhiều replica, cấu hình profile team đầy đủ. Profile dùng PostgreSQL/PGVector, blob storage tương thích S3, Redis và worker bền vững riêng; chart từ chối trộn một phần backend shared và local. Bắt đầu từ file values được bảo vệ như sau:

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 phải khớp chính xác entry legacy và map khóa cũng phải chứa STORAGE_ENCRYPTION_ACTIVE_KEY_ID. secrets.jwtSecret phải là một giá trị ổn định, entropy cao, dùng chung cho mọi Pod app và worker; chart từ chối mode team nếu thiếu để session không phụ thuộc material tạo local trong Pod. Giữ TLS đã xác minh cho PostgreSQL managed; không thêm tham số TLS driver vào databaseUrl. Limit pool áp dụng cho từng Pod app và worker, vì vậy hãy dành ít nhất (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX kết nối database cộng khoảng dự phòng vận hành. Cài bằng file values được bảo vệ:

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

Không commit file đó hoặc truyền secret production qua --set. Lưu bằng workflow values mã hóa được bảo vệ. Scale provider model và Pod sandbox Work độc lập; khi work.enabled=true, worker team ngoài nhận cùng runtime image, StorageClass và limit work.env như Pod app. Worker cũng nhận cùng endpoint Ollama đã resolve, timeout request và context tối đa tự áp dụng như app, vì embedding document, chat bền vững và run Work thực hiện provider call tại đó. Ứng dụng team active (replicaCount dương hoặc bật autoscaling) cần ít nhất một worker ngoài; chart từ chối cấu hình không worker trước khi cài. Đặt cả replicaCount và worker.replicaCount bằng 0 để tạm dừng hoàn toàn. Chỉ đặt count app bằng 0 là mode drain/recovery chỉ worker có chủ ý: không phục vụ web traffic nhưng worker tiếp tục xử lý công việc bền vững trong queue.

Nâng cấp team và tương thích lược đồ​

Libre hỗ trợ policy version schema chính xác, không hỗ trợ upgrade database trộn version hoặc zero-downtime. Deployment app và external worker đều dùng Recreate để Pod cũ và mới không overlap trong cùng Deployment. Kubernetes không phối hợp hai Deployment thành một boundary upgrade duy nhất. Trước khi upgrade, dừng ingress mới, để hoàn tất hoặc hủy job bền vững và Work active, scale cả hai Deployment cũ về 0, tạo backup team đã xác minh và xác nhận mọi Pod app/worker cũ đã kết thúc. Chỉ sau đó upgrade release với POSTGRES_MIGRATION_MODE=apply; một process mới giữ PostgreSQL advisory leader lock trong khi mọi process mới khác chờ và validate cùng migration ledger. Để rollback, restore backup đã xác minh trước vào target PostgreSQL/S3 sạch; không bao giờ trỏ binary cũ vào schema mà nó không hỗ trợ chính xác. Quy trình này cố ý gây gián đoạn dịch vụ.

Truy cập cục bộ​

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

Mở http://localhost:8080.

Ollama bên ngoài​

Dùng endpoint Ollama hiện có:

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

Bí mật​

Đặt JWT secret và encryption key ổn định cho production. Mặc định chart tạo <release>-libre-webui-secrets từ các giá trị secrets.* không rỗng:

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

Với Secret do operator quản lý, đặt secrets.existingSecret. Khi đó chart không render Secret và cả Pod app lẫn worker đều tham chiếu object có tên:

secrets:
  existingSecret: libre-webui-runtime

Tạo Secret đó trước khi cài release. Nó phải có jwt-secret và encryption-key. Mode team còn cần database-url, redis-url và storage-encryption-keys. Các key tùy chọn chart hiểu gồm session-secret, s3-access-key-id, s3-secret-access-key và s3-session-token. OAuth GitHub và Hugging Face cũng có thể đọc cặp *-client-id/*-client-secret từ Secret có tên khi giá trị tương ứng secrets.githubClientId hoặc secrets.huggingfaceClientId không rỗng bật integration. Chart chủ ý không validate hoặc copy giá trị Secret; thiếu key bắt buộc khiến Pod không start.

Với automation production, ưu tiên secrets.existingSecret cùng controller external-secrets hoặc cung cấp giá trị ổn định qua workflow values Helm mã hóa. Giá trị --set trên command line có thể lộ qua process inspection và được giữ trong metadata release Helm. Thêm credential provider qua extension chart có chủ ý hoặc cấu hình credential theo user trong WebUI.

NetworkPolicy của ứng dụng và worker​

Đặt networkPolicy.enabled=true để render ingress policy cho app và, trong mode team, external worker bền vững:

networkPolicy:
  enabled: true

App chỉ nhận ingress trên port HTTP container. Worker không nhận ingress. Policy này không giới hạn egress: process app/worker vẫn phải tới endpoint PostgreSQL, Redis, S3, Ollama, tool và model-provider đã cấu hình; operator quyết định service nằm ở đâu.

Cài đặt này tách khỏi work.networkPolicy.enabled, điều khiển policy default-deny trong namespace sandbox Work và mặc định bật khi Work bật. Cả hai cần CNI thực sự enforce Kubernetes NetworkPolicy; chỉ render object không chứng minh network isolation.

Lưu trữ bền vững​

Giữ PVC data Libre WebUI và PVC model Ollama trên storage bền vững. Backup volume data Libre WebUI cùng encryption key.

Workspace task Work nằm trong PVC riêng ở namespace sandbox, không ở PVC data Libre WebUI. Recovery Work đầy đủ cần cả database (ownership task, tên resource, run) và các PVC đó; backup cùng nhau dưới cùng policy.

Ingress​

Để truy cập public, cấu hình ingress với HTTPS và đặt chính xác browser origin qua chart:

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 là số hop chính xác, không phải boolean. Mặc định an toàn của chart là 0, bỏ qua địa chỉ client forwarded. Chỉ dùng 1 khi một ingress proxy nối trực tiếp Libre; đếm mọi load balancer hoặc proxy hop đáng tin trong chain cố định dài hơn và giữ Service không thể truy cập quanh chain đó. Count quá nhỏ gom client dưới địa chỉ proxy và có thể làm cạn limit login dùng chung; quá lớn có thể tin địa chỉ do client cung cấp. Chart chỉ nhận 0 đến 16, không bao giờ true không giới hạn, và chỉ gửi giá trị tới Pod app HTTP.

Chart hiện tại không expose BASE_URL hoặc giá trị callback URL OAuth. Deployment dùng OAuth phải extend chart hoặc patch Deployment để đặt biến đó; callback URL phải khớp domain public.

Lập kế hoạch tài nguyên​

Với Ollama local trong cluster, schedule Pod Ollama trên node đủ memory và GPU cho model dự định chạy. Nếu cluster đã có Ollama chuyên dụng hoặc inference service, Ollama external thường đơn giản hơn.

Tài liệu liên quan​