服务器K8s集群KaiwuDB排错：Pod启动失败与连接异常排查

KaiwuDB 在 K8s 集群里跑不起来，多半不是数据库本身的问题，而是资源限制、存储挂载或网络配置导致 Pod 无法正常启动。
下面按从外到内的顺序，带你一步步定位并修复。

先确认 Pod 到底卡在哪一层

排错第一步不是翻数据库日志，而是看 K8s 层面的状态。
执行以下命令查看 KaiwuDB 相关 Pod：

kubectl get pods -n <命名空间> -l app=kaiwudb -o wide

重点关注 STATUS 列：

• Pending：调度失败，通常是资源不足或节点选择器不匹配。
• CrashLoopBackOff：容器反复重启，需要看容器日志。
• Running 但 READY 为 0/1：容器起来了但健康检查没过。
• Error：启动命令直接报错退出。

如果是 Pending，继续执行：

kubectl describe pod  -n <命名空间>

拉到 Events 区域，常见提示有 Insufficient cpu、Insufficient memory、node(s) had taint 或 volume node affinity conflict。
这些信息直接告诉你该调资源还是调存储。

日志里优先搜这几类关键词

容器能启动但反复重启时，日志是最直接的线索：

kubectl logs  -n <命名空间> --previous

加 --previous 是为了看上一次崩溃前的输出，因为当前容器可能已经重启到没有有效日志。
重点搜：

• permission denied：数据目录权限不对，常见于挂载了宿主机目录但 UID 不匹配。
• connection refused：KaiwuDB 内部节点之间连不上，检查 Service 或 headless service 配置。
• no space left on device：存储卷满了，先清理再考虑扩容。
• OOMKilled：内存超限，需要调大 resources.limits.memory 或优化查询。

如果日志里出现 failed to connect to peer 这类集群通信错误，回到 K8s 网络层检查：

kubectl get svc -n <命名空间>
kubectl get endpoints -n <命名空间>

确认 Service 的 Endpoints 是否有对应 Pod IP。
为空说明标签选择器写错了，或者 Pod 没就绪。

常见配置错误与修复动作

资源配额不够：describe 里看到 Insufficient memory，就需要调整 Deployment 或 StatefulSet 中的 resources.requests 和 limits。
KaiwuDB 对内存较敏感，建议 requests 和 limits 设为相同值，避免节点内存碎片导致调度失败。

存储卷挂载失败：如果 Events 里出现 FailedMount，先检查 PVC 是否绑定成功：

kubectl get pvc -n <命名空间>

状态为 Pending 时，查看 StorageClass 是否存在、容量是否满足。
云环境还要确认磁盘类型是否支持动态供给。

节点亲和性或污点问题：KaiwuDB 通常要求特定节点运行。
用以下命令查看节点污点：

kubectl describe node <节点名称> | grep Taints

如果节点有 NoSchedule 污点，需要在 Pod 模板中加 tolerations，或者去掉污点。

健康检查超时：Running 但 READY 为 0/1，多半是 livenessProbe 或 readinessProbe 的 initialDelaySeconds 太短。
KaiwuDB 启动需要一定时间，建议把初始延迟调到 30 秒以上，并适当放宽 failureThreshold。

修复后怎么验证集群正常

改完配置后，先删除旧 Pod 让控制器重建：

kubectl delete pod  -n <命名空间>

然后观察新 Pod 状态变化：

kubectl get pods -n <命名空间> -w

等到所有副本的 READY 变成 1/1，再进入容器执行一次连接测试：

kubectl exec -it  -n <命名空间> -- kaiwudb-client --host=127.0.0.1 --port=<端口>

能进入交互界面并执行 SELECT 1; 返回结果，说明单节点已正常。
如果是多节点集群，继续检查各节点之间的复制状态，通常可以通过 KaiwuDB 内置的集群状态命令查看。

排错时容易忽略的细节

• 不要直接改运行中的 Pod：K8s 中 Pod 是临时资源，直接 kubectl edit pod 的改动不会持久化。所有修改应作用于 Deployment、StatefulSet 或 Helm values。
• 命名空间别搞混：多环境共用集群时，kubectl 默认命名空间可能不是 KaiwuDB 所在空间，命令后务必带 -n。
• 日志级别调高再复现：如果默认日志看不出原因，可以在配置中临时把日志级别调到 debug，复现后再调回，避免磁盘被日志写满。
• 先备份再改存储：涉及 PVC 扩容或 StorageClass 变更时，先确认数据有快照或备份，否则可能造成数据丢失。

如果按上述步骤仍然无法恢复，建议收集 kubectl describe pod、容器日志和节点 dmesg 信息，再对照 KaiwuDB 官方文档中对应版本的部署要求核对参数。