Kuvasz 监控服务 API 接口详解

项目概述

Kuvasz（发音为"koovas"）是一款开源的在线状态和SSL证书监控服务，提供全面的API接口用于管理监控任务、获取监控数据以及配置系统设置。本文将详细介绍Kuvasz的API功能和使用方法。

API 基础信息

Kuvasz API遵循OpenAPI 3.0.1规范，所有接口都需要API密钥进行认证。API主要分为三大类操作：

1. 管理操作（Management operations）
2. 监控操作（Monitor operations）
3. 设置操作（Settings operations）

监控操作 API

获取监控列表

端点：GET /api/v1/monitors

此接口返回所有监控任务的详细信息，支持以下查询参数进行筛选：

• enabled：布尔值，筛选启用/禁用的监控
• uptimeStatus：数组，按在线状态筛选
• sslStatus：数组，按SSL状态筛选
• sslCheckEnabled：布尔值，筛选启用/禁用SSL检查的监控

响应：返回MonitorDetailsDto数组，包含每个监控任务的完整信息。

创建监控任务

端点：POST /api/v1/monitors

创建新的监控任务需要提供以下必填字段：

• name：监控名称（最小长度1）
• url：监控URL（需符合URL格式）
• uptimeCheckInterval：检查间隔（秒，最小5）

可选字段包括：

• enabled：是否启用（默认true）
• sslCheckEnabled：是否启用SSL检查（默认false）
• requestMethod：HTTP方法（默认GET）
• 以及其他监控配置选项

注意：如果系统配置为从YAML文件加载监控任务，此接口将返回405错误。

导出监控配置

端点：GET /api/v1/monitors/export/yaml

以YAML格式导出所有监控任务的配置，便于备份或迁移。

获取监控统计

端点：GET /api/v1/monitors/stats

获取所有监控任务的累计统计数据，支持period参数指定统计周期（默认为7天）。

单个监控操作

端点：/api/v1/monitors/{monitorId}

支持以下操作：

• GET：获取指定监控的详细信息
• DELETE：删除指定监控
• PATCH：更新监控配置（仅更新请求中包含的字段）

监控事件查询

Kuvasz提供以下事件查询接口：

• GET /api/v1/monitors/{monitorId}/ssl-events：获取SSL相关事件
• GET /api/v1/monitors/{monitorId}/uptime-events：获取在线状态事件
• GET /api/v1/monitors/{monitorId}/stats：获取单个监控的统计数据

系统管理 API

健康检查

端点：GET /api/v1/health

返回服务健康状态：

• 200：服务正常运行
• 503：服务不可用

系统设置

端点：GET /api/v1/settings

获取当前系统设置信息。

数据模型说明

MonitorDetailsDto

监控任务详细信息，包含：

• 基本信息（ID、名称、URL等）
• 状态信息（在线状态、SSL状态）
• 时间信息（创建时间、最后检查时间等）
• 配置信息（检查间隔、HTTP方法等）
• 集成信息（通知集成配置）

MonitorCreateDto/MonitorUpdateDto

用于创建/更新监控任务的数据传输对象，包含可配置的所有监控参数。

状态枚举

• UptimeStatus：在线状态（UP/DOWN/UNKNOWN）
• SslStatus：SSL状态（VALID/INVALID/EXPIRING/EXPIRED）
• HttpMethod：HTTP方法（GET/HEAD）

最佳实践

1. 监控创建：创建监控时建议先设置较长的检查间隔（如60秒），确认无误后再调整为实际需要的频率。

2. 错误处理：所有API都可能返回400/404/405等错误，客户端应妥善处理这些响应。

3. 批量操作：获取监控列表时可以使用筛选参数减少数据传输量。

4. 监控更新：使用PATCH方法更新监控时，只需发送需要修改的字段，未包含的字段将保持不变。

总结

Kuvasz提供了一套完整的API接口，使开发者能够轻松集成监控功能到自己的系统中。通过合理使用这些API，可以实现监控任务的自动化管理、实时状态查询以及历史数据分析等功能。