# 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` 事件的完整列表推送后，才允许向下执行差分算法，以规避因为数据加载不完整导致误删监控项的边界情况。