Kubernetes

Libre WebUI มี chart Helm อยู่ที่ helm/libre-webui

Work บน Kubernetes

Work ทำงานแบบ native บน Kubernetes โดยไม่ใช้ daemon, CLI หรือ socket Docker เปิดใช้ระหว่างติดตั้ง:

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

การตั้งค่านี้เปลี่ยน backend เป็น WORK_RUNTIME_BACKEND=kubernetes และสร้าง:

• namespace sandbox เฉพาะ (work.namespace, ค่าเริ่มต้น libre-webui-work) ที่มีหนึ่ง Pod ต่อ sandbox ที่ทำงานและหนึ่ง PersistentVolumeClaim ต่อพื้นที่ทำงาน (work.workspaceSize, ค่าเริ่มต้น 5Gi ซึ่งเป็นโควตาดิสก์จริงต่องาน นโยบาย Work ที่มีชื่อกำหนดขนาดอื่นได้);
• Role และ RoleBinding ในขอบเขต namespace ที่ให้ ServiceAccount ของ backend เฉพาะ pods (get/list/create/delete), pods/exec (get/create) และ persistentvolumeclaims (get/list/create/delete) ใน namespace นั้น ไม่มี secrets หรือขอบเขต cluster สิทธิ์นี้แทน socket Docker ทั้งหมด โดยเซิร์ฟเวอร์ API ไม่ใช่แอป เป็นผู้บังคับว่า spec sandbox เมานต์เส้นทางโฮสต์ไม่ได้
• NetworkPolicy ที่ปฏิเสธทราฟฟิก sandbox ทั้งหมดโดยค่าเริ่มต้น อนุญาต ingress จาก backend ที่พอร์ตตัวอย่างเท่านั้น และให้ sandbox ที่มีเครือข่าย egress Internet ยกเว้น work.networkPolicy.blockedEgressCidrs (ค่าเริ่มต้นครอบคลุมช่วงส่วนตัว ช่วง CGNAT ที่ cluster จัดการบางแห่งใช้สำหรับ CIDR pod/บริการ และช่วง link-local ของ metadata cloud ให้ตรวจว่า CIDR ของ cluster ครอบคลุม) DNS sandbox อนุญาตเฉพาะ kube-system; cluster ที่ใช้ DNS ใน node ต้องมีข้อยกเว้นเอง

sandbox ทำงานแบบ non-root ด้วยระบบไฟล์ root อ่านอย่างเดียว ถอน capability ทั้งหมด ใช้ seccomp RuntimeDefault และไม่มี token ServiceAccount ไฟล์ คำสั่ง git และ terminal โต้ตอบผ่านทรัพยากรย่อย exec ของเซิร์ฟเวอร์ API ตัวอย่างส่งจาก IP Pod sandbox ผ่าน proxy same-origin ที่ลงนาม ซึ่งต้องให้ backend ทำงานใน cluster ตาม topology chart ปกติ backend นี้ไม่รองรับพื้นที่ทำงานโฟลเดอร์โฮสต์

หมายเหตุสองข้อสำหรับผู้ปฏิบัติ การบังคับ NetworkPolicy ต้องใช้ CNI ที่รองรับ (Calico, Cilium, kind รุ่นใหม่ และค่าเริ่มต้นของ cluster จัดการส่วนใหญ่) ให้ยืนยันกับ cluster ก่อนถือว่าการแยก sandbox ทำงาน ชุดทดสอบ CI end-to-end รายงานว่า cluster บังคับหรือไม่ และอย่าเมานต์ socket runtime คอนเทนเนอร์ของ node เข้า Pod WebUI backend Kubernetes มีขึ้นเพื่อไม่ต้องทำเช่นนั้น

ติดตั้ง

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

chart เริ่มต้นติดตั้ง Libre WebUI พร้อมพื้นที่เก็บถาวรและบริการ Ollama ที่รวมมา การเปลี่ยน 0.14.1 ตรึงกับ digest image หลายสถาปัตยกรรมที่ตรวจแล้ว chart ถัดไปใช้ image appVersion เชิงความหมายที่ตรงโดยค่าเริ่มต้น ตั้ง image.tag หรือ image.digest เมื่อจงใจต้องการ image อื่นเท่านั้น image.tag ที่ไม่ว่างมีลำดับเหนือ digest การเปลี่ยน

โปรไฟล์ solo เริ่มต้นรับ replicaCount: 0 เพื่อพักโดยตั้งใจ หรือ replicaCount: 1 สำหรับปกติ ปฏิเสธค่ามากกว่าและ HorizontalPodAutoscaler เพราะ SQLite ไฟล์ในเครื่อง และการประสานในโปรเซสไม่ปลอดภัยหลังหลาย Pod รุ่นศูนย์ replica จัดเตรียมทรัพยากรควบคุมแต่ไม่ให้ทราฟฟิก Libre WebUI

สำหรับหลาย replica ให้กำหนดโปรไฟล์ team เต็ม ซึ่งใช้ PostgreSQL/PGVector, คลัง blob ที่เข้ากันได้กับ S3, Redis และ worker ถาวรแยก chart ปฏิเสธการผสม backend ร่วมกับในเครื่องบางส่วน เริ่มจากไฟล์ values ที่ปกป้อง:

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 และแผนที่คีย์ต้องมี STORAGE_ENCRYPTION_ACTIVE_KEY_ID ด้วย secrets.jwtSecret ต้องเป็นค่าเสถียร entropy สูงที่แชร์ทุก Pod แอปและ worker chart ปฏิเสธโหมด team หากไม่มี เพื่อไม่ให้เซสชันพึ่งวัสดุที่สร้างเฉพาะ Pod รักษา TLS ที่ตรวจแล้วสำหรับ PostgreSQL จัดการ อย่าเพิ่มพารามิเตอร์ TLS ไดรเวอร์ใน databaseUrl ขีดจำกัด pool ใช้กับทุก Pod จึงสำรองการเชื่อมต่ออย่างน้อย (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX บวกส่วนเผื่อ ติดตั้งด้วยไฟล์ values ที่ปกป้อง:

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

อย่า commit ไฟล์นั้นหรือส่งข้อมูล production ผ่าน --set ให้เก็บด้วยขั้นตอน values เข้ารหัสที่ปกป้อง ขยายผู้ให้บริการโมเดลและ Pod sandbox Work แยกกัน เมื่อ work.enabled=true worker team ภายนอกได้รับ image runtime, StorageClass และขีดจำกัด work.env เดียวกับ Pod แอป และได้รับ endpoint Ollama ที่แปลง เวลา timeout คำขอ และบริบทสูงสุดที่รับอัตโนมัติเหมือนแอป เพราะ embedding เอกสาร แชตถาวร และงาน Work เรียกผู้ให้บริการที่นั่น แอป team active (replicaCount บวกหรือ autoscaling เปิด) ต้องมี worker ภายนอกอย่างน้อยหนึ่ง และ chart ปฏิเสธศูนย์ worker ก่อนติดตั้ง ตั้งทั้ง replicaCount และ worker.replicaCount เป็นศูนย์เพื่อพักเต็ม การตั้งเฉพาะแอปเป็นศูนย์คือโหมดระบายหรือกู้เฉพาะ worker โดยตั้งใจ ไม่ให้ทราฟฟิกเว็บแต่ worker ยังประมวลงานถาวรในคิว

การอัปเกรด team และความเข้ากันได้ของ schema

Libre รองรับนโยบายเวอร์ชัน schema ที่ตรง ไม่ใช่การอัปเกรดฐานข้อมูลหลายเวอร์ชันหรือไม่มี downtime Deployment แอปและ worker ภายนอกใช้ Recreate ป้องกัน Pod เก่าใหม่ทับกันใน Deployment เดียว Kubernetes ไม่ประสานสอง Deployment เป็นขอบเขตเดียว ก่อนอัปเกรดให้หยุด ingress ใหม่ ปล่อยหรือยกเลิกงานถาวรและ Work active ลด Deployment เก่าทั้งสองเป็นศูนย์ ทำข้อมูลสำรอง team ที่ตรวจแล้ว และยืนยัน Pod เก่าทั้งหมดจบ จากนั้นอัปเกรดด้วย POSTGRES_MIGRATION_MODE=apply; โปรเซสใหม่หนึ่งถือ advisory leader lock PostgreSQL ขณะอื่นรอและตรวจ ledger เดียวกัน rollback โดยกู้ข้อมูลสำรองก่อนหน้าไปยังเป้าหมาย PostgreSQL/S3 สะอาด อย่าชี้ binary เก่าไป schema ที่ไม่รองรับตรง คาดว่าบริการหยุดโดยตั้งใจระหว่างขั้นตอน

เข้าถึงในเครื่อง

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

เปิด http://localhost:8080

Ollama ภายนอก

ใช้ endpoint 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

ข้อมูลลับ

กำหนดข้อมูลลับ JWT และคีย์เข้ารหัสที่เสถียรสำหรับ production โดยค่าเริ่มต้น chart สร้าง <release>-libre-webui-secrets จากค่า secrets.* ที่ไม่ว่าง:

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

สำหรับ Secret ที่ผู้ปฏิบัติจัดการ ให้ตั้ง secrets.existingSecret จากนั้น chart ไม่ render Secret และ Pod แอปกับ worker อ้างอิงออบเจ็กต์ชื่อ:

secrets:
  existingSecret: libre-webui-runtime

สร้าง Secret ก่อนติดตั้ง ต้องมี jwt-secret และ encryption-key โหมด team ต้องมี database-url, redis-url และ storage-encryption-keys เพิ่ม คีย์เลือกได้คือ session-secret, s3-access-key-id, s3-secret-access-key และ s3-session-token GitHub และ Hugging Face OAuth อ่านคู่ *-client-id และ *-client-secret จาก Secret ได้เมื่อค่า secrets.githubClientId หรือ secrets.huggingfaceClientId ที่ไม่ว่างเปิดการผสาน chart ตั้งใจไม่ตรวจหรือคัดลอกค่า Secret คีย์ที่ขาดทำให้ Pod เริ่มไม่ได้

สำหรับระบบอัตโนมัติ production ให้ใช้ secrets.existingSecret กับ controller external-secrets หรือส่งค่าที่เสถียรผ่านขั้นตอน values Helm เข้ารหัส ค่า --set ใน command line อาจเปิดเผยผ่านการตรวจโปรเซสและเก็บในเมทาดาทารุ่น Helm เพิ่มข้อมูลผู้ให้บริการผ่านส่วนขยาย chart โดยตั้งใจหรือกำหนดต่อผู้ใช้ใน WebUI

NetworkPolicy ของแอปและ worker

ตั้ง networkPolicy.enabled=true เพื่อ render นโยบาย ingress สำหรับแอปและ worker ถาวรภายนอกในโหมด team:

networkPolicy:
  enabled: true

แอปรับ ingress เฉพาะพอร์ต HTTP ของคอนเทนเนอร์ worker ไม่รับ ingress นโยบายเหล่านี้ไม่จำกัด egress โปรเซสแอปและ worker ยังต้องเข้าถึง endpoint PostgreSQL, Redis, S3, Ollama, เครื่องมือ และผู้ให้บริการโมเดลที่กำหนด ผู้ปฏิบัติเป็นผู้กำหนดตำแหน่งบริการ

การตั้งค่านี้แยกจาก work.networkPolicy.enabled ซึ่งควบคุมนโยบายปฏิเสธเริ่มต้นใน namespace sandbox Work และเปิดโดยค่าเริ่มต้นเมื่อเปิด Work ทั้งสองต้องใช้ CNI ที่บังคับ Kubernetes NetworkPolicy จริง การ render ออบเจ็กต์อย่างเดียวไม่พิสูจน์การแยกเครือข่าย

การเก็บข้อมูลถาวร

เก็บ PVC ข้อมูล Libre WebUI และ PVC โมเดล Ollama บนพื้นที่เก็บถาวร สำรอง volume ข้อมูล Libre WebUI พร้อมคีย์เข้ารหัส

พื้นที่ทำงาน Work อยู่ใน PVC ของตนใน namespace sandbox ไม่อยู่ใน PVC ข้อมูล Libre WebUI การกู้ Work เต็มต้องมีทั้งฐานข้อมูล (เจ้าของงาน ชื่อทรัพยากร การทำงาน) และ PVC เหล่านั้น ให้สำรองพร้อมกันภายใต้นโยบายเดียว

Ingress

สำหรับการเข้าถึงสาธารณะ ให้กำหนด ingress ด้วย HTTPS และตั้ง origin เบราว์เซอร์ที่ตรงผ่าน 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 คือจำนวน hop ที่ตรง ไม่ใช่ boolean ค่า chart ที่ปลอดภัยคือ 0 ซึ่งไม่ใช้ที่อยู่ไคลเอนต์ที่ส่งต่อ ใช้ 1 เฉพาะเมื่อ ingress proxy หนึ่งเชื่อม Libre โดยตรง นับทุก load balancer หรือ proxy ที่เชื่อถือในโซ่คงที่ยาวและทำให้ Service เข้าถึงไม่ได้รอบโซ่ จำนวนต่ำเกินจะรวมไคลเอนต์ใต้ที่อยู่ proxy และอาจใช้ขีดจำกัดเข้าสู่ระบบร่วมหมด จำนวนสูงเกินอาจเชื่อที่อยู่จากไคลเอนต์ chart รับเฉพาะ 0 ถึง 16 ไม่รับ true ไม่จำกัด และส่งค่าเฉพาะ Pod แอป HTTP

chart ปัจจุบันไม่เปิดค่า BASE_URL หรือ URL callback OAuth การติดตั้งที่ใช้ OAuth ต้องขยาย chart หรือ patch Deployment เพื่อตั้งตัวแปร และ URL callback ต้องตรงกับโดเมนสาธารณะ

การวางแผนทรัพยากร

สำหรับ Ollama ใน cluster ให้จัด Pod Ollama บน node ที่มีหน่วยความจำและ GPU พอสำหรับโมเดล หาก cluster มีบริการ Ollama หรืออนุมานเฉพาะอยู่แล้ว Ollama ภายนอกมักง่ายกว่า

เอกสารที่เกี่ยวข้อง

• Work: พื้นที่ทำงานแบบแยก
• Docker
• ข้อกำหนดฮาร์ดแวร์
• ตัวแปรสภาพแวดล้อม
• การยืนยันตัวตน