Budibase 内嵌 Apache CouchDB Helm Chart 部署与配置全指南集群安装、密钥管理、升级迁移与参数详解【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibaseApache CouchDB 是一款支持无缝多主multi-master同步的 NoSQL 数据库从大数据量到移动端场景均可伸缩并提供直观的 HTTP/JSON API 与高可靠性设计。Budibase 的 Kubernetes 官方 Chartcharts/budibase将上游 Apache CouchDB Helm Chart 作为子 Chart 完整内嵌用于为 Budibase 应用、自动化与工作流提供底层数据存储。本文以仓库内 couchdb 子 Chart README 为骨架结合其 values.yaml 与模板源码系统讲解如何在 Kubernetes 上部署、配置、升级与迁移 CouchDB 集群。读完本文你将掌握 CouchDB Helm Chart 的完整参数体系、管理员密钥的三种注入方式、UUID 与 adminHash 的集群一致性要求以及它在 Budibase 主 Chart 中的实际落地方式。CouchDB 在 Budibase 中的角色Budibase 是一个AI agents、自动化与应用驱动业务运营的低代码平台其 Helm Chart 默认会在集群内拉起一个 CouchDB 实例见 主 Chart values.yaml 中services.couchdb配置默认enabled: true端口 5984。Budibase 的应用数据、文档模型都存储在 CouchDB 中因此理解该子 Chart 的部署与配置是自托管 Budibase 的关键前置技能。该子 Chart 使用 StatefulSet 部署 CouchDB 集群并在其前端创建一个 ClusterIP Service 用于负载均衡同时默认额外生成一个 headless Service 作为集群节点间通信的稳定网络标识详见下文双 Service 架构。默认持久化方式为临时本地文件系统生产环境务必开启persistentVolume.enabled。前置条件Kubernetes 1.9且启用 Beta API如需使用 Ingress要求 Kubernetes 1.19已安装 Helm并具备向目标集群安装 Release 的权限。快速部署TL;DR以下命令以最简方式完成安装先添加 CouchDB 官方 Helm 仓库再以--set方式开启allowAdminParty集群将以无管理员账户的管理派对模式启动所有用户均获得管理权限并注入一个随机 UUID$ helm repo add couchdb https://apache.github.io/couchdb-helm $ helm install couchdb/couchdb \ --version4.5.3 \ --set allowAdminPartytrue \ --set couchdbConfig.couchdb.uuid$(curl https://www.uuidgenerator.net/api/version4 2/dev/null | tr -d -)说明couchdbConfig.couchdb.uuid是集群必需参数详见升级到 3.0.0任何安装/升级都必须在命令行或 values 文件中提供。完整安装步骤以 Release 名my-release安装注意先将文档示例中的 UUIDdecafbaddecafbaddecafbaddecafbad替换为你自定义的值$ helm repo add couchdb https://apache.github.io/couchdb-helm $ helm install \ --name my-release \ --version4.5.3 \ --set couchdbConfig.couchdb.uuiddecafbaddecafbaddecafbaddecafbad \ couchdb/couchdb安装后Chart 会创建一个包含集群管理员凭据的 Secret可用如下命令取回自动生成的adminPassword$ kubectl get secret my-release-couchdb -o go-template{{ .data.adminPassword }} | base64 --decode管理员凭据的三种注入方式方式一由 Chart 自动生成默认。createAdminSecret默认为truesecrets.yaml 会生成名为ReleaseName-couchdb的 Secret其中包含adminUsername、adminPassword、erlangCookie与cookieAuthSecret等键。方式二预先创建自定义 Secret。提前用kubectl create secret创建包含adminUsername、adminPassword和cookieAuthSecret三个键的 Secret$ kubectl create secret generic my-release-couchdb \ --from-literaladminUsernamefoo \ --from-literaladminPasswordbar \ --from-literalcookieAuthSecretbaz方式三固定adminHash保证跨节点盐值一致。若希望集群各节点的管理员密码哈希保持一致避免各节点哈希不一致导致集群会话异常可在 Secret 中直接放入adminHash并在安装时通过--set createAdminSecretfalse关闭自动生成$ kubectl create secret generic my-release-couchdb \ --from-literaladminUsernamefoo \ --from-literalcookieAuthSecretbaz \ --from-literaladminHash-pbkdf2-d4b887da.... $ helm install \ --name my-release \ --version4.5.3 \ --set createAdminSecretfalse \ --set couchdbConfig.couchdb.uuiddecafbaddecafbaddecafbaddecafbad \ couchdb/couchdb从源码看当adminHash存在时statefulset.yaml 会额外注入一个名为admin-hash-copy的 init 容器将[admins]段写入/local.d/password.ini从而以配置文件方式固定管理员哈希。提示可用helm list查看当前集群中的所有 Release。卸载 Chart卸载会删除与该 Release 关联的所有 Kubernetes 组件$ helm delete my-release升级到新 Major 版本Chart 主版本号变化如 v0.2.3 → v1.0.0意味着存在不兼容的破坏性变更需要人工介入。升级到 3.0.0UUID 成为必填自 3.0.0 起CouchDB 服务实例 UUID 必须显式设置。升级时必须生成 UUID 并通过 values 传入$ helm upgrade release-name \ --version3.6.4 \ --reuse-values \ --set couchdbConfig.couchdb.uuidUUID \ couchdb/couchdb这一强制性在模板中有直接体现configmap.yaml 渲染 inifile 时首先注入couchdb.uuid而 _helpers.tpl 中的couchdb.uuid定义使用required校验——若未设置会直接渲染失败并报错 A value for couchdbConfig.couchdb.uuid must be set。升级到 4.0.0adminHash 语义变化v3 与 v4 之间的破坏性变更是 Secret 中的adminHashv4 不再使用password.ini方式存放明文密码派生配置而是只存储adminHash本身。如果你使用自定义 Secret务必据此更新。从 stable/couchdb 迁移该 Chart 取代了 Helm 官方仓库中已被移除的stable/couchdbChart并延续其版本语义。可直接从stable/couchdb平滑升级$ helm repo add couchdb https://apache.github.io/couchdb-helm $ helm upgrade my-release --version4.5.3 couchdb/couchdb核心配置参数下表为最常用的配置参数及其默认值对应 values.yamlKey类型默认值说明allowAdminPartyboolfalse开启后集群启动时不创建管理员账户所有用户均获得管理权限关闭时系统会查找名为ReleaseName-couchdb的 Secret其中需含adminUsername、adminPassword和cookieAuthSecret键参见createAdminSecretclusterSizeint3CouchDB 集群初始节点数直接映射为 StatefulSet 的replicas见 statefulset.yamlcouchdbConfigobject{chttpd:{bind_address:any,require_valid_user:false}}覆盖默认 CouchDB 配置该 map 会被重排为.ini文件并通过 ConfigMap 下发createAdminSecretbooltrue开启时创建含自动生成凭据的 SecretReleaseName-couchdb若希望自行管理可在 values 中直接定义adminUsername、adminPassword、adminHash、cookieAuthSecret注意 values 会以明文形式存储在 Tiller 命名空间的 ConfigMap 中或关闭本开关并提前创建含所需键的 SecretenableSearchboolfalse开启后为每个 Pod 附带 SearchClouseau容器用于 Lucene 全文检索erlangFlagsobject{name:couchdb}通过ERL_FLAGS环境变量传递给 Erlang VM 的旗标name是建立集群节点间连接所必需的persistentVolumeobject{accessModes:[ReadWriteOnce],enabled:false,size:10Gi}StatefulSet 中每个 Pod 使用的存储卷未开启时 Pod 使用emptyDir临时存储。storageClass设为-可禁用动态供应留空则使用集群默认 provisionercouchdbConfig 关键项couchdbConfig的取值遵循 CouchDB 官方配置文档其中默认值及必填项如下参数说明默认值couchdb.uuid该 CouchDB 服务实例的 UUID集群场景下必填无chttpd.bind_address设为any时监听所有网卡anychttpd.require_valid_user设为true时禁用 5984 端口上的所有匿名请求false从模板渲染逻辑看configmap.yaml 会把couchdbConfig的每个 section 与 key 拼装为标准 INI 格式如[chttpd]、bind_address any再由 init 容器复制到/opt/couchdb/etc/default.d/下见 statefulset.yaml。这解释了为什么任意 CouchDB 配置项都能通过该 map 直接注入。集群 seedlist 与 DNSConfigMap 中第二个 keyseedlistinifile会生成[cluster] seedlist ...配置节点 FQDN 由 _helpers.tpl 中的couchdb.seedlist定义生成格式为couchdbrelease-couchdb-序号.release-couchdb.namespace.svc.clusterDomainSuffix最多列出 5 个节点域名后缀由dns.clusterDomainSuffix控制默认cluster.local。这正是 CouchDB 节点互相发现并组建集群的网络基础。完整参数一览以下参数均可在 values 中配置详见 values.yaml 注释参数默认值adminUsernameadminadminPassword自动生成adminHash空cookieAuthSecret自动生成extraPorts[]ContainerPort 对象列表image.repositorycouchdbimage.tag3.3.3image.pullPolicyIfNotPresentsearchImage.repositorykocolosk/couchdb-searchsearchImage.tag0.2.0以仓库 values.yaml 为准searchImage.pullPolicyIfNotPresentinitImage.repositorybusyboxinitImage.taglatestinitImage.pullPolicyAlwaysingress.enabledfalseingress.className空ingress.hostschart-example.localingress.annotations空ingress.path/ingress.tls空persistentVolume.accessModesReadWriteOncepersistentVolume.storageClass集群默认persistentVolume.annotations{}persistentVolume.existingClaims[]含volumeName、claimName、persistentVolumeName、volumeSource的 PV/PVC 对象列表数量须与 clusterSize 一致persistentVolume.volumeName空persistentVolume.claimName空persistentVolume.volumeSource空persistentVolumeClaimRetentionPolicy.enabled控制 StatefulSet 生命周期中 PVC 的删除行为persistentVolumeClaimRetentionPolicy.whenScaledStatefulSet 副本缩减时卷的保留策略RetainpersistentVolumeClaimRetentionPolicy.whenDeletedStatefulSet 删除时卷的保留策略RetainpodDisruptionBudget.enabledfalsepodDisruptionBudget.minAvailablenilpodDisruptionBudget.maxUnavailable1podManagementPolicyParallelaffinity/topologySpreadConstraints/tolerations空labels/annotations空resources/initResources空autoSetup.enabledfalse开启时要求service.enabledtrue且 Secret 中有正确的adminPassword建议配合--wait安装以避免首个 Job 失败autoSetup.image.repository/tag/pullPolicycurlimages/curl / latest / AlwaysautoSetup.defaultDatabases[_global_changes]service.annotations/labels空service.enabledtrueservice.typeClusterIPservice.externalPort5984service.targetPort5984service.extraPorts[]ServicePort 对象列表dns.clusterDomainSuffixcluster.localnetworkPolicy.enabledtrueserviceAccount.enabled/serviceAccount.createtrue / trueimagePullSecrets空sidecars{}livenessProbe.enabled/failureThreshold/initialDelaySeconds/periodSeconds/successThreshold/timeoutSecondstrue / 3 / 0 / 10 / 1 / 1readinessProbe.*true / 3 / 0 / 10 / 1 / 1prometheusPort.enabled/port/bind_addressfalse / 17986以仓库 values.yaml 为准/ 0.0.0.0placementConfig.enabledfalseplacementConfig.image.repository/tagcaligrafix/couchdb-autoscaler-placement-manager / 0.1.0podSecurityContext/containerSecurityContext空从源码理解部署拓扑双 Service 架构headless Serviceheadless.yamlclusterIP: None且publishNotReadyAddresses: true为 StatefulSet 的每个 Pod 提供稳定网络标识是集群节点互相发现的基础客户端 Serviceservice.yaml默认ClusterIP类型暴露 5984 端口externalPort/targetPort对外提供负载均衡入口可通过service.type切换为 NodePort/LoadBalancer或配合ingress.*暴露到集群外部。探针与安全当couchdbConfig.chttpd.require_valid_usertrue时statefulset.yaml 中的存活/就绪探针会从httpGet自动切换为带-u ${COUCHDB_USER}:${COUCHDB_PASSWORD}的 exec curl 检查确保匿名请求被禁后探针仍可正常工作。networkPolicy.enabled默认为true默认生成的 NetworkPolicy 允许集群内任意来源访问 5984 端口及额外端口并仅允许 CouchDB Pod 之间互访 9100epmd与 4369 端口用于集群内部通信见 networkpolicy.yaml。autoSetup 自动建库将autoSetup.enabled设为true时Chart 会创建一个post-install钩子 Jobjob.yaml向/_cluster_setup发送{action: finish_cluster}完成集群收尾随后按autoSetup.defaultDatabases列表依次PUT创建数据库默认_global_changes。该 Job 依赖客户端 Service 与有效密码因此文档明确要求安装时携带--wait。在 Budibase 主 Chart 中的实际应用Budibase 主 Chart 在其 values.yaml 的couchdb:段中覆盖了子 Chart 的关键值用于开箱即用的自托管部署clusterSize: 1默认单节点注释说明可改为 3 以获得高可用image.repository: budibase/database、tag: 2.1.0使用 Budibase 定制镜像并在extraEnvs中注入DATA_DIR/data该镜像内置 Clouseau 搜索组件故enableSearch保持falsepersistentVolume.enabled: true、size: 10Gi、mountPath: /data默认开启持久化存储couchdbConfig.couchdb.uuid: budibase-couchdb固定集群 UUIDextraPorts与service.extraPorts默认暴露 SQS 端口 4984与仓库 hosting/sqs 目录中的 SQS 组件对应主 Chart 的代理服务通过http://release-svc-couchdb:5984访问 CouchDB见services.proxy.upstreams。若你的 Budibase 部署需要高可用 CouchDB可在安装主 Chart 时覆盖couchdb.clusterSize3并注意所有节点需共享一致的adminHash/cookieAuthSecret与集群 UUID这正是本文升级到 4.0.0一节强调的要点。运维提示生产环境务必开启persistentVolume.enabled否则 Pod 重建后数据将丢失emptyDir仅适合开发验证。多节点集群务必显式设置couchdbConfig.couchdb.uuid并保持一致否则节点将无法加入同一集群。若需匿名访问保持chttpd.require_valid_userfalse开启后记得为 Fauxton 配置httpd.WWW-Authenticatevalues 中已有示例注释。可结合podDisruptionBudget如maxUnavailable: 1、affinity的podAntiAffinity与topologySpreadConstraints提升集群在节点故障场景下的可用性。从 CouchDB 3.2.0 起提供/_node/_local/_prometheus指标端点开启prometheusPort.enabled可暴露独立的未认证指标端口供 Prometheus 采集。反馈与贡献该 Chart 源自 Apache CouchDB 上游 Helm Chart欢迎通过项目 Issue 提交反馈。Budibase 仓库根目录的 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md 提供了参与贡献与问题上报的规范指引。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考