企业官网建设流程全解析

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

【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase

Budibase 是一个开源的 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:v2（Helm 3 标准格式）
• type:application
• 依赖：官方 Apache CouchDB Chart（couchdb，版本4.5.6），仅在services.couchdb.enabled为 true 时安装

按照 README.md 的要求，在开始安装之前，你的集群需要满足以下前置条件：

值得注意的是，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 CouchDB

Budibase 使用 CouchDB 作为主数据库。该 Chart 依赖官方的 Apache CouchDB Helm Chart（版本 4.5.6），完整依赖声明位于 Chart.yaml：

dependencies: - name: couchdb version: 4.5.6 repository: https://apache.github.io/couchdb-helm condition: services.couchdb.enabled

需要注意以下几点（结合 values.yaml 中的couchdb段）：

1. 使用自定义镜像：Budibase 使用自己构建的 CouchDB 镜像（budibase/database），并将 Clouseau 搜索组件内置其中，官方不支持替换为其他 CouchDB 镜像，否则无法保证 Budibase 正常工作。因此在 values.yaml 中对应注释明确写着 "You shouldn't change this, and if you do we can't guarantee that Budibase will work."
2. 集群规模：couchdb.clusterSize默认为1，简单场景足够；如果追求高可用，可设置为3。
3. SQS 端口：Chart 默认在 CouchDB Service 上额外暴露 SQS 端口（4984），该端口用于 Budibase 的 SQL 查询能力（对应 Deployment 中的COUCH_DB_SQL_URL环境变量）。
4. 持久化：CouchDB 数据默认持久化在/data路径（对应DATA_DIR环境变量），PV 默认大小10Gi。
5. 搜索能力：enableSearch被强制固定为false，因为 Clouseau 已随budibase/database镜像内置，属于 Budibase 核心体验的一部分，不可单独关闭。

三、从 2.x 升级到 3.0.0：破坏性变更清单

README 专门用一个章节列出了从 2.x 升级到 3.0.0 的破坏性变更。升级前请逐条核对你的现有配置：

1. 不再内置ingress-nginx：如果你此前依赖 Chart 自带的 ingress-nginx 提供 Ingress 控制器，升级后需要自行单独部署 ingress-nginx，官方指引为 Kubernetes 官方 ingress-nginx 文档。
2. CouchDB Chart 版本升级：从3.3.4升级到4.3.0，主要动机是让 Chart 版本与 CouchDB 运行时版本对齐（CouchDB 从 3.1.1 升级到 3.2.1）。同时官方 CouchDB 镜像被替换为 Budibase 自建镜像。
3. AWS ALB Ingress 独立成块：此前在 EKS 中通过ingress.enabled: false+ingress.aws: true启用的 AWS ALB Ingress，现在改为awsAlbIngress.enabled: true，且所有相关配置统一收敛在awsAlbIngress命名空间下。
4. 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 git@github.com:budibase/budibase.git $ cd budibase/charts/budibase $ helm install --create-namespace --namespace budibase budibase .

卸载

$ helm uninstall --namespace budibase budibase

安装后，Chart 会在budibase命名空间中创建以下核心资源（对应 templates 目录）：

• app-service：Budibase 应用服务（app-service-deployment.yaml），容器端口 4002
• worker-service：后台 Worker 服务（worker-service-deployment.yaml），容器端口 4003
• automation-worker-service：自动化执行 Worker（automation-worker-service-deployment.yaml）
• proxy-service：Nginx 反向代理（proxy-service-deployment.yaml），对外端口 10000，负责将请求路由到 apps、worker、MinIO、CouchDB 各上游
• minio-service：MinIO 对象存储（minio-service-deployment.yaml）
• redis-service：Redis 缓存（redis-service-deployment.yaml）
• couchdb：依赖子 Chart 提供的 CouchDB 集群
• litellm-service：可选的 LiteLLM AI 网关（litellm-service-deployment.yaml）
• Secrets：自动生成内部密钥（secrets.yaml）

其中 proxy 是唯一对外的入口，所有 Ingress 都指向proxy-service的 10000 端口。

五、最小可运行配置示例（HomeLab 场景）

README 给出了一个非常实用的示例：在家庭集群中，使用 nginx Ingress 控制器 + NFS 作为集群存储，将 Budibase 跑起来的最小values.yaml：

ingress: enabled: true className: "nginx" hosts: - host: budibase.local # set this to whatever DNS name you'd 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

这个示例点明了三个关键配置思路：

1. Ingress 指向 proxy-service 的 10000 端口：Ingress 的默认后端是proxy-service，所有流量经由 Nginx 代理再分发到内部服务（这与 ingress.yaml 的默认hosts结构完全一致）。
2. 三个持久化存储位置：CouchDB（数据库）、MinIO（对象存储）、Redis（缓存）都需要持久化，在 NFS 场景下统一指定storageClass: "nfs-client"即可。
3. CouchDB 管理员密码：couchdb.adminPassword需要在首次部署时指定。官方上游 Chart 默认不为 admin 用户设置持久化密码，values.yaml 中专门注释提醒：要让密码持久化必须显式设置adminPassword。

六、配置参数全解：结合源码逐项解读

以下是 README 中完整的配置参数表（继承自 values.yaml 的 helm-docs 自动生成），并补充了源码级解读。

6.1 全局配置（globals）

源码解读：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 ALB

源码解读：标准 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 通用配置

注：apps 与 worker 额外支持logLevel（默认info）与httpLogging（默认1）；automationWorkers 额外支持enabled（默认true，关闭后自动化改由 apps 服务处理）。

源码解读：探针默认值在 values.yaml 中定义，均为 HTTP GET 健康检查。例如 apps 服务的 readiness 探针每 3 秒检查/health，liveness 探针每 5 秒检查/health。各 Deployment 模板（如 app-service-deployment.yaml）还内置了preStop钩子（sleep preStopDelaySeconds，默认 45 秒）用于等待负载均衡器注销，配合terminationGracePeriodSeconds: 70保证零中断滚动更新。HPA 模板（如 proxy-service-hpa.yaml）会自动选择autoscaling/v2或v2beta2API，并支持 CPU 与内存双指标。

proxy 专属配置

源码解读：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_URL=http://app-service.<namespace>.svc.cluster.local:4002。

redis 配置

objectStore（MinIO / S3）配置

couchdb 配置

源码解读：启用备份后，couchdb-backup.yaml 会创建一个使用redgeoff/replicate-couchdb-cluster镜像的 Deployment（Recreate策略），通过SOURCE、TARGET、RUN_EVERY_SECS、VERBOSE四个环境变量控制复制源、目标和周期。

litellm 配置（AI 网关，可选）

源码解读：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 顶层通用配置

此外，values.yaml 中还有 README 参数表未覆盖但值得了解的配置：

• podDisruptionBudget：默认启用（enabled: true，minAvailable: 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.username：Redis 6+ 启用 ACL 认证时需要。

七、配置要点与实战建议

1. 密钥管理优先考虑自动生成

默认createSecrets: true会在首次安装时生成全部六个密钥并持久化在 Kubernetes Secret 中（secrets.yaml 通过lookup保证幂等复用）。因此：

• 不要在 values.yaml 中硬编码globals.internalApiKey、globals.jwtSecret、globals.apiEncryptionKey等敏感值；
• 密钥轮换时，利用internalApiKeyFallback与jwtSecretFallback设置旧值过渡，避免服务中断。

2. 持久化存储三件套

CouchDB（10Gi）、MinIO（2Gi）、Redis（100Mi）各自有独立 PV。在 NFS 等共享存储环境（如 README 的 HomeLab 示例）统一指定storageClass即可；在生产环境建议为 CouchDB 提供高性能存储并考虑clusterSize: 3的高可用拓扑。

3. 对外暴露与 HTTPS

所有对外流量都经过proxy-service（10000 端口）：

• 通用场景：启用ingress.enabled: true并配置className与hosts；
• EKS 场景：启用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。该值必须是 IP（proxy-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.yaml：EKS ALB 集成细节
• couchdb-backup.yaml：CouchDB 周期备份实现

【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase