当Coroot服务地图空白时？从内核到配置的5层排查指南

你是否遇到过这样的情况：部署Coroot后，界面上的服务地图一片空白，明明应用都在正常运行，却看不到任何服务依赖关系？这种"看得见应用，摸不着依赖"的困境，往往让运维人员陷入"监控盲区"。本文将通过一个电商平台的真实故障案例，带你从内核层到应用层逐层排查，30分钟内恢复服务地图可视化。

问题场景：双11前的服务地图"消失术"

某电商平台在双11大促前一周部署了Coroot可观测平台，期望通过服务地图梳理微服务依赖关系。然而部署完成后，Web界面的服务地图始终显示"无数据"，但所有应用Pod状态正常，Prometheus也能采集到基础指标。距离大促仅剩72小时，这个问题直接影响架构优化和故障定位效率。

故障现象

• 服务地图页面显示"未发现服务依赖"
• Agent状态页面显示node-agent和cluster-agent均为Running
• 基础设施监控面板能正常显示CPU、内存等指标
• 应用日志中无明显错误信息

根因分析：数据采集的"隐形屏障"

服务地图的数据来源于eBPF探针采集的网络流量和进程信息，这个过程就像给系统安装了"神经传感器"。当传感器与大脑（Coroot后端）之间的通信被阻断，或者传感器本身工作异常，就会导致服务地图空白。通过对Coroot架构的分析，我们发现可能的问题点分布在五个层面：

1. 内核层：eBPF程序依赖特定内核版本和模块
2. 权限层：容器缺少必要的系统调用权限
3. 网络层：Pod间通信被网络策略阻断
4. 配置层：服务发现规则未正确设置
5. 应用层：应用未暴露必要的指标接口

解决方案：从内核到应用的全栈修复

1. 内核兼容性验证

eBPF程序就像精密的"外科手术刀"，需要与内核版本精确匹配。Coroot的eBPF模块要求Linux内核≥5.4，且需安装对应版本的内核头文件。

📌 实操步骤：

# 检查内核版本
uname -r  # 输出应显示5.4.0或更高版本

# 安装内核头文件（Ubuntu/Debian）
apt-get install -y linux-headers-$(uname -r)

# 验证内核模块
lsmod | grep -e bpf -e perf_event

⚠️ 注意事项：

• 内核版本低于5.4时需升级系统，参考安装文档
• 阿里云ECS等特殊环境可能需要使用特定内核版本，需联系云服务商获取支持

核心配置示例（coroot.yaml）：

agent:
  ebpf:
    enabled: true
    kernelHeaders: /usr/src/linux-headers-$(uname -r)  # 指定内核头文件路径

效果验证：重启agent后查看日志

grep "eBPF program loaded" /var/log/coroot/node-agent.log

2. 容器权限强化

Coroot的node-agent需要CAP_BPF和CAP_PERFMON权限才能正常采集系统调用和性能事件，这就像给医生配备必要的手术器械。

📌 实操步骤： 修改docker-compose.yaml文件：

services:
  coroot-node-agent:
    cap_add:
      - CAP_BPF          # 允许加载eBPF程序
      - CAP_PERFMON      # 允许性能监控
      - CAP_SYS_ADMIN    # 系统管理权限
    volumes:
      - /sys/kernel/debug:/sys/kernel/debug:ro  # 只读挂载调试文件系统
      - /proc:/host/proc:ro                     # 挂载proc文件系统

源码参考：collector/collector.go中的eBPF初始化逻辑

效果验证：检查agent权限配置

docker exec -it coroot-node-agent capsh --print | grep "cap_bpf"

3. 网络策略调整

在Kubernetes环境中，默认的网络策略可能会阻断agent与应用之间的通信，就像在医院各科室间设置了不必要的门禁。

📌 实操步骤： 创建允许Coroot通信的NetworkPolicy：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-coroot-communication
  namespace: coroot
spec:
  podSelector:
    matchLabels:
      app: coroot
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector: {}  # 允许所有命名空间访问
    ports:
    - protocol: TCP
      port: 9091             # Coroot agent通信端口

参考文档：配置指南中的网络配置部分

效果验证：测试Pod间连通性

kubectl exec -it coroot-agent -- curl -I http://<app-pod-ip>:9091/health

4. 服务发现规则配置

对于未使用标准Kubernetes Service的应用，需要手动配置服务发现规则，就像给快递员提供详细的送货地址。

📌 实操步骤： 修改coroot配置文件：

customApplications:
  - name: "payment-service"  # 应用名称
    selector:
      matchLabels:
        app: payment          # 匹配的Pod标签
    ports:
      - 8080                 # 应用监听端口
    protocol: http           # 协议类型（http/grpc/tcp）

源码参考：config/project.go中的自定义应用配置解析逻辑

效果验证：查看服务发现状态

curl http://coroot-api:8080/api/v1/applications | jq '.[] | select(.name=="payment-service")'

5. 应用指标暴露检查

应用需要正确暴露Prometheus指标或符合OpenTelemetry规范的追踪数据，这就像病人需要配合医生做必要的检查。

📌 实操步骤： 检查应用是否暴露/metrics端点：

# 直接访问应用Pod
kubectl exec -it <app-pod> -- curl http://localhost:8080/metrics

# 或通过Service访问
kubectl port-forward svc/<app-service> 8080:8080
curl http://localhost:8080/metrics

参考文档：指标采集指南

效果验证：在Coroot UI的"Metrics"页面搜索应用相关指标

预防策略：构建服务地图"免疫系统"

经验总结

1. 版本兼容性优先：部署前使用兼容性检查脚本验证内核版本和依赖
2. 权限最小化原则：仅授予必要的CAP权限，避免过度授权带来的安全风险
3. 监控先行：为Coroot agent本身配置监控，设置关键指标告警（如ebpf_errors>0）

自动化检查清单

创建定期执行的健康检查脚本：

#!/bin/bash
# coroot-healthcheck.sh

# 1. 检查内核版本
if [ $(uname -r | cut -d. -f1-2) \< "5.4" ]; then
  echo "ERROR: Kernel version too old"
  exit 1
fi

# 2. 检查agent权限
if ! docker exec coroot-node-agent capsh --has-p=cap_bpf; then
  echo "ERROR: CAP_BPF not enabled"
  exit 1
fi

# 3. 检查服务发现状态
if ! curl -s http://coroot-api:8080/api/v1/applications | grep -q "payment-service"; then
  echo "ERROR: Service discovery failed"
  exit 1
fi

echo "Coroot health check passed"

问题速查索引

故障类型	可能原因	解决方案
服务地图空白	内核版本过低	升级内核至5.4+并安装头文件
服务地图空白	eBPF权限不足	添加CAP_BPF和CAP_PERFMON权限
服务地图部分空白	网络策略限制	配置允许9091端口通信的NetworkPolicy
自定义应用不显示	服务发现规则错误	检查customApplications配置
依赖关系不完整	应用未暴露指标	配置/metrics端点和OpenTelemetry

通过以上步骤，开篇提到的电商平台在2小时内解决了服务地图空白问题，赶在双11前完成了微服务依赖梳理。记住，服务地图空白往往不是单一原因造成的，需要从内核到应用的全栈视角进行排查。当你再次遇到类似问题时，不妨按照本文的5层排查法逐一验证，让Coroot真正成为你系统的"透视镜"。

提示：如果以上步骤仍未解决问题，可以使用corootctl collect-logs命令收集完整诊断信息，并在社区论坛寻求帮助。