云原生容器编排【免费下载链接】chartsBitnami Helm Charts项目地址https://gitcode.com/GitHub_Trending/charts30/charts点击查看免费下载Matomo前身 Piwik是一款实时 Web 分析软件可为网站访客行为提供详细报告。本指南以当前仓库中的 Bitnami Matomo Helm ChartChart.yaml为骨架系统讲解如何通过 Helm 在 Kubernetes 上完成 Matomo 的一键部署、参数化配置、持久化、监控接入与定时归档等全流程运维。读完本文你将掌握从裸集群到生产可用的 Matomo 分析平台所需的完整配置方法与底层实现原理。一、Chart 概览Matomo 是如何被打包的本 Chart 位于bitnami/matomo/用于在 Kubernetes 集群上通过 Helm 引导一个完整的 Matomo 部署其核心信息如下Chart 版本11.0.1应用版本appVersion5.3.2对应bitnami/matomo容器镜像 5.3.2 系列类型applicationtanzuCategory关键字为 matomo、analytics、php、web 等依赖在 Chart.yaml 中声明了两个子 Chartmariadb条件依赖mariadb.enabled默认安装用于为 Matomo 提供数据库commonbitnami-common 2.x提供命名、标签、亲和性、资源预设等公共模板能力。Chart 的模板文件位于 bitnami/matomo/templates/其中核心资源包括deployment.yaml主 Deployment承载 MatomoApache PHP容器、metrics 边车容器以及各类 init 容器cronjob.yaml两个定时任务 CronJob归档与计划任务pvc.yaml / pv.yaml数据卷声明与 hostPath 支持secrets.yaml应用密码与 SMTP 密码的 Secretsvc.yaml、ingress.yaml流量暴露networkpolicy.yaml、pdb.yaml网络安全与调度保护postinit-configmap.yaml自定义 post-init 脚本挂载。二、前置条件与快速安装2.1 环境要求部署前需要确认集群满足以下前置条件Kubernetes 1.23Helm 3.8.0底层基础设施支持PV Provisioner若要将replicaCount扩到多个副本需要底层存储支持ReadWriteMany卷默认replicaCount1仅需 ReadWriteOnce2.2 TL;DR 一键安装helm install my-release oci://registry-1.docker.io/bitnamicharts/matomo这是最简安装方式Chart 会同时拉起 Matomo 应用与一个独立 MariaDB 实例并在首次启动时自动完成 Matomo 的安装向导与数据库初始化。2.3 指定镜像仓库安装在安装命令中REGISTRY_NAME与REPOSITORY_NAME需要替换为实际的 Chart 仓库。例如 Bitnami 官方仓库helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/matomo即REGISTRY_NAMEregistry-1.docker.io、REPOSITORY_NAMEbitnamicharts。安装完成后可用helm list查看当前所有 release。三、配置参数总览ParametersChart 的完整可配置项集中在 values.yaml按功能划分为若干参数组。以下是各组的关键参数安装时可通过--set keyvalue或-f values.yaml覆盖。3.1 Global 与 Common 参数参数说明默认值global.imageRegistry全局镜像仓库覆盖包括子 Chart 在内的所有镜像global.imagePullSecrets全局镜像拉取 Secret 名数组[]global.defaultStorageClass全局默认 StorageClassglobal.security.allowInsecureImages是否跳过镜像验证falseglobal.compatibility.openshift.adaptSecurityContextOpenshift restricted-v2 SCC 适配可选auto检测到 Openshift 时应用、force、disabledautokubeVersion强制指定目标 Kubernetes 版本nameOverride/fullnameOverride/namespaceOverride覆盖资源命名与命名空间commonAnnotations/commonLabels为所有 Matomo 资源添加公共注解/标签模板化求值{}extraDeploy随 release 额外部署的对象数组[]usePasswordFiles凭据以文件方式挂载而非环境变量true3.2 Matomo 应用参数参数说明默认值image.registry/image.repository/image.tagMatomo 镜像地址与标签当前默认5.3.2-debian-12-r12docker.io/bitnami/matomoimage.digest指定镜像 digest设置后将覆盖 tagimage.pullPolicy镜像拉取策略IfNotPresentimage.pullSecrets镜像拉取 Secret 数组[]image.debug是否输出调试日志对应BITNAMI_DEBUGfalsereplicaCount副本数需要 ReadWriteMany PVC1matomoUsername/matomoPassword管理员账号与密码密码未设置时自动生成随机 10 位字符串user/matomoEmail管理员邮箱userexample.commatomoWebsiteName/matomoWebsiteHost站点名称与分析目标站点地址example/https://example.orgmatomoSkipInstall跳过安装向导迁移、从 SQL dump 恢复时很有用对应环境变量MATOMO_SKIP_BOOTSTRAPfalsecustomPostInitScripts自定义 post-init.d 脚本支持.sh或.php仅在容器首次启动执行{}allowEmptyPassword是否允许数据库空密码对应ALLOW_EMPTY_PASSWORDtrueupdateStrategy.type更新策略单副本 RWO 卷时建议Recreate避免更新卡死RollingUpdatepdb.create/pdb.minAvailable/pdb.maxUnavailablePod 中断预算两者都为空时默认maxUnavailable1true//sidecars/initContainers/extraEnvVars/extraVolumes扩展容器与自定义环境/存储[]existingSecret应用密码所在 Secret 名称containerPorts.http/containerPorts.https容器监听端口对应APACHE_HTTP_PORT_NUMBER/APACHE_HTTPS_PORT_NUMBER8080/8443值得说明的是默认hostAliases中包含了127.0.0.1 - status.localhost这是为了让 apache-exporter 边车能够通过http://status.localhost:8080/server-status/?auto抓取 Apache 状态页见 deployment.yaml 与 metrics 容器命令。3.3 SMTP 邮件配置参数说明默认值smtpAuth认证机制Plain/Login/Cram-md5smtpHost/smtpPortSMTP 服务器与端口smtpUser/smtpPasswordSMTP 账号与密码smtpProtocol协议ssl/tls/nilnoreplyName/noreplyAddress发件人名称与地址对应MATOMO_NOREPLY_NAME/MATOMO_NOREPLY_ADDRESSsmtpExistingSecret已有 SMTP 凭据 Secret须含smtp-password键设置后忽略smtpPassword从模板实现看这些值会按需映射为MATOMO_SMTP_AUTH、MATOMO_SMTP_HOST、MATOMO_SMTP_PORT、MATOMO_SMTP_USER、MATOMO_SMTP_PROTOCOL等环境变量供 Bitnami Matomo 镜像的初始化脚本消费。3.4 探针Probe参数参数说明默认值startupProbe.enabled启用启动探针路径/matomo.phpfalselivenessProbe.enabled存活探针基于 HTTP 端口 TCP 探测truereadinessProbe.enabled/readinessProbe.path就绪探针HTTP GET/matomo.phptrue//matomo.phpcustomStartupProbe/customLivenessProbe/customReadinessProbe完全自定义探针覆盖{}Matomo 根路径/matomo.php对未认证请求可直接响应因此适合作为启动与就绪探针路径若改用自定义镜像或修改了路由建议通过自定义探针覆盖默认值。3.5 使用--set与 values 文件helm install my-release \ --set matomoUsernameuser,matomoPasswordpassword,mariadb.auth.rootPasswordsecretpassword \ oci://REGISTRY_NAME/REPOSITORY_NAME/matomo上述命令将管理员账号设为user、密码设为password并将 MariaDB root 密码设为secretpassword。也可把参数写入 YAML 后通过-f传入helm install my-release -f values.yaml oci://REGISTRY_NAME/REPOSITORY_NAME/matomo重要提示Chart 部署完成后无法再通过 Helm 修改应用访问凭据。如需变更只能删除 Chart 使用的持久卷后重新部署或使用应用自带的管理工具修改。四、数据库内置 MariaDB 与外部数据库Chart 默认在mariadb.enabledtrue时随应用一并部署 Bitnami MariaDB 子 Chart为 Matomo 自动创建数据库与用户默认库bitnami_matomo、用户bn_matomo。4.1 内置 MariaDB 关键参数参数说明默认值mariadb.enabled是否部署内置 MariaDBtruemariadb.architecture架构standalone或replicationstandalonemariadb.auth.rootPasswordMariaDB root 密码mariadb.auth.database创建的数据库名bitnami_matomomariadb.auth.username/mariadb.auth.password数据库用户与密码bn_matomo/mariadb.primary.persistence.enabled数据库持久化truemariadb.primary.persistence.size数据库卷大小8Gimariadb.primary.resourcesPreset/mariadb.primary.resources数据库容器资源预设/自定义资源micro/{}4.2 外部数据库将mariadb.enabled设为false并配置externalDatabase即可接入已有数据库参数说明默认值externalDatabase.host数据库主机externalDatabase.port端口3306externalDatabase.user/externalDatabase.password数据库用户与密码bn_matomo/externalDatabase.database数据库名bitnami_matomoexternalDatabase.existingSecret存放数据库凭据的 Secret数据库连接信息由 _helpers.tpl 中的matomo.databaseHost、matomo.databasePort、matomo.databaseName、matomo.databaseUser、matomo.databaseSecretName等模板函数统一计算内置 MariaDB 时主机指向RELEASE-mariadbreplication 架构下指向RELEASE-mariadb-primary、密码键为mariadb-password外部数据库时使用externalDatabase各字段、密码键为db-password。这保证了 Deployment 与两个 CronJob 使用完全一致的数据库连接配置。五、持久化PVC、已有卷与 hostPathBitnami Matomo 镜像将站点数据与配置保存在容器的/bitnami/matomo路径。Chart 通过 PersistentVolumeClaim 保证数据跨部署留存该方案已确认可在 GCE、AWS 与 minikube 上工作。5.1 持久化参数参数说明默认值persistence.enabled启用 PVC 持久化关闭后回退到emptyDirtruepersistence.storageClass卷的 StorageClass-表示禁用动态供给persistence.accessModes访问模式[ReadWriteOnce]persistence.size容量请求8Gipersistence.dataSource自定义 PVC 数据源{}persistence.existingClaim复用已有 PVC需先手动创建persistence.hostPath挂载到宿主机指定路径persistence.annotations/persistence.selectorPVC 注解 / 匹配已有 PV 的 selector{}5.2 复用已有 PVC先创建 PersistentVolume再创建 PersistentVolumeClaim安装时指定helm install my-release --set persistence.existingClaimPVC_NAME oci://REGISTRY_NAME/REPOSITORY_NAME/matomo从 pvc.yaml 的实现可以看到设置了existingClaim后 Chart 不再生成 PVCDeployment 直接引用该 Claimpersistence.hostPath被设置时storageClassName会被强制置空由 pv.yaml 生成对应的 hostPath PV。5.3 hostPath 挂载本地开发场景系统兼容性已在 OSX/MacOSxhyve 驱动与 LinuxVirtualBox验证Windows 未验证minikube 官方支持按 Pod 挂载宿主目录。步骤确保指定的 hostPath 目录已存在安装helm install my-release --set persistence.hostPath/PATH/TO/HOST/MOUNT oci://REGISTRY_NAME/REPOSITORY_NAME/matomo此时matomo-data卷挂载到该 hostPath 目录目录中有有效数据则直接复用否则在首次启动时初始化由于容器无法控制宿主机目录权限需自行设置 Matomo 文件目录的权限。5.4 备份与恢复推荐使用 Velero 进行备份恢复将源部署的 Persistent Volume 备份后挂载到新部署即可完成迁移完整操作流程可参考 Velero 官方文档及 Bitnami 应用目录的备份恢复指南。此外volumePermissions参数组默认关闭可以在默认runAsUser/fsGroup不生效的存储环境下启用 init 容器对/bitnami/matomo目录执行 chown见 _helpers.tpl。六、流量暴露Service 与 Ingress6.1 Service 参数参数说明默认值service.typeService 类型LoadBalancerservice.ports.http/service.ports.httpsService 对外端口80/443service.loadBalancerSourceRanges限制 LoadBalancer 来源 IP[]service.loadBalancerIP指定负载均衡 IP云厂商相关service.nodePortsNodePort30000-32767{}service.externalTrafficPolicy客户端源 IP 保留策略Clusterservice.sessionAffinity会话亲和性None或ClientIPNoneservice.extraPorts/service.annotations附加端口与注解[]/{}在 svc.yaml 中targetPort直接引用容器命名端口http/https与containerPorts一一对应。minikube 等本地环境建议将service.type改为NodePort。6.2 Ingress 参数参数说明默认值ingress.enabled启用 Ingressfalseingress.pathType路径类型ImplementationSpecificingress.ingressClassNameIngressClassKubernetes 1.18ingress.hostname默认域名matomo.localingress.path路径ALB 控制器可能需设为/*/ingress.annotations注解可放 cert-manager 自动签发注解{}ingress.tls/ingress.selfSigned启用 TLS / 用 Helm 生成自签名证书falseingress.extraHosts/ingress.extraPaths/ingress.extraTls/ingress.extraRules/ingress.secrets附加主机、路径、TLS、规则与证书 Secret[]七、安全与加固配置7.1 Security Context 默认值Chart 默认开启 Pod 与容器两级安全上下文podSecurityContext.fsGroup1001、fsGroupChangePolicyAlwayscontainerSecurityContext.runAsUser1001、runAsGroup0、runAsNonRoottrue、privilegedfalseallowPrivilegeEscalationfalsecapabilities.drop[ALL]seccompProfile.typeRuntimeDefault这些默认值与 Bitnami 镜像内的非 root 运行要求匹配。对于 Openshift 集群global.compatibility.openshift.adaptSecurityContextauto会自动移除runAsUser/runAsGroup/fsGroup交由平台分配默认 ID以兼容 restricted-v2 SCC。7.2 NetworkPolicy默认开启参数说明默认值networkPolicy.enabled是否生成 NetworkPolicytruenetworkPolicy.allowExternal是否允许任意来源访问监听端口false时仅带正确 server label 的 Pod 可访问truenetworkPolicy.allowExternalEgress是否允许任意出站truenetworkPolicy.extraIngress/networkPolicy.extraEgress附加入站/出站规则[]networkPolicy.ingressNSMatchLabels/ingressNSPodMatchLabels允许其他命名空间的标签匹配{}默认策略允许所有 Pod 访问containerPorts与extraContainerPorts声明的端口生产环境可按需收紧allowExternal并补充extraIngress白名单。7.3 镜像验证与不可变标签自 9.1.0 起 Chart 引入镜像验证如需跳过可设置global.security.allowInsecureImagestrue。生产环境强烈建议使用不可变镜像标签如带 digest 或精确版本号避免同一标签被更新后部署内容悄然变化。Bitnami 会在主容器出新版本、重大变更或存在严重漏洞时发布新版 Chart 更新镜像。可使用image.digest以sha256:...形式固定镜像指纹该值会覆盖image.tag。7.4 私有镜像仓库若镜像位于私有仓库在命名空间内手动创建 image pull secret参照 docker config 方式注意imagePullSecrets不能通过--set传入需使用 values 文件imagePullSecrets: - name: SECRET_NAME再执行安装。八、资源请求与限制Bitnami Chart 允许通过resources为所有容器设置 request/limit生产负载必须按实际用量调整resources: requests: cpu: 2 memory: 512Mi limits: cpu: 3 memory: 1024Mi同时 Chart 提供resourcesPreset可选值none、nano、micro、small、medium、large、xlarge、2xlarge一键套用预设规格预设定义来自 bitnami/common 的_resources.tpl。从 deployment.yaml 可以看到优先级resources非空时优先使用否则回退到resourcesPresetnone则不设置。注意生产环境不建议依赖resourcesPreset因为它未必贴合你的实际负载。九、Prometheus 监控集成将metrics.enabledtrue后Chart 会在每个 Pod 中部署一个 apache-exporter 边车容器bitnami/apache-exporter监听 9117 端口并生成带 Prometheus 抓取注解的metricsService。抓取目标边车通过http://status.localhost:8080/server-status/?auto抓取 Apache server-status依赖默认 hostAliases 解析status.localhost然后以/metrics暴露指标。Pod 注解默认注入prometheus.io/scrape: true与prometheus.io/port: 9117。前提集群中需已安装可用的 Prometheus 或 Prometheus Operator可直接部署仓库中的 prometheus 或 kube-prometheus Chart。与 Prometheus Operator 集成设置metrics.serviceMonitor.enabledtrue可生成ServiceMonitor对象由 Operator 自动发现抓取目标。若集群未安装 Prometheus Operator 的 CRD会报错no matches for kind ServiceMonitor in version monitoring.coreos.com/v1此时需先通过 kube-prometheus Chart 安装 CRD 与 Operator。metrics 相关参数还包括metrics.image.*、metrics.resourcesPreset默认small、metrics.resources、metrics.podAnnotations详见 values.yaml。十、定时任务归档与计划任务Matomo 依赖后台任务完成数据归档core:archive与定时计划任务core:run-scheduled-tasks。Chart 通过两个 CronJob 承载见 cronjob.yaml默认每 5 分钟执行一次*/5 * * * *并设置concurrencyPolicy: Forbid防止并发重叠cronjobs.archive执行 Matomo 归档流程命令链为加载环境变量与脚本 →apache/setup.sh、php/setup.sh、mysql-client/setup.sh、matomo/setup.sh→post-init.sh→php console core:archive使用/bitnami/matomo数据卷持久化。cronjobs.taskScheduler执行php console core:run-scheduled-tasks同样复用数据卷与数据库凭据。两组 CronJob 均支持enabled、schedule、suspend、affinity、nodeSelector、tolerations、独立的podSecurityContext/containerSecurityContext、resourcesarchive 未设置时回退到主应用resources、persistence.enabled/existingClaim、extraEnvVars、initContainers等参数。注意 6.0.0 起CronJob 的持久化与资源配置从顶层persistence/resources迁移到各自分组下3.2.0 起废弃了cronjobs.enabled改用cronjobs.taskScheduler.enabled与cronjobs.archive.enabled_helpers.tpl中的matomo.cronjobs.enabled模板仍兼容旧的cronjobs.enabled。十一、证书注入对于需要自定义 CA 或证书的场景certificates参数组会通过 os-shell 边车/init 容器向容器注入证书参数说明默认值certificates.customCertificate.certificateSecret含证书与私钥的 Secretcertificates.customCertificate.chainSecret.name/.key证书链 Secret 名与键secret-name/secret-keycertificates.customCertificate.certificateLocation/keyLocation/chainLocation证书、私钥、链在容器内的落盘路径/etc/ssl/certs/ssl-cert-snakeoil.pem等certificates.customCAs导入容器信任库的自定义 CA Secret 列表[]certificates.image.*证书处理边车镜像默认 os-shell-当customCAs非空时deployment.yaml 会创建内存emptyDir/etc/ssl/certs、/etc/ssl/private与custom-ca-certificatesprojected 卷并由 init 容器执行install_packages ca-certificates openssl后导入未提供自定义证书时还会生成自签 snakeoil 证书带主机名 SAN。十二、凭据管理与更新12.1 密码的生成与挂载matomoPassword为空时Chart 通过 bitnami/common 的密码管理模板自动生成随机 10 位字符串并写入 Secret见 secrets.yaml。usePasswordFilestrue默认时Secret 以 projected 卷挂载到/secrets容器通过MATOMO_PASSWORD_FILE、MATOMO_DATABASE_PASSWORD_FILE、MATOMO_SMTP_PASSWORD_FILE读取设为false则回退为环境变量注入valueFrom.secretKeyRef。可预先创建 Secret 并通过existingSecret指定此时 Chart 不再生成应用密码 Secret。12.2 部署后更新凭据Bitnami Chart 在首次启动时固化凭据之后对 Secret 的修改需要人工干预先按 Matomo 官方 FAQ 在应用内更新用户密码再以新值重建 Secret替换SECRET_NAME、PASSWORD、SMTP_PASSWORD占位符kubectl create secret generic SECRET_NAME --from-literalmatomo-passwordPASSWORD --from-literalsmtp-passwordSMTP_PASSWORD --dry-run -o yaml | kubectl apply -f -十三、调度与亲和性Chart 提供三层调度控制预设亲和性podAffinityPreset、podAntiAffinityPreset默认soft、nodeAffinityPreset.type/key/values可选soft或hard实现来自 bitnami/common 的亲和性模板自定义affinity设置后完全覆盖上述预设其他调度参数nodeSelector、tolerations、topologySpreadConstraints、priorityClassName、schedulerName。从 deployment.yaml 可以看出affinity为空时才渲染预设的三段亲和性podAffinity/podAntiAffinity/nodeAffinity。十四、升级指南Upgrading升级前建议先阅读 Bitnami 官方 Helm Chart 故障排查指南。以下为仓库中记录的主要版本变更版本变更要点11.0.0MariaDB 子 Chart 升级至 12.0从 11.8 升级到 12.0 需参照上游升级说明预计无重大阻碍10.0.0MariaDB 升级至 11.8从 11.4 升级9.1.0引入镜像验证可用global.security.allowInsecureImagestrue关闭9.0.0MariaDB 子 Chart 升级至 20.0.0StatefulSet 改用 headless service 提供 DNS 记录由于涉及不可变字段升级前需删除旧 StatefulSetkubectl delete sts RELEASE_NAME-mariadb --cascadefalse再执行helm upgrade8.0.0MariaDB 升级至 11.47.0.0安全默认值调整resourcesPreset由none改为测试套件可用最小值生产仍建议用resourcesglobal.compatibility.openshift.adaptSecurityContext由disabled改为autonetworkPolicy分组归一化且默认enabledtrue默认放行 EgressIngress 仅允许访问containerPorts/extraContainerPorts端口MariaDB 子 Chart 升级至 18.x6.0.0CronJob 持久化迁移到cronjobs.archive.persistence/cronjobs.taskScheduler.persistencearchive 资源迁移到cronjobs.archive.resources4.0.0 / 3.0.0 / 2.0.0 / 1.0.0逐次升级 MariaDB11.2 → 11.1 → 11.0 → 10.11均需参照上游 MariaDB 升级说明3.2.0废弃cronjobs.enabled改用 taskScheduler/archive 独立开关升级前的常见注意点自定义初始化脚本与旧版networkPolicy/resources配置可能在 7.0.0 之后需要同步调整。十五、小结通过本指南你已经掌握了 Bitnami Matomo Helm Chart 的完整使用链路从 TL;DR 一键安装、参数化覆盖、内置/外部数据库选择、PVC 与 hostPath 持久化、Service/Ingress 暴露到 Prometheus 监控、双 CronJob 归档、SMTP 邮件、证书注入、安全加固与历史升级路径。深入阅读 values.yaml、deployment.yaml、cronjob.yaml 与 _helpers.tpl 即可进一步理解每一项默认值背后的实现逻辑据此搭建符合自身业务规格的 Matomo 分析平台。本 Chart 遵循 Apache License 2.0 许可Copyright © 2025 Broadcom可自由用于学习与生产部署。赞分享云原生容器编排【免费下载链接】chartsBitnami Helm Charts项目地址https://gitcode.com/GitHub_Trending/charts30/charts点击查看免费下载相关推荐使用 Bitnami Helm Chart 在 Kubernetes 上部署 Kong API 网关完整安装、配置与运维指南使用 Bitnami Helm Chart 在 Kubernetes 上部署 Kong API 网关完整安装、配置与运维指南 本文以 Bitnami 官方 K云原生容器编排Bitnami Jaeger Helm Chart 实战指南在 Kubernetes 上部署 Jaeger v2 分布式追踪平台Bitnami Jaeger Helm Chart 实战指南在 Kubernetes 上部署 Jaeger v2 分布式追踪平台 Jaeger 是面向微服务架云原生容器编排Bitnami JupyterHub Helm Chart 实战指南在 Kubernetes 上部署多用户 Jupyter Notebook 平台Bitnami JupyterHub Helm Chart 实战指南在 Kubernetes 上部署多用户 Jupyter Notebook 平台 Jupyt云原生容器编排上一篇【亲测免费】 Idle Master 项目常见问题解决方案下一篇CircleMenu Android最佳实践总结提升开发效率的完整清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/5 1:41:17 · 阅读 1.2k Bitnami Matomo Helm Chart 部署指南：在 Kubernetes 上构建与运维 Matomo 网站分析平台
云原生容器编排【免费下载链接】chartsBitnami Helm Charts项目地址https://gitcode.com/GitHub_Trending/charts30/charts点击查看免费下载Matomo前身 Piwik是一款实时 Web 分析软件可为网站访客行为提供详细报告。本指南以当前仓库中的 Bitnami Matomo Helm ChartChart.yaml为骨架系统讲解如何通过 Helm 在 Kubernetes 上完成 Matomo 的一键部署、参数化配置、持久化、监控接入与定时归档等全流程运维。读完本文你将掌握从裸集群到生产可用的 Matomo 分析平台所需的完整配置方法与底层实现原理。一、Chart 概览Matomo 是如何被打包的本 Chart 位于bitnami/matomo/用于在 Kubernetes 集群上通过 Helm 引导一个完整的 Matomo 部署其核心信息如下Chart 版本11.0.1应用版本appVersion5.3.2对应bitnami/matomo容器镜像 5.3.2 系列类型applicationtanzuCategory关键字为 matomo、analytics、php、web 等依赖在 Chart.yaml 中声明了两个子 Chartmariadb条件依赖mariadb.enabled默认安装用于为 Matomo 提供数据库commonbitnami-common 2.x提供命名、标签、亲和性、资源预设等公共模板能力。Chart 的模板文件位于 bitnami/matomo/templates/其中核心资源包括deployment.yaml主 Deployment承载 MatomoApache PHP容器、metrics 边车容器以及各类 init 容器cronjob.yaml两个定时任务 CronJob归档与计划任务pvc.yaml / pv.yaml数据卷声明与 hostPath 支持secrets.yaml应用密码与 SMTP 密码的 Secretsvc.yaml、ingress.yaml流量暴露networkpolicy.yaml、pdb.yaml网络安全与调度保护postinit-configmap.yaml自定义 post-init 脚本挂载。二、前置条件与快速安装2.1 环境要求部署前需要确认集群满足以下前置条件Kubernetes 1.23Helm 3.8.0底层基础设施支持PV Provisioner若要将replicaCount扩到多个副本需要底层存储支持ReadWriteMany卷默认replicaCount1仅需 ReadWriteOnce2.2 TL;DR 一键安装helm install my-release oci://registry-1.docker.io/bitnamicharts/matomo这是最简安装方式Chart 会同时拉起 Matomo 应用与一个独立 MariaDB 实例并在首次启动时自动完成 Matomo 的安装向导与数据库初始化。2.3 指定镜像仓库安装在安装命令中REGISTRY_NAME与REPOSITORY_NAME需要替换为实际的 Chart 仓库。例如 Bitnami 官方仓库helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/matomo即REGISTRY_NAMEregistry-1.docker.io、REPOSITORY_NAMEbitnamicharts。安装完成后可用helm list查看当前所有 release。三、配置参数总览ParametersChart 的完整可配置项集中在 values.yaml按功能划分为若干参数组。以下是各组的关键参数安装时可通过--set keyvalue或-f values.yaml覆盖。3.1 Global 与 Common 参数参数说明默认值global.imageRegistry全局镜像仓库覆盖包括子 Chart 在内的所有镜像global.imagePullSecrets全局镜像拉取 Secret 名数组[]global.defaultStorageClass全局默认 StorageClassglobal.security.allowInsecureImages是否跳过镜像验证falseglobal.compatibility.openshift.adaptSecurityContextOpenshift restricted-v2 SCC 适配可选auto检测到 Openshift 时应用、force、disabledautokubeVersion强制指定目标 Kubernetes 版本nameOverride/fullnameOverride/namespaceOverride覆盖资源命名与命名空间commonAnnotations/commonLabels为所有 Matomo 资源添加公共注解/标签模板化求值{}extraDeploy随 release 额外部署的对象数组[]usePasswordFiles凭据以文件方式挂载而非环境变量true3.2 Matomo 应用参数参数说明默认值image.registry/image.repository/image.tagMatomo 镜像地址与标签当前默认5.3.2-debian-12-r12docker.io/bitnami/matomoimage.digest指定镜像 digest设置后将覆盖 tagimage.pullPolicy镜像拉取策略IfNotPresentimage.pullSecrets镜像拉取 Secret 数组[]image.debug是否输出调试日志对应BITNAMI_DEBUGfalsereplicaCount副本数需要 ReadWriteMany PVC1matomoUsername/matomoPassword管理员账号与密码密码未设置时自动生成随机 10 位字符串user/matomoEmail管理员邮箱userexample.commatomoWebsiteName/matomoWebsiteHost站点名称与分析目标站点地址example/https://example.orgmatomoSkipInstall跳过安装向导迁移、从 SQL dump 恢复时很有用对应环境变量MATOMO_SKIP_BOOTSTRAPfalsecustomPostInitScripts自定义 post-init.d 脚本支持.sh或.php仅在容器首次启动执行{}allowEmptyPassword是否允许数据库空密码对应ALLOW_EMPTY_PASSWORDtrueupdateStrategy.type更新策略单副本 RWO 卷时建议Recreate避免更新卡死RollingUpdatepdb.create/pdb.minAvailable/pdb.maxUnavailablePod 中断预算两者都为空时默认maxUnavailable1true//sidecars/initContainers/extraEnvVars/extraVolumes扩展容器与自定义环境/存储[]existingSecret应用密码所在 Secret 名称containerPorts.http/containerPorts.https容器监听端口对应APACHE_HTTP_PORT_NUMBER/APACHE_HTTPS_PORT_NUMBER8080/8443值得说明的是默认hostAliases中包含了127.0.0.1 - status.localhost这是为了让 apache-exporter 边车能够通过http://status.localhost:8080/server-status/?auto抓取 Apache 状态页见 deployment.yaml 与 metrics 容器命令。3.3 SMTP 邮件配置参数说明默认值smtpAuth认证机制Plain/Login/Cram-md5smtpHost/smtpPortSMTP 服务器与端口smtpUser/smtpPasswordSMTP 账号与密码smtpProtocol协议ssl/tls/nilnoreplyName/noreplyAddress发件人名称与地址对应MATOMO_NOREPLY_NAME/MATOMO_NOREPLY_ADDRESSsmtpExistingSecret已有 SMTP 凭据 Secret须含smtp-password键设置后忽略smtpPassword从模板实现看这些值会按需映射为MATOMO_SMTP_AUTH、MATOMO_SMTP_HOST、MATOMO_SMTP_PORT、MATOMO_SMTP_USER、MATOMO_SMTP_PROTOCOL等环境变量供 Bitnami Matomo 镜像的初始化脚本消费。3.4 探针Probe参数参数说明默认值startupProbe.enabled启用启动探针路径/matomo.phpfalselivenessProbe.enabled存活探针基于 HTTP 端口 TCP 探测truereadinessProbe.enabled/readinessProbe.path就绪探针HTTP GET/matomo.phptrue//matomo.phpcustomStartupProbe/customLivenessProbe/customReadinessProbe完全自定义探针覆盖{}Matomo 根路径/matomo.php对未认证请求可直接响应因此适合作为启动与就绪探针路径若改用自定义镜像或修改了路由建议通过自定义探针覆盖默认值。3.5 使用--set与 values 文件helm install my-release \ --set matomoUsernameuser,matomoPasswordpassword,mariadb.auth.rootPasswordsecretpassword \ oci://REGISTRY_NAME/REPOSITORY_NAME/matomo上述命令将管理员账号设为user、密码设为password并将 MariaDB root 密码设为secretpassword。也可把参数写入 YAML 后通过-f传入helm install my-release -f values.yaml oci://REGISTRY_NAME/REPOSITORY_NAME/matomo重要提示Chart 部署完成后无法再通过 Helm 修改应用访问凭据。如需变更只能删除 Chart 使用的持久卷后重新部署或使用应用自带的管理工具修改。四、数据库内置 MariaDB 与外部数据库Chart 默认在mariadb.enabledtrue时随应用一并部署 Bitnami MariaDB 子 Chart为 Matomo 自动创建数据库与用户默认库bitnami_matomo、用户bn_matomo。4.1 内置 MariaDB 关键参数参数说明默认值mariadb.enabled是否部署内置 MariaDBtruemariadb.architecture架构standalone或replicationstandalonemariadb.auth.rootPasswordMariaDB root 密码mariadb.auth.database创建的数据库名bitnami_matomomariadb.auth.username/mariadb.auth.password数据库用户与密码bn_matomo/mariadb.primary.persistence.enabled数据库持久化truemariadb.primary.persistence.size数据库卷大小8Gimariadb.primary.resourcesPreset/mariadb.primary.resources数据库容器资源预设/自定义资源micro/{}4.2 外部数据库将mariadb.enabled设为false并配置externalDatabase即可接入已有数据库参数说明默认值externalDatabase.host数据库主机externalDatabase.port端口3306externalDatabase.user/externalDatabase.password数据库用户与密码bn_matomo/externalDatabase.database数据库名bitnami_matomoexternalDatabase.existingSecret存放数据库凭据的 Secret数据库连接信息由 _helpers.tpl 中的matomo.databaseHost、matomo.databasePort、matomo.databaseName、matomo.databaseUser、matomo.databaseSecretName等模板函数统一计算内置 MariaDB 时主机指向RELEASE-mariadbreplication 架构下指向RELEASE-mariadb-primary、密码键为mariadb-password外部数据库时使用externalDatabase各字段、密码键为db-password。这保证了 Deployment 与两个 CronJob 使用完全一致的数据库连接配置。五、持久化PVC、已有卷与 hostPathBitnami Matomo 镜像将站点数据与配置保存在容器的/bitnami/matomo路径。Chart 通过 PersistentVolumeClaim 保证数据跨部署留存该方案已确认可在 GCE、AWS 与 minikube 上工作。5.1 持久化参数参数说明默认值persistence.enabled启用 PVC 持久化关闭后回退到emptyDirtruepersistence.storageClass卷的 StorageClass-表示禁用动态供给persistence.accessModes访问模式[ReadWriteOnce]persistence.size容量请求8Gipersistence.dataSource自定义 PVC 数据源{}persistence.existingClaim复用已有 PVC需先手动创建persistence.hostPath挂载到宿主机指定路径persistence.annotations/persistence.selectorPVC 注解 / 匹配已有 PV 的 selector{}5.2 复用已有 PVC先创建 PersistentVolume再创建 PersistentVolumeClaim安装时指定helm install my-release --set persistence.existingClaimPVC_NAME oci://REGISTRY_NAME/REPOSITORY_NAME/matomo从 pvc.yaml 的实现可以看到设置了existingClaim后 Chart 不再生成 PVCDeployment 直接引用该 Claimpersistence.hostPath被设置时storageClassName会被强制置空由 pv.yaml 生成对应的 hostPath PV。5.3 hostPath 挂载本地开发场景系统兼容性已在 OSX/MacOSxhyve 驱动与 LinuxVirtualBox验证Windows 未验证minikube 官方支持按 Pod 挂载宿主目录。步骤确保指定的 hostPath 目录已存在安装helm install my-release --set persistence.hostPath/PATH/TO/HOST/MOUNT oci://REGISTRY_NAME/REPOSITORY_NAME/matomo此时matomo-data卷挂载到该 hostPath 目录目录中有有效数据则直接复用否则在首次启动时初始化由于容器无法控制宿主机目录权限需自行设置 Matomo 文件目录的权限。5.4 备份与恢复推荐使用 Velero 进行备份恢复将源部署的 Persistent Volume 备份后挂载到新部署即可完成迁移完整操作流程可参考 Velero 官方文档及 Bitnami 应用目录的备份恢复指南。此外volumePermissions参数组默认关闭可以在默认runAsUser/fsGroup不生效的存储环境下启用 init 容器对/bitnami/matomo目录执行 chown见 _helpers.tpl。六、流量暴露Service 与 Ingress6.1 Service 参数参数说明默认值service.typeService 类型LoadBalancerservice.ports.http/service.ports.httpsService 对外端口80/443service.loadBalancerSourceRanges限制 LoadBalancer 来源 IP[]service.loadBalancerIP指定负载均衡 IP云厂商相关service.nodePortsNodePort30000-32767{}service.externalTrafficPolicy客户端源 IP 保留策略Clusterservice.sessionAffinity会话亲和性None或ClientIPNoneservice.extraPorts/service.annotations附加端口与注解[]/{}在 svc.yaml 中targetPort直接引用容器命名端口http/https与containerPorts一一对应。minikube 等本地环境建议将service.type改为NodePort。6.2 Ingress 参数参数说明默认值ingress.enabled启用 Ingressfalseingress.pathType路径类型ImplementationSpecificingress.ingressClassNameIngressClassKubernetes 1.18ingress.hostname默认域名matomo.localingress.path路径ALB 控制器可能需设为/*/ingress.annotations注解可放 cert-manager 自动签发注解{}ingress.tls/ingress.selfSigned启用 TLS / 用 Helm 生成自签名证书falseingress.extraHosts/ingress.extraPaths/ingress.extraTls/ingress.extraRules/ingress.secrets附加主机、路径、TLS、规则与证书 Secret[]七、安全与加固配置7.1 Security Context 默认值Chart 默认开启 Pod 与容器两级安全上下文podSecurityContext.fsGroup1001、fsGroupChangePolicyAlwayscontainerSecurityContext.runAsUser1001、runAsGroup0、runAsNonRoottrue、privilegedfalseallowPrivilegeEscalationfalsecapabilities.drop[ALL]seccompProfile.typeRuntimeDefault这些默认值与 Bitnami 镜像内的非 root 运行要求匹配。对于 Openshift 集群global.compatibility.openshift.adaptSecurityContextauto会自动移除runAsUser/runAsGroup/fsGroup交由平台分配默认 ID以兼容 restricted-v2 SCC。7.2 NetworkPolicy默认开启参数说明默认值networkPolicy.enabled是否生成 NetworkPolicytruenetworkPolicy.allowExternal是否允许任意来源访问监听端口false时仅带正确 server label 的 Pod 可访问truenetworkPolicy.allowExternalEgress是否允许任意出站truenetworkPolicy.extraIngress/networkPolicy.extraEgress附加入站/出站规则[]networkPolicy.ingressNSMatchLabels/ingressNSPodMatchLabels允许其他命名空间的标签匹配{}默认策略允许所有 Pod 访问containerPorts与extraContainerPorts声明的端口生产环境可按需收紧allowExternal并补充extraIngress白名单。7.3 镜像验证与不可变标签自 9.1.0 起 Chart 引入镜像验证如需跳过可设置global.security.allowInsecureImagestrue。生产环境强烈建议使用不可变镜像标签如带 digest 或精确版本号避免同一标签被更新后部署内容悄然变化。Bitnami 会在主容器出新版本、重大变更或存在严重漏洞时发布新版 Chart 更新镜像。可使用image.digest以sha256:...形式固定镜像指纹该值会覆盖image.tag。7.4 私有镜像仓库若镜像位于私有仓库在命名空间内手动创建 image pull secret参照 docker config 方式注意imagePullSecrets不能通过--set传入需使用 values 文件imagePullSecrets: - name: SECRET_NAME再执行安装。八、资源请求与限制Bitnami Chart 允许通过resources为所有容器设置 request/limit生产负载必须按实际用量调整resources: requests: cpu: 2 memory: 512Mi limits: cpu: 3 memory: 1024Mi同时 Chart 提供resourcesPreset可选值none、nano、micro、small、medium、large、xlarge、2xlarge一键套用预设规格预设定义来自 bitnami/common 的_resources.tpl。从 deployment.yaml 可以看到优先级resources非空时优先使用否则回退到resourcesPresetnone则不设置。注意生产环境不建议依赖resourcesPreset因为它未必贴合你的实际负载。九、Prometheus 监控集成将metrics.enabledtrue后Chart 会在每个 Pod 中部署一个 apache-exporter 边车容器bitnami/apache-exporter监听 9117 端口并生成带 Prometheus 抓取注解的metricsService。抓取目标边车通过http://status.localhost:8080/server-status/?auto抓取 Apache server-status依赖默认 hostAliases 解析status.localhost然后以/metrics暴露指标。Pod 注解默认注入prometheus.io/scrape: true与prometheus.io/port: 9117。前提集群中需已安装可用的 Prometheus 或 Prometheus Operator可直接部署仓库中的 prometheus 或 kube-prometheus Chart。与 Prometheus Operator 集成设置metrics.serviceMonitor.enabledtrue可生成ServiceMonitor对象由 Operator 自动发现抓取目标。若集群未安装 Prometheus Operator 的 CRD会报错no matches for kind ServiceMonitor in version monitoring.coreos.com/v1此时需先通过 kube-prometheus Chart 安装 CRD 与 Operator。metrics 相关参数还包括metrics.image.*、metrics.resourcesPreset默认small、metrics.resources、metrics.podAnnotations详见 values.yaml。十、定时任务归档与计划任务Matomo 依赖后台任务完成数据归档core:archive与定时计划任务core:run-scheduled-tasks。Chart 通过两个 CronJob 承载见 cronjob.yaml默认每 5 分钟执行一次*/5 * * * *并设置concurrencyPolicy: Forbid防止并发重叠cronjobs.archive执行 Matomo 归档流程命令链为加载环境变量与脚本 →apache/setup.sh、php/setup.sh、mysql-client/setup.sh、matomo/setup.sh→post-init.sh→php console core:archive使用/bitnami/matomo数据卷持久化。cronjobs.taskScheduler执行php console core:run-scheduled-tasks同样复用数据卷与数据库凭据。两组 CronJob 均支持enabled、schedule、suspend、affinity、nodeSelector、tolerations、独立的podSecurityContext/containerSecurityContext、resourcesarchive 未设置时回退到主应用resources、persistence.enabled/existingClaim、extraEnvVars、initContainers等参数。注意 6.0.0 起CronJob 的持久化与资源配置从顶层persistence/resources迁移到各自分组下3.2.0 起废弃了cronjobs.enabled改用cronjobs.taskScheduler.enabled与cronjobs.archive.enabled_helpers.tpl中的matomo.cronjobs.enabled模板仍兼容旧的cronjobs.enabled。十一、证书注入对于需要自定义 CA 或证书的场景certificates参数组会通过 os-shell 边车/init 容器向容器注入证书参数说明默认值certificates.customCertificate.certificateSecret含证书与私钥的 Secretcertificates.customCertificate.chainSecret.name/.key证书链 Secret 名与键secret-name/secret-keycertificates.customCertificate.certificateLocation/keyLocation/chainLocation证书、私钥、链在容器内的落盘路径/etc/ssl/certs/ssl-cert-snakeoil.pem等certificates.customCAs导入容器信任库的自定义 CA Secret 列表[]certificates.image.*证书处理边车镜像默认 os-shell-当customCAs非空时deployment.yaml 会创建内存emptyDir/etc/ssl/certs、/etc/ssl/private与custom-ca-certificatesprojected 卷并由 init 容器执行install_packages ca-certificates openssl后导入未提供自定义证书时还会生成自签 snakeoil 证书带主机名 SAN。十二、凭据管理与更新12.1 密码的生成与挂载matomoPassword为空时Chart 通过 bitnami/common 的密码管理模板自动生成随机 10 位字符串并写入 Secret见 secrets.yaml。usePasswordFilestrue默认时Secret 以 projected 卷挂载到/secrets容器通过MATOMO_PASSWORD_FILE、MATOMO_DATABASE_PASSWORD_FILE、MATOMO_SMTP_PASSWORD_FILE读取设为false则回退为环境变量注入valueFrom.secretKeyRef。可预先创建 Secret 并通过existingSecret指定此时 Chart 不再生成应用密码 Secret。12.2 部署后更新凭据Bitnami Chart 在首次启动时固化凭据之后对 Secret 的修改需要人工干预先按 Matomo 官方 FAQ 在应用内更新用户密码再以新值重建 Secret替换SECRET_NAME、PASSWORD、SMTP_PASSWORD占位符kubectl create secret generic SECRET_NAME --from-literalmatomo-passwordPASSWORD --from-literalsmtp-passwordSMTP_PASSWORD --dry-run -o yaml | kubectl apply -f -十三、调度与亲和性Chart 提供三层调度控制预设亲和性podAffinityPreset、podAntiAffinityPreset默认soft、nodeAffinityPreset.type/key/values可选soft或hard实现来自 bitnami/common 的亲和性模板自定义affinity设置后完全覆盖上述预设其他调度参数nodeSelector、tolerations、topologySpreadConstraints、priorityClassName、schedulerName。从 deployment.yaml 可以看出affinity为空时才渲染预设的三段亲和性podAffinity/podAntiAffinity/nodeAffinity。十四、升级指南Upgrading升级前建议先阅读 Bitnami 官方 Helm Chart 故障排查指南。以下为仓库中记录的主要版本变更版本变更要点11.0.0MariaDB 子 Chart 升级至 12.0从 11.8 升级到 12.0 需参照上游升级说明预计无重大阻碍10.0.0MariaDB 升级至 11.8从 11.4 升级9.1.0引入镜像验证可用global.security.allowInsecureImagestrue关闭9.0.0MariaDB 子 Chart 升级至 20.0.0StatefulSet 改用 headless service 提供 DNS 记录由于涉及不可变字段升级前需删除旧 StatefulSetkubectl delete sts RELEASE_NAME-mariadb --cascadefalse再执行helm upgrade8.0.0MariaDB 升级至 11.47.0.0安全默认值调整resourcesPreset由none改为测试套件可用最小值生产仍建议用resourcesglobal.compatibility.openshift.adaptSecurityContext由disabled改为autonetworkPolicy分组归一化且默认enabledtrue默认放行 EgressIngress 仅允许访问containerPorts/extraContainerPorts端口MariaDB 子 Chart 升级至 18.x6.0.0CronJob 持久化迁移到cronjobs.archive.persistence/cronjobs.taskScheduler.persistencearchive 资源迁移到cronjobs.archive.resources4.0.0 / 3.0.0 / 2.0.0 / 1.0.0逐次升级 MariaDB11.2 → 11.1 → 11.0 → 10.11均需参照上游 MariaDB 升级说明3.2.0废弃cronjobs.enabled改用 taskScheduler/archive 独立开关升级前的常见注意点自定义初始化脚本与旧版networkPolicy/resources配置可能在 7.0.0 之后需要同步调整。十五、小结通过本指南你已经掌握了 Bitnami Matomo Helm Chart 的完整使用链路从 TL;DR 一键安装、参数化覆盖、内置/外部数据库选择、PVC 与 hostPath 持久化、Service/Ingress 暴露到 Prometheus 监控、双 CronJob 归档、SMTP 邮件、证书注入、安全加固与历史升级路径。深入阅读 values.yaml、deployment.yaml、cronjob.yaml 与 _helpers.tpl 即可进一步理解每一项默认值背后的实现逻辑据此搭建符合自身业务规格的 Matomo 分析平台。本 Chart 遵循 Apache License 2.0 许可Copyright © 2025 Broadcom可自由用于学习与生产部署。赞分享云原生容器编排【免费下载链接】chartsBitnami Helm Charts项目地址https://gitcode.com/GitHub_Trending/charts30/charts点击查看免费下载相关推荐使用 Bitnami Helm Chart 在 Kubernetes 上部署 Kong API 网关完整安装、配置与运维指南使用 Bitnami Helm Chart 在 Kubernetes 上部署 Kong API 网关完整安装、配置与运维指南 本文以 Bitnami 官方 K云原生容器编排Bitnami Jaeger Helm Chart 实战指南在 Kubernetes 上部署 Jaeger v2 分布式追踪平台Bitnami Jaeger Helm Chart 实战指南在 Kubernetes 上部署 Jaeger v2 分布式追踪平台 Jaeger 是面向微服务架云原生容器编排Bitnami JupyterHub Helm Chart 实战指南在 Kubernetes 上部署多用户 Jupyter Notebook 平台Bitnami JupyterHub Helm Chart 实战指南在 Kubernetes 上部署多用户 Jupyter Notebook 平台 Jupyt云原生容器编排上一篇【亲测免费】 Idle Master 项目常见问题解决方案下一篇CircleMenu Android最佳实践总结提升开发效率的完整清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考