API

相关源文件

• package-lock.json
• package.json
• server/auth.js
• server/database.js
• server/image-data-uri.js
• server/jobs.js
• server/jobs/clear-old-data.js
• server/model/monitor.js
• server/notification-providers/matrix.js
• server/prometheus.js
• server/rate-limiter.js
• server/server.js
• server/socket-handlers/api-key-socket-handler.js
• server/uptime-kuma-server.js
• server/util-server.js
• src/pages/EditMonitor.vue

此页面记录了 Uptime Kuma 的 API 功能，包括身份验证方法、可用端点和使用模式。Uptime Kuma API 提供对监控数据、指标和系统功能的编程访问。

API 架构概述

Uptime Kuma 提供了两种主要方法与系统进行编程交互

1. REST API - 用于特定操作的 HTTP 端点，通过基本身份验证或 API 密钥进行保护
2. Socket.IO 接口 - 基于 WebSocket 的实时通信，这是前端使用的主要方法

来源

• server/auth.js134-179
• server/server.js295-296
• server/server.js326-473
• server/socket-handlers/api-key-socket-handler.js1-155

身份验证

Uptime Kuma 支持多种身份验证方法

基本身份验证

对于 REST API 端点，您可以使用基本身份验证，并提供用户名和密码

Authorization: Basic base64(username:password)

API 密钥身份验证

API 密钥提供了一种更安全的方式来访问 REST API，而无需使用用户名和密码。API 密钥可以通过 UI 或以编程方式创建、管理和控制。

API 密钥格式

API 密钥遵循此格式

uk{id}_{key}

其中

• uk: 固定前缀
• {id}: 密钥的数据库 ID
• _{key}: 下划线后跟随机密钥值

使用 API 密钥

API 密钥与基本身份验证一起使用，其中 API 密钥将放在密码字段中

Authorization: Basic base64(any_username:apikey)

使用 API 密钥时，用户名部分将被忽略。

管理 API 密钥

可以通过 Socket.IO 接口创建、禁用和删除 API 密钥

来源

• server/auth.js11-37
• server/auth.js44-66
• server/auth.js158-179
• server/socket-handlers/api-key-socket-handler.js16-154

速率限制

Uptime Kuma 实现了速率限制以防止滥用

• REST API：每分钟 60 个请求
• 登录尝试：每分钟 20 个请求

如果您超出这些限制，您将收到错误消息：“过于频繁，请稍后重试。”

来源

• server/rate-limiter.js50-69
• server/auth.js84-94

REST API 端点

Prometheus 指标端点

GET /metrics

此端点返回与 Prometheus 兼容的监控指标。它需要身份验证（基本身份验证或 API 密钥）。

示例指标包括

• monitor_cert_days_remaining: SSL 证书过期剩余天数
• monitor_cert_is_valid: SSL 证书是否有效（1=是，0=否）
• monitor_response_time: 响应时间（毫秒）
• monitor_status: 监控状态（1=UP，0=DOWN，2=PENDING，3=MAINTENANCE）

来源

• server/server.js295-296
• server/prometheus.js12-33

状态页信息流

Uptime Kuma 提供状态页的 RSS/ATOM 信息流，可以以编程方式访问。

来源

• server/server.js313-314

Socket.IO 接口

Socket.IO 接口是与 Uptime Kuma 进行编程交互的主要方法。Web UI 使用此接口执行所有操作。

Socket.IO 身份验证

Socket.IO 连接使用 JWT 令牌进行身份验证

1. 连接到 Socket.IO 端点
2. 使用以下任一方式进行身份验证
   • login 事件（使用用户名和密码）
   • loginByToken 事件（使用之前颁发的 JWT 令牌）
3. 成功身份验证后，您将收到一个 JWT 令牌，可用于未来的会话

身份验证流程示例

常用的 Socket.IO 事件

Socket.IO 事件按功能进行组织

监控事件

• getMonitorList - 获取监控列表
• addMonitor - 创建新监控
• editMonitor - 更新现有监控
• deleteMonitor - 删除监控

状态页事件

• getStatusPageList - 获取状态页列表
• addStatusPage - 创建新状态页
• editStatusPage - 更新现有状态页
• deleteStatusPage - 删除状态页

API 密钥管理事件

• addAPIKey - 创建新 API 密钥
• getAPIKeyList - 获取所有 API 密钥
• deleteAPIKey - 删除 API 密钥
• disableAPIKey - 禁用 API 密钥
• enableAPIKey - 启用已禁用的 API 密钥

来源

• server/server.js326-473
• server/socket-handlers/api-key-socket-handler.js16-154

API 数据流

下图说明了数据如何在 Uptime Kuma API 系统中流动

来源

• server/server.js295-296
• server/server.js326-473
• server/auth.js134-179
• server/rate-limiter.js50-69
• server/prometheus.js35-119

API 用法示例

检索 Prometheus 指标

使用 API 密钥身份验证

使用基本身份验证

以编程方式与 Socket.IO 交互

最佳实践

1. API 密钥安全:

   • 安全存储 API 密钥
   • 设置适当的过期日期
   • 为每次集成使用不同的 API 密钥
   • 定期轮换密钥

2. 速率限制:

   • 实现指数退避重试逻辑
   • 在适当的情况下缓存响应以减少 API 调用

3. 错误处理:

   • 优雅地处理身份验证失败
   • 实现适当的速率限制错误处理

来源

• server/auth.js44-66
• server/rate-limiter.js24-38

实现细节

API 身份验证和速率限制功能实现在以下文件中

• server/auth.js - 包含基本身份验证和 API 密钥的身份验证逻辑
• server/socket-handlers/api-key-socket-handler.js - 处理 API 密钥管理的 Socket.IO 事件
• server/rate-limiter.js - 为 API 请求实现速率限制
• server/prometheus.js - 定义了 /metrics 端点公开的 Prometheus 指标

Socket.IO 服务器在 server/uptime-kuma-server.js 中初始化，事件处理程序在 server/socket-handlers/ 目录的各种文件中定义。

来源

• server/auth.js1-180
• server/socket-handlers/api-key-socket-handler.js1-155
• server/rate-limiter.js1-76
• server/prometheus.js1-124
• server/uptime-kuma-server.js1-349