Skip to main content

故障排查

本文档提供 KubePolaris 常见问题的诊断和解决方法。

诊断工具​

健康检查​

# API 健康检查
curl http://localhost:8080/api/health

# 预期响应
{
  "status": "healthy",
  "database": "connected",
  "version": "1.0.0",
  "uptime": "10h30m"
}

日志查看​

# Docker
docker logs kubepolaris-backend -f --tail 100

# Kubernetes
kubectl logs -f deployment/kubepolaris-backend -n kubepolaris

# 查看错误日志
kubectl logs deployment/kubepolaris-backend -n kubepolaris | grep -i error

资源检查​

# Pod 状态
kubectl get pods -n kubepolaris

# 事件
kubectl get events -n kubepolaris --sort-by='.lastTimestamp'

# 资源使用
kubectl top pods -n kubepolaris

常见问题​

服务无法启动​

症状​

  • Pod 状态 CrashLoopBackOff
  • 日志显示启动错误

诊断​

# 查看 Pod 状态
kubectl describe pod -l app=kubepolaris -n kubepolaris

# 查看日志
kubectl logs -f deployment/kubepolaris-backend -n kubepolaris --previous

常见原因​

1. 配置文件错误

# 验证配置
kubectl get configmap kubepolaris-config -n kubepolaris -o yaml

2. 数据库连接失败

# 测试数据库连接
kubectl run -it --rm mysql-client --image=mysql:8.0 -- \
  mysql -h kubepolaris-mysql -u root -p

3. 端口被占用

# 检查端口
netstat -tlnp | grep 8080

解决方案​

  • 修正配置文件语法
  • 确认数据库地址和凭据
  • 更换或释放端口

登录失败​

症状​

  • 无法登录
  • 提示用户名或密码错误

诊断​

# 查看认证日志
kubectl logs deployment/kubepolaris-backend -n kubepolaris | grep -i auth

常见原因​

1. 密码错误

# 重置管理员密码
kubectl exec -it deployment/kubepolaris-backend -n kubepolaris -- \
  ./kubepolaris-backend reset-password --user admin --password newpass

2. 账号锁定

  • 多次错误登录导致锁定
  • 等待锁定时间过期或手动解锁

3. JWT 配置问题

# 检查 JWT 配置
kubectl get secret kubepolaris-secrets -n kubepolaris -o yaml

无法连接集群​

症状​

  • 添加集群失败
  • 集群状态显示异常

诊断​

# 从 KubePolaris Pod 测试连接
kubectl exec -it deployment/kubepolaris-backend -n kubepolaris -- \
  curl -k https://api-server:6443/healthz

常见原因​

1. 网络不通

# 检查网络
kubectl exec -it deployment/kubepolaris-backend -n kubepolaris -- \
  ping api-server-ip

2. 认证配置错误

  • kubeconfig 格式错误
  • Token 过期
  • 证书不匹配

3. 防火墙阻止

  • 确保 6443 端口开放

解决方案​

# 验证 kubeconfig
kubectl --kubeconfig=your-config.yaml get nodes

# 测试 Token
curl -H "Authorization: Bearer $TOKEN" -k https://api-server:6443/api/v1/nodes

终端连接失败​

症状​

  • Pod 终端无法打开
  • WebSocket 连接失败

诊断​

# 检查 WebSocket 服务
kubectl logs deployment/kubepolaris-backend -n kubepolaris | grep -i websocket

# 浏览器控制台检查
# 打开开发者工具 → Network → WS

常见原因​

1. Nginx/Ingress 不支持 WebSocket

# 确保 Nginx 配置
location /ws/ {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

2. 超时配置

proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

3. Pod 不支持 exec

# 检查 RBAC
kubectl auth can-i create pods/exec -n default

页面加载慢​

症状​

  • 页面响应缓慢
  • API 请求超时

诊断​

# 检查 API 响应时间
time curl http://localhost:8080/api/clusters

# 检查资源使用
kubectl top pods -n kubepolaris

常见原因​

1. 资源不足

# 增加资源限制
resources:
  limits:
    cpu: 4000m
    memory: 4Gi

2. 数据库慢查询

-- 检查慢查询
SHOW PROCESSLIST;
SHOW STATUS LIKE 'Slow_queries';

3. 网络延迟

  • 检查到 API Server 的网络延迟
  • 考虑就近部署

监控数据缺失​

症状​

  • 监控图表不显示
  • Prometheus/Grafana 连接失败

诊断​

# 测试 Prometheus 连接
curl http://prometheus:9090/api/v1/query?query=up

# 测试 Grafana 连接
curl -H "Authorization: Bearer $API_KEY" http://grafana:3000/api/org

常见原因​

1. 地址配置错误

  • 检查系统设置中的地址配置

2. 认证失败

  • Grafana API Key 过期
  • 权限不足

3. 网络问题

  • 从 KubePolaris Pod 无法访问监控服务

数据库问题​

症状​

  • 数据库连接错误
  • 数据不一致

诊断​

# 检查数据库状态
mysql -h mysql-host -u kubepolaris -p -e "SHOW STATUS"

# 检查连接数
mysql -h mysql-host -u kubepolaris -p -e "SHOW PROCESSLIST"

常见原因​

1. 连接池耗尽

# 增加连接池
database:
  max_idle_conns: 20
  max_open_conns: 200

2. 锁等待超时

-- 检查锁
SHOW ENGINE INNODB STATUS;

3. 磁盘空间不足

# 检查磁盘
df -h

日志分析​

常见错误日志​

# 数据库连接错误
dial tcp mysql:3306: connect: connection refused

# 认证错误
invalid token: signature is invalid

# Kubernetes 连接错误
unable to load root certificates

# 权限错误
forbidden: User "system:serviceaccount:..." cannot get resource

日志级别调整​

# 临时开启 debug 日志
log:
  level: debug

性能优化​

数据库优化​

-- 分析慢查询
SET profiling = 1;
SELECT * FROM clusters;
SHOW PROFILES;

-- 添加索引
CREATE INDEX idx_cluster_status ON clusters(status);

应用优化​

# 调整连接池
database:
  max_idle_conns: 50
  max_open_conns: 200
  conn_max_lifetime: 3600

# 调整 K8s 客户端
kubernetes:
  qps: 100
  burst: 200

获取帮助​

收集信息​

# 收集诊断信息
kubectl get pods -n kubepolaris -o wide
kubectl get events -n kubepolaris
kubectl logs deployment/kubepolaris-backend -n kubepolaris --tail=1000 > backend.log
kubectl describe pod -l app=kubepolaris -n kubepolaris > pod-describe.txt

提交 Issue​

访问 GitHub Issues 并提供：

  1. KubePolaris 版本
  2. 部署方式
  3. 问题描述
  4. 复现步骤
  5. 错误日志
  6. 环境信息

下一步​