Kubernetes

Libre WebUI 在 helm/libre-webui 下提供 Helm Chart。

Kubernetes 上的 Work

Work 在 Kubernetes 上原生运行，不涉及 Docker 守护进程、CLI 或套接字。安装时启用：

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

此命令将后端切换为 WORK_RUNTIME_BACKEND=kubernetes，并创建：

专用沙盒命名空间（work.namespace，默认 libre-webui-work），每个运行沙盒一个 Pod，每个任务工作区一个 PersistentVolumeClaim（work.workspaceSize，默认 5Gi，是真实的单任务磁盘配额；命名 Work 策略可为其创建的任务设置其他大小）；
限定命名空间的 Role 和 RoleBinding，只向后端 ServiceAccount 授予该命名空间内的 pods（get/list/create/delete）、pods/exec（get/create）和 persistentvolumeclaims（get/list/create/delete）权限——无 Secret、无集群范围。此授权完全替代 Docker 套接字：由 API 服务器而非应用强制沙盒规范不能挂载宿主机路径；
默认拒绝所有沙盒流量的 NetworkPolicy，只允许后端访问预览端口，并允许启用网络的沙盒访问互联网，但排除 work.networkPolicy.blockedEgressCidrs（默认包括私有范围、部分托管集群用于 Pod/服务 CIDR 的 CGNAT 范围和云元数据链路本地范围；请确认覆盖集群的 Pod 和服务 CIDR）。沙盒 DNS 仅允许访问 kube-system；采用节点本地 DNS 的集群需要自行添加 DNS 例外。

沙盒以非 root 身份运行，根文件系统只读，移除所有能力，采用 seccomp RuntimeDefault，且没有 ServiceAccount 令牌。文件、命令、Git 和交互式终端通过 API 服务器 exec 子资源；预览从沙盒 Pod IP 经同源签名代理提供，因此后端必须在集群内运行（Chart 的常规拓扑）。此后端不支持宿主机文件夹工作区。

有两点需要注意。NetworkPolicy 需要实际实现它的 CNI（Calico、Cilium、新版 kind 和大多数托管集群默认值）；将沙盒隔离视为生效前请先验证，端到端 CI 套件会报告其集群是否执行。切勿把节点的容器运行时套接字挂载到 WebUI Pod；Kubernetes 后端的目的正是避免此操作。

安装

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

默认 Chart 使用持久存储和内置 Ollama 服务部署 Libre WebUI。0.14.1 过渡版本固定到经过验证的多架构映像摘要；后续 Chart 默认使用与语义 appVersion 匹配的映像。仅在明确需要不同映像时设置 image.tag 或 image.digest。非空 image.tag 优先于过渡摘要。

默认 solo 配置接受 replicaCount: 0 作为主动暂停，或 replicaCount: 1 正常运行。它拒绝更大值和 HorizontalPodAutoscaler，因为 SQLite、本地文件和进程内协调在多个 Pod 后不安全。零副本版本会预配控制面资源，但不提供 Libre WebUI 流量。

多个副本需要完整 team 配置。它使用 PostgreSQL/PGVector、S3 兼容 Blob 存储、Redis 和独立持久 Worker；Chart 拒绝共享与本地后端的部分混合。请从受保护值文件开始：

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 必须是所有应用和 Worker Pod 共享的稳定高熵值；Chart 拒绝没有该值的团队模式，避免会话依赖 Pod 本地生成材料。托管 PostgreSQL 应保持已验证 TLS；不要向 databaseUrl 添加驱动 TLS 参数。连接池限制应用于每个应用和 Worker Pod，因此至少预留 (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX 个数据库连接以及运营余量。使用受保护值文件安装：

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

不要提交该文件，也不要通过 --set 传递生产密钥。请使用受保护的加密值流程保存。模型提供商和 Work 沙盒 Pod 应独立扩缩。设置 work.enabled=true 时，外部团队 Worker 接收与应用 Pod 相同的运行时映像、StorageClass 和 work.env 限制；它也接收相同的 Ollama 端点、请求超时和自动采用的最大上下文，因为文档嵌入、持久聊天和 Work 运行会在其中调用提供商。活跃团队应用（正数 replicaCount 或启用自动扩缩）至少需要一个外部 Worker，Chart 在安装前拒绝零 Worker。将 replicaCount 和 worker.replicaCount 都设为零可完全暂停。仅将应用设为零是主动的仅 Worker 排空或恢复模式：不提供 Web 流量，但继续处理持久队列。

团队升级与架构兼容性

Libre 采用严格架构版本策略，不支持混合版本或数据库零停机升级。应用和外部 Worker Deployment 均使用 Recreate，防止同一 Deployment 内新旧 Pod 重叠；Kubernetes 不会将两个 Deployment 作为单一升级边界协调。升级前停止新入口，让持久和 Work 作业完成或取消，将两个旧 Deployment 缩到零，创建已验证团队备份，并确认所有旧 Pod 终止。然后才以 POSTGRES_MIGRATION_MODE=apply 升级；一个新进程持有 PostgreSQL advisory leader 锁，其他进程等待并验证相同迁移账本。回滚时将之前的已验证备份恢复到干净 PostgreSQL/S3 目标；绝不要让旧二进制连接不完全支持的架构。此过程会有计划中断。

本地访问

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

打开 http://localhost:8080。

外部 Ollama

使用现有 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

Secret

为生产环境设置稳定 JWT Secret 和加密密钥。Chart 默认从非空 secrets.* 值创建 <release>-libre-webui-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 不会渲染 Secret，应用和 Worker Pod 都引用命名对象：

secrets:
  existingSecret: libre-webui-runtime

安装前创建该 Secret。必须包含 jwt-secret 和 encryption-key；团队模式还需要 database-url、redis-url 和 storage-encryption-keys。可选键包括 session-secret、s3-access-key-id、s3-secret-access-key 和 s3-session-token。当相应非空 secrets.githubClientId 或 secrets.huggingfaceClientId 启用集成时，GitHub 和 Hugging Face OAuth 也可从命名 Secret 读取 *-client-id 和 *-client-secret 对。Chart 有意不验证或复制 Secret 值；缺少必需键会导致 Pod 无法启动。

生产自动化应优先使用 secrets.existingSecret 和外部 Secret 控制器，或通过加密 Helm 值流程提供稳定值。命令行 --set 值可能通过进程检查暴露，并保存在 Helm 版本元数据中。请通过明确的 Chart 扩展添加提供商凭据，或在 WebUI 中配置按用户凭据。

应用与 Worker NetworkPolicy

设置 networkPolicy.enabled=true，为应用和团队模式的外部持久 Worker 渲染入站策略：

networkPolicy:
  enabled: true

应用仅在其 HTTP 容器端口接受入站，Worker 不接受入站。这些策略不限制出站：应用和 Worker 仍需访问已配置的 PostgreSQL、Redis、S3、Ollama、工具和模型提供商端点，服务位置由操作员决定。

此设置不同于 work.networkPolicy.enabled，后者控制 Work 沙盒命名空间的默认拒绝策略，并在启用 Work 时默认启用。两者都需要实际执行 Kubernetes NetworkPolicy 的 CNI；仅渲染对象不能证明网络隔离。

持久化

将 Libre WebUI 数据 PVC 和 Ollama 模型 PVC 保存在持久存储上。数据卷和加密密钥必须一同备份。

Work 任务工作区位于沙盒命名空间自己的 PVC 中，而不在 Libre WebUI 数据 PVC。完整 Work 恢复需要数据库（任务所有权、资源名称、运行）和这些 PVC；请按相同策略一同备份。

Ingress

公共访问应配置 HTTPS Ingress，并通过 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 是精确跳数，不是布尔值。安全默认值 0 忽略转发的客户端地址。只有一个 Ingress 代理直接连接 Libre 时才使用 1；更长固定链中要计算每个可信负载均衡器或代理跳，并保持 Service 无法绕过该链访问。数值过小会把客户端归到代理地址并耗尽共享登录限制；过大会信任客户端提供的地址。Chart 只接受 0 到 16，绝不接受无限制 true，且只将值发送给 HTTP 应用 Pod。

当前 Chart 不公开 BASE_URL 或 OAuth 回调 URL。使用 OAuth 的部署必须扩展 Chart 或修补 Deployment 来设置这些变量，回调 URL 必须与公共域名一致。

资源规划

若在集群内运行本地 Ollama，请将 Ollama Pod 调度到有足够内存和 GPU 容量的节点。若集群已有专用 Ollama 或推理服务，使用外部 Ollama 通常更简单。

Kubernetes 上的 Work​

安装​

团队升级与架构兼容性​

本地访问​

外部 Ollama​

Secret​

应用与 Worker NetworkPolicy​

持久化​

Ingress​

资源规划​

相关文档​