Skip to content
TDnorthgarden
PodFlow
Public

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

PodFlow - 容器智能故障分析插件

Rust License: MIT Build Status

PodFlow 是一个面向容器环境的智能故障诊断插件，基于 eBPF/bpftrace 采集内核级观测数据，通过规则引擎和 AI 增强生成诊断结论，并支持告警推送。

✨ 核心特性

🔍 多维度采集

采集 7 类容器性能证据：

  • Block I/O：块设备 I/O 延迟
  • Network：网络连接延迟
  • Syscall Latency：系统调用延迟
  • OOM Events：内存溢出事件
  • FS Stall：文件系统卡顿
  • NRI Events：容器生命周期事件
  • Cgroup Metrics：Cgroup 资源指标

🧠 智能诊断

支持 5 种诊断规则：

  • Threshold Rule：阈值规则
  • Trend Rule：趋势规则
  • Correlation Rule：关联规则
  • Statistical Rule：统计规则
  • Custom Rule：自定义规则

🤖 AI 增强

集成真实 AI 服务：

  • OpenAI：GPT-4、GPT-3.5-turbo
  • Anthropic：Claude 3 系列
  • 缓存机制：避免重复调用
  • 重试机制：指数退避算法
  • 降级策略：AI 不可用时保持核心链路

📢 多渠道告警

支持多种告警推送方式：

  • Webhook：HTTP 回调
  • Kafka：消息队列
  • Email：邮件通知
  • 钉钉：企业通讯
  • 企业微信：企业通讯

🔐 安全隔离

  • UID 验证：基于 UID 的权限验证
  • gRPC 通道：安全的通道隔离
  • TLS 支持：加密通信

⚡ 高性能

  • 异步处理：Tokio 异步运行时
  • 缓存优化：智能缓存机制
  • 批量处理：批量事件处理
  • 并发支持：支持大规模集群

📊 项目质量

指标 值
代码行数 28,700 行
源文件数 62 个
测试数 139 个
测试通过率 100%
编译警告 0 个
质量评分 100/100

🚀 快速开始

前置要求

  • 操作系统: Linux 内核 5.8+（支持 eBPF）
  • Rust 工具链: 1.70+（编译时需要）
  • bpftrace: v0.19+
  • 权限: root 或 CAP_BPF, CAP_SYS_ADMIN, CAP_SYS_PTRACE

安装依赖

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y bpftrace curl build-essential pkg-config libssl-dev

# CentOS/RHEL
sudo yum install -y bpftrace curl gcc make openssl-devel

# openEuler
sudo dnf install -y bpftrace curl gcc make openssl-devel

从源码编译

# 克隆项目
git clone https://github.com/TDnorthgarden/PodFlow.git
cd PodFlow

# 编译项目
cargo build --release

# 安装 bpftrace 脚本
sudo mkdir -p /usr/share/podflow/bpftrace
sudo cp -r scripts/bpftrace/* /usr/share/podflow/bpftrace/
sudo chmod -R 755 /usr/share/podflow/bpftrace

快速体验

# 启动服务（需要 root 权限）
sudo ./target/release/podflow

# 在另一个终端使用 CLI
./target/release/podflow-cli -s http://localhost:8080 trigger --cgroup-id <cgroup-id> --evidence-types network,block_io

🏗️ 架构设计

系统架构

┌─────────────────────────────────────────────────────────────┐
│                    Kubernetes / Runtime                     │
│  ┌─────────────┐                                            │
│  │    NRI      │─────Pod Metadata─────┐                    │
│  └─────────────┘                      │                    │
└───────────────────────────────────────┼────────────────────┘
                                        │
┌───────────────────────────────────────▼────────────────────┐
│                 PodFlow (Core Plugin)                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Trigger   │  │  Collector  │  │  Evidence   │        │
│  │   Service   │  │ (bpftrace)  │  │ Aggregator  │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│         │                │                 │               │
│         └────────────────┼─────────────────┘               │
│                          │                                 │
│                  ┌───────▼───────┐                        │
│                  │   Diagnosis   │                        │
│                  │    Engine     │                        │
│                  └───────┬───────┘                        │
│                          │                                 │
│                  ┌───────▼───────┐  ┌─────────────┐      │
│                  │    Result     │  │     AI      │      │
│                  │   Publisher   │◄─┤   Adapter   │      │
│                  └───────┬───────┘  └─────────────┘      │
│                          │                                 │
└──────────────────────────┼─────────────────────────────────┘
                           │
                  ┌────────▼────────┐
                  │  Output Targets │
                  │ ┌─────────────┐ │
                  │ │ Local Logs  │ │
                  │ │  (JSON)     │ │
                  │ └─────────────┘ │
                  │ ┌─────────────┐ │
                  │ │ Alert       │ │
                  │ │ Platform    │ │
                  │ └─────────────┘ │
                  └─────────────────┘

权限分离架构

┌─────────────────┐    gRPC/Unix Socket    ┌─────────────────┐
│  Main Service   │◄──────────────────────►│  Collector      │
│  (non-privileged)│                        │  Daemon         │
│                 │                        │  (privileged)   │
│  - HTTP API     │                        │  - bpftrace     │
│  - CLI          │                        │  - eBPF         │
│  - Rule Engine  │                        │  - kernel       │
│  - AI Adapter   │                        │  monitoring     │
└─────────────────┘                        └─────────────────┘

📁 项目结构

podflow/
├── src/
│   ├── main.rs              # 主服务入口
│   ├── lib.rs               # 库定义
│   ├── bin/
│   │   ├── podflow_observer_cli.rs      # CLI 工具
│   │   └── collector_daemon.rs       # 特权采集守护进程
│   ├── api/                 # HTTP API 实现
│   ├── collector/           # 数据采集模块
│   ├── diagnosis/           # 诊断引擎
│   ├── ai/                  # AI 增强模块
│   ├── publisher/           # 结果发布器
│   └── types/               # 类型定义
├── scripts/
│   └── bpftrace/            # bpftrace 采集脚本
│       ├── network/         # 网络诊断脚本
│       ├── block_io/        # 块设备 I/O 脚本
│       ├── syscall_latency/ # 系统调用延迟脚本
│       └── templates/       # 脚本模板
├── systemd/                 # systemd 服务文件
├── docs/                    # 项目文档
├── examples/                # 使用示例
├── cases/                   # 故障案例库
├── proto/                   # gRPC 协议定义
├── plans/                   # 项目规划文档
├── Cargo.toml              # Rust 项目配置
├── config.yaml             # 主配置文件
└── README.md               # 本文档

🔧 配置说明

主配置文件

创建 /etc/podflow/config.yaml：

# 服务器配置
server:
  bind_address: "0.0.0.0"
  port: 8080

# 日志级别
log_level: "info"

# AI 配置（可选）
ai:
  enabled: true
  provider: "openai"  # openai, claude, local
  model: "gpt-4"
  api_key: "your-api-key"
  timeout_secs: 30

# 告警配置（可选）
alert:
  enabled: true
  webhook_url: "https://your-alert-platform.com/webhook"
  throttle_secs: 60

# 条件触发器
condition_triggers:
  - name: "high_io_latency"
    condition: "block_io.io_latency_p99_ms > 100"
    evidence_types: ["block_io", "syscall_latency"]
    window_seconds: 30
    cooldown_seconds: 300
    enabled: true

# 采集器配置
collector:
  daemon_socket: "/run/podflow/collector.sock"
  fallback_mode: "dev_sudo"
  max_collection_time_secs: 60

📖 使用指南

用户指南

技术文档

HTTP API

触发诊断

curl -X POST http://localhost:8080/v1/diagnostics:trigger \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "pod": {
        "namespace": "default",
        "name": "nginx"
      }
    },
    "evidence_types": ["network", "block_io"],
    "time_window": {
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-01-01T00:01:00Z"
    }
  }'

查询诊断结果

curl "http://localhost:8080/v1/diagnostics/<task-id>"

CLI 工具

# 查看帮助
./target/release/podflow-cli --help

# 触发诊断
./target/release/podflow-cli -s http://localhost:8080 trigger \
  --cgroup-id <cgroup-id> \
  --evidence-types network,block_io

# 查询 AI 增强结果（使用诊断 ID）
./target/release/podflow-cli -s http://localhost:8080 query --diagnosis-id <diagnosis-id>

# 查看服务状态
./target/release/podflow-cli -s http://localhost:8080 status

🐳 容器化部署（计划中）

⚠️ 注意: Docker 支持正在开发中，以下 Dockerfile 为参考示例。

构建镜像

创建 Dockerfile：

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y bpftrace && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/podflow /usr/local/bin/
COPY --from=builder /app/target/release/podflow-collector /usr/local/bin/
COPY --from=builder /app/scripts/bpftrace /usr/share/podflow/bpftrace
COPY config.yaml /etc/podflow/config.yaml
EXPOSE 8080
CMD ["podflow"]

构建并运行：

docker build -t podflow:latest .
docker run -d --name podflow --privileged --pid=host -p 8080:8080 podflow:latest

运行容器

docker run -d \
  --name podflow \
  --privileged \
  --pid=host \
  -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -v /run/podflow:/run/podflow \
  -v /etc/podflow:/etc/podflow:ro \
  -p 8080:8080 \
  podflow:latest

🏭 生产环境部署

Systemd 服务部署

# 创建系统用户和组
sudo groupadd podflow
sudo useradd -r -g podflow -s /bin/false podflow

# 创建目录
sudo mkdir -p /etc/podflow /var/log/podflow /run/podflow /usr/share/podflow/bpftrace

# 复制文件
sudo cp systemd/*.service /etc/systemd/system/
sudo cp config.yaml /etc/podflow/
sudo cp -r scripts/bpftrace/* /usr/share/podflow/bpftrace/

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable podflow-collector podflow
sudo systemctl start podflow-collector podflow

📊 支持的证据类型

证据类型 采集指标 输出字段
network TCP 连接延迟、丢包率、连通率 latency_p99_ms, loss_rate, connect_rate
block_io I/O 延迟、吞吐量、队列深度 io_latency_p99_ms, throughput_mbps, queue_depth
syscall_latency 系统调用延迟统计 top_syscalls, p99_latency_ms, call_count
fs_stall 文件系统卡顿分析 stall_duration_ms, operation_type, file_path
cgroup_contention cgroup 资源争抢 cpu_throttle_rate, memory_usage_percent, io_wait_time
oom OOM 事件检测 oom_time, victim_pid, memory_usage_before

⚠️ 开发阶段声明
本项目处于积极开发阶段（v0.1.0），部分功能尚未达到生产就绪状态。
预计生产就绪时间：3-4 周

🤖 AI 增强功能

支持的 AI 提供商

# OpenAI
ai:
  enabled: true
  provider: "openai"
  model: "gpt-4"
  api_key: "sk-..."

# Claude
ai:
  enabled: true
  provider: "claude"
  model: "claude-3-opus-20240229"
  api_key: "sk-ant-..."

# 本地模型（如 vLLM）
ai:
  enabled: true
  provider: "local"
  model: "qwen/qwen3-coder-next"
  api_base: "http://localhost:1234/v1"

AI 输出示例

{
  "ai_enhancement": {
    "status": "completed",
    "summary": "检测到网络延迟异常升高，可能与后端服务负载过高有关",
    "root_cause_analysis": "1. 网络延迟 P99 从 50ms 升高到 200ms\n2. 同时观察到 CPU 使用率上升 30%\n3. 后端服务响应时间同步增加",
    "actionable_steps": [
      "检查后端服务监控指标",
      "验证网络带宽使用情况",
      "考虑增加服务实例或优化查询"
    ],
    "confidence": 0.85
  }
}

🔍 故障案例库

项目内置 openEuler 社区常见故障模式：

# 查看所有案例（开发中）
# ./target/release/podflow-cli case list

# 匹配当前状态（开发中）
# ./target/release/podflow-cli case match --target pod:nginx

内置案例包括：

  • cpu_throttle: CPU Throttle 导致服务延迟升高
  • memory_pressure: 内存压力触发 OOM Kill
  • network_latency_spike: 网络延迟 P99 异常升高
  • disk_io_latency: 磁盘 IO 延迟导致应用卡顿

📈 监控与运维

健康检查

# 基础健康检查
curl http://localhost:8080/health

# 详细健康状态
curl http://localhost:8080/health/ready

# 统计信息
curl http://localhost:8080/health/stats

日志查看

# 查看服务日志
sudo journalctl -u podflow -f

# 查看采集守护进程日志
sudo journalctl -u podflow-collector -f

# 查看结构化诊断日志
tail -f /var/log/podflow/diagnostics.log

🐛 故障排除

常见问题

  1. 权限不足

    # 检查 bpftrace 权限
sudo bpftrace -l 'tracepoint:syscalls:sys_enter_*' | head -5

# 检查 capabilities
sudo getcap /usr/local/bin/podflow-collector

  2. bpftrace 脚本加载失败

    # 验证脚本语法
sudo bpftrace -d /usr/share/podflow/bpftrace/network/tcp_connect.bt

# 检查内核版本
uname -r

  3. 服务无法启动

    # 检查端口占用
sudo lsof -i :8080

# 查看服务状态
sudo systemctl status podflow
sudo journalctl -u podflow -n 50

调试模式

# 启用调试日志
export RUST_LOG=debug
./target/release/podflow

# 或修改配置文件
log_level: "debug"

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

  1. Fork 项目
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 打开 Pull Request

开发环境设置

# 安装开发依赖
cargo install cargo-watch

# 运行测试
cargo test

# 开发模式运行
cargo watch -x run

# 代码格式化
cargo fmt

# 代码检查
cargo clippy

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 联系方式

🙏 致谢

感谢以下开源项目：

PodFlow - 让容器故障诊断更智能、更高效！ 🚀

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages