Uptime Kuma 监控同步设计

你会学到：OpenFlare 与 Uptime Kuma 监控服务集成的设计背景、基于 Socket.IO 协议的控制流设计、以标签隔离为核心的防污染模型，以及差分增量同步的状态机比对逻辑。

---

需求分析

在多节点的网关架构中，监控系统的状态与反向代理路由的状态通常是相互脱节的：

1. 录入开销大：每当网关控制面新增或下线一个站点，管理员都必须在监控系统（如 Uptime Kuma）中重复配置对应的探测地址与告警策略。
2. 数据不一致：当代理路由域名发生变更或切换 HTTPS 时，容易遗漏修改监控参数，导致监控系统误报或漏报。
3. 环境污染隐患：如果简单的在监控中执行全量“删除-重建”同步，不仅会清空监控系统中的历史统计指标和 SLA 曲线，还会影响到用户在此监控实例上自行配置的、与网关无关的其他监控任务。

为了解决这些痛点，OpenFlare 引入了基于客户端/服务器模式的 Uptime Kuma 自动监控同步机制，实现网关站点路由定义与可用性监测系统的强一致、低开销以及零污染同步。

---

核心架构设计

Uptime Kuma 同步子系统完全运行在 Server 控制面 的后台调度器中。

  [ 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 事件：

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