智诊引擎—基于eBPF的系统异常观测与根因定位工具

1. 项目简介

智诊引擎（ZZOS）是一套面向 openKylin 和 Linux 系统的异常观测与根因定位工具。系统利用 eBPF 采集内核调度、系统调用等底层事件，并融合 procfs、vmstat、diskstats 和 dmesg 等系统数据，对 CPU、I/O、内存、锁竞争和系统调用热点进行分析，输出包含异常对象、关键指标、时间窗口、疑似根因、证据链和处置建议的结构化报告。

系统依次完成多源数据采集、节点与进程身份关联、动态基线分析、风险评估、按需深度观测和根因推断，并通过 CLI、后台服务、Web 控制中心和 Android 客户端提供诊断结果。

2. 应用场景

openKylin 服务器、虚拟机和开发节点的性能异常诊断。
CPU 占用、I/O 抖动、内存回收、锁竞争和系统调用热点的定位与复现。
多节点运行状态、诊断报告和告警信息的集中查看。
操作系统实验、课程教学和比赛评测中的 eBPF 观测与验证。

3. 主要功能

五类异常观测：覆盖 CPU、I/O、内存、锁和系统调用五个诊断域。
根因定位与证据链：将异常关联到节点、进程、PID、线程、设备或系统调用，并记录诊断依据。
进程画像与风险预测：保存连续时间窗特征，分析进程行为和短期风险趋势。
动态基线：根据节点及进程历史状态调整判定基准。
按需深度观测：补充调用栈、进程树和系统调用序列等细粒度证据。
受控处置建议：通过规则库、RAG 和安全约束生成可审计的建议。
多端访问：支持 CLI、Headless、Web、节点 Push Agent 和 Android 客户端。

4. 目录结构

路径	内容
`src/`	eBPF 程序、用户态采集器、诊断服务、Web、Android、模型和测试代码
`demo/`	一键部署、自动测试、五类异常复现脚本、运行说明和 Android APK
`docs/`	项目说明书、项目创新说明、成员分工说明和工具使用声明
`tests/`	测试方法、验收记录、实验数据、日志和验证证据
`presentation/`	项目展示 PPT 和演示视频

5. 系统环境与依赖

项目	要求
操作系统	openKylin 2.0 SP2；兼容 Ubuntu 22.04
内核	Linux 6.6 及以上，提供可用的 BTF 信息
架构	当前交付主要在 x86_64 环境验证
硬件	建议 4 核 CPU、8 GiB 内存和 50 GiB 可用存储
Python	Python 3.10 及以上
权限	`root`，或具备 eBPF、perf 和系统指标采集所需能力

原生构建需要 clang、LLVM、gcc、make、libbpf-dev、libelf-dev、zlib1g-dev、bpftool 和 perf。压力复现使用 stress-ng、fio 和 jq。Python 测试依赖见 src/requirements-test.txt；重新训练时序模型需要 PyTorch。

运行前可检查内核 BTF：

test -r /sys/kernel/btf/vmlinux && echo "BTF available"

6. 构建与安装

在交付根目录执行一键部署：

bash demo/deploy_node.sh --help
sudo bash demo/deploy_node.sh

脚本会安装 openKylin 或 Ubuntu 依赖，编译 eBPF 程序与用户态采集器，安装 zzos 命令，并启动 zhizhenos-live.service。系统已经具备依赖时可执行：

sudo bash demo/deploy_node.sh --skip-dependencies

手动构建方式：

cd src
make
sudo python3 -m zhizhenos.cli check
sudo bash scripts/install_zzos_cli.sh

7. 运行方法

7.1 单项诊断

进入 src/ 目录后运行：

sudo python3 -m zhizhenos.cli diag cpu --duration 5

将 cpu 替换为 io、memory、lock 或 syscall，可运行其他诊断域。安装 CLI 后可使用 sudo zzos ops top 查看综合运维视图。

7.2 Web 控制中心

一键部署完成后检查服务：

sudo systemctl status zhizhenos-live.service --no-pager
sudo journalctl -u zhizhenos-live.service -f

访问 http://127.0.0.1:8080/login.html。首次启动生成的账户信息保存在 src/.runtime/bootstrap_credentials.json。

开发模式可在 src/ 中直接启动：

sudo python3 -m zhizhenos.live_server \
  --host 0.0.0.0 --port 8080 --collect --interval 1

7.3 Headless 模式

cd src
sudo python3 -m zhizhenos.cli watch --once --strict --no-llm

持续运行可安装 scripts/install_headless_service.sh。诊断结果写入 src/reports/ 和 src/.runtime/。同一节点部署时，在 zhizhenos-live.service 与 zzos-headless.service 中选择一种周期采集方式。

7.4 多节点上报

在采集节点的 src/ 目录配置控制中心和节点身份：

sudo env \
  ZHIZHENOS_CONTROL_URL=https://your-control-center.example.com \
  ZHIZHENOS_AGENT_TOKEN='<node-token>' \
  ZHIZHENOS_NODE_ID=openkylin-node-01 \
  ZHIZHENOS_NODE_NAME=openKylin-01 \
  bash scripts/install_push_agent_service.sh

节点通过 HTTP/HTTPS 主动上报诊断结果和运行状态。

8. 测试方法

检查 openKylin 和 eBPF 运行环境：

sudo bash src/scripts/check_openkylin_eval_env.sh

创建独立 Python 测试环境并运行自动化测试：

bash demo/test.sh --prepare-env

测试依赖已经安装时直接执行 bash demo/test.sh。该入口会编译检查主要 Python 模块并运行 pytest 测试集。

运行五类异常复现：

sudo bash demo/reproduce.sh

复现脚本依次构造 CPU、I/O、内存、锁竞争和系统调用负载，并生成诊断结果。后台输出可进一步检查：

cd src
sudo python3 -m zhizhenos.cli watch --once --strict --no-llm
python3 scripts/headless_quality_gate.py \
  --latest .runtime/headless/latest.json

测试方法、执行记录和实验结果见 tests/测试与验证说明.md、tests/交付验收.md 和 tests/evidence/。

9. 已知限制

eBPF 采集需要 Linux 内核支持、BTF 信息和相应系统权限，Windows 不能运行内核采集端。
自动依赖安装脚本当前支持 openKylin 和 Ubuntu，其他 Linux 发行版需要手动配置依赖。
当前交付主要完成 x86_64 环境验证，其他处理器架构需要重新编译和测试。
五类异常复现会产生 CPU、磁盘、内存和锁压力，应在独立测试节点或虚拟机中运行。
多节点模式和 Android 客户端需要可访问的控制中心，并正确配置节点标识、账户和认证令牌。
时序模型重新训练需要 PyTorch、连续进程画像数据和与目标环境匹配的阈值校准。
本地建议模型为可选组件；未配置模型服务时，系统使用规则库生成处置建议。

10. 相关材料

docs/项目说明书.pdf：系统设计、技术路线、核心实现和实验结果。
docs/项目创新说明.pdf：主要技术创新、代码位置和验证依据。
demo/运行说明.md：部署、测试和演示入口说明。
tests/证据索引.md：实验数据与验证证据索引。