Uptime Kuma 介绍与选型指南

Uptime Kuma 定位、架构与功能全景：源码方式最小可用安装实测，并用社区活跃度与版本节奏量化对比 Uptime Robot、Gatus、Netdata。

Uptime KumaUptime Kuma2026/10/17

Uptime Kuma 介绍与选型指南

‍‍​​‌​‍‍​​‌​> 目标：讲清 Uptime Kuma 是什么、架构如何、能做什么，给出源码方式的最小可用安装路径，并用社区活跃度与版本节奏量化对比 Uptime Robot、Gatus、Netdata 三款同类工具，帮你判断它是否适合你的监控场景。

一、环境信息

本文实测与选型数据均在以下环境采集：

项目值
操作系统Ubuntu 22.04（x86_64）
Uptime Kuma 版本1.23.17（2025-07-15 发布，实测运行验证）
Node.js18.20.8（源码方式实测）
数据查询日期2026-10-17
选型数据来源GitHub 公开 API（星标 / 发布记录）与各产品官网

二、软件概述

Uptime Kuma 是一款开源的自托管可用性监控与状态页工具，MIT 协议，使用 JavaScript / Node.js 开发。它对标 Uptime Robot 这类在线拨测服务：把「定时探测目标、记录心跳、故障告警、对外展示状态页」这条链路完整搬到自己的服务器上运行，数据不出内网，监控数量与频率不收订阅费。

关键事实速览：

维度事实
定位服务可用性监控（拨测类），不是主机资源监控
协议MIT，完全开源
语言 / 技术栈Node.js（服务端）+ Vue 3（前端）
存储SQLite 单文件数据库（WAL 模式），无需独立数据库服务
部署形态单进程常驻，官方提供预制运行环境与源码两种方式
运行资源1 vCPU / 512 MB 内存即可稳定运行（官方推荐）
实测版本1.23.17，内置 22 种监控类型与 54 种通知渠道

需要强调定位边界：Uptime Kuma 回答的是「我的服务现在可不可达、响应多快」，面向网站、API、端口、证书这类拨测对象；想知道「这台服务器内存还剩多少、哪个进程吃 CPU」属于主机监控范畴，应配合 Netdata、node_exporter 等工具，第七节的对比矩阵会展开这一点。

三、核心架构

Uptime Kuma 是典型的单进程全栈应用，技术栈版本取自 1.23.17 的 package.json：

组件版本角色
Node.js≥14，官方运行环境为 18.x运行时
Express~4.21.0HTTP 路由（页面、公开状态页 API、Push 接口、指标端点）
Socket.IO~4.8.0界面实时通道，心跳结果推送与全部管理操作
@louislam/sqlite315.1.6SQLite 驱动（官方维护的分支）
redbean-node / knex~0.3.0 / 内置ORM 与查询构建
nodemailer~6.9.13SMTP 邮件通知
Vue 3~3.3.4前端框架（预构建产物随版本发布）
prom-client~13.2.0Prometheus 指标输出

心跳链路：每条监控项在服务内持有一个独立调度器，按 interval 定时执行探测；探测结果写入 SQLite heartbeat 表，同时经 Socket.IO 推送到在线界面。首次添加立即执行一次探测，之后严格按间隔滚动。

判定与告警链路：单次探测失败先进入重试状态（retryInterval 节奏），连续失败超过 maxretries 次才翻转 DOWN 并触发通知；恢复时发出恢复通知。通知内容同时投递到该监控项挂载的全部渠道（54 种内置）。

存储模型：全部数据在一个 SQLite 文件中（kuma.db + WAL 日志），按表组织用户、监控项、心跳、通知、状态页与设置。WAL 模式保证「边监控边查询边备份」互不阻塞；数据保留期默认 180 天，清理任务每小时整点自动删除过期心跳。

进程与扩展性：一个进程承担调度、探测、存储与界面服务，天然单机单点——这决定了它适合中小规模（数十到数百条监控项），超大规模或高可用需求需要另做设计（详见第六节）。

实时界面：所有管理操作（增删监控、收发通知、编辑状态页）走 Socket.IO 通道而非 RESTful，这一点在自动化集成时要注意——官方没有完整的管理 REST API，但状态页数据与 Prometheus 指标端点是公开的。

四、功能特性

监控类型（22 种，1.23.17 实测枚举自添加监控表单）：

类别类型
网络与 HTTP 拨测http、keyword（HTTP 关键字）、json-query（JSON 取值比对）、grpc-keyword（gRPC 探测）、ping、port（TCP 端口）、dns
服务探活postgres、mysql、sqlserver、mongodb、redis、mqtt、kafka-producer、radius（认证链路）
专项steam（Steam 游戏服）、gamedig（各游戏协议）、tailscale-ping（组网拨测）、real-browser（真实浏览器渲染）、外部宿主机服务状态、push（被动接收心跳）、group（聚合组）

通知渠道（54 种，实测枚举自源码）：飞书、钉钉、企业微信、Server 酱等国内渠道与 Slack、Teams、Telegram、Discord 等国际渠道齐备，另有 PagerDuty、Opsgenie 等值班平台接入与通用 Webhook / SMTP 兜底，完整矩阵见《Uptime Kuma 配置参数详解》第七节。

状态页：多条监控聚合成对外发布页面，支持分组、自定义主题与 CSS、绑定域名、整体状态 SVG 徽章；公开数据经只读 JSON 端点输出，可直接被其他系统集成。实测样式见《Uptime Kuma 配置参数详解》第八节。

运维配套：

  • 维护窗口：计划内停机期间自动暂停告警，避免噪音；
  • 证书到期提醒：TLS 证书剩余 14 / 30 天时分别提醒；
  • API 密钥与 Prometheus 指标：以 prom-client 输出每条监控的可用率与延迟，方便接入既有指标体系；
  • 标签与分组：监控项可打标签、按父级分组聚合，组状态随子项联动；
  • 双因素认证：管理员可启用 TOTP 二次验证；
  • 多语言：界面含简体中文在内的数十种语言。

五、快速开始（最小可用）

以下用源码方式在 Ubuntu 22.04 上完成安装并跑通「启动 → 初始化 → 建监控 → 看心跳」的最小闭环，全部命令实测。

1. 安装 Node.js 18

$ curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
$ apt-get install -y nodejs
$ node --version
v18.20.8

Ubuntu 22.04 源内的 nodejs（12.x）不满足要求，需按官方仓库推荐安装 18.x。同时准备编译依赖（npm 安装原生模块时使用）：

$ apt-get install -y git python3 build-essential

2. 获取源码并安装依赖

$ cd /opt
$ git clone --depth 1 --branch 1.23.17 https://github.com/louislam/uptime-kuma.git
$ cd uptime-kuma
$ npm ci --production --no-audit --no-fund
added 754 packages in 6s

包数量以实际输出为准（1.23.17 生产依赖共 754 个）；首次执行需联网下载，耗时数分钟，重复执行命中本地缓存后仅数秒。国内网络连 npm 官方源缓慢时，将 registry 切换到国内加速站再执行（本次实测即采用该方式）。命令行 npm config set registry https://registry.npmmirror.com 或用 --registry 参数皆可。

3. 获取前端产物并启动

$ npm run download-dist
Downloading dist
https://github.com/louislam/uptime-kuma/releases/download/1.23.17/dist.tar.gz
Extracting dist...

1.x 的源码仓库不含前端构建产物，download-dist 从发布页下载与版本一致的 dist 压缩包并解压；受限网络环境可直接在浏览器下载同一地址的 dist.tar.gz，解压到源码根目录（产物内含 dist/ 目录），效果等价（本次实测即采用该方式，文件 sha256 为 f2e0132e...768acfe8e7）。

$ UPTIME_KUMA_PORT=3100 node server/server.js

首次启动日志（节选，完整迁移过程自动完成）：

Welcome to Uptime Kuma
Your Node.js version: 18.20.8
2026-10-17T09:04:28Z [SERVER] INFO: Version: 1.23.17
2026-10-17T09:04:28Z [DB] INFO: Your database version: 0
2026-10-17T09:04:28Z [DB] INFO: Latest database version: 10
2026-10-17T09:04:28Z [DB] INFO: Database patch is needed
2026-10-17T09:04:29Z [DB] INFO: Database Patched Successfully
2026-10-17T09:04:29Z [SERVER] INFO: JWT secret is not found, generate one.
2026-10-17T09:04:29Z [SERVER] INFO: No user, need setup
2026-10-17T09:04:29Z [SERVER] INFO: Listening on 3100

4. 初始化与最小可用验证

访问 http://<服务器IP>:3100 进入初始化向导创建管理员（实测接口返回 {"ok":true,"msg":"Added Successfully."}），登录后添加一条监控：类型 HTTP，URL 填 http://127.0.0.1:3100（监控服务自身，最简单的自检闭环），保存后立即产生第一条心跳：

{"monitor_id":1,"time":"2026-10-17 09:05:43.942","status":1,"msg":"200 - OK","ping":10}

至此最小可用达成：服务运行、账号就绪、一条 HTTP 监控以 60 秒间隔持续拨测自身。日常生产部署更推荐按《Uptime Kuma Docker Compose 部署指南》的编排方式运行；源码方式的优势在于紧跟开发分支调试与定制，两者数据目录结构一致，可随时互换。

六、适用场景与限制

适合的场景：

  • 中小团队、个人开发者的网站 / API / 端口可用性监控，规模在数百条监控项以内；
  • 对数据主权有要求：监控数据必须留在内网或私有环境，不能接受第三方拨测服务；
  • 需要一个对外（客户 / 领导）的公开状态页，且希望品牌自定义；
  • 监控内网服务：探测点就在内网，天然覆盖 Uptime Robot 等外部服务够不到的目标；
  • 被动心跳场景：定时任务、CI 流水线、IoT 设备通过 Push 类型「报平安」，漏报即告警。

明确的限制：

  • 单机单点：官方架构不支持原生集群或高可用，监控服务自身宕机则监控中断；对可用性要求高时，用两台服务器各跑一套并交叉监控对方，是最朴素的互备方案；
  • SQLite 的规模上限：数千条高频监控会带来心跳表写入与查询压力，超大规模应选带独立数据库的方案（如 Gatus 可选 PostgreSQL）；
  • 告警能力偏基础：有重试与恢复通知，但没有内置的告警升级、值班排班、静默策略联动，需要这类能力应对接 PagerDuty / Opsgenie 类平台（通知渠道原生支持）；
  • 管理接口以界面为主：没有完整的监控项管理 REST API，批量自动化配置不如配置文件型工具（Gatus 用 YAML 声明监控，GitOps 友好）；
  • 资源型监控不在射程内：CPU / 内存 / 磁盘等主机指标请交给 Netdata 或 node_exporter，Uptime Kuma 只负责「可不可达」。

七、同类选型对比

四款工具的社区活跃度与版本节奏（GitHub 公开 API，查询日期 2026-10-17）：

指标Uptime KumaUptime RobotGatusNetdata
定位自托管拨测监控 + 状态页商业在线拨测服务自托管拨测（配置文件驱动）主机与应用实时性能监控
开源协议MIT闭源（免费层）Apache-2.0GPL-3.0
主语言JavaScript / Node.js-GoC
GitHub 星标74,900-7,50076,100
Fork 数6,900-6006,100
开源 Open Issues736-86
创建时间2020-122010 年前后（商业服务）2019-032013-06
最近提交2026-10-17（当日）-2026-10-17（当日）2026-10-17（当日）
近期发布节奏1.23.17（2025-07）、1.23.16（2025-02）、1.23.15（2024-12）；2023 年约 19 个 1.x 版本，2024 年 11 个服务化，无版本概念v5.17.0（2025-04）、v5.16.0（2025-03），小步快跑v3.3.1（2025-06）、v3.3.0（2025-06），周级发布
部署形态单进程（源码 / 预制环境均可）SaaS，零部署单进程（预制环境优先）常驻 Agent，自带 Web UI
存储内置 SQLite云端内置 SQLite / PostgreSQL / 内存内置时序数据库
免费额度无限制（自担资源）50 条监控、5 分钟间隔无限制（自担资源）无限制（自担资源）
付费参考无Starter $24/年（10 监控、1 分钟）；Solo $74.40/年（50 监控）；Team $402/年（100 监控）无商业版按节点订阅（社区版功能完整）
状态页内置，可自定义域名与 CSS付费计划提供支持（YAML 声明）不以内置状态页见长

三组结论供选型参考：

「要不要自托管」是第一分叉。Uptime Robot 的价值是零运维与多地域拨测视角（从全球节点看你的公网服务），免费层 50 条监控、5 分钟间隔适合个人项目；一旦需要 1 分钟间隔与更多监控，费用按年叠加（实测定价：50 监控 1 分钟间隔的 Solo 档 $74.40/年）。Uptime Kuma 与 Gatus 自托管无数量限制，代价是自己维护探测点与可用性——内外结合（自托管为主 + Uptime Robot 免费层做公网交叉验证）是常见折中。

「界面驱动还是配置驱动」是第二分叉。Uptime Kuma 全部配置在 Web 界面完成，上手最快，非运维角色也能添加监控；Gatus 用 YAML 声明监控项与告警，配置可进 Git、可代码评审，适合基础设施即代码的团队。两者的探测类型与告警渠道高度重叠，团队协作模式决定选择。

「可用性监控还是性能监控」是第三分叉。Netdata 与前三者不是同一物种：它秒级采集主机与应用的数千项指标，回答「慢在哪里」，对「通不通」的拨测告警反而不如前三者直接。典型组合是 Netdata 管主机性能 + Uptime Kuma 管服务可用性 + 状态页对外，三者互补而非互替。

八、参考链接