Uptime Kuma 核心文档:拨测监控从原理到实战

1. 为什么需要主动拨测监控？

指标监控回答的是服务内部视角的问题——进程活着吗、资源够吗、延迟高吗。但用户能不能访问到服务，是外部视角的问题，中间隔着 DNS、防火墙、负载均衡、证书过期、证书链错误、后端假死（进程活着但不响应）。

拨测（主动探测）就是模拟用户的视角：从一台独立的机器上，定时向服务发起真实的 HTTP 请求/TCP 连接/Ping，问一个问题——"现在，这个服务能访问吗？"

指标监控和拨测监控各自只能看到一半真相：

故障	指标监控能看到吗	拨测能看到吗
进程 OOM 被杀	能（进程数=0）	能（探测失败）
证书过期	看不到	能（TLS 握手失败）
DNS 被劫持/解析错误	看不到	能（解析到错误 IP）
防火墙规则误封端口	看不到	能（连接超时）
后端假死（活着不响应）	半能（延迟指标可能没采集到）	能（请求超时）
磁盘将满、内存泄漏趋势	能（趋势告警）	看不到（挂了才知道）

/ / /

2. Uptime Kuma 是什么？

一个开源自托管的拨测监控系统，GitHub 60k+ star，单容器即可跑起来。

-
项目：https://github.com/louislam/uptime-kuma
-
技术栈：Node.js + Vue.js + SQLite + Socket.IO
-
默认端口：3001

核心能力四件套：

[01]多协议探测
：HTTP(s)、TCP/Ping、ICMP、DNS、Keyword（页面内容）、Push（被动心跳）等 90+ 监控类型
[02]告警通知
：状态翻转时推送到飞书/企业微信/Telegram/Slack/邮件/Webhook 等 90+ 渠道
[03]状态页
：对外公开展示服务可用性，类似 GitHub Status
[04]维护窗口
：计划内维护期间静默告警，且有审计记录

：零依赖单实例部署，被监控方完全无改造。

/ / /

3. Uptime Kuma 与 Prometheus/夜莺的区别

一句话定位：Kuma 回答"通不通"，Prometheus/夜莺回答"健不健康"。

维度	Uptime Kuma	Prometheus / 夜莺
定位	可用性拨测	指标/性能监控
采集方式	主动探测（无需 Agent）	Pull /metrics 或 Agent
数据模型	状态 + 响应时间（心跳）	时序指标（多维标签）
存储	SQLite 单文件	TSDB / MySQL+TDengine
告警	状态翻转 + 简单阈值	PromQL 复杂规则 + 自愈
仪表盘	简单状态页	Grafana 风格多维图表
规模	百级监控项	万级指标
部署成本	单容器	全套组件

选型结论：拨测用 Kuma，性能容量趋势用夜莺/Prometheus。两者数据打通的场景：Kuma 的心跳数据可通过 API 导出，接入夜莺做统一告警面板。

/ / /

4. Uptime Kuma 核心架构

设计	好处	代价（约束）
无 Agent 主动探测	被监控方零改造	探测结果依赖 Kuma 自身网络位置
SQLite 单文件库	部署零依赖、备份=拷文件	单写者：只能 1 副本，禁 NFS
Socket.IO 实时推送	前端秒级刷新	自动化要走 Socket.IO API，不是 REST

记住"SQLite 单写者"这一条，K8s 上所有部署决策（单副本、Recreate、local PV）都是从它推出来的。

/ / /

5. 部署实践（K8s）

四个资源：PV + PVC + Deployment + Service(NodePort)。

apiVersion: apps/v1kind: Deploymentspec:  replicas: 1                 # 生死线1：永远单副本  strategy:    type: Recreate            # 生死线2：禁 RollingUpdate，防双实例并发写库  template:    spec:      nodeSelector:        kubernetes.io/hostname: cve2183-w1    # 生死线3：钉在 PV 节点      containers:        - name: uptime-kuma          image: louislam/uptime-kuma:1          volumeMounts:            - name: data              mountPath: /app/data   # kuma.db 所在      volumes:        - name: data          persistentVolumeClaim:            claimName: uptime-kuma-data

部署检查清单：

-
PV 用 local path（节点 /data/uptime-kuma），禁 NFS/RWX——SQLite 文件锁在 NFS 上不可靠
-
无 StorageClass 的集群：PV 和 PVC 用同名 storageClassName 手动绑定

-
健康探针 httpGet :3001/，资源 100-500m CPU / 128-512Mi
-

关键运行参数：

参数	默认	生产建议
interval	60s	关键服务 20-30s
maxretries	1	3（防瞬时抖动误告警）
retryInterval	60s	与 interval 一致
ignoreTls	false	内网自签证书设 true
keepDataForDays	180	按合规要求

/ / /

6. 通知告警配置

触发逻辑：心跳 DOWN → 连续失败超过 maxretries → 触发通知；恢复 UP 再发一条恢复通知。状态翻转记为 important heartbeat（= 告警历史，可 API 查询）。

渠道配置（以飞书为例）：

[01]
飞书群 → 设置 → 群机器人 → 添加自定义机器人 → 拿 Webhook URL
[02]
Kuma → Settings → Notifications → 新建 Feishu/Lark → 填 URL → Test
on")

/ / /

7. Status Page 设计

对外展示服务可用性的公开页面，访问 http://<host>/status/<slug>。

核心概念：

-slug
：URL 路径标识，只允许小写字母数字连字符
-Group 分组
：按业务域分组（如"公网服务"/"内部依赖"），避免一屏堆几十个监控项
-Incident 故障公告
：出现故障时挂公告（时间线 + 说明），用户看到"已知故障，修复中"而不是一片红

-theme/auto
：自动深浅色，可配 customCSS

API 创建（实测参数顺序坑）：

设计建议：状态页只放用户关心的入口服务（网站/API 网关），不放内部中间件细节；每个入口服务配三层探测（HTTP 状态码 + Keyword 内容 + 依赖 TCP）。

/ / /