实用工具和辅助函数

相关源文件

• db/knex_migrations/2024-04-26-0000-snmp-monitor.js
• server/model/group.js
• server/model/heartbeat.js
• server/monitor-types/snmp.js
• src/components/CountUp.vue
• src/components/Datetime.vue
• src/components/Status.vue
• src/components/Uptime.vue
• src/util-frontend.js
• src/util.js
• src/util.ts

本文档提供了在使用 Uptime Kuma 的开发人员可用的实用函数和助手方法的全面概述。这些实用工具旨在简化常用操作、确保代码库的一致性，并将复杂功能抽象为可重用组件。

这些实用工具根据其目的和功能分为不同的类别。其中大多数实用工具由前端和后端共享，一些特定实用工具专为其中一侧设计。

目录

• 核心工具
• 日志系统
• 时间和日期实用工具
• URL 和路径实用工具
• 随机生成和加密
• JSON 查询实用工具
• 仅限前端的实用工具

核心工具

Uptime Kuma 定义了几个核心实用工具，这些工具在整个应用程序中使用，以处理常见任务并保持一致性。

状态常量

系统定义了一组数值常量，用于表示监视器的状态

常量	值	描述
UP	1	Monitor is up and functioning（监视器正常运行）
DOWN	0	Monitor is down or not responding（监视器已关闭或无响应）
待处理 (PENDING)	2	Monitor is waiting for a response（监视器正在等待响应）
MAINTENANCE	3	Monitor is under maintenance（监视器正在维护中）

状态页面也存在类似的常量

常量	值	描述
STATUS_PAGE_ALL_UP	1	All monitors on the status page are up（状态页面上的所有监视器均正常）
STATUS_PAGE_ALL_DOWN	0	All monitors on the status page are down（状态页面上的所有监视器均已关闭）
STATUS_PAGE_PARTIAL_DOWN	2	Some monitors on the status page are down（状态页面上的某些监视器已关闭）
STATUS_PAGE_MAINTENANCE	3	Status page is in maintenance mode（状态页面处于维护模式）

这些常量在整个应用程序中使用，以保持状态表示的一致性。

来源： src/util.ts25-33 src/util.js25-33

状态操作

flipStatus 函数允许在 UP 和 DOWN 之间反转监视器的状态

这对于测试和需要反转状态的场景很有用。

来源： src/util.ts128-138 src/util.js106-114

字符串操作

实用工具包括几个字符串操作函数

• ucfirst：将字符串的第一个字母大写（类似于 PHP 的 ucfirst）
• polyfill：为旧浏览器的 String.prototype.replaceAll 提供 polyfill

来源： src/util.ts154-161 src/util.js120-126 src/util.ts378-390 src/util.js254-263

实用工具组织图

来源： src/util.ts src/util.js src/util-frontend.js

日志系统

Uptime Kuma 提供了一个全面的日志系统，允许在应用程序中进行一致的日志记录。日志系统以 Logger 类为中心，该类提供了用于以不同级别（debug、info、warn、error）和不同模块进行日志记录的方法。

Logger 类

Logger 类具有以下关键方法

• log(module, msg, level)：主要的日志记录方法
• info(module, msg)：记录 INFO 消息
• warn(module, msg)：记录 WARN 消息
• error(module, msg)：记录 ERROR 消息
• debug(module, msg)：记录 DEBUG 消息
• exception(module, exception, msg)：将异常记录为 ERROR

每个日志消息都包含时间戳、模块名称、日志级别和消息本身。日志记录器还支持在终端环境中运行时进行彩色输出。

日志配置

日志记录器支持通过环境变量进行配置

• UPTIME_KUMA_HIDE_LOG：要隐藏的日志条目的逗号分隔列表，格式为 level_module（例如，debug_monitor,info_monitor）
• TIMELOGGER：设置为“1”时，启用时间日志记录

日志系统架构

来源： src/util.ts172-367 src/util.js132-252

时间和日期实用工具

Uptime Kuma 提供一套基于 dayjs 库的时间和日期操作实用工具。

时间常量

定义了几个用于格式化日期和时间的常量

• SQL_DATE_FORMAT：“YYYY-MM-DD”
• SQL_DATETIME_FORMAT：“YYYY-MM-DD HH:mm:ss”
• SQL_DATETIME_FORMAT_WITHOUT_SECOND：“YYYY-MM-DD HH:mm”
• MAX_INTERVAL_SECOND：2073600（24 天）
• MIN_INTERVAL_SECOND：20 秒

时间转换函数

实用工具包含几个用于在不同时间格式之间转换的函数

• isoToUTCDateTime：将 ISO 日期转换为 UTC 日期时间字符串
• utcToISODateTime：将 UTC 日期时间转换为 ISO 字符串
• utcToLocal：将 UTC 日期时间转换为本地时间
• localToUTC：将本地时间转换为 UTC 日期时间

时间解析函数

还提供了用于解析时间对象的函数

• parseTimeObject：将时间字符串（例如，“12:00”）解析为时间对象
• parseTimeFromTimeObject：将时间对象转换回字符串

Sleep 实用工具

提供了一个 sleep 函数，用于需要等待指定时间的异步操作

时间实用工具图

来源： src/util.ts33-40 src/util.js33-40 src/util.ts145-147 src/util.js116-118 src/util.ts553-597 src/util.js348-380 src/util.ts604-634 src/util.js382-396

URL 和路径实用工具

Uptime Kuma 提供用于在应用程序内生成 URL 和路径的实用函数。

监视器和维护 URL

• getMonitorRelativeURL(id)：为监视器仪表板生成相对 URL（/dashboard/{id}）
• getMaintenanceRelativeURL(id)：为维护窗口生成相对 URL（/maintenance/{id}）

前端 URL 实用工具

特定于前端的 URL 实用工具包括

• getResBaseURL()：获取资源的基 URL，处理开发环境
• isDevContainer()：检查应用程序是否在开发容器中运行
• getDevContainerServerHostname(): 获取开发容器中服务器的主机名
• hostNameRegexPattern(mqtt = false): 提供用于验证主机名和 IP 地址的正则表达式模式

来源: src/util.ts534-545 src/util.js340-347 src/util-frontend.js78-126

随机生成和加密

Uptime Kuma 包含用于生成随机值的实用程序，包括加密安全的随机值。

随机数生成

• getRandomArbitrary(min, max): 生成一个介于 min 和 max 之间的随机浮点数
• getRandomInt(min, max): 生成一个介于 min 和 max 之间的随机整数（包含 min 和 max）
• getCryptoRandomInt(min, max): 生成一个介于 min 和 max 之间的加密安全随机整数

密钥生成

• genSecret(length = 64): 生成指定长度的随机字母数字字符串，可用于 API 密钥和其他密钥

随机生成流程

来源: src/util.ts420-527 src/util.js276-338

JSON 查询实用工具

Uptime Kuma 提供了一个强大的 JSON 查询实用程序，允许针对数据评估 JSON 表达式，这对于自定义监控条件特别有用。

evaluateJsonQuery

evaluateJsonQuery 函数评估提供的 JSON 查询表达式与给定数据之间的关系

此函数支持各种比较运算符

• >, >=, <, <=: 数字比较
• ==, !=: 相等性检查
• contains: 字符串包含检查

该函数用于 SNMP 等监控类型，以针对检索到的数据评估条件。

JSON 查询流程

来源: src/util.ts661-724 src/util.js406-459 server/monitor-types/snmp.js45-52

仅限前端的实用工具

Uptime Kuma 提供了一些特定于前端应用程序的实用程序。

时区实用程序

• timezoneList(): 返回一个按 UTC 偏移量排序的时区列表
• getTimezoneOffset(timeZone): 获取指定时区相对于 UTC 的偏移量

区域设置

• setPageLocale(): 根据选定的区域设置来设置 HTML 文档的语言和方向属性

UI 辅助工具

• colorOptions(self): 为 UI 元素提供标准的颜色选项列表
• loadToastSettings(): 加载 toast 通知设置
• getToastSuccessTimeout(): 获取成功 toast 通知的超时时间
• getToastErrorTimeout(): 获取错误 toast 通知的超时时间

组件工具

几个 Vue 组件使用了实用函数

• Status.vue: 使用状态常量来显示监控状态
• Uptime.vue: 使用状态常量来显示正常运行时间信息
• Datetime.vue: 使用日期格式化工具
• CountUp.vue: 使用 sleep 实用程序进行动画

前端工具图

来源: src/util-frontend.js13-215 src/components/Status.vue src/components/Uptime.vue src/components/Datetime.vue src/components/CountUp.vue

在监控中的应用

实用函数广泛应用于监控类型的实现中。例如，SNMP 监控类型使用 evaluateJsonQuery 函数来评估 SNMP 响应的条件。

来源: server/monitor-types/snmp.js2-52

与数据库模型的集成

实用函数也用于数据库模型中以格式化和操作数据

• Heartbeat 模型: 使用状态常量表示监控状态
• Group 模型: 使用实用函数进行数据操作

来源: server/model/heartbeat.js server/model/group.js

结论

Uptime Kuma 的实用函数为应用程序的常见操作提供了一个强大的基础。通过集中这些函数，代码库可以保持一致性并减少重复。开发人员在实施新功能或修改现有功能时应利用这些实用程序，以确保一致性和可维护性。

有关数据库架构的更多信息，请参阅 数据流。