Uptime Kuma：开源自建监控工具的核心功能与部署指南

是什么

Uptime Kuma 是由开发者 Louis Lam 创建的一款开源自建（Self-hosted）监控应用。在系统管理与网站开发领域，“自建”是指将应用程序安装并运行在自己的本地计算机、家庭实验室（HomeLab）或私有虚拟服务器上，而不是依赖第三方商业云厂商来托管和管理服务。

根据项目仓库的说明，作者开发 Uptime Kuma 的初衷，是为了寻找一款类似于商业服务 Uptime Robot 的自建可用性追踪工具。在此期间，作者曾考虑过另一款开源工具 Statping，但由于该工具当时变得不够稳定且已停止积极维护，作者便决定打造一款现代化的替代方案，并把重点放在反应灵敏且视觉精致的界面体验上。

该应用基于现代前端与网络技术构建。在用户界面层面，它整合了 Vue 3、Vite.js 以及 Bootstrap 5 样式。Uptime Kuma 没有采用传统的 REST API（即由网页客户端不断发送独立的 HTTP 请求来获取服务器状态），而是设计为通过 WebSockets 通信的单页面应用（SPA）。单页面应用只需加载一次页面即可动态更新展示信息，而 WebSockets 则在用户浏览器与服务器之间建立了一条持久的双向通信通道。这种架构让实时监控指标能够直接推送到屏幕上，无需用户手动刷新网页。

如果希望在实际部署前查看界面的运行效果，该项目在德国法兰克福托管了一个临时在线演示环境，可通过项目演示链接访问。该演示环境会在 10 分钟后自动清除所有记录的数据，其运行资金来自社区赞助。

能做什么

Uptime Kuma 具备监控多种网络服务及线上基础设施的运行状态、可用性与响应特性的能力。根据项目 README 的介绍，该软件提供了一个精美、交互流畅且响应迅速的界面和使用体验，并完整支持浅色与深色两种显示模式。

其监控引擎支持丰富的检测类型与网络协议：

• HTTP 与 HTTPS 端点：监控常规网站 URL 的连通性及响应状态码。除基础可用性检测外，管理员还可以设置关键字搜索以确认返回的页面内容中包含预期文本，或通过 JSON 查询对结构化 API 响应中的特定字段进行校验。
• TCP 连接：基于传输控制协议（TCP）检测网络连通性，验证远程服务器上的指定端口是否能够正常建立连接。
• Ping 监控：发送网络 Ping 请求检测目标主机是否在线，并在交互式图表上记录网络响应延迟。
• DNS 记录：检测域名系统（DNS）记录，确保域名能够正确解析到预期的 IP 地址或记录值。
• WebSocket 连接：连接至 WebSocket 端点，验证实时长连接通道是否保持开启且响应正常。
• Push 监控：提供被动“心跳”检测机制，允许外部后台作业、自动化脚本或定时任务主动向 Uptime Kuma 发送 HTTP 请求。若在预定周期内未收到预期的打卡请求，系统将触发警报。
• 游戏服务器与容器：为 Steam 游戏服务器以及本地 Docker 容器提供了专属监控支持。

该应用的检测频率最高可设为每 20 秒一次。除了正常运行时间外，它还会提取并显示 SSL/TLS 证书信息，帮助管理员监控证书有效性与到期时间，从而预防突发的服务中断。

为了向外部访客或内部团队展示运行指标，Uptime Kuma 支持创建多个独立的状态页。管理员可以自定义这些页面，并为其绑定专属域名。

当监控服务发生故障或恢复正常时，Uptime Kuma 支持将通知推送到 90 多种服务渠道。项目文档中列出的示例包括 Telegram、Discord、Gotify、Slack、Pushover，以及基于 SMTP 的常规电子邮件等。

在运维安全与权限管理方面，该软件内置了双因素身份验证（2FA）支持，在登录时要求提供二次验证码以强化账户安全。它还支持代理设置，在需要时可通过中间代理服务器发送监控请求，并依托 Weblate 平台由社区贡献者协作完成了多语言本地化。

怎么开始

Uptime Kuma 根据不同的基础设施偏好提供了多种安装途径。项目官方文档记录的主要部署方式包括：Docker Compose、单条 Docker 命令，以及基于 Node.js 与 PM2 的非容器化部署。

Docker Compose 部署

使用 Docker Compose 是启动该服务的一种便捷方式。使用此方法安装时，只需创建一个专属目录，获取官方配置文件并启动容器：

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

容器启动后，Uptime Kuma 会在所有网络接口上监听 3001 端口，可以在浏览器中通过 http://localhost:3001 或 http://your-ip:3001 访问。

官方文档特别强调了一项关键的存储注意事项：系统不支持 NFS（网络文件系统）等网络共享存储。存储目录必须挂载在本地磁盘或原生的本地 Docker 数据卷上，以避免数据库发生异常。

单条 Docker 命令部署

如果不使用 Docker Compose，也可以直接通过单条 Docker CLI 命令来启动容器：

docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

默认情况下，该命令会将 3001 端口映射到所有网络接口。如果希望限制为仅允许本机访问，可以调整端口映射参数：

docker run ... -p 127.0.0.1:3001:3001 ...

非容器化环境安装

在未采用容器技术的环境中，Uptime Kuma 也可以直接安装在宿主操作系统上。此方式需要系统中已安装 Git、Node.js 20.4 或更高版本，以及 PM2（用于保证 Node.js 应用在后台持续运行的生产环境进程管理器）。

克隆并初始化项目：

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

# Option 1. Try it
node server/server.js

# (Recommended) Option 2. Run in the background using PM2
# Install PM2 if you don't have it:
npm install pm2 -g && pm2 install pm2-logrotate

# Start Server
pm2 start server/server.js --name uptime-kuma

服务启动后，即可通过 3001 端口访问 Web 仪表盘。对于使用 PM2 管理进程的管理员，项目文档还提供了常用的维护命令：

# If you want to see the current console output
pm2 monit

# If you want to add it to startup
pm2 startup && pm2 save

如果需要配置反向代理或特殊网络路由等进阶部署，可参考项目 Wiki 文档中的详细安装指南与更新指南。

价格与门槛

根据项目仓库元数据记载，Uptime Kuma 是一款基于 MIT 许可证分发的开源软件。关于商业服务、赞助或官方托管方案的具体细节，均以其官方网站 uptime.kuma.pet 的公布信息为准。

部署和运行该软件需满足特定的平台与运行时条件：

• 支持的操作系统：支持 Debian、Ubuntu、Fedora、ArchLinux 等主流 Linux 发行版。在 Windows 环境下，支持 64 位版本的 Windows 10、Windows Server 2012 R2 或更高版本。
• 不支持的环境：项目文档明确指出不支持类 BSD 系统（FreeBSD、OpenBSD、NetBSD）。此外，Replit 和 Heroku 等无容器（Containerless）托管平台也已被列为不支持的环境。
• 运行环境与依赖工具：若采用非 Docker 方式安装，系统需要配备 20.4 或更高版本的 Node.js、Git 版本控制工具，以及配合 pm2-logrotate 插件运行的 PM2 进程管理器。
• 文件系统限制：文件数据必须存放在本地文件系统或常规本地数据卷中，明确不支持 NFS（网络文件系统）挂载存储。

适合谁

Uptime Kuma 适合希望全面掌控自身监控基础设施、不依赖外部商业 SaaS 服务的系统管理员、DevOps 工程师、HomeLab 爱好者以及 Web 开发者。由于该软件完全在私有设施上运行，因此特别适合用于监控内部局域网、本地 Docker 容器以及公网云扫描器无法触及的内网受保护服务器。

该应用同样适用于需要向公众或客户同步运行状态的组织机构。团队可以通过自定义独立状态页并绑定专属域名，向客户或内部相关人员实时展示服务可用性。

此外，Uptime Kuma 也非常适合开源贡献者与社区维护者。用户可以参与测试 Pull Request、评估测试版、通过 Weblate 提交多语言翻译，或在项目 Subreddit 论坛（r/UptimeKuma）和 GitHub Issues 中与同行交流并获取支持。

替代品

• Gatus 是一套可选的服务监控工具。
• Healthchecks 是另一个用于监控系统健康状态的备选工具。

来源

• https://github.com/louislam/uptime-kuma
• https://github.com/TwiN/gatus
• https://github.com/healthchecks/healthchecks