企业官网建设流程全解析

本指南聚焦于在 Kubernetes 集群中使用 Helm 部署 Kong 且数据后端选择 Postgres 时，最常见的两类启动失败故障：helm upgrade后 Kong 无法启动、以及全新安装时 Kong 无法连接数据库。文章将结合本仓库stable/kongchart 的迁移 Job、initContainer 与密码注入实现（migrations.yaml、deployment.yaml、_helpers.tpl），讲清故障根因，并给出可立即执行的排查命令与规避方案。

背景：Postgres 模式下 Kong 的启动与密码链路

Kong 的 Helm chart 支持无数据库（DB-less）、Postgres、Cassandra 三种数据后端，其中 Postgres 是 Kubernetes 部署的推荐选择，可通过postgresql.enabled: true随 chart 一并拉起一个 Postgres 实例（依赖定义见 requirements.yaml）。在这一模式下，Kong 的启动涉及三条关键链路：

1. 初始化迁移 Job：当runMigrations: true且env.database非off时，chart 会渲染一个*-init-migrationsJob，执行kong migrations bootstrap（见 migrations.yaml），用于在首次部署时初始化数据库 schema。
2. 升级迁移 Job：helm upgrade时会通过 Helm hook 触发pre-upgrade与post-upgrade两个迁移 Job，分别执行kong migrations up与kong migrations finish（见 migrations-pre-upgrade.yaml 与 migrations-post-upgrade.yaml）。
3. 数据库就绪等待与密码注入：Deployment 的proxy容器之前会挂载wait-for-dbinitContainer，循环执行kong start直到数据库可用；而数据库密码则是通过secretKeyRef从 Postgres 子 chart 生成的 Secret 中动态读取（见 _helpers.tpl 中kong.final_env定义的KONG_PG_PASSWORD以及kong.wait-for-db定义）。

正是这第三条链路——密码从 Secret 动态注入——构成了 FAQ 中第一个故障的核心诱因。

FAQ 一：helm upgrade之后 Kong 启动失败，如何处理？

故障现象与根因

在 FAQs.md 中记录了这样一个高频问题：使用 Postgres 时，执行helm upgrade后 Kong 无法启动。该问题被追踪为 helm/charts 仓库的 issue #12575，其上游根因是 helm/helm 的 issue #3053。

故障链路如下：

• Helm 在每次发布（release）时，如果子 chart 的密码参数未显式指定，会重新生成一个随机的 Postgres 密码并写入新的 Secret；
• 而 Postgres 的数据是持久化的——数据库中保存的是上一代 release 的旧密码；
• chart 通过secretKeyRef将新 Secret 中的密码注入为KONG_PG_PASSWORD（见 _helpers.tpl 中kong.final_env的KONG_PG_PASSWORD定义）；
• 于是 Kong 拿新密码去连保存旧密码的数据库，基于密码的认证必然失败，Kong 进程随之反复启动失败。

从源码可以印证：kong.final_env中KONG_PG_PASSWORD引用的是{{ template "kong.postgresql.fullname" . }}这个 Secret 中的postgresql-password键（migrations.yaml、deployment.yaml 中的迁移 Job 与proxy容器都使用同一套环境变量），也就是说迁移 Job 与 Kong 主容器共用同一个密码来源——密码一旦错位，从迁移到启动会全线失败。

解决方案：为 postgresql 子 chart 指定固定密码

根治办法是为postgresql子 chart 显式设置一个固定密码，确保每次升级时使用的都是同一个用户提供的密码，而不是 Helm 随机生成的新密码。对应的 values.yaml 配置如下：

postgresql: enabled: true postgresqlPassword: <你的固定密码> # 关键：固定密码，防止升级时随机重建 postgresqlUsername: kong postgresqlDatabase: kong service: port: 5432

这样无论执行多少次helm upgrade，Secret 中的密码都保持不变，与数据库中持久化的密码始终一致，密码认证不再失配。

补充建议

• 若密码已经错位，升级前应先核对当前 Secret 中的密码与数据库实际密码是否一致，必要时先在数据库侧重置密码；
• 在 values.yaml 中，postgresql段的默认值为enabled: false，其下postgresqlUsername: kong、postgresqlDatabase: kong、service.port: 5432均已注释给出示例，按需取消注释并填写即可。

FAQ 二：全新安装 Postgres 时 Kong 启动失败，如何处理？

故障现象与根因

第二个高频问题是：全新安装（fresh install）时 Kong 启动失败。FAQ 给出的结论是：请先确认集群中是否存在上一次 release 残留的 PersistentVolume（PV）。若存在残留 PV，会导致数据或密码与当前 release 不同步，进而引发连接问题。

这与第一个问题其实是同一条根因链的另一个入口：PV 是持久化载体，只要数据卷还在，里面的旧密码/旧数据就不会因为 release 删除而消失；而新 release 的新 Secret 携带新密码，两者再次错位。

排查步骤

使用以下命令检查当前命名空间下是否存在残留 PV：

kubectl get pv -n <your-namespace>

重点观察输出的AGE列：

• 若存在创建时间远早于当前 release 的旧卷，即为残留 PV；
• 残留 PV 是故障来源，需要清理。

处理流程

确认存在残留 PV 后，按顺序执行：

1. 删除 release：helm delete <release-name>（旧版本 Helm 使用helm delete --purge <release-name>）；
2. 删除残留的 PersistentVolume；
3. 执行一次全新的安装。

需要特别提醒：PV 的生命周期与命名空间解耦——即使删除了 PV 所在的命名空间，这些 PersistentVolume 仍然会残留在集群中。因此清理时必须显式针对 PV 资源操作，而不能指望删除 namespace 顺带清理。

总结：Postgres + Kong 部署的三个预防要点

1. 密码显式固定：只要使用postgresql子 chart，就务必在 values 中固定postgresqlPassword，这是规避helm upgrade密码失配的唯一直截了当的手段；
2. 升级前检查 PV 残留：在做任何重建、回滚或跨版本升级前，用kubectl get pv -n <namespace>检查AGE，及时清理旧卷，避免"假全新安装"；
3. 理解密码注入路径：从源码可见，迁移 Job、wait-for-dbinitContainer 与proxy容器共用同一份kong.final_env环境变量（见 _helpers.tpl 与 deployment.yaml），密码来源单一，任何一处的 Secret 错位都会表现为 Kong 反复启动失败——排查时优先核对 Secret 与数据库两侧密码的一致性。

若希望进一步了解该 chart 的其他部署形态（DB-less、Ingress Controller 模式）与全部可配置参数，可阅读同目录下的 README.md 与默认配置 values.yaml。需要注意的是，本仓库中的该 chart 已标记为 DEPRECATED，官方推荐迁移至 Kong 维护的独立 chart 仓库，但本文所述故障机理与排查思路对迁移后的部署依然适用。