K8s集群中StarRocks常见故障排查与修复步骤

在Kubernetes集群里跑StarRocks，最常见的故障是CN或BE节点掉线、FE无法选主、Pod反复重启。
排错的核心思路是先用kubectl确认Pod状态，再根据日志定位是配置、资源还是网络问题。
下面按顺序说明每一步怎么查、怎么修。

先确认集群和Pod的基本状态

登录到能执行kubectl的服务器，检查StarRocks相关命名空间下的Pod：

kubectl get pods -n starrocks -o wide

重点看三列：STATUS、RESTARTS、NODE。
如果某个Pod的STATUS是CrashLoopBackOff或Error，先记下Pod名称和所在节点。

接着查看Pod的详细事件，事件里通常包含调度失败、镜像拉取失败或探针失败的原因：

kubectl describe pod  -n starrocks

如果事件里出现OOMKilled，说明容器内存超限；
出现Liveness probe failed，说明健康检查配置可能太严格或服务启动太慢。

分角色排查FE、BE和CN

StarRocks在K8s中通常分为FE、BE和CN三种角色，排错时不要混在一起看。

FE无法启动或无法选主

FE负责元数据管理和查询协调。
如果FE Pod起不来，先看日志：

kubectl logs  -n starrocks --tail=100

常见报错包括meta_dir权限不足、edit_log端口被占用、或者JAVA_OPTS内存设置过大导致容器OOM。
如果是权限问题，检查PVC挂载路径的属主是否为starrocks用户。
FE选主失败通常是因为节点间网络不通，可以用kubectl exec进入Pod测试telnet或nc到其他FE的edit_log_port（默认9010）。

BE或CN节点掉线

BE和CN负责数据存储和计算。
如果SHOW BACKENDS或SHOW COMPUTE NODES中节点显示Dead，先在K8s侧确认Pod是否还在运行：

kubectl get pods -n starrocks | grep -E 'be|cn'

如果Pod正常但StarRocks里显示掉线，可能是BE/CN的心跳端口（默认9050）没有正确暴露，或者FE的heartbeat_service_port配置与BE不一致。
检查Service的端口映射：

kubectl get svc -n starrocks

确保BE/CN的heartbeat_service_port在Service中已声明，并且网络策略没有阻断FE到BE/CN的流量。

检查配置和资源限制

很多排错最后都落在配置项上。
重点核对以下三处：

• 资源限制：resources.limits.memory如果设得太小，BE在导入数据时容易触发OOM。建议BE的limit不低于8Gi，CN按查询并发适当上调。
• JVM参数：FE的JAVA_OPTS中-Xmx不能超过容器内存limit的70%，否则会被OOMKilled。
• 存储卷：PVC的storageClassName必须存在且可动态供给。如果PVC一直Pending，用kubectl describe pvc -n starrocks查看是存储类问题还是容量不足。

修改配置后，用kubectl apply重新应用StatefulSet或Helm values，然后观察Pod是否正常进入Running且RESTARTS不再增长。

避坑指南

• 不要直接删除PVC：FE的元数据存储在PVC中，删除会导致集群元数据丢失，必须先确认有备份。
• 滚动重启要分批：FE有多个节点时，一次只重启一个，等它恢复并加入集群后再操作下一个。
• 日志级别不要长期开DEBUG：DEBUG日志会快速消耗磁盘，排错结束后记得调回INFO。
• 网络策略先放行再收紧：如果用了NetworkPolicy，先确认FE、BE、CN之间的心跳和RPC端口全部放行，再逐步限制。

验证排错效果

修复后，按以下顺序验证：

1. 确认所有Pod状态为Running，且RESTARTS在5分钟内没有增加：

kubectl get pods -n starrocks -w

1. 进入FE Pod，用MySQL客户端连接并检查节点状态：

kubectl exec -it  -n starrocks -- mysql -h127.0.0.1 -P9030 -uroot

SHOW BACKENDS;
SHOW COMPUTE NODES;

1. 建一张测试表并插入少量数据，确认写入和查询都正常：

CREATE TABLE test.t1 (id int) DISTRIBUTED BY HASH(id) BUCKETS 1;
INSERT INTO test.t1 VALUES (1);
SELECT * FROM test.t1;

如果SHOW BACKENDS中所有节点Alive为true，且测试查询返回结果，说明集群已恢复。

常见疑问

Pod一直Pending，但事件里没有明显报错，怎么办？
先看节点资源是否充足：kubectl describe node ，检查Allocated resources里CPU和内存是否已满。如果资源足够，再检查是否有污点或亲和性规则导致无法调度。

FE日志里出现Too many open files怎么处理？
这是文件描述符限制问题。在Pod的securityContext或容器的ulimit中调大nofile，同时确认节点内核参数fs.file-max足够大。

BE节点频繁掉线但Pod没有重启，可能是什么原因？
优先检查FE和BE之间的网络延迟与丢包。如果K8s集群跨节点通信质量差，心跳超时会导致BE被标记为Dead。可以用ping和tcpdump在节点间做基础排查。

排错完成后，建议把本次的故障现象、定位命令和修复动作记录到运维文档里，下次遇到同类问题可以直接对照处理。