Kubernetes (Helm)

使用官方 Helm chart（litefuse/litefuse-k8s）在 Kubernetes 上部署 Litefuse。如果你的团队运维 Kubernetes，这是生产环境运行 Litefuse 的推荐方式。

Chart 会同时部署 Litefuse Web、Worker 以及全部后端存储。所有存储默认都是内置的，一条 helm install 就能得到一个可用的完整技术栈；每个存储也都可以独立切换为外部或托管服务。

前置条件

• Kubernetes 1.24+
• Helm 3.18+
• 默认 StorageClass——Doris FE/BE、PostgreSQL、Valkey 和 SeaweedFS 默认都会申请 PVC（也可以通过各存储的 storageClass 字段单独指定）
• 默认单副本部署所需的集群容量：约 6.5 CPU / 13Gi requests 和 ~300Gi 存储卷。笔记本或小型开发集群请从 examples/values-dev.yaml 开始，资源占用大约减半。

快速开始

从 OCI registry 安装（推荐）

发布包已捆绑所有子 chart 依赖，无需 helm repo add：

helm install litefuse oci://ghcr.io/litefuse/litefuse --version 1.0.0 \
  -n litefuse --create-namespace

无需克隆仓库即可查看全部配置：

helm show values oci://ghcr.io/litefuse/litefuse --version 1.0.0   # 全部配置项（含注释）
helm show readme oci://ghcr.io/litefuse/litefuse --version 1.0.0   # 完整参考文档

从源码安装

git clone https://github.com/litefuse/litefuse-k8s.git && cd litefuse-k8s
helm dependency update charts/litefuse
helm install litefuse charts/litefuse -n litefuse --create-namespace

开发规模的安装：

helm install litefuse charts/litefuse -n litefuse --create-namespace \
  -f examples/values-dev.yaml

首次安装的预期表现

首次安装会先引入 Doris Operator 的 CRD，然后创建 DorisCluster 自定义资源。Doris FE/BE 需要几分钟组建集群，在 schema 迁移成功之前 web/worker Pod 会反复重启——这是预期行为。 用以下命令观察进度：

kubectl get doriscluster -n litefuse
kubectl get pods -n litefuse -w

当 DorisCluster 报告 FE/BE 可用、web/worker Pod 处于 Running 且 Ready 时，安装即完成。

访问 UI

未配置 ingress 时：

kubectl port-forward -n litefuse svc/litefuse-web 3000:3000

打开 http://localhost:3000 注册第一个账号。正式部署请启用 ingress 并把 litefuse.nextauth.url 设置为对外的正式 URL。创建完账号后，用 litefuse.features.signUpDisabled=true 关闭公开注册。

配置

所有配置项都在 values.yaml 中并附有内联文档；chart 会把它们渲染成 web/worker Pod 的环境变量。三条规则：

1. 优先使用结构化字段（litefuse.*、postgresql.*、redis.*、doris.*、s3.*）。它们在渲染时会被校验，并自动接入正确的 Secret。
2. litefuse.additionalEnv 是兜底出口，用于没有结构化字段的配置。同一个变量用两种方式重复设置会在渲染时被拒绝。
3. Litefuse 环境变量使用 LITEFUSE_ 前缀。残留的 LANGFUSE_ 前缀变量会被静默忽略——从 langfuse-k8s 迁移 values 时要特别注意。

所有敏感字段都同时支持内联值和引用已有 Kubernetes Secret 两种写法：

someSecretField:
  value: ""                # 内联（测试时可用）
  secretKeyRef:            # 推荐：引用你自己的 Secret
    name: my-secret
    key: my-key

正式 URL

任何正式部署都必须设置：

litefuse:
  nextauth:
    url: https://litefuse.example.com

安全密钥

留空时，三者都会在首次安装时自动生成并持久化到 <release>-app Secret 中，该 Secret 在卸载后仍会保留。丢失 SALT 或 ENCRYPTION_KEY 是不可恢复的——API key 和加密数据将无法读取。

生产环境请固定这些密钥，尤其是在 GitOps 场景下（helm template 无法读取集群中已生成的 Secret）：

litefuse:
  salt:
    secretKeyRef: { name: litefuse-app-credentials, key: salt }
  encryptionKey:
    secretKeyRef: { name: litefuse-app-credentials, key: encryption-key }
  nextauth:
    secret:
      secretKeyRef: { name: litefuse-app-credentials, key: nextauth-secret }

Ingress

只有 web Service 会对外暴露；worker 没有 HTTP 端点。

litefuse:
  ingress:
    enabled: true
    className: nginx
    annotations:
      # SDK 批量 ingestion 请求可能很大——不要停留在 nginx 默认的 1m 上限
      nginx.ingress.kubernetes.io/proxy-body-size: 100m
    hosts:
      - host: litefuse.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      enabled: true
      secretName: litefuse-tls

SSO 与 SMTP

SSO 提供方（auth0、cognito、azureAd、github、gitlab、google、keycloak、okta、workos 等）在 litefuse.auth.providers 下配置，邮件发送在 litefuse.smtp 下配置。详见 chart 参考文档。

连接外部存储

每个内置存储都遵循同一模式：<store>.deploy: false 加上连接与认证字段。缺少必填的 endpoint 会在渲染时校验失败。

外部 Doris

doris:
  deploy: false
  operator:
    enabled: false
  host: my-doris-fe.example.com   # FE 端点（MySQL 协议 + HTTP）
  httpPort: 8030
  queryPort: 9030
  database: litefuse
  auth:
    username: admin
    existingSecret: my-doris-credentials
    existingSecretKey: password
  replicationNum: 3   # BE 数量 >= 3 时保持 3

只有单个 BE 的外部 Doris 必须设置 replicationNum: 1——默认值 3 会导致存活 BE 不足时所有 CREATE TABLE 失败。

外部 PostgreSQL

postgresql:
  deploy: false
  host: my-postgres.example.com
  port: 5432
  auth:
    username: litefuse
    database: litefuse
    existingSecret: my-postgres-credentials
    secretKeys:
      userPasswordKey: password

使用托管/云上 Postgres 时，还可以关注 postgresql.directUrl（迁移专用的独立连接串）和 postgresql.shadowDatabaseUrl（数据库用户没有 CREATE DATABASE 权限时必需）。

外部 Redis

redis:
  deploy: false
  host: my-redis.example.com
  port: 6379
  auth:
    username: "default"
    existingSecret: my-redis-credentials
    existingSecretPasswordKey: password

Redis Cluster（redis.cluster.enabled + nodes）和 Sentinel（redis.sentinel.*）也都支持。外部 Redis/Valkey 必须配置 maxmemory-policy noeviction——发生淘汰时 Litefuse 会丢失任务数据。

外部 S3 / 对象存储

s3:
  deploy: false
  bucket: my-litefuse-bucket
  region: eu-west-1
  forcePathStyle: false
  accessKeyId:
    secretKeyRef: { name: my-s3-credentials, key: access-key-id }
  secretAccessKey:
    secretKeyRef: { name: my-s3-credentials, key: secret-access-key }

accessKeyId/secretAccessKey 留空则使用 Pod 自身的身份（IRSA / instance profile）。MinIO 或其他 S3 兼容网关需要额外设置 s3.endpoint，并把 forcePathStyle 改为 true（上面的 AWS 示例用的是 false）。Azure Blob 和 GCS 通过 s3.storageProvider 支持。

示例 values 文件

可直接使用的 values 文件位于 examples/：

扩缩容

• 每个 web/worker 副本是一个 Node.js 进程（饱和时约占 1 核）——横向扩容，而不是纵向加大资源：

  litefuse:
    web:
      replicas: 6
    worker:
      replicas: 12

• web 和 worker 都提供 HPA、KEDA、VPA 配置块（litefuse.web.hpa.*、litefuse.worker.keda.* 等）。

• 默认创建 PodDisruptionBudget（maxUnavailable: 1）。

• 生产环境 Doris 高可用需要 3 FE / 3+ BE 副本并设置 doris.replicationNum: 3——参见 examples/values-production.yaml。

• Doris Operator 安装的是集群级资源——每个 Kubernetes 集群只能运行一个 Operator。部署第二个 Litefuse release 时，设置 doris.operator.enabled=false 复用已有 Operator。

• 整个技术栈保持 UTC（litefuse.timezone，即默认值）——Doris 的日期分区依赖它。

升级

helm upgrade litefuse oci://ghcr.io/litefuse/litefuse --version <ver> -n litefuse

• web/worker 镜像默认跟随 chart 的 appVersion；固定 litefuse.image.tag 可以独立控制应用版本。web Pod 启动时会执行 Postgres/Doris 迁移。
• Helm 从不升级 CRD。 当 chart 升级带来新版 Doris Operator 依赖时，请在升级前手动应用其更新后的 CRD（从 Operator release 中 kubectl apply -f）。

故障排查

完整列表见 chart README。

卸载

helm uninstall litefuse -n litefuse

卸载后有意保留的内容：

• Doris FE/BE、PostgreSQL、Valkey 和 SeaweedFS 的 PVC（即数据）
• <release>-app Secret（SALT / ENCRYPTION_KEY / NEXTAUTH_SECRET）以及自动生成的各存储凭据 Secret——它们是解锁这些数据卷的钥匙

使用相同 release 名重新安装会自动接管这些资源，数据完好恢复。只有在确实要丢弃数据时，才手动删除 PVC 和 Secret。