mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 22:06:38 +08:00
ryan
110 lines
6.0 KiB
Markdown
110 lines
6.0 KiB
Markdown
# Uptime Kuma 监控同步设计
|
||
|
||
你会学到：OpenFlare 与 Uptime Kuma 监控服务集成的设计背景、基于 Socket.IO 协议的控制流设计、以标签隔离为核心的防污染模型，以及差分增量同步的状态机比对逻辑。
|
||
|
||
---
|
||
|
||
## 需求分析
|
||
|
||
在多节点的网关架构中，监控系统的状态与反向代理路由的状态通常是相互脱节的：
|
||
1. **录入开销大**：每当网关控制面新增或下线一个站点，管理员都必须在监控系统（如 Uptime Kuma）中重复配置对应的探测地址与告警策略。
|
||
2. **数据不一致**：当代理路由域名发生变更或切换 HTTPS 时，容易遗漏修改监控参数，导致监控系统误报或漏报。
|
||
3. **环境污染隐患**：如果简单的在监控中执行全量“删除-重建”同步，不仅会清空监控系统中的历史统计指标和 SLA 曲线，还会影响到用户在此监控实例上自行配置的、与网关无关的其他监控任务。
|
||
|
||
为了解决这些痛点，OpenFlare 引入了基于客户端/服务器模式的 **Uptime Kuma 自动监控同步机制**，实现网关站点路由定义与可用性监测系统的强一致、低开销以及零污染同步。
|
||
|
||
---
|
||
|
||
## 核心架构设计
|
||
|
||
Uptime Kuma 同步子系统完全运行在 **Server 控制面** 的后台调度器中。
|
||
|
||
```text
|
||
[ OpenFlare 控制面 / 数据库 ] [ Uptime Kuma 实例 ]
|
||
│ │
|
||
1. 定时 Cron 触发 (Job) │
|
||
│ │
|
||
2. 读取代理路由与选项配置 │
|
||
│ │
|
||
3. 连接 Socket.IO 接口 <──── 4. Socket.IO 握手 & 登录 ───┤
|
||
│ │
|
||
├────── 5. 校验 / 创建 "OpenFlare" 标签 ────────►│
|
||
├────── 6. 比对监测站点属性与 Kuma 监控清单 ──────►│
|
||
│ │
|
||
└────── 7. 执行差分指令 (add / edit / delete) ─►│
|
||
```
|
||
|
||
同步子系统不经过数据面的 Agent 节点，而是由 Server 通过 Uptime Kuma 暴露的 Socket.IO 端点直接交互。这种设计可以降低边缘节点的网络开销，并将鉴权凭证（Kuma 用户名与密码）安全收拢在控制面中。
|
||
|
||
---
|
||
|
||
## 标签隔离与防污染设计
|
||
|
||
为了在一个共享的 Uptime Kuma 实例中安全运行，而不干扰用户手动创建的其他监控项，设计上采用了 **专属标签隔离机制**：
|
||
|
||
1. **`OpenFlare` 专属标签**：
|
||
* 同步程序首次连接时，会调用 `getTags` 接口拉取实例中的所有标签。
|
||
* 检查是否存在名为 `OpenFlare` 的标签（默认颜色为靛蓝色 `#4f46e5`）。如果不存在，则通过 `addTag` 接口在 Kuma 中自动创建它。
|
||
2. **过滤范围收拢**：
|
||
* 同步任务在拉取 Uptime Kuma 的监控列表（`monitorList`）后，仅会保留**打有 `OpenFlare` 标签**的监控项。
|
||
* 所有的修改比对（`editMonitor`）和下线清理（`deleteMonitor`）**仅在此过滤子集内进行**。任何未绑定 `OpenFlare` 标签的监控项对同步程序均是“隐形”的，实现了完美的防污染隔离。
|
||
|
||
---
|
||
|
||
## 差分同步状态机逻辑
|
||
|
||
同步程序每次执行时，会对 OpenFlare 本地配置与 Uptime Kuma 数据进行差分计算，根据比对结果执行不同的 Socket.IO 事件：
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> 检查站点状态与监控范围
|
||
|
||
state "检查监控范围" as Scope {
|
||
[*] --> 校验站点是否启用并且在 Scope 内
|
||
校验站点是否启用并且在 Scope 内 --> 在Scope内 : 是
|
||
校验站点是否启用并且在 Scope 内 --> 不在Scope内 : 否
|
||
}
|
||
|
||
不在Scope内 --> 检查Kuma中是否存在同名且带标签的监控
|
||
检查Kuma中是否存在同名且带标签的监控 --> 执行清理 : 存在
|
||
检查Kuma中是否存在同名且带标签的监控 --> 忽略 : 不存在
|
||
|
||
在Scope内 --> 检查Kuma中是否存在同名监控
|
||
|
||
state "比对属性" as Compare {
|
||
[*] --> 检查是否存在
|
||
检查是否存在 --> 新建监控项 : 否
|
||
检查是否存在 --> 比对元数据 : 是
|
||
比对元数据 --> 属性一致 : 匹配
|
||
比对元数据 --> 属性不一致 : 不匹配
|
||
}
|
||
|
||
新建监控项 --> 发送add指令并绑定Tag
|
||
属性不一致 --> 发送editMonitor指令
|
||
属性一致 --> 忽略
|
||
|
||
执行清理 --> 发送deleteMonitor指令
|
||
忽略 --> [*]
|
||
```
|
||
|
||
### 1. 监测 URL 规范化
|
||
站点路由在 OpenFlare 中可配置多个域名，同步程序自动提取其主域名（Primary Domain）并根据是否启用 HTTPS 组装为标准的 `http://` 或 `https://` 前缀。
|
||
|
||
### 2. 比对属性清单
|
||
如果同名且带标签的监控已存在，同步程序会细致比对以下 5 个关键字段是否与当前网关全局 Option 一致。只要有一个字段不匹配，便会触发更新：
|
||
* **URL 地址**：`Url`
|
||
* **探测频率**：`Interval`（默认 60s）
|
||
* **重试次数**：`MaxRetries`
|
||
* **重试间隔**：`RetryInterval`（默认 60s）
|
||
* **请求超时**：`Timeout`（默认 48s）
|
||
|
||
---
|
||
|
||
## 调度器与高并发保护
|
||
|
||
1. **基于 Cron 的单线程执行**：
|
||
* Server 周期性（每 1 分钟）通过后台的 Cron Job 探测是否达到配置的同步间隔（`UptimeKumaSyncInterval`）。
|
||
* 任务内部设计了互斥锁（Mutex Locking）。如果前一次同步请求因为网络延迟等原因尚未结束，下一次调度将自动跳过，防止并发多个 Socket.IO 连接对 Uptime Kuma 实例造成 DDOS 冲击。
|
||
2. **WebSocket 状态监听**：
|
||
* 同步程序利用 Socket.IO 的事件监听机制，在连接建立后，必须等到监听到 `monitorList` 事件的完整列表推送后，才允许向下执行差分算法，以规避因为数据加载不完整导致误删监控项的边界情况。
|