基于 eBPF 的轻量级系统异常观测与根因定位工具

     

🚀 一键诊断 · 实时观测 · 根因定位 · AI 增强分析 · 可视化工作台

English Version | 测试报告 | 技术细节

📋 概述

eBPF Diagnoser 是一个面向 Linux/openKylin 的系统异常实时观测与根因定位工具。它通过 libbpf + CO-RE 探针采集内核事件，并用规则引擎、动态基线、跨场景关联和可选 LLM 分析生成结构化诊断报告；内置 Web 诊断工作台可将报告呈现为风险概览、根因证据链和关联图。

诊断报告包含证据链、置信度解释、异常时间线、场景指纹、容器上下文和可选热点调用栈，便于评委或运维人员回溯每个根因判断。

当前支持 5 类诊断场景：

• CPU 异常：占用率、调度延迟、上下文切换升高
• I/O 延迟：延迟抖动、队列拥堵、热点设备
• 内存压力：回收抖动、OOM 风险、内存泄漏
• 锁竞争：futex/mutex 竞争、死锁检测
• 系统调用：高频/高耗时热点追踪

🖥️ 环境要求

• Linux 内核 6.6+，推荐 openKylin 2.0 SP2
• Python 3.9+
• clang/LLVM 14+
• libbpf、libelf、zlib
• run/test 需要 root 权限；Web/TUI 工作台、离线 replay、Agent 和报告校验不需要 root
• 压测和基准测试建议安装 stress-ng、fio、sysbench

Windows 和 macOS 适合作为开发同步主机；真实 eBPF 构建和运行应在 Linux、WSL 合适内核、VM 或目标 openKylin 主机上完成。

📦 安装

Ubuntu / Debian

sudo apt update
sudo apt install -y build-essential clang llvm llvm-dev libbpf-dev \
  "linux-headers-$(uname -r)" libclang-dev pkg-config libelf-dev zlib1g-dev \
  stress-ng fio sysbench

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e .
make all

安装开发和 LLM 依赖：

python3 -m pip install -e ".[all]"

如果系统启用了 PEP 668 保护，可使用：

python3 -m pip install --break-system-packages -e ".[all]"

生产或评审机推荐使用 venv 或自解压安装器；不要依赖普通用户的 user-site 包再通过 sudo ebpf-diagnoser 调用，很多发行版的 sudo secure_path 会找不到该入口。

openKylin 2.0 SP2

SP2 使用 OSTree，normal 模式下 /usr 只读，且官方仓库中的 llvm、bpftool、stress-ng、fio 可用性与 Ubuntu 不同。请先进入维护模式并按对应宿主机指南配置：

• Windows/VMware openKylin 环境搭建指南
• macOS/UTM openKylin 安装与复现指南

Fedora / RHEL 类系统

sudo dnf install -y gcc clang llvm llvm-devel libbpf-devel \
  kernel-devel elfutils-libelf-devel zlib-devel stress-ng fio sysbench

python3 -m pip install -e .
make all

详细步骤见：openKylin 环境搭建指南。

🚀 常用命令

# 检查环境
ebpf-diagnoser status --verbose

# 运行所有探针
sudo ebpf-diagnoser run

# 运行指定探针
sudo ebpf-diagnoser run --probe cpu,io,mem --duration 60

# 输出 JSON 报告
sudo ebpf-diagnoser run --duration 60 --output json --output-file diagnosis_report.json

# 输出 Markdown 报告
sudo ebpf-diagnoser run --duration 60 --output md --output-file report.md

# 覆盖阈值
sudo ebpf-diagnoser run --threshold cpu_usage_high=80,io_p99_high=30

# 内置 5 类异常测试
sudo ebpf-diagnoser test --duration 30

# 配置管理
ebpf-diagnoser config show
ebpf-diagnoser config init
ebpf-diagnoser config path

# 终端工作台
ebpf-diagnoser tui

# Web 可视化工作台
ebpf-diagnoser web --report diagnosis_report.json

🔄 离线回放与结构校验

在没有 root 或 eBPF 环境时，可先用离线回放验证诊断链路：

ebpf-diagnoser replay \
  -i examples/replay_metrics_5_scenarios.json \
  --output json \
  --output-file replay_report.json

ebpf-diagnoser validate-report -i replay_report.json

相关文件：

• JSON 模式文件：docs/schemas/diagnosis.schema.json
• 示例报告：examples/diagnosis_report_example.json
• 5 类离线回放指标：examples/replay_metrics_5_scenarios.json

🌐 Web 可视化工作台

无需 root、Node.js 或额外 Web 依赖即可启动本地工作台。可先用五场景回放生成内容完整的演示报告：

ebpf-diagnoser replay \
  -i examples/replay_metrics_5_scenarios.json \
  --output json \
  --output-file replay_report.json
ebpf-diagnoser web --report replay_report.json

浏览器默认打开 http://127.0.0.1:8765。未传 --report 时加载内置示例；指定文件被重新生成后，页面会自动刷新。页面也可直接打开本地 JSON，数据只在浏览器内解析。

工作台包括运行总览、严重度与场景分布、异常筛选、根因/关键指标/证据链详情、可交互证据关系图、热点调用栈、系统环境、工具开销和原始 JSON。远程访问必须显式使用 --allow-remote，并应通过防火墙或反向代理限制访问。

完整说明：Web 可视化工作台指南。

🤖 TUI 与 Diagnosis Agent

交互式工作台：

ebpf-diagnoser tui
ebpf-diagnoser dashboard --watch --interval 2

tui 菜单集成环境检查、五场景 replay、Agent 报告、报告校验、实时诊断向导和配置查看。在非 TTY 环境会自动退化为静态看板，便于 CI 和文档截图。

证据驱动 Agent：

ebpf-diagnoser agent -i examples/diagnosis_report_example.json
ebpf-diagnoser agent -i replay_report.json --output md --output-file agent_report.md
ebpf-diagnoser agent -i replay_report.json --llm --question "最高优先级根因是什么？"

Agent 默认离线运行，只读取输入报告，输出固定工具计划、trace、证据引用、证据完整度、关联关系和人工复核处置队列。启用 --llm 时，模型只综合 Agent 已索引的证据；LLM 失败会降级为 completed_with_warnings，不会丢弃确定性结果。

安全边界：

• Agent 不执行命令，不修改主机状态。
• remediate --execute 不使用 shell，只允许少量白名单命令，并会逐条二次确认。
• Prompt 明确要求引用 evidence_chain、timeline、key_metrics 等真实证据，证据不足时必须说明。

✅ 验证

在 openKylin/Linux 目标机上运行：

make clean && make all
python3 scripts/verify_core.py
sudo ebpf-diagnoser status --verbose
sudo ebpf-diagnoser test --duration 30
sudo bash scripts/run_tests.sh
sudo bash scripts/benchmark_overhead.sh

benchmark_overhead.sh 会在 /tmp/ebpf-diagnoser-benchmark/ 生成 overhead_report.json 和 overhead_report.md，用于复核工具自身 CPU、内存和吞吐影响。

📦 打包发布

Python wheel/sdist 用于离线 replay、Agent、报告校验和文档资源分发：

python3 -m pip install build
python3 -m build
python3 -m pip wheel . --no-deps

架构相关的 eBPF .bpf.o 和 bpf_loader 建议使用自解压安装器交付：

bash scripts/build_installer.sh
sudo bash dist/ebpf-diagnoser-<version>-<arch>.sh

🔌 规则插件

除内置规则外，可将 YAML 规则放入 config/rules.d/，或通过环境变量加载外部规则目录：

export EBPF_DIAGNOSER_RULES_DIR=/path/to/rules.d

插件规则触发后会在诊断报告的 fingerprint.source 中标记来源。

🧠 LLM 智能分析

安装 LLM 依赖：

python3 -m pip install -e ".[llm]"

推荐使用 .env 配置。仓库提供 .env.example，本地 .env 已被 .gitignore 忽略，不应提交真实密钥。

cp .env.example .env

MiMo 配置示例：

MIMO_API_KEY=your-api-key
EBPF_DIAGNOSER_LLM_PROVIDER=mimo
EBPF_DIAGNOSER_LLM_MODEL=mimo-v2.5-pro

生成 LLM 分析报告：

sudo ebpf-diagnoser run --duration 60 --output json --output-file diagnosis_report.json
ebpf-diagnoser analyze -i diagnosis_report.json --llm-provider mimo --llm-model mimo-v2.5-pro -o md -f analysis.md

其他 LLM 命令：

ebpf-diagnoser remediate -i diagnosis_report.json
ebpf-diagnoser chat -c diagnosis_report.json -q "为什么 CPU 使用率高？"
ebpf-diagnoser log-analyze -i diagnosis_report.json -l dmesg

支持的 provider：

• openai
• anthropic
• qwen / dashscope
• ernie
• spark
• zhipu / glm
• deepseek
• moonshot / kimi
• mimo / xiaomimimo
• baichuan
• lingyiwanwu / yi

🔧 开发检查

python -m compileall src scripts/verify_core.py
python -m pytest -q
ruff check .
ruff format --check .

📚 文档

• 技术细节
• 设计说明
• 评分对照与复现指南
• 测试报告
• Web 可视化工作台指南
• openKylin 环境搭建指南
• macOS/UTM openKylin 安装与复现指南
• Windows/VMware openKylin SP2 完整测评报告
• macOS/UTM openKylin SP2 完整测评报告
• Windows/VMware MiMo LLM 分析报告
• macOS/UTM MiMo LLM 分析报告

🎬 演示视频

• B站视频
• 百度网盘（提取码: 1895）

竞赛初赛作品：项目说明书.pdf

📄 许可证

Apache License 2.0