HstXPGeV0c/jyedxtycgcygydwgj

woodpecker

基于 eBPF 的系统异常观测与智能根因定位工具

woodpecker 以低侵入、低开销的方式持续采集内核与用户态行为数据，通过可扩展插件系统实时检测 CPU 饱和、I/O 抖动、内存压力、锁竞争、系统调用热点等典型异常，并在异常触发时即时调用 LLM 推理引擎完成根因分析，输出结构化诊断报告与操作建议。

特性

AI 驱动的根因分析

异常发生时自动调用 LLM（兼容 DeepSeek / OpenAI API 格式）进行多维度根因推断
支持用户对已发现的 incident 发起交互式对话，逐步深挖根因
内置双模型配置：轻量速决模型（model）+ 深度 RCA 模型（model_deep）
LLM agent 可读取插件携带的专项知识库（Markdown），有效压制幻觉

基于 eBPF 的可扩展插件系统

插件 = eBPF 程序（CO-RE 预编译 .bpf.o）+ 指标声明 + 规则 DSL + 知识库
每个插件安装后即刻生效，daemon 热加载，无需重启
内置插件覆盖 CPU 调度压力、I/O 时延、内存回收、futex 锁竞争、上下文切换风暴等场景
规则引擎支持 rate()、delta()、滑动窗口聚合、多维度关联表达式

统一 HTTP API 架构

daemon 对外暴露一套 JSON over HTTP + SSE 接口（OpenAPI 规范）
CLI、TUI、Web UI 三种客户端均连接同一 API，数据完全一致
Web UI 嵌入 daemon 二进制（无需独立部署），随启随用

架构一览

woodpeckerd (daemon)
  ├── eBPF / procfs 数据采集
  ├── 规则引擎检测 + 告警存储 (SQLite)
  ├── LLM agent (根因分析 / 交互对话)
  ├── 插件热加载管理
  └── HTTP API :8787
        ├── woodpecker (CLI)
        ├── woodpecker_tui (TUI)
        └── 浏览器 Web UI

快速开始

1. 构建

# 需要 Rust 工具链（推荐 1.78+）和 libbpf-dev
cargo build --release

# 产出的二进制：
#   target/release/woodpeckerd   — daemon
#   target/release/woodpecker    — CLI
#   target/release/woodpecker_tui — TUI

2. 准备配置文件

创建 /etc/woodpecker/config.yaml（可从下方示例复制）：

database:
  path: /var/lib/woodpecker/woodpecker.db

socket:
  path: /run/woodpecker/woodpecker.sock

source: ebpf          # ebpf（默认）或 procfs（无 root 时回退）
interval: 5           # 采样间隔（秒）
window: 12            # 滑动窗口帧数（= 最近 60 秒）

detectors:
  - cpu_saturation
  - cpu_hot_process
  - io_latency
  - mem_pressure
  - lock_contention
  - syscall_hotspot

plugins:
  dir: /etc/woodpecker/plugins   # 已安装插件目录

llm:
  provider: openai              # openai 兼容格式（DeepSeek 等）
  base_url: https://api.deepseek.com
  api_key: ${DEEPSEEK_API_KEY}  # 支持 ${ENV_VAR} 占位，不必明文写入配置
  model: deepseek-chat
  model_deep: deepseek-reasoner # 可选，--deep 分析时使用
  knowledge_dir: /etc/woodpecker/knowledge

web:
  bind: 127.0.0.1:8787          # 非 loopback 时必须显式设置 token

初始化目录：

sudo mkdir -p /etc/woodpecker/plugins /var/lib/woodpecker /run/woodpecker
sudo cp -r plugins/* /etc/woodpecker/plugins/    # 安装内置插件

运行说明

Daemon

直接启动：

sudo DEEPSEEK_API_KEY=sk-... ./target/release/woodpeckerd --config /etc/woodpecker/config.yaml

启动后 daemon 输出类似：

[INFO] woodpeckerd starting (pid 12345, log level Info)
[INFO] config loaded: db=/var/lib/woodpecker/woodpecker.db bind=127.0.0.1:8787 interval=5s window=12
[INFO] auth token written to /tmp/woodpecker_token
[INFO] HTTP API listening on 127.0.0.1:8787

认证 token 自动生成并写入 /tmp/woodpecker_token（0600 权限），CLI / TUI 自动读取，无需手动传入。

注册为 systemd 服务：

# 将二进制安装到 PATH
sudo cp target/release/woodpeckerd /usr/local/bin/

# 创建 systemd unit
sudo tee /etc/systemd/system/woodpecker.service > /dev/null <<'EOF'
[Unit]
Description=woodpecker system anomaly observation daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/woodpeckerd --config /etc/woodpecker/config.yaml
Environment="DEEPSEEK_API_KEY=sk-..."
Restart=on-failure
RestartSec=5
# eBPF 需要以下能力；如不希望完整 root 可用 AmbientCapabilities
User=root

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now woodpecker
sudo systemctl status woodpecker

CLI (`woodpecker`)

# 安装（可选）
sudo cp target/release/woodpecker /usr/local/bin/

# 查看 daemon 状态
woodpecker status

# Incident 管理
woodpecker incidents list                     # 最新 50 条
woodpecker incidents list --active            # 仅活跃告警
woodpecker incidents list --limit 100
woodpecker incidents show <ID>                # 详情（Markdown）
woodpecker incidents show <ID> --format json  # json|yaml|md
woodpecker incidents export json              # 全量导出
woodpecker incidents export md --id <ID>      # 单条导出

# LLM 根因分析
woodpecker analyze <ID>          # 标准分析
woodpecker analyze <ID> --deep   # 使用深度 RCA 模型

# 监控会话（针对特定进程的专项观测）
woodpecker session start <label> --target-match llama
woodpecker session start <label> --target-pid 1234 --duration-secs 120
woodpecker session list
woodpecker session stop <ID>
woodpecker session show <ID>

# 插件管理
woodpecker plugin list            # 已加载的插件
woodpecker plugin install <路径>  # 安装新插件
woodpecker plugin reload <名称>   # 热重载
woodpecker plugin remove <名称>

# 单次诊断（无需启动 daemon）
woodpecker oneshot --source procfs
woodpecker oneshot --source ebpf -f json

TUI (`woodpecker_tui`)

# 安装（可选）
sudo cp target/release/woodpecker_tui /usr/local/bin/

# 启动（自动连接 127.0.0.1:8787，读取 /tmp/woodpecker_token）
woodpecker_tui

# 连接自定义地址
woodpecker_tui --config /etc/woodpecker/config.yaml

TUI 键盘操作：

按键	功能
`h/j/k/l` 或方向键	导航
`Tab`	切换面板（Dashboard / Incidents / Sessions / Help）
`Enter`	展开当前 incident 详情
`a`	触发 LLM 分析当前 incident
`r`	刷新
`q` / `Ctrl-C`	退出

Web UI

Web UI 已内嵌于 daemon 二进制，daemon 启动后直接用浏览器访问：

http://127.0.0.1:8787

如需从其他机器访问，修改配置中的 web.bind：

web:
  bind: 0.0.0.0:8787
  token: your-static-token   # 非 loopback 时必须显式设置

然后访问 http://<host-ip>:8787，在登录页输入 token。

Web UI 功能：

实时系统状态仪表盘（CPU、内存、网络 + 每个插件的实时指标面板，数据来自 /api/metrics/live）
Incident 列表 + 详情 + LLM 分析报告（打开详情自动触发分析）
交互式 LLM 对话（针对已有 incident 深入追问，SSE 流式）
插件管理界面：启用/禁用（热切换，不卸载）、查看 eBPF 程序 / 规则 DSL / 知识库
LLM 插件生成向导：用自然语言描述观测目标，LLM 自动生成完整插件包（eBPF 源码 + manifest + 规则 + 知识库），daemon 即时编译并热加载

Web UI 构建

Web UI 是 React (Vite) 应用，源码在 ../comp_frondend/，构建产物嵌入 daemon 二进制：

cd ../comp_frondend
bash build-and-embed.sh   # npm install + vite build → woodpecker_web/dist/ + 重新编译 daemon

Vite 直接输出到 crates/woodpecker_web/dist/（daemon 通过 include_dir! 嵌入），因此改动前端后必须同时重新编译 daemon。开发时 npm run dev 通过 Vite 代理连接本地 daemon（用 ?token=<tok> 传入认证）。

插件开发

一个最小插件的目录结构：

my_plugin/
├── manifest.yaml      # 插件元数据、eBPF attach、指标声明、规则引用
├── my_plugin.bpf.o    # CO-RE 预编译的 eBPF 目标文件
├── rules/
│   └── my_plugin.yaml # 规则 DSL（触发条件 + 告警级别）
└── knowledge/
    └── my_plugin.md   # LLM 可读的诊断知识库

安装后通过 CLI 热加载，无需重启 daemon：

woodpecker plugin install ./my_plugin/

详细开发指南见 skills/ 目录下的插件模板。

异常复现脚本

# CPU 压力
bash scripts/verify_cpu.sh

# I/O 抖动
bash scripts/verify_io.sh

# 内存抖动
bash scripts/verify_mem.sh

# 锁竞争
bash scripts/verify_lock.sh

# 系统调用热点
bash scripts/verify_syscall.sh

要求

Linux kernel ≥ 6.1（CO-RE eBPF）；推荐 6.6（openKylin 默认内核）
CAP_BPF、CAP_PERFMON、CAP_SYS_ADMIN（或直接以 root 运行）
架构：x86_64 / ARM64

原始赛题说明见 docs/README.official.md。