企业官网建设流程全解析

• 云原生
• 容器编排

本文以 bitnami/mongodb/CHANGELOG.md 的完整版本演进为主线，结合该 chart 的 values.yaml、Chart.yaml 与模板源码，梳理 Bitnami MongoDB Helm Chart 从 7.x 到 17.x 的核心能力变迁，并给出可直接落地的安装、认证、TLS、备份、监控与安全配置方案。读完本文，你将掌握该 chart 的架构选型、关键参数含义、密码轮换与备份恢复的实战操作，以及版本升级时需要注意的破坏性变更点。

一、Chart 概览与版本脉络

1.1 当前版本与组成

当前仓库中 mongodb chart 的版本为17.0.2（Chart 版本），对应的应用版本为MongoDB 8.0.13，由 Chart.yaml 定义。图表依赖common子 chart（2.x.x，通过 OCI 仓库引用），核心镜像包括：

• bitnami/mongodb:8.0.13-debian-12-r0：MongoDB 服务端
• bitnami/mongodb-exporter:0.47.0-debian-12-r1：Prometheus 指标导出器
• bitnami/nginx：TLS 证书生成 init 容器所用镜像
• bitnami/kubectl：外部访问自动发现 init 容器所用镜像
• bitnami/os-shell：DNS 检查 init 容器所用镜像

chart 的模板结构分为五大工作负载族，见 templates 目录：

另有configmap.yaml、secrets.yaml、secrets-ca.yaml、metrics-svc.yaml、servicemonitor.yaml、prometheusrule.yaml、networkpolicy.yaml、psp.yaml、role.yaml、rolebinding.yaml等横切资源模板。

1.2 CHANGELOG 时间线特征

从 CHANGELOG.md（2211 行）看，该 chart 经历了从 7.8.9（2020 年 3 月）到 17.0.2（2026 年 4 月）约六年的持续迭代，其中大量版本为「updating components versions」式的常规镜像升级，真正的功能演进集中在若干个 minor/major 版本中。理解这些节点，是评估升级风险与能力边界的关键。

二、架构选型：standalone 与 replicaset

2.1 两种架构的语义

architecture参数决定工作负载类型（values.yaml）：

• standalone（默认）：部署一个 Deployment（或通过useStatefulSet: true改为 StatefulSet），不可横向扩展。replicaCount大于 1 时会被强制降为 1，从 dep-sts.yaml 的replicas: {{ gt (.Values.replicaCount | int) 1 | ternary 1 .Values.replicaCount }}可以看出这一硬性约束。CHANGELOG 中 10.25.2 引入Recreate更新策略、10.21.2 明确 standalone 副本数为 1、12.0.0 完成整体标准化，均围绕单机语义完善。
• replicaset：部署 StatefulSet，按replicaCount创建多个 mongod 实例，通过 headless Service（<release>-headless）互相发现，构成 MongoDB 副本集。副本集模式下默认启用replicaSetHostnames: true（使用 DNS 主机名而非 IP 参与副本集配置）。

从 replicaset/statefulset.yaml 可见副本集 StatefulSet 使用podManagementPolicy: OrderedReady（依次启动），并支持updateStrategy、亲和性预设（podAffinityPreset/podAntiAffinityPreset/nodeAffinityPreset）、topologySpreadConstraints等调度控制。

2.2 副本集的高级成员

13.x 之后 chart 逐步补齐了 MongoDB 副本集的完整成员拓扑（CHANGELOG 中 10.8.0 新增 hidden node 支持、8.2.0 允许禁用 arbiter、14.2.0 增加 arbiter 的 nodeSelector 能力等）：

• Arbiter（仲裁节点）：只参与选举、不存储数据，默认每个副本集附带一个。其 StatefulSet、headless Service 与 PDB 独立于主副本集管理（见 arbiter）。15.0.2 与 14.12.2 曾修复仲裁节点 emptyDir 挂载问题。
• Hidden（隐藏节点）：拥有数据但不参与客户端读取，通常用于备份/分析，其外部访问、TLS 证书等均有独立配置入口（见 hidden）。

2.3 外部访问（externalAccess）

当副本集需要被集群外客户端访问时，启用externalAccess（values.yaml），支持三种 Service 类型：NodePort、LoadBalancer、ClusterIP（10.10.0 新增 ClusterIP 支持）。关键配套能力：

• autoDiscovery：通过 init 容器（使用bitnami/kubectl镜像）自动查询 K8s API 获取每个副本的 LB IP 或 NodePort，无需手工填写loadBalancerIPs/nodePorts。
• dnsCheck：当使用publicNames时，init 容器负责校验外部域名可解析（13.x 之后引入，15.6.22 为其补充了安全上下文）。
• externalMaster：13.15.0 起支持将 chart 部署的副本集引导自集群外已存在的 MongoDB 主节点（externalAccess.externalMaster.host/port），用于跨集群复制拓扑。

注意replicaSetHostnames在externalAccess.enabled=true时会被忽略（values.yaml），因为外部访问依赖可解析的公开地址而非集群内 DNS。

三、认证与密码管理：auth 体系深度解析

3.1 auth 参数族

auth是使用最频繁的配置区（values.yaml）：

auth: enabled: true # 是否启用认证 rootUser: root # 根用户名 rootPassword: "" # 根密码（为空时自动随机生成） usernames: [] # 初始化时创建的自定义用户列表 passwords: [] # 与 usernames 一一对应的密码 databases: [] # 与用户关联的自定义数据库 replicaSetKey: "" # 副本集成员间认证用的 key（replicaset 架构） existingSecret: "" # 指定已有 Secret，包含 mongodb-passwords / mongodb-root-password / mongodb-metrics-password / mongodb-replica-set-key

要点：

• 多用户支持：10.29.0 引入多个自定义用户/数据库的支持（替代早期单一auth.username/password/database），10.26.0 允许自定义 root 用户名，13.15.2 修复对MONGODB_ROOT_USER环境变量的尊重。
• existingSecret 优先：一旦设置auth.existingSecret，上述密码类参数全部被忽略（15.5.3 修复了 existingSecret 与 rootPassword 的 "or" 条件逻辑）。
• 密钥文件挂载：17.x 默认usePasswordFiles: true，即通过MONGODB_ROOT_PASSWORD_FILE等文件路径挂载密码而非直接注入环境变量（16.5.0 将该值改为默认 true，对应 CHANGELOG 中 "Set usePasswordFiles=true by default"），减少凭据泄露面。从 backup/cronjob.yaml 可以看到两种模式在模板中的分支实现。

3.2 密码更新 Job（passwordUpdateJob）

16.3.0 引入的「password update job」是本 chart 一项重要的运维能力。它通过 Helmpre-upgradehook（见 update-password/job.yaml 的helm.sh/hook: pre-upgrade注解），在helm upgrade更换密码时自动执行：

1. 使用MONGODB_PREVIOUS_ROOT_PASSWORD连接数据库；
2. 通过mongosh执行db.changeUserPassword()更新 root、自定义用户与 metrics 用户的密码；
3. 使用/job-status/*-changed文件标记已完成的用户，保证幂等（重试不会重复执行）；
4. 同时在 StatefulSet/Deployment 的 Pod 注解中写入charts.bitnami.com/password-last-update时间戳，强制触发滚动更新。

其 values 配置支持previousPasswords.rootPassword/previousPasswords.existingSecret（当密码 Secret 已被预先变更时使用）、backoffLimit、独立的安全上下文与资源预设等（values.yaml）。

3.3 认证相关的历史修复

CHANGELOG 中认证相关的修复密度极高，可作排查参考：

• 16.5.2：修复 mongodump Job 中因usePasswordFiles导致的认证失败；
• 13.18.4：auth.enabled=false时备份任务不再要求密码；
• 13.8.3 / 13.18.4：auth.enabled=false场景下升级与备份的兼容性；
• 10.28.0：对 existingSecret 值支持模板函数（tpl）渲染；
• 10.1.3：确保密码以字符串处理，避免 YAML 数字被误读。

四、TLS 与 mTLS：证书的自动生成与引入

4.1 tls 参数族

TLS 能力在 9.x–13.x 期间持续完善，当前配置集中在 values.yaml：

tls: enabled: false # 开启集群内部节点间以及客户端-节点间 TLS mTLS: enabled: true # 启用后要求客户端也提供证书（14.0.13 起可单独关闭） autoGenerated: true # 自动生成自签 CA 与证书 existingSecret: "" # 提供已有 CA（mongodb-ca-cert / mongodb-ca-key） caCert: "" # 自定义 CA 证书（base64） caKey: "" # CA 私钥（base64） pemChainIncluded: false # 证书文件是否已包含完整 CA 链（13.14.0 新增） mode: requireTLS # 取值 allowTLS / preferTLS / requireTLS（10.29.3 引入 tlsMode） extraDnsNames: [] # 向 CA 追加额外 DNS 名称（10.27.0 起支持，10.30.3 扩展至 replicaset 架构） standalone/replicaset/hidden/arbiter: existingSecret(s): # 各成员可分别指定已有证书 Secret

4.2 证书生成的实现路径

当tls.autoGenerated=true时，每个 MongoDB Pod 的 init 容器generate-tls-certs会调用 common-scripts-cm.yaml 中的generate-certs.sh脚本，基于 chart 生成的 CA（secrets-ca.yaml）为每个成员签发证书。从 replicaset/statefulset.yaml 可见该 init 容器通过 downward API 注入MY_POD_NAMESPACE、MY_POD_HOST_IP、MY_POD_NAME，将证书 SAN 与 Pod 网络身份绑定；备份 CronJob 同样拥有独立的generate-tls-certsinit 容器（backup/cronjob.yaml）。

值得注意的历史修复：

• 13.6.8：升级时不重新生成自签证书，避免证书抖动导致集群不可用；
• 13.15.1：TLS 开启时避免主机名校验失败；
• 12.1.5 / 10.30.7：修正证书 SAN 字段，避免 "IP Address in the DNS Name field" 弃用告警；
• 16.5.17：TLS init 容器正确继承tls.securityContext。

4.3 备份任务对 TLS 的适配

当tls.enabled=true时，mongodump 命令会自动追加--ssl --sslPEMKeyFile=/certs/mongodb.pem --sslCAFile=/certs/mongodb-ca-cert（backup/cronjob.yaml）。14.0.5 专门修复了 standalone + TLS 模式下备份不可用的问题。

五、备份与恢复：mongodump CronJob 实战

5.1 启用定时备份

备份功能由backup参数族控制，模板见 templates/backup：

backup: enabled: true cronjob: schedule: "0 2 * * *" # 每天 2 点执行 timeZone: "UTC" # 时区（16.2.2 起支持，注意变量为 timeZone 驼峰命名） concurrencyPolicy: Forbid failedJobsHistoryLimit: 3 successfulJobsHistoryLimit: 3 startingDeadlineSeconds: 3600 backoffLimit: 5 # 15.1.0 起可配置 ttlSecondsAfterFinished: 300 restartPolicy: OnFailure resourcesPreset: "micro" storage: mountPath: /data/dump subPath: "" existingClaim: "" # 复用已有 PVC serviceAccount: name: "" # 16.5.10 起可为备份任务单独指定 SA

CronJob 生成的 Job 内执行：

mongodump --username=${MONGODB_ROOT_USER} --password=${MONGODB_ROOT_PASSWORD} \ --authenticationDatabase=admin --host=${MONGODB_SERVICE_NAME} --port=27017 \ --gzip --archive=/data/dump/mongodump-$(date '+%Y-%m-%d-%H-%M').gz

replicaset 架构下会自动追加--oplog以便生成时间点一致的快照（backup/cronjob.yaml）。备份数据默认写入自动创建的 PVCmongodump（见 backup/pvc.yaml），也可以配置existingClaim复用外部 PVC。13.18.0 还提供「trivial backup」的简化开关。

5.2 恢复操作

使用mongorestore从归档恢复：

mongorestore --username=root --password=<ROOT_PASSWORD> \ --authenticationDatabase=admin --gzip \ --archive=/data/dump/mongodump-<时间戳>.gz

对于 replicaset 架构，--oplog归档需要配合--oplogReplay进行日志回放以恢复到精确时间点。CHANGELOG 中与备份直接相关的修复包括：14.4.9（为备份 Job 设置认证数据库）、13.18.4（无认证模式下的备份）、14.0.5（TLS standalone 备份）。

六、监控与指标：metrics 全家桶

chart 内置基于mongodb-exporter的监控体系（镜像版本见 Chart.yaml）。模板包括 metrics-svc.yaml、servicemonitor.yaml、prometheusrule.yaml 与 networkpolicy.yaml。

主要能力与演进：

• ServiceMonitor 与 PrometheusRule：10.24.0 支持relabelings/metricRelabelings；10.0.1 与 11.1.10 修复 Prometheus 规则；10.13.0 等版本持续更新。
• Exporter 探针与参数：13.12.0 支持通过 chart values 传递 exporter 参数；13.13.0 支持为 metrics 容器挂载额外卷；12.1.0 允许自定义 metrics 容器的 command/args；10.26.2 支持配置 exporter 的认证凭据。
• 连接串细节：16.4.6 使用实际主机名而非 localhost 构造 exporter URI；16.5.1（即 17.0.1 同批）修复 URI 中特殊字符的 URL 编码问题；12.1.2 修复 standalone 模式下 metrics 容器端口。
• 探针端点：13.6.7、12.1.30 相继调整 metrics liveness/readiness 探针端点（因 exporter--test参数被移除）。

七、安全加固：从 PSP 到 PSA 的演进

安全是该 chart 迭代最密集的领域之一，CHANGELOG 呈现出一条清晰的主线：

1. PSP 阶段：10.5.0 启用 PodSecurityPolicy；14.0.3 复用 common 的 PSP 能力；10.28.6 将 PSP 标记为弃用。
2. SecurityContext 强化：15.0.0 以 breaking change 方式改进安全默认值；14.12.0 增加readOnlyRootFilesystem支持；14.6.0 完善 pod/container securityContext 的必备字段；14.5.1 默认不自动挂载 ServiceAccount token；14.7.0 将 SA token 挂载声明移至 Pod 声明。
3. 当前默认值（见 values.yaml）：
   • podSecurityContext：fsGroup: 1001、fsGroupChangePolicy: Always
   • containerSecurityContext：runAsUser/runAsGroup: 1001、runAsNonRoot: true、readOnlyRootFilesystem: true、allowPrivilegeEscalation: false、capabilities.drop: ["ALL"]、seccompProfile: RuntimeDefault
   • automountServiceAccountToken: false
4. 平台适配：14.13.0 支持 OpenShift restricted-v2 SCC 自动适配；global.compatibility.openshift.adaptSecurityContext: auto（values.yaml）；14.1.0 增加 PSA（Pod Security Admission）restricted 策略支持；14.0.10 修正 YAML 解析空格问题。
5. NetworkPolicy：14.1.1 引入 networkpolicy 模板；14.8.1 默认开启；15.2.0 完成策略评审；16.4.2 移除模板中的未定义 rts 键。

其他横切安全能力还包括：global.security.allowInsecureImages（镜像签名校验）、serviceBindings.enabled（生成 ServiceBinding 兼容 Secret，13.7.0 引入）、RBAC 自定义（10.18.0）、enableServiceLinks（14.2.0 起可关闭，避免大量 Service 环境变量拖慢启动）、extraDeploy（10.17.0）与mongo-labeler侧车模式（10.19.0 支持动态标记 primary Pod）。

八、其他关键演进与升级注意事项

8.1 镜像与 OCI 化

• 13.1.0 支持镜像 digest 寻址（image.digest覆盖 tag）；
• 13.10.0 使 charts 100% OCI 化，安装命令为helm install my-release oci://registry-1.docker.io/bitnamicharts/mongodb；
• 15.5.0 起在替换非官方镜像时输出告警；16.4.0 支持检测非标准镜像。

8.2 资源与存储

• 14.9.0 引入resourcesPreset（none/nano/micro/small/medium/large/xlarge/2xlarge），主容器默认small，init 容器默认nano/micro；
• 15.4.0 支持为volumeClaimTemplates配置 labels；14.5.0 支持自定义持久卷名称与 PVC 名称；15.6.14 使全局 StorageClass 成为默认值；14.3.0 支持 StatefulSet 的 PVC 保留策略。

8.3 稳定性修复

• 12.1.21 / 14.12.1：修复由探针导致的僵尸进程问题；
• 13.1.5：支持自定义探针（customLivenessProbe等，见 values.yaml）；
• 15.5.1：liveness/readiness 使用不同的探针实现；
• 13.6.6：增大探针超时；10.15.3：提升旧版本 MongoDB 的 readiness 兼容性。

8.4 升级路径建议

结合 CHANGELOG 中的 major 版本节点（10.0.0 升级到 Helm v2 chart 格式、12.0.0 标准化、13.0.0/14.0.0/15.0.0 安全与结构调整、16.0.0/17.0.0 常规大版本），升级时重点关注：

1. 认证从环境变量迁移到usePasswordFiles的行为变化；
2. containerSecurityContext默认值收紧（readOnlyRootFilesystem、capabilities drop）对自定义镜像的兼容性；
3. 密码更新需配合passwordUpdateJob与previousPasswords使用，避免升级后认证失配；
4. 旧版自定义证书需核对tls.pemChainIncluded与新 SAN 生成逻辑；
5. 若使用 PSP，注意其已被标记弃用并逐步移除。

九、总结

通过 CHANGELOG 的演进脉络可以清晰地看到，Bitnami MongoDB chart 在六年内从单一 Deployment 形态成长为覆盖 standalone、replicaset、arbiter、hidden 多拓扑，集成了认证轮换、自动 TLS、定时备份、Prometheus 监控与完整安全加固的成熟 Helm 包。理解这些版本节点背后的变更动机（如 values.yaml 中usePasswordFiles默认值调整、update-password/job.yaml 的 hook 机制、backup/cronjob.yaml 的 TLS 适配），将帮助你在实际部署与升级中精准定位参数、规避破坏性变更，并正确规划生产环境的备份、监控与安全策略。

• 云原生
• 容器编排