Loading... # Catpaw 事件监控工具入门指南 # 一、概述 ## 1. 简介 ### A. 是什么 catpaw 是一个轻量级事件监控工具，用于检测系统异常并生成标准化事件。它采用插件化架构，支持多种监控场景，适合与告警系统集成。 ### B. 为什么学 - 轻量级设计，零重依赖，资源占用极低 - 插件化架构，按需启用，灵活性高 - 适合监控系统自监控，避免循环依赖 - 配置简洁，快速实现监控覆盖 ### C. 学完能做什么 - 部署 catpaw 到各类 Linux/Windows 环境 - 配置常用插件进行系统监控 - 集成 Flashduty 或自定义事件接收器 - 开发自定义监控插件 ## 2. 前置知识 ### A. 必备技能 - 基本 Linux 命令操作 - 了解监控和告警的基本概念 ### B. 推荐知识 - Toml 配置文件语法 - 系统监控指标含义（CPU、内存、磁盘等） # 二、环境准备 ## 1. 系统要求 - Linux：主流发行版（Ubuntu、CentOS、Debian 等） - Windows：支持 Windows 服务运行 - 跨平台：支持多架构二进制文件 ## 2. 安装步骤 下载二进制文件： ```bash # 从 GitHub Releases 下载对应平台版本 wget https://github.com/cprobe/catpaw/releases/download/v0.9.0/catpaw-linux-amd64 chmod +x catpaw-linux-amd64 mv catpaw-linux-amd64 /usr/local/bin/catpaw ``` ## 3. 验证安装 ```bash catpaw --version ``` # 三、核心概念 ## 1. 基本术语 - 事件：监控系统产生的告警或状态变化 - 插件：实现特定监控功能的独立模块 - 事件接收器：接收并处理监控事件的系统 ## 2. 工作原理 ```mermaid graph LR A[catpaw<br/>监控引擎] --> B{插件调度器} B --> C[插件1: cert] B --> D[插件2: disk] B --> E[插件3: http] C --> F[事件生成器] D --> F E --> F F --> G[Flashduty<br/>告警路由] F --> H[自定义接收器] ```  # 四、快速上手 ## 1. Hello World 示例 ```bash # 测试模式运行，事件打印到终端 ./catpaw -test ``` ## 2. 核心功能演示 配置 Flashduty 集成： 编辑 conf.d/config.toml，设置 integration_key 启用磁盘监控插件： 编辑 conf.d/p.disk/test.toml，配置监控路径和阈值 ## 3. 正常运行 ```bash ./catpaw ``` # 五、插件详解 ## 1. 系统资源类插件 ### A. cpu 插件 CPU 利用率和负载检查，支持按核心归一化计算。 ### B. mem 插件 内存和交换空间使用检查，支持阈值告警。 ### C. disk 插件 磁盘空间、inode 和可写性检查，支持多路径监控。 ## 2. 网络监控类插件 ### A. http 插件 HTTP 可用性、状态码、响应体和证书过期检查。 ### B. ping 插件 ICMP 可达性、丢包率和延迟检查。 ### C. dns 插件 DNS 解析检查，验证域名解析能力。 ### D. net 插件 TCP/UDP 连接性和响应时间检查。 ## 3. 容器和进程类插件 ### A. docker 插件 Docker 容器监控，检查运行状态、频繁重启、健康检查和资源使用。 ### B. procfd 插件 进程级文件描述符监控，防止打开文件数过多。 ### C. procnum 插件 进程数量检查，支持系统级和特定进程监控。 ### D. systemd 插件 systemd 服务状态检查，确保关键服务正常运行。 ## 4. 日志和文件类插件 ### A. logfile 插件 普通文本日志文件监控，支持 offset 追踪、日志轮转检测和多编码。 ### B. journaltail 插件 通过 journalctl 增量读取日志，支持关键字匹配。 ### C. filecheck 插件 文件存在性、修改时间和校验和检查。 ## 5. 安全和证书类插件 ### A. cert 插件 TLS 证书过期检查，支持远程连接、本地证书文件、STARTTLS 和 SNI。 ### B. secmod 插件 SELinux/AppArmor 安全模块基准检查。 ## 6. 内核和网络底层类插件 ### A. conntrack 插件 Linux conntrack 表使用监控，防止静默丢包。 ### B. neigh 插件 Linux ARP/邻居表使用监控，防止新 IP 通信失败。 ### C. netif 插件 网络接口健康检查，监控链路状态和错误/丢弃变化。 ### D. tcpstate 插件 TCP 连接状态监控，检测 CLOSE_WAIT/TIME_WAIT 积累。 ### E. sockstat 插件 TCP 监听队列溢出检测。 ### F. sysctl 插件 内核参数基准检查，检测重启/升级后的静默重置。 ## 7. 高级功能插件 ### A. exec 插件 运行脚本或命令，从输出生成事件，支持 JSON 和 Nagios 模式。 ### B. scriptfilter 插件 运行脚本并将输出行与过滤规则匹配以触发告警。 ### C. uptime 插件 意外重启检测，当运行时间低于阈值时触发告警，属于自愈事件。 ### D. zombie 插件 僵尸进程检测，统计系统中处于 Z 状态的进程数量。 # 六、配置说明 ## 1. 全局配置 配置文件：conf.d/config.toml 主要配置项： - Flashduty 集成密钥 - 事件接收器 URL - 全局超时设置 - 日志级别 ## 2. 插件配置 配置文件：conf.d/p.<plugin>/*.toml 特点： - 每个插件目录支持多个配置文件 - 加载时自动合并多个配置文件 - 支持 SIGHUP 信号热重载配置 热重载配置： ```bash kill -HUP $(pidof catpaw) ``` ## 3. 配置示例 磁盘监控配置示例： ```toml [targets] path = "/var/log" [thresholds] usage_percent = 80 [alert] enabled = true ``` # 七、部署方式 ## 1. 二进制部署 适合生产环境，直接下载二进制文件运行。 ## 2. systemd 服务 配置 systemd service 文件，实现开机自启和守护运行。 ## 3. Docker 部署 提供 Docker 镜像，支持容器化部署。 # 八、集成 Flashduty ## 1. 创建集成 在 Flashduty 控制台创建"标准告警事件"集成，获取 webhook URL。 ## 2. 配置 catpaw 在 conf.d/config.toml 中设置 flashduty.url 字段。 ## 3. 事件流转 catpaw 生成标准化事件 -> Flashduty 接收 -> 告警路由 -> 通知发送 # 九、常见问题 ## 1. 配置热重载不生效 检查配置文件语法是否正确，使用 SIGHUP 信号重载。 ## 2. 插件未触发事件 检查插件配置是否正确启用，确认阈值设置。 ## 3. 与 Flashduty 集成失败 验证 integration_key 和 URL 配置，检查网络连通性。 # 十、进阶开发 ## 1. 插件开发 catpaw 提供插件开发指南，支持自定义监控插件。 ## 2. 事件数据模型 了解事件结构、标签设计和 AlertKey 规则。 ## 3. 命令行参考 完整查看 CLI 选项和参数说明。 *** ## 参考资料 1. [catpaw GitHub 仓库](https://github.com/cprobe/catpaw) 2. [Flashduty 产品官网](https://flashcat.cloud/product/flashduty/) 3. [catpaw CLI 参考文档](https://github.com/cprobe/catpaw/blob/master/docs/cli.md) 4. [catpaw 部署指南](https://github.com/cprobe/catpaw/blob/master/docs/deployment.md) 最后修改：2026 年 03 月 01 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏