eBPF Diagnose

面向 openKylin/Linux 的系统异常观测与根因定位平台，使用 eBPF、Go、C++ 和 Qt，覆盖 CPU、内存、I/O、锁、系统调用五类场景。适用于系统性能排查、异常复现、证据回查和教学演示。数据链路为浅层采集 → 异常窗口判断 → 限时目标化深层采集 → 根因与证据关联 → JSONL/Prometheus → CLI 与 Qt。

项目获取与演示视频下载

材料	下载或访问链接	获取说明
项目源码、说明文档及测试验证材料	GitLink 项目仓库（master 分支）	获取 `master` 分支的完整交付目录，随后按照本文的构建、运行与测试方法使用。源码访问需要具有该仓库访问权限的 GitLink 账号。
完整纯净版交付包	下载压缩包 · SHA-256 校验文件	约 1.20 GB，解压约需 11.6 GiB；包含源码、归档测试证据与演示材料。按照解压与构建说明安装依赖并构建运行，验证信息见交付包清单。
项目演示视频	百度网盘下载链接	提取码：vxsy。打开链接，输入提取码后选择演示视频进行在线播放或下载；下载时按网盘页面提示登录。

源码也可通过终端获取（HTTPS 提示认证时，使用具有仓库访问权限的账号）：

git clone --depth 1 --branch master \
  https://gitlink.org.cn/IlAAAzZZSM/jyedxtycgcygydwgj.git ebpf-diagnose
cd ebpf-diagnose

视频下载入口及提取码同时保存在项目演示视频链接.txt。2026-10-07 已核验网盘分享页面可访问、提取码验证通过；实际播放与下载以网盘页面及账号权限为准。

交付目录

README.md
src/                  源码、配置、机器可读数据契约、构建与运行入口
  bpf/ collectors/ cmd/ internal/ pkg/
  analyzer/ ebpf-UI/ configs/ scripts/ tools/ schemas/ docs/
  Makefile go.mod go.sum
docs/                 仅存放要求的四份 PDF文档
tests/                测试脚本、负载、配置、原始证据、结果与报告
demo/                 可运行、可复现的演示入口
presentation/         决赛答辩 PPT、配套 PDF 与演示视频链接
作品原创承诺书.pdf

当前分支为 master。四份规定 PDF、原创承诺书及决赛现场演示 PPT 已整理到规定位置。成员仅使用 A（组长）、B、C。工具使用声明仍需团队在模板空白栏完成手抄；演示视频通过项目演示视频链接提供，文本包含网盘地址和提取码。

测试材料只存放于根目录 tests/，运行与实验结果存放于 tests/results/，源码直接引用这两个目录。本机构建产物与工具缓存不属于交付源码，导出时已自动排除。

主要功能与应用场景

场景	观测与诊断
CPU	利用率、运行队列、调度延迟、热点 PID/TID 和栈
内存	可用内存、RSS、fault、回收及 OOM 事件
I/O	IOPS、吞吐、请求时延、设备、进程和文件归因
锁	futex 等待、时延、锁地址和线程归因
系统调用	频率、时延、错误率、调用名称和 PID/TID

CLI 统一提供环境检查、实时观测、状态查询、报告、解释和回放，以及证据索引、质量检查、五层证据链、多源关联、受约束 AI 上下文包。Qt 提供中英文切换、五场景面板、告警、诊断报告、证据回查和项目功能测试。功能状态以异常矩阵为准，实测结论见测试总结。

五场景 17 类异常与测试验证矩阵

异常目录包含 CPU 4 类、I/O 4 类、内存 4 类、锁 2 类、系统调用 3 类，共 17 类。其中 16 类默认启用异常均保留了真实闭环 PASS 记录；OOM_RISK 为默认关闭的实验功能，未计入正式通过统计。下表逐类列出一份可复核的用例审核记录，中文名称与 Qt 界面保持一致。

场景	用例	异常名称	诊断类型标识	测试情况与证据
CPU	C-01	CPU 异常占用	`CPU_HIGH_USAGE`	PASS：CPU 高占用闭环
CPU	C-03	CPU 调度延迟	`CPU_SCHED_LATENCY`	PASS：调度延迟闭环
CPU	C-07	上下文切换风暴	`CONTEXT_SWITCH_STORM`	PASS：切换风暴修复后验证
CPU	C-05	CPU 线程竞争	`CPU_THREAD_CONTENTION`	PASS：线程竞争闭环
I/O	I-03	I/O 时延抖动	`IO_LATENCY_JITTER`	PASS：I/O 时延闭环
I/O	I-06	I/O 队列拥塞	`IO_QUEUE_CONGESTION`	PASS：队列拥塞闭环
I/O	I-04	I/O 热点文件	`IO_HOT_FILE`	PASS：热点文件闭环
I/O	I-05	I/O 热点进程	`IO_HOT_PROCESS`	PASS：热点进程闭环
内存	M-01	内存压力	`MEMORY_PRESSURE`	PASS：内存压力闭环
内存	M-03	内存回收抖动	`MEMORY_RECLAIM_JITTER`	PASS：回收抖动闭环
内存	M-04	内存 OOM	`MEMORY_OOM`	PASS：隔离环境 OOM 闭环
内存	M-05	OOM 风险	`OOM_RISK`	实验功能，默认关闭；功能状态
锁	L-01	锁竞争	`LOCK_CONTENTION`	PASS：锁竞争闭环
锁	L-03	疑似大临界区	`LARGE_CRITICAL_SECTION`	PASS：大临界区修复后验证
系统调用	S-02	高频系统调用热点	`SYSCALL_FREQUENCY_HOTSPOT`	PASS：高频调用闭环
系统调用	S-04	高耗时系统调用热点	`SYSCALL_LATENCY_HOTSPOT`	PASS：调用时延闭环
系统调用	S-03	系统调用错误风暴	`SYSCALL_ERROR_STORM`	PASS：错误调用闭环

PASS 表示对应运行按该用例的适用条件通过审核。已逐项核对上述 16 份记录的预期异常、审核错误数、原始引用解析、CLI 五层证据链与来源核验、必需采集质量和清理状态；对象核验范围以各用例的 case-audit.json 为准。同目录中的 ground-truth.json、data-quality.json、cli-query/verify.json、cleanup-result.json 和 validation-session.json 提供独立真值及完整闭环信息。

这些记录来自保存的不同运行批次，不能据此宣称所有历史运行或当前构建均已通过。五类正常对照 C-06、I-02、M-08、L-02、S-08 也保留了通过示例；整体准确性、失败及无法判定样本的统计口径见测试总结和通过示例索引。

Qt 界面与证据回查流程

Qt 与 CLI 使用同一套指标、JSONL 诊断及原始事件数据。以下核心截图直接提取自决赛现场演示 PPT 第 28～30 页，展示保存的实际演示画面；具体测试结果可通过上方矩阵中的审核记录复核。

1. 运行总览：查看资源与数据状态

Qt 运行总览：资源表盘、近期事件与五分钟趋势

总览集中展示 CPU、可用内存比例、磁盘最大平均时延、窗口平均锁等待和已观测系统调用速率，以及健康评分、去重异常数和近期事件预览。右侧趋势图将不同单位的指标归一化，便于观察变化；近期事件预览最多展示 200 条。顶部区分系统运行、指标连接、近期诊断记录和数据加载状态，右上角可切换中文与英文。

2. 告警中心：筛选异常并进入诊断

Qt 告警中心：异常类型、严重程度、对象与记录状态

告警中心汇总五场景诊断，提供模块、严重程度和文本筛选，按高、中、低显示告警级别。每条记录包含时间、PID/TID、异常类型、描述及近期或历史状态；选择记录后可查看对应场景及诊断报告。顶部“近期记录”按最近五分钟统计，表格同时支持查看已加载的历史记录。

3. 五层证据链：核对异常依据

Qt 五层证据链：触发证据、目标、根因、支持证据和原始事件

证据链依次呈现触发证据 → 目标 → 疑似根因 → 支持证据 → 原始事件。示例将 CPU 异常占用关联到 stress-ng-cpu 的 PID/TID，列出 CPU 持续高占用和线程运行占比等支持条件，再链接到原始事件。结合场景页的规则阈值、观测值、采集质量和根因候选，可以逐项检查结论的依据与缺失信息。

4. 诊断报告：查看详情并导出

Qt CPU 诊断报告：异常摘要、关联对象、规则指标与证据

报告汇总异常类型、严重程度、时间窗口、目标身份、疑似根因、规则判定、关键指标和证据摘要，支持复制及 Markdown/JSON 导出。图中 CPU 观测值约 99.07%，对应阈值为 90%；证据支持度 0.90 为规则评分，不能直接解释为根因正确概率。项目功能测试入口则按用例执行真实负载、独立真值、诊断与证据审核，并展示通过、失败、跳过或无法判定的实际终态。

系统环境与依赖要求

目标环境为 openKylin 2.0 SP2、Linux 6.6+、x86_64，要求可读 /sys/kernel/btf/vmlinux。ARM64 有构建适配，运行能力须另行验证。依赖 Go 1.24+、Clang/LLVM（BPF 后端）、libelf、CMake 3.24+、C++20 编译器、Cap’n Proto 与 capnpc-go、Python 3。GUI 依赖 Qt 6.4+ 的 Core、Gui、Qml、Quick、Quick Controls 2、Network 开发组件、QML 运行时模块及图形桌面。C++ 单测需要 GoogleTest。

压力验证另需 curl、fio、stress-ng、sudo、cgroup v2 和独立测试盘。Go 版本与依赖由 go.mod、go.sum 锁定，保留第三方代码版权和 SPDX 标识；关键许可证及完整 Go 模块清单见第三方说明。

构建与安装

构建命令在 src/ 执行：

cd src
source scripts/dev-env.sh
# 首次联网准备 Go 依赖；后续构建默认离线
make prepare-go-deps-online
go install capnproto.org/go/capnp/v3/capnpc-go@v3.1.0-alpha.2
export PATH="$(go env GOPATH)/bin:$PATH"
make diagnosis-build JOBS=2
make ui-build JOBS=2

dev-env.sh 在存在本地工具链缓存时使用它，交付环境可使用系统工具链。离线环境须预先提供对应模块缓存、Cap’n Proto 工具和系统依赖。后端产物位于 src/_output/{bin,bpf,conf}/，UI 位于 src/build/ui/。采用仓库内运行方式，无需安装系统服务；部署时保持上述目录关系。见开发说明与配置说明。技术文档中的构建和运行命令在 src/ 执行。

运行方法

图形演示在交付根目录执行：

bash demo/run.sh doctor
sudo -v
bash demo/run.sh start
bash demo/run.sh status
bash demo/run.sh stop

已运行时可使用 bash demo/run.sh restart。仅后端可用 bash src/scripts/manage_ebpf_stack_openkylin.sh start-backend，随后用 status-backend 查看、stop-backend 停止。统一 CLI 示例：

src/_output/bin/ebpf-diagnose --help
src/_output/bin/ebpf-diagnose doctor
sudo src/_output/bin/ebpf-diagnose observe --scenarios all --duration 60s
src/_output/bin/ebpf-diagnose report --session /absolute/path/to/session
src/_output/bin/ebpf-diagnose evidence --help

也可统一通过 bash demo/run.sh cli <命令> <参数> 调用，如 bash demo/run.sh cli doctor、bash demo/run.sh cli evidence --help。此入口保留调用终端的当前目录，相对路径无需改成 src/ 下的路径；bash demo/run.sh status/stop 仍用于管理 Qt 实时栈。

Codex 对话诊断通过项目技能接入。执行 bash demo/run.sh codex-install 后，在 Codex 中输入 $ebpf-diagnose 帮我检查当前系统最近五分钟的异常，或指定场景、PID、历史数据目录。Codex 根据需求调用统一 CLI，核查目标、规则指标、采集质量和来源哈希，再返回带证据的候选结论。技能源文件及调用脚本位于 src/integrations/codex/ebpf-diagnose，安装仅创建本地 .agents/skills/ 发现链接。模型由当前 Codex 会话提供，项目没有新增常驻 AI 服务或 API 密钥配置。

eBPF 加载需要 root 或等价能力。Qt 托管实时数据写入 tests/results/runtime/；CLI observe 自行创建含 session.json 的会话目录，查询命令 --session 指向该目录，不能直接使用 Qt 的 runtime/live。CLI 观测与 Qt 托管后端应分别运行，避免共用 Agent、socket 和端口。见演示说明、CLI 说明。

测试方法与脚本分工

cd src
source scripts/dev-env.sh
make test JOBS=2

包含目录检查、Go 单测、Analyzer CTest、Qt CTest 和 Python 验证器测试。可分别执行 make test-go、make analyzer-test、make ui-test、make evaluation-test、make cli-test。Go/C++/Qt 单测与所属源码模块共同维护，Python 脚本单测位于根目录 tests/scripts/unit/、tests/evaluation/unit/。

路径	职责
`src/scripts/`	构建、服务管理、授权、安全约束，以及 Qt 功能测试需要的单例 runner
`tests/scripts/validation/`	独立真值采集、证据审计、CLI 与功能验证
`tests/evaluation/`	准确性、性能实验、热点剖析及结果汇总
`tests/scripts/` 的独立入口	证据校验、实时与 Qt 核对、目录检查及交付导出

根目录执行演示验证：

bash demo/run.sh validate --dry-run
# 目标机满足授权、资源隔离及独立测试盘要求后
bash demo/run.sh validate

复现批量评估的命令见测试材料说明，隔离与清理要求见压力测试约束。

已知限制

诊断是基于规则与证据的候选结论，受内核能力、权限、采样窗口、目标选择和事件丢失影响。准确性材料包含多个开发版本与无法判定样本，不能代表当前冻结版本的完整准确率；根因仅有部分独立验证。保留的 Syscall 正式复测中 AUTO 吞吐下降约 56.31%，仍有显著开销。内存结果受透明大页与基线波动影响。OOM_RISK 属于默认关闭的实验功能；OOM 压力实验仅限可丢弃的隔离 VM。Qt 需要图形桌面，无桌面可使用 CLI。见完整限制。

评估总汇、测试总结明确历史报告、当前回归与未验证项。整理不更改原始 JSON/CSV、实验判定或统计口径；不能用筛选通过的展示示例宣称整体准确率。

交付检查与导出

python3 tests/scripts/check_project_layout.py
python3 tests/scripts/verify_evidence.py
python3 tests/scripts/check_project_layout.py --submission
python3 tests/scripts/check_project_layout.py --submission --video-delivery link
python3 tests/scripts/export_delivery.py --output /var/tmp/ebpf-diagnose-final.tar.gz

导出包含源码、说明与保留测试证据，排除本机工具链、生成文件和实时运行目录。--submission 默认按原规范检查 MP4；--video-delivery link 按选择检查视频链接文本存在并含 HTTP(S) 地址。