Budibase Helm Chart 完整部署与配置指南：从安装到生产级调优

Budibase Helm Chart 完整部署与配置指南从安装到生产级调优【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibaseBudibase 是一个开源的 low-code 平台帮助团队在几分钟内构建工作场所应用。本文以仓库中 charts/budibase/README.md 为核心系统讲解如何在 Kubernetes 集群中使用官方 Helm Chart 部署 Budibase包括前置条件、安装方式、2.x 到 3.0 的升级注意事项、完整的 values 配置参数表结合源码逐项解读以及基于仓库模板实现的生产级调优技巧。读完本文你将能够独立完成 Budibase 在任意 Kubernetes 集群上的安装、配置、备份与卸载并能理解每个配置项在底层 Deployment、Service、Ingress 与 Secret 中的真实作用。一、Chart 概览与前置条件Budibase Helm Chart 是 Budibase 官方提供的 Kubernetes 部署方式它不是一个单容器应用而是将 Budibase 的完整运行时拆分为多个服务组件由 Chart 统一编排。从 Chart.yaml 可以看到该 Chart 的核心元信息如下apiVersion:v2Helm 3 标准格式type:application依赖官方 Apache CouchDB Chartcouchdb版本4.5.6仅在services.couchdb.enabled为 true 时安装按照 README.md 的要求在开始安装之前你的集群需要满足以下前置条件前置条件用途说明helmv3 或更高版本运行 Chart 的包管理器Kubernetes 1.4集群最低版本要求存储控制器Storage Controller若需要使用持久化存储CouchDB、MinIO、Redis 均依赖 PVIngress 控制器Ingress Controller若需要定义Ingress资源对外暴露服务metrics-server若需要使用水平 Pod 自动扩缩容HPA值得注意的是README 中标注的 Kubernetes 1.4 是兼容性下限。实际模板代码中对 API 版本做了分版本处理例如 ingress.yaml 会根据集群版本自动选择networking.k8s.io/v1≥1.19、networking.k8s.io/v1beta1≥1.14或extensions/v1beta1因此较新版本集群才能获得完整功能如ingressClassName、pathType等字段。二、Chart 依赖Apache CouchDBBudibase 使用 CouchDB 作为主数据库。该 Chart 依赖官方的 Apache CouchDB Helm Chart版本 4.5.6完整依赖声明位于 Chart.yamldependencies: - name: couchdb version: 4.5.6 repository: https://apache.github.io/couchdb-helm condition: services.couchdb.enabled需要注意以下几点结合 values.yaml 中的couchdb段使用自定义镜像Budibase 使用自己构建的 CouchDB 镜像budibase/database并将 Clouseau 搜索组件内置其中官方不支持替换为其他 CouchDB 镜像否则无法保证 Budibase 正常工作。因此在 values.yaml 中对应注释明确写着 You shouldnt change this, and if you do we cant guarantee that Budibase will work.集群规模couchdb.clusterSize默认为1简单场景足够如果追求高可用可设置为3。SQS 端口Chart 默认在 CouchDB Service 上额外暴露 SQS 端口4984该端口用于 Budibase 的 SQL 查询能力对应 Deployment 中的COUCH_DB_SQL_URL环境变量。持久化CouchDB 数据默认持久化在/data路径对应DATA_DIR环境变量PV 默认大小10Gi。搜索能力enableSearch被强制固定为false因为 Clouseau 已随budibase/database镜像内置属于 Budibase 核心体验的一部分不可单独关闭。三、从 2.x 升级到 3.0.0破坏性变更清单README 专门用一个章节列出了从 2.x 升级到 3.0.0 的破坏性变更。升级前请逐条核对你的现有配置不再内置ingress-nginx如果你此前依赖 Chart 自带的 ingress-nginx 提供 Ingress 控制器升级后需要自行单独部署 ingress-nginx官方指引为 Kubernetes 官方 ingress-nginx 文档。CouchDB Chart 版本升级从3.3.4升级到4.3.0主要动机是让 Chart 版本与 CouchDB 运行时版本对齐CouchDB 从 3.1.1 升级到 3.2.1。同时官方 CouchDB 镜像被替换为 Budibase 自建镜像。AWS ALB Ingress 独立成块此前在 EKS 中通过ingress.enabled: falseingress.aws: true启用的 AWS ALB Ingress现在改为awsAlbIngress.enabled: true且所有相关配置统一收敛在awsAlbIngress命名空间下。HPA 拆分原先通过hpa.enabled: true配置的单一 HorizontalPodAutoscaler 被拆分为 3 个独立的 HPA分别对应apps、worker、proxy三个服务配置入口迁移至services.{apps,worker,proxy}.autoscaling。从源码看pdb.yaml 还会为 proxy、apps、worker、automation worker及可选的 litellm分别创建独立的 PodDisruptionBudget这印证了 3.x 之后每个服务独立管理生命周期的设计思路。四、安装 Budibase方式一从官方 Helm 仓库安装推荐$ helm repo add budibase https://budibase.github.io/budibase/ $ helm repo update $ helm install --create-namespace --namespace budibase budibase budibase/budibase方式二从源码仓库安装$ git clone gitgithub.com:budibase/budibase.git $ cd budibase/charts/budibase $ helm install --create-namespace --namespace budibase budibase .卸载$ helm uninstall --namespace budibase budibase安装后Chart 会在budibase命名空间中创建以下核心资源对应 templates 目录app-serviceBudibase 应用服务app-service-deployment.yaml容器端口 4002worker-service后台 Worker 服务worker-service-deployment.yaml容器端口 4003automation-worker-service自动化执行 Workerautomation-worker-service-deployment.yamlproxy-serviceNginx 反向代理proxy-service-deployment.yaml对外端口 10000负责将请求路由到 apps、worker、MinIO、CouchDB 各上游minio-serviceMinIO 对象存储minio-service-deployment.yamlredis-serviceRedis 缓存redis-service-deployment.yamlcouchdb依赖子 Chart 提供的 CouchDB 集群litellm-service可选的 LiteLLM AI 网关litellm-service-deployment.yamlSecrets自动生成内部密钥secrets.yaml其中 proxy 是唯一对外的入口所有 Ingress 都指向proxy-service的 10000 端口。五、最小可运行配置示例HomeLab 场景README 给出了一个非常实用的示例在家庭集群中使用 nginx Ingress 控制器 NFS 作为集群存储将 Budibase 跑起来的最小values.yamlingress: enabled: true className: nginx hosts: - host: budibase.local # set this to whatever DNS name youd use paths: - backend: service: name: proxy-service port: number: 10000 path: / pathType: Prefix couchdb: persistentVolume: enabled: true storageClass: nfs-client adminPassword: admin services: objectStore: storageClass: nfs-client redis: storageClass: nfs-client将该文件保存为values.yaml后执行$ helm install --create-namespace --namespace budibase budibase . -f values.yaml这个示例点明了三个关键配置思路Ingress 指向 proxy-service 的 10000 端口Ingress 的默认后端是proxy-service所有流量经由 Nginx 代理再分发到内部服务这与 ingress.yaml 的默认hosts结构完全一致。三个持久化存储位置CouchDB数据库、MinIO对象存储、Redis缓存都需要持久化在 NFS 场景下统一指定storageClass: nfs-client即可。CouchDB 管理员密码couchdb.adminPassword需要在首次部署时指定。官方上游 Chart 默认不为 admin 用户设置持久化密码values.yaml 中专门注释提醒要让密码持久化必须显式设置adminPassword。六、配置参数全解结合源码逐项解读以下是 README 中完整的配置参数表继承自 values.yaml 的 helm-docs 自动生成并补充了源码级解读。6.1 全局配置globalsKey类型默认值说明globals.apiEncryptionKeystring用于加密存储在数据库中的 API key 和环境变量。若createSecrets为 true 则无需设置globals.appVersionstring要部署的 Budibase 版本。默认取{{ .Chart.AppVersion }}会作为 apps、proxy、worker 三个镜像的版本 tagglobals.automationMaxIterationsstring200自动化循环步骤允许的最大迭代次数globals.budibaseEnvstringPRODUCTION设置 apps 和 worker Pod 的BUDIBASE_ENVIRONMENT环境变量通常无需修改globals.cookieDomainstring设置 Budibase 会话 Cookie 的 Domain 属性globals.createSecretsbooltrue自动生成内部 API key、JWT secret、对象存储 access key/secret并存入 KubernetesSecretglobals.enableAnalyticsstring1是否启用遥测分析globals.google.clientIdstringGoogle OAuth 应用的 Client IDglobals.google.secretstringGoogle OAuth 应用的 Client secretglobals.httpMigrationsstring0是否通过 HTTP API 执行数据迁移设为0时迁移在启动时执行globals.internalApiKeystringBudibase 内部 API 调用使用的 keycreateSecrets为 true 时无需设置globals.internalApiKeyFallbackstringinternalApiKey的回退值。轮换加密密钥期间可设为旧值globals.jwtSecretstring用于签名 JWT 的密钥createSecrets为 true 时无需设置globals.jwtSecretFallbackstringjwtSecret的回退值JWT 密钥轮换期间使用globals.platformUrlstring设置platformUrl绑定自托管时也可在 Settings Organisation 中设置globals.smtp.enabledboolfalse是否启用 SMTPglobals.smtp.fromstringBudibase 发送邮件时 From: 字段的邮箱地址globals.smtp.hoststringSMTP 服务器主机名globals.smtp.passwordstringSMTP 认证密码globals.smtp.portstring587SMTP 服务器端口globals.smtp.userstringSMTP 认证用户名globals.sqsobject{}SQS 连接配置url / port默认端口 4984globals.tempBucketNamestring使用 S3 时用于存放临时文件的 bucket 名称globals.tenantFeatureFlagsstring设置各租户启用的功能开关通常无需修改源码解读globals.createSecrets是安全性的核心开关。查看 secrets.yaml当它为 true 时Chart 会创建一个 Opaque Secret包含internalApiKey、jwtSecret、objectStoreAccess、objectStoreSecret、bbEncryptionKey、apiEncryptionKey六个键。更关键的是模板使用lookup函数检查是否已有同名 Secret$existingSecret存在则复用旧值不存在才用budibase.defaultsecret模板见 _helpers.tpl随机生成 20 位字母数字并 base64 编码。这一机制保证了升级或重装时密钥不漂移避免已加密数据无法解密。globals.appVersion直接决定镜像版本例如 app-service-deployment.yaml 中的镜像构造逻辑image: {{ .Values.services.apps.image | default (printf %sbudibase/apps:%s (.Values.globals.dockerRegistry | default ) (.Values.globals.appVersion | default .Chart.AppVersion)) }}即默认拉取budibase/apps:appVersion、budibase/worker:appVersion、budibase/proxy:appVersion三个同版本镜像。6.2 Ingress 与 AWS ALBKey类型默认值说明ingress.classNamestring使用的 Ingress classingress.enabledbooltrue是否创建指向 Budibase proxy 的 Ingress 资源ingress.hostslist[]Ingress 标准的 hosts 块默认指向 Budibase proxyawsAlbIngress.accessLogs.bucketstringALB 访问日志 S3 bucket须与 ALB 同区域且 bucket 策略允许 ELB 日志投递主体写入awsAlbIngress.accessLogs.enabledboolfalse是否启用 ALB 访问日志awsAlbIngress.accessLogs.prefixstringbucket 内的对象键前缀日志落在prefix/AWSLogs/...awsAlbIngress.certificateArnstring使用 HTTPS 时 ACM 证书的 ARNawsAlbIngress.enabledboolfalse是否创建指向 Budibase proxy 的 ALB Ingress需要 AWS ALB Ingress Controller源码解读标准 Ingress 模板ingress.yaml会根据集群版本自动切换 API 版本并支持tls配置。AWS ALB 场景则使用独立的 alb-ingress.yaml其中预置了完整的 ALB 注解internet-facing方案、ip目标类型、健康检查路径/health、成功码200启用certificateArn后会自动增加ssl-redirect: 443并同时监听 80/443启用accessLogs后通过load-balancer-attributes注解写入 S3。此外还支持deregistrationDelay默认 30 秒、sslPolicy、securityGroups等扩展配置。6.3 服务级配置services.*apps / worker / proxy / automationWorkers 通用配置Key类型默认值说明services.{svc}.autoscaling.enabledboolfalse是否启用水平 Pod 自动扩缩容services.{svc}.autoscaling.maxReplicasint10HPA 最大副本数services.{svc}.autoscaling.minReplicasint1HPA 最小副本数services.{svc}.autoscaling.targetCPUUtilizationPercentageint80HPA 目标 CPU 利用率。注意需要集群配置 metrics-server且为 Pod 设置 resources 才能生效services.{svc}.extraContainerslist[]追加到 Pod 的额外容器sidecarservices.{svc}.extraEnvlist[]追加的环境变量namevalue 列表services.{svc}.extraEnvFromSecretlist[]从同命名空间 K8s Secret 注入环境变量避免敏感信息写在 values.yaml 中services.{svc}.extraVolumeMountslist[]主容器额外的 volumeMountservices.{svc}.extraVolumeslist[]Pod 额外的 volumeservices.{svc}.livenessProbeobjectHTTP 健康检查存活探针一般无需修改services.{svc}.readinessProbeobjectHTTP 健康检查就绪探针一般无需修改services.{svc}.startupProbeobjectHTTP 健康检查启动探针一般无需修改services.{svc}.resourcesobject{}Pod 资源 requests/limitsservices.{svc}.terminationGracePeriodSecondsint60请求关闭到强制杀容器之间的宽限时间用于优雅处理请求注apps 与 worker 额外支持logLevel默认info与httpLogging默认1automationWorkers 额外支持enabled默认true关闭后自动化改由 apps 服务处理。源码解读探针默认值在 values.yaml 中定义均为 HTTP GET 健康检查。例如 apps 服务的 readiness 探针每 3 秒检查/healthliveness 探针每 5 秒检查/health。各 Deployment 模板如 app-service-deployment.yaml还内置了preStop钩子sleep preStopDelaySeconds默认 45 秒用于等待负载均衡器注销配合terminationGracePeriodSeconds: 70保证零中断滚动更新。HPA 模板如 proxy-service-hpa.yaml会自动选择autoscaling/v2或v2beta2API并支持 CPU 与内存双指标。proxy 专属配置Key类型默认值说明services.proxy.resolverstringNginx 代理在请求时解析上游使用的 DNS resolver。必须是 IP 地址Nginx 在配置加载时解析一次DNS 名不可解析会直接致命退出。留空时在 install/upgrade 时自动探测 kube-dns 的 ClusterIP仅当自动探测无法执行例如 RBAC 受限无法lookup时才需手动设置services.proxy.replicaCountint1proxy 副本数values.yaml 中默认 2源码解读resolver 的自动探测逻辑在 proxy-service-deployment.yaml 中实现优先使用用户显式配置的services.proxy.resolver否则用lookup查询kube-system命名空间下的kube-dnsService 取其 ClusterIP再退化为kube-dns.kube-system.svc.dns域名。同时 proxy 的四个上游apps、worker、MinIO、CouchDB通过upstreams模板变量生成例如APPS_UPSTREAM_URLhttp://app-service.namespace.svc.cluster.local:4002。redis 配置Key类型默认值说明services.redis.enabledbooltrue是否在集群内部署 Redis Podservices.redis.imagestringredisRedis 镜像services.redis.portint6379Redis 端口services.redis.passwordstringbudibaseRedis 连接密码。官方建议在集群内运行时修改默认值services.redis.storagestring100MiRedis 持久化存储大小services.redis.storageClassstring设置后写storageClassName: storageClass设为-则禁用动态供给不设置则使用集群默认 provisionerservices.redis.urlstring若使用 Chart 外部的 Redis在此填写连接地址objectStoreMinIO / S3配置Key类型默认值说明services.objectStore.miniobooltrue设为 false 表示使用 S3 等其他对象存储此时需设置services.objectStore.urlservices.objectStore.browserbooltrue是否启用 MinIO Web 控制台。若将 MinIO 暴露到公网如自定义 Ingress应设为 falseservices.objectStore.accessKeystring使用 S3 时的 AWS_ACCESS_KEYservices.objectStore.secretKeystring使用 S3 时的 AWS_SECRET_ACCESS_KEYservices.objectStore.regionstring使用 S3 时的 AWS_REGIONservices.objectStore.urlstringhttp://minio-service:9000对象存储 URL。仅在使用外部对象存储如 S3时修改并记得同时设minio: falseservices.objectStore.storagestring2GiMinIO 在 PersistentVolumeClaim 中的存储大小services.objectStore.storageClassstring同 redis.storageClass 语义services.objectStore.cloudfront.cdnstring启用 CloudFront 时填写 distribution 的 URLservices.objectStore.cloudfront.publicKeyIdstring存储在 CloudFront 的公钥 IDservices.objectStore.cloudfront.privateKey64string上述公钥对应的 Base64 私钥couchdb 配置Key类型默认值说明services.couchdb.enabledbooltrue是否在集群内启动 CouchDB 实例。为 true 时其详细配置位于根级couchdb键下services.couchdb.portint5984CouchDB 端口services.couchdb.backup.enabledboolfalse是否启用周期性 CouchDB 备份通过复制到另一个 CouchDB 实例实现services.couchdb.backup.intervalstring备份间隔秒services.couchdb.backup.resourcesobject{}备份 Pod 的资源services.couchdb.backup.targetstring备份目标 CouchDB 实例主机名或 IPservices.dnsstringcluster.local服务发现的 DNS 后缀仅当集群使用不同后缀时修改源码解读启用备份后couchdb-backup.yaml 会创建一个使用redgeoff/replicate-couchdb-cluster镜像的 DeploymentRecreate策略通过SOURCE、TARGET、RUN_EVERY_SECS、VERBOSE四个环境变量控制复制源、目标和周期。litellm 配置AI 网关可选Key类型默认值说明services.litellm.enabledboolfalse是否部署 litellm 网关services.litellm.imagestringghcr.io/berriai/litellm:main-v1.83.10-stablelitellm 镜像services.litellm.portint4000litellm 容器端口services.litellm.replicaCountint2litellm 副本数services.litellm.configstring见下以 config.yaml 形式传给 litellm 的内联配置services.litellm.masterKey / saltKey / bbaiKeystringlitellm 主密钥、盐密钥、Budibase AI 虚拟 keyBBAI_LITELLM_KEY会注入 apps 服务与 automation worker源码解读litellm 的启动探针使用 TCP socket 检查因为 litellm 启动时不暴露专用/health端点配置通过 litellm-configmap.yaml 渲染为config.yamlConfigMap 挂载。默认内联配置启用了数据库模式store_model_in_db: true与提示词日志store_prompts_in_spend_logs: true并设置了重试策略。若store_model_in_db为 true需在extraEnv中配置DATABASE_URL指向 PostgreSQL。6.4 顶层通用配置Key类型默认值说明affinityobject{}所有 Pod 的 affinity 设置通常无需修改imagePullSecretslist[]传递给所有 Pod 的镜像拉取凭据nameOverridestring覆盖 deployment 名称默认{{ .Chart.Name }}service.portint10000Service 暴露的端口service.typestringClusterIP指向 Budibase proxy Pod 的 Service 类型serviceAccount.annotationsobject{}ServiceAccount 注解serviceAccount.createbooltrue是否创建 ServiceAccountserviceAccount.namestring使用的 ServiceAccount 名称未设置且 create 为 true 时用 fullname 模板生成tolerationslist[]所有 Pod 的 tolerations通常无需修改此外values.yaml 中还有 README 参数表未覆盖但值得了解的配置podDisruptionBudget默认启用enabled: trueminAvailable: 1会为 proxy、apps、worker、automation worker 及 litellm 分别创建 PDB各服务可用services.name.pdb.minAvailable单独覆盖。services.proxy.rollingUpdate默认maxSurge: 1, maxUnavailable: 0保证零中断滚动更新。globals.deployTimestamp可作为注解盖在每个 Pod 模板上改变其值可触发滚动重启无需更换镜像便于让 Pod 拾取可变 tag 或外部管理的配置变更。services.objectStore.ignoreSelfSigned针对使用自签名证书的 HTTPS 对象存储端点设为 true 可跳过 TLS 证书校验。services.redis.usernameRedis 6 启用 ACL 认证时需要。七、配置要点与实战建议1. 密钥管理优先考虑自动生成默认createSecrets: true会在首次安装时生成全部六个密钥并持久化在 Kubernetes Secret 中secrets.yaml 通过lookup保证幂等复用。因此不要在 values.yaml 中硬编码globals.internalApiKey、globals.jwtSecret、globals.apiEncryptionKey等敏感值密钥轮换时利用internalApiKeyFallback与jwtSecretFallback设置旧值过渡避免服务中断。2. 持久化存储三件套CouchDB10Gi、MinIO2Gi、Redis100Mi各自有独立 PV。在 NFS 等共享存储环境如 README 的 HomeLab 示例统一指定storageClass即可在生产环境建议为 CouchDB 提供高性能存储并考虑clusterSize: 3的高可用拓扑。3. 对外暴露与 HTTPS所有对外流量都经过proxy-service10000 端口通用场景启用ingress.enabled: true并配置className与hostsEKS 场景启用awsAlbIngress.enabled: true配合 ACM 证书 ARN 自动获得 HTTPS 与 HTTP→HTTPS 重定向若将 MinIO 通过自定义 Ingress 暴露到公网务必设置services.objectStore.browser: false关闭 Web 控制台。4. 弹性扩缩容为 proxy/apps/worker 分别启用services.name.autoscaling.enabled设置minReplicas/maxReplicas/targetCPUUtilizationPercentage。前提是集群装有 metrics-server且对应服务设置了resources否则 HPA 无法计算利用率。注意 automationWorkers 的 HPA 在 README 参数表中标注为 apps service实际作用于 automation worker配置时以services.automationWorkers.autoscaling.*为准。5. 故障排查resolver 问题如果 proxy Pod 启动失败且日志提示 resolver 相关错误优先检查services.proxy.resolver。该值必须是 IPproxy-service-deployment.yaml 中 Nginx 在配置加载时解析一次自动探测依赖lookup权限RBAC 受限时需手动获取kubectl -n kube-system get svc kube-dns -o jsonpath{.spec.clusterIP}。八、总结Budibase Helm Chart 通过一组精心编排的模板templates 目录下 20 余个 YAML将 apps、worker、automation worker、proxy、CouchDB、MinIO、Redis 等组件统一封装配合自动生成的密钥 Secret 与可选 LiteLLM AI 网关形成一套开箱即用、可弹性伸缩、可生产化配置的 Kubernetes 部署方案。结合 README.md 的参数表与仓库模板源码你可以按需调整 Ingress、持久化、HPA、SMTP、OAuth、备份与对象存储等维度将 Budibase 稳定运行在任何符合前置条件的 Kubernetes 集群上。进一步深入学习可参考Chart 主文档本文的原始依据values.yaml全部可配置项与默认值app-service-deployment.yaml 与 worker-service-deployment.yaml核心服务的环境变量注入逻辑secrets.yaml密钥自动生成与复用机制alb-ingress.yamlEKS ALB 集成细节couchdb-backup.yamlCouchDB 周期备份实现【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考