引言
「A fancy self-hosted monitoring tool.」
这是「一天一个开源项目」系列的第 261 篇 。今天的项目是 louislam 的 Uptime Kuma。
个人站点、自家服务、小团队的内部系统，都有同一个朴素的需求：它挂了，我要第一时间知道。商业服务比如 Uptime Robot 能做，但免费额度有限，数据也在别人手里。Uptime Kuma 的答案是：自己在一台机器上跑一个，界面漂亮、配置简单，挂了就往 Telegram、钉钉之类的地方推消息。
它已经是 GitHub 上相当热门的运维类项目，约 9.4 万 Stars。本文基于 README 和仓库元数据整理，我没有实际部署运行这些命令。
你将学到什么
- Uptime Kuma 能监控什么，不能监控什么
- 用 Docker 或 Node 直接部署的几种方式，以及容易踩的限制
- 状态页、通知渠道这两项最常用的功能
- 项目的定位、局限，以及什么场景下不适合用它
前置知识
- 了解 Docker 的基本用法，或会在 Linux 上装 Node.js
- 对「监控、告警、状态页」这些概念有基本认识
- 可选：用过 Uptime Robot 或类似的服务
项目背景
项目简介
作者在 README 里说得很直白：他想要一个 Uptime Robot 的替代品，但试过的 statping 不稳定且不再维护，于是自己写。顺便的目标还包括：做一个好看的界面、学习 Vue 3 和 vite.js、展示 Bootstrap 5、用 WebSocket 加单页应用而不是传统 REST，以及发布他的第一个 Docker Hub 镜像。
项目数据
- ⭐ GitHub Stars：约 93,609
- 🍴 Forks：约 8,706
- 💻 语言：JavaScript
- 📅 创建时间：2021-07-03，最近一次推送为 2026-11-13，最新发布版本 2.5.11（2026-11-12）
- 📄 许可证：MIT
- 👤 作者：louislam
- 🌐 官网：uptime.kuma.pet
主要功能
它解决的问题
没有监控时：
网站或服务挂了 → 要等用户反馈才知道
↑ 排查晚、损失大
用 Uptime Kuma：
定时检查你的服务 → 不通就告警
↓ 消息推送到你常用的渠道
↑ 同时给用户一个公开的状态页核心能力
| 能力 | 说明 |
|---|---|
| 监控类型 | HTTP(s)、TCP、HTTP(s) 关键字、HTTP(s) JSON 查询、Websocket、Ping、DNS 记录、Push、Steam 游戏服务器、Docker 容器 |
| 检查频率 | 最短 20 秒一次 |
| 通知渠道 | Telegram、Discord、Gotify、Slack、Pushover、邮件（SMTP）等，合计 90 多种 |
| 状态页 | 可建多个，并映射到指定域名 |
| 其他 | 响应式快速界面、多语言、Ping 图表、证书信息、代理支持、双因素认证（2FA） |
快速开始
方式一：Docker Compose
bash
mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d方式二：一条 Docker 命令
bash
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2两种方式都在 3001 端口提供服务，并且默认监听所有网卡。如果只想本机访问，把端口映射改成 -p 127.0.0.1:3001:3001。
方式三：不用 Docker
bash
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
# 先试一试
node server/server.js
# 推荐：用 PM2 放到后台
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma几个常用的 PM2 命令：pm2 monit 查看控制台输出，pm2 startup && pm2 save 设为开机启动。
环境要求
- Node.js 20.4 及以上
- Git
- 想后台运行需要 pm2
支持的平台
- 主流 Linux 发行版（Debian、Ubuntu、Fedora、ArchLinux 等）
- Windows 10（x64）或 Windows Server 2012 R2（x64）及更新版本
- 不支持 FreeBSD、OpenBSD、NetBSD、Replit、Heroku
想先看看效果，可以用官方演示站，数据 10 分钟后会被清空。
项目详细剖析
几个值得注意的使用细节
1. 监控类型选对，才能测到真实的故障
- 只测「端口通不通」用 TCP 就够
- 网站能打开但页面内容坏了，用 HTTP(s) 关键字监控，检查页面里有没有某个词
- 接口返回 200 但数据不对，用 JSON 查询监控，检查返回里的某个字段
- 定时任务（备份、同步）有没有按时跑，用 Push 监控：任务完成时主动调用 Uptime Kuma 提供的地址，一段时间没收到就告警
- 服务跑在容器里，可以直接监控 Docker 容器的状态
2. 状态页
状态页是给「别人」看的：把几个监控项挑出来，放到一个公开页面上，还能绑定自己的域名。对个人项目和小团队，这比自己写一个状态页省事得多。
3. 数据存放
Docker 命令里的 -v uptime-kuma:/app/data 就是数据卷。README 特别提醒：不支持 NFS 之类的网络文件系统，要映射到本地目录或卷，否则可能出问题。
4. 通知渠道
README 说有 90 多种。常见的 Telegram、Discord、Slack、邮件都在里面。至于每个渠道的具体配置字段，我没有逐个核实，部署时以界面里的填写项为准。
项目的技术选择
从 README 的自述可以看出作者的几个选择：前端用 Vue 3 加 vite.js，样式用 Bootstrap 5，前后端用 WebSocket 通信，做成单页应用，而不是传统的 REST 接口。翻译由 Weblate 协作完成，文件在 src/lang 下。
局限与注意事项
README 中提到的：
- 不支持网络文件系统（如 NFS）作为数据目录
- 作者不通过邮件提供支持，问题请走 GitHub Issues 或 r/UptimeKuma
- 作者说有很多 PR 在排队，没有足够时间一一测试
uptimekuma.co不是官方网站，也不受项目控制
我补充两点判断：
- 它是单实例工具：监控本身跑在你的一台机器上，如果这台机器或它的网络出问题，监控也会跟着失效。重要的场景最好再配一个外部的探测，或者把 Uptime Kuma 部署在与被监控服务不同的网络
- 深度有限：它擅长「通不通、快不快」这类可用性监控，不是 Prometheus、Grafana 那样的指标与链路监控，别指望它替代
另外，我没有核实 2.x 版本相对 1.x 有哪些不兼容的变化，从旧版升级前请先读发布说明。
赞助与贡献
项目通过 Open Collective 和 GitHub Sponsors 获得资助，README 提到一个特别赞助商 Atlas Cloud，每月提供 400 美元用于使用其 AI 模型。欢迎的贡献包括提 PR、测试 PR 和 Beta 版本、报告 Bug、提需求、翻译和修改语法，后续的计划记录在 GitHub 的里程碑里。
项目地址与资源
- 🌟 GitHub ：github.com/louislam/up...
- 🌐 官网 ：uptime.kuma.pet
- 🎮 在线演示：README 中给出的演示站（数据 10 分钟后清空）
- 💬 社区：GitHub Issues、r/UptimeKuma
- 📄 许可证：MIT
总结与展望
核心要点回顾
- 定位清晰：自托管的可用性监控，Uptime Robot 的开源替代
- 功能够用：十种监控类型、最短 20 秒检查、90 多种通知渠道、可绑定域名的状态页
- 部署简单 ：一条
docker run，或者 Node 加 PM2 - 有明确边界：不支持 NFS，不替代指标监控，单实例本身也可能失效
- 作者的维护带宽有限：PR 排队，支持渠道只有 Issues 和社区
适用人群
- 有个人站点、自建服务，想要低成本监控的开发者
- 小团队内部的服务可用性监控
- 想给产品做一个公开状态页的人
学习建议
先用官方演示站点点一圈，熟悉监控类型和通知设置。然后在一台小机器上用 docker run 装一个，先监控你自己的一个网站，配上 Telegram 或邮件通知，故意把服务停掉，验证告警是否收到。确认可用后，再考虑把状态页绑定到自己的域名上。
欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。
更多实用知识和有趣产品，欢迎访问我的个人主页