Uptime Kuma 监控搭建完整指南

用 Docker 搭建 Uptime Kuma v2,配置 HTTP 探测、重试、通知与状态页,备份数据并判断单节点探测的覆盖范围。

最佳实践
分布在不同地区的服务与监测链路示意图

Uptime Kuma 是一款开源、自托管的可用性监控工具,界面漂亮、部署简单,被称为"自托管版的 UptimeRobot"。适合个人项目、小团队快速搭建监控与状态页。本文带你从零跑通完整流程。

准备工作

一台能运行 Uptime Kuma v2 镜像的 Docker 主机。默认使用 SQLite 时,数据卷应落在支持 POSIX 文件锁的本地文件系统上,避免使用存在锁兼容问题的 NFS 共享目录。

docker --version   # 确认 Docker 可用

第一步:Docker 一键部署

docker run -d --restart=unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

参数解读:

  • -d:后台运行;
  • --restart=unless-stopped:Docker 按重启策略拉起容器,手动停止的容器保持停止。它依赖宿主机和 Docker 正常运行;
  • -p 127.0.0.1:3001:3001:宿主机回环地址的 3001 端口 → 容器 3001;
  • -v uptime-kuma:/app/data:数据卷持久化,删容器不丢配置;
  • --name uptime-kuma:容器命名,方便管理。

在 Docker 主机上打开 http://127.0.0.1:3001 创建管理员账号。远程初始化可用 SSH 端口转发。Docker Engine 28.0.0 以前,同一二层网络的其他主机仍可能访问发布到回环地址的端口。Docker 端口发布说明

需要对外提供 HTTPS 时,可在前面部署支持 WebSocket 转发的反向代理。官方安装说明 · 反向代理配置

:2 用于新装 v2。已有 v1 实例升级前先停止容器、备份整个数据目录,再用原数据卷创建 v2 容器,查看迁移日志。迁移期间不要启动第二个写入同一 SQLite 卷的实例。回退时用升级前备份恢复到单独的卷,再以原版本启动。v1 到 v2 迁移说明

第二步:创建监控器

点"添加监控项",常用类型:

  • HTTP(s):填 URL,设置探测间隔(新建监控器默认 60 秒)、重试次数和接受的 HTTP 状态码。需要匹配响应正文时选择 HTTP(s) - Keyword;
  • TCP 端口:检查数据库端口(3306/5432)、SSH(22)等能否建立 TCP 连接。查询或登录能否成功,需要另行验证;
  • Ping:检查目标是否响应 ICMP。网络策略可能屏蔽 ICMP;
  • DNS:通过指定的解析器查询所选记录类型;
  • Docker 容器:通过已配置的 Docker 主机检查容器状态,以及容器提供的健康检查结果。连接 Docker API 涉及宿主机权限。

第三步:配置通知

设置 → 通知,支持几十种渠道:Telegram、Slack、Discord、邮件、Webhook、企业微信等。配置后点"测试"确认能收到,再把通知绑定到各监控器上。渠道测试只能证明测试消息可达。用一个测试监控项触发真实失败与恢复,检查重试期间的 Pending 状态以及转为 Down 后的通知。

第四步:搭建状态页

"状态页"功能可以把选定监控器的可用性公开成一个页面(类似 status.example.com):分组展示服务、显示近期可用率与事件信息。公开前确认展示名称、事故说明与访问范围。同一 Kuma 实例提供的状态页会受到该实例自身故障的影响。

Uptime Kuma 的局限:什么时候该换

开源单机架构决定了它的边界:

  • 单点问题:监控工具本身跑在一台机器上,那台机器挂了 = 监控全盲。而它监控的对象往往就包括那台机器所在的基础设施;
  • 本地探测点:普通 HTTP、TCP 等监控项从 Kuma 实例所在网络发起。结果只代表该路径。v2 提供单独的 Globalping 监控类型,需要按其支持的探测方式另行配置;
  • 权限边界:对外发布状态页与开放后台管理是两项独立的权限决策;
  • 数据关联:Kuma 有探测记录和可用率。排查时若要关联应用日志、链路等数据,需要在对应平台接入;
  • 容量:并发探测与历史数据的成本取决于监控类型、频率、超时与保留策略。

个人项目与小团队内部系统,Uptime Kuma 完全够用;面向客户的核心业务,需要多地域、高可用、与可观测性数据打通的平台。

如果需要由外部节点验证 Uptime Kuma 所在网络之外的访问情况,可另外配置观测云 HTTP 拨测。对同一业务路径使用一致的可用判断条件,比较内外两处结果,再检查各自的 DNS、TLS 与入口路径。日志和链路的排查入口仍需事先接入并按服务与时间核对。

常见问题(FAQ)

Q:Uptime Kuma 数据怎么备份?
A:下面以本地 Docker 卷中的 SQLite 数据为例。先停 Kuma,再以只读方式挂载数据卷进行归档。命令会暂时中断探测和同实例提供的状态页。归档校验通过后重新启动,并将备份保存在独立位置。

docker stop uptime-kuma &&
docker run --rm \
  -v uptime-kuma:/data:ro -v "$PWD:/backup" \
  busybox:1 tar -czf /backup/kuma-backup.tar.gz -C /data . &&
tar -tzf kuma-backup.tar.gz &&
docker start uptime-kuma

归档或校验失败时,先手动执行 docker start uptime-kuma 恢复监控,再重做备份。升级前应拿到可读的备份。如果配置了外部数据库,还需要按该数据库的流程另行备份。

Q:能监控内网服务吗?
A:这正是自托管的优势——Uptime Kuma 部署在内网就能探测内网地址。观测云同样支持自建拨测节点覆盖内网。

Q:Uptime Kuma 挂了谁来报警?
A:在另一台主机或外部服务上,探测能从那里访问的 Kuma HTTPS 页面或独立心跳。单测 TCP 端口只能验证连接,访问路径也不必公开管理端口。报警渠道应能独立送达。

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台