English | 中文

🐾 catpaw

catpaw 是一个轻量的监控 Agent，具备 AI 智能诊断能力。 它通过插件化检查探测异常、产出标准事件，并在告警触发时自动调用 AI 进行根因分析——内置 70+ 诊断工具，覆盖系统、网络、存储、安全等各个维度。

事件可推送到任意告警平台（Flashduty、PagerDuty 或任何 HTTP 端点），也可直接输出到控制台快速验证。

✨ 核心特点

• 🪶 轻量无重依赖 — 单二进制，部署简单
• 🔌 插件化监控 — 25+ 检查插件，按需启用
• 🤖 AI 自动诊断 — 告警触发后自动分析根因
• 💬 AI 交互排障 — 命令行对话式排障，AI + 工具联动
• 🩺 主动健康巡检 — 按需对目标执行 AI 驱动的深度检查
• 🛠️ 70+ 诊断工具 — 系统、网络、存储、安全、进程、内核全覆盖
• 📡 灵活通知 — 控制台、通用 WebAPI、Flashduty、PagerDuty，可同时开启多个
• 🔄 适合自监控 — 监控系统的监控系统，避免循环依赖

🏗️ 架构概览

┌─────────────────────────────────────────────────────────────────┐
│                        catpaw agent                             │
│                                                                 │
│  ┌─────────────┐   告警    ┌──────────────┐    AI + 工具       │
│  │  25+ 检查   │ ────────── │  AI 诊断    │ ──────────────┐   │
│  │    插件     │   触发     │    引擎     │               │   │
│  └──────┬──────┘            └──────────────┘               │   │
│         │                                                  ▼   │
│         │ 事件      ┌──────────────┐         ┌───────────────┐ │
│         └────────── │   通知渠道   │         │  70+ 诊断    │ │
│                     │  （多选）    │         │     工具     │ │
│                     └──────────────┘         └───────────────┘ │
│                                                                 │
│  ┌─────────────┐                                                │
│  │  AI Chat    │ ───── 交互式排障                               │
│  │  (命令行)   │                                                │
│  └─────────────┘                                                │
└─────────────────────────────────────────────────────────────────┘

🔍 检查插件

🧠 AI 诊断工具（70+）

AI 诊断被触发时（告警、巡检或 Chat），AI Agent 可调用以下工具深入排查：

⚙️ 系统与进程：CPU Top、内存分布、OOM 历史、cgroup 限制/用量、进程线程（含 wchan）、打开文件列表、环境变量、PSI 压力指标

🌐 网络：ping、traceroute、DNS 解析、ARP 邻居表、TCP 连接状态、Socket 详情（RTT/cwnd）、重传率、连接延迟分布、Listen 队列溢出、TCP 内核调优检查、softnet 统计、路由表、IP 地址、网卡流量、防火墙规则

💾 存储：磁盘 I/O 延迟、块设备拓扑树、LVM 状态、挂载信息

🔐 内核与安全：dmesg 内核日志、中断分布、conntrack 统计、NUMA 内存分布、热区温度、sysctl 快照、SELinux/AppArmor 状态、coredump 列表

📜 日志：日志尾部读取、日志 grep（模式匹配）、journald 查询

🐳 服务：systemd 服务状态、失败服务列表、定时器列表、Docker ps/inspect

🔌 远程插件（如 Redis、Redis Sentinel）会注册专用诊断工具，用于对目标实例进行深入检查。

Redis 插件的检查项、集群语义和诊断工具见 plugins/redis/README.md。 Redis Sentinel 插件的检查项、诊断工具和配置语义见 plugins/redis_sentinel/README.md。

🖥️ 命令行

catpaw run [flags]                      # 启动监控 Agent
catpaw chat [-v]                        # AI 交互式排障
catpaw inspect <plugin> [target]        # AI 主动健康巡检
catpaw diagnose list|show <id>          # 查看历史诊断记录
catpaw selftest [filter] [-q]           # 诊断工具自检

🚀 快速开始

📦 安装

从 GitHub Releases 下载对应平台的二进制。

基础监控

1. 在 conf.d/p.<plugin>/ 下启用需要的插件配置
2. 启动：

./catpaw run

默认配置已开启 [notify.console]，事件会以带颜色的格式输出到终端——无需任何外部服务即可快速验证。

📡 事件通知

catpaw 支持多种通知渠道，在 conf.d/config.toml 中配置，可同时启用多个：

控制台（默认开启，快速验证）：

[notify.console]
enabled = true

通用 WebAPI（推送原始 Event JSON 到任意 HTTP 端点）：

[notify.webapi]
url = "https://your-service.example.com/api/v1/events"
# method = "POST"
# timeout = "10s"
[notify.webapi.headers]
Authorization = "Bearer ${WEBAPI_TOKEN}"

Flashduty：

[notify.flashduty]
integration_key = "your-integration-key"

PagerDuty：

[notify.pagerduty]
routing_key = "your-routing-key"

🤖 AI 智能诊断（可选）

在 conf.d/config.toml 中添加：

[ai]
enabled = true
model_priority = ["default"]

[ai.models.default]
base_url = "https://api.openai.com/v1"
api_key = "${OPENAI_API_KEY}"
model = "gpt-4o"

配置后，告警触发时 AI 会自动调用内置诊断工具分析根因。

💬 交互式 Chat

./catpaw chat

直接提问，如"CPU 为什么高？"、"检查磁盘 I/O"等，AI 会使用诊断工具和 Shell 命令（需用户确认）进行排查。

⚙️ 配置说明

• 全局配置：conf.d/config.toml
• 本地覆盖：conf.d/config.local.toml（最后加载，已加入 git ignore，适合开发者本地调试）
• 插件配置：conf.d/p.<plugin>/*.toml（每个目录可放多个 .toml 文件，合并加载）
• 顶层加载顺序：config.toml -> conf.d/ 中其他文件 -> config.local.toml
• 支持 SIGHUP 热加载插件配置：

kill -HUP $(pidof catpaw)

📚 详细文档

💬 交流

可加微信 picobyte 进群交流，备注 catpaw。