Uptime Kuma —— 自托管轻量拨测与状态页工具

分类：02 可视化与告警呈现 适用：Linux / Windows / 容器；个人、小团队、边缘节点的可用性拨测与对外状态页（数十至数百探针） 一句话：用 HTTP/TCP/Ping/DNS 等拨测判断服务存活，秒级发现故障并推送 90+ 种通知、生成公开状态页 官方：https://uptime.kuma.pet　GitHub：https://github.com/louislam/uptime-kuma 授权：MIT License（完全开源免费）

1. 它解决什么问题

• 没有外部可用性视角：服务内部指标正常不代表用户能访问；Uptime Kuma 从外部主动拨测 URL、端口、DNS、ICMP，判断「用户视角是否可用」。
• 自建服务不想买 SaaS：替代 UptimeRobot 类托管服务，数据、状态页、通知全在自己机器上。
• 告警配置繁琐：Web UI 点选即建监控、绑定通知，最快 20 秒一次心跳，无需写 exporter 规则。
• 对外沟通缺窗口：内置多套公开状态页、自定义域名、事件公告与维护公告，故障时可向客户同步进展。
• 证书悄悄过期：自动检查 HTTPS 证书剩余天数并提前提醒。
• 边界：它是可用性拨测（黑盒），不采集主机指标、不存时序指标库、不做日志分析；指标/日志要交给 Prometheus、Loki 等。

2. 核心概念与架构

 拨测调度器 (Uptime Kuma / Node.js)              存储与展示
 ┌────────────────────────────────────┐      ┌──────────────────────────────┐
 │ Monitor(类型+间隔+重试+通知绑定)    │ 写入 │ SQLite / MariaDB: ./data     │
 │   │ 定时触发                       │─────►│ kuma.db, db-config.json      │
 │   ▼                                │      └──────────┬───────────────────┘
 │ Heartbeat(HTTP/TCP/Ping/DNS 探测)  │                 │ 查询
 │   │ 判定 UP / DOWN                 │      ┌──────────▼───────────────────┐
 │   ▼                                │      │ Dashboard(实时曲线/历史)     │
 │ Event(状态变化，去抖后)            │      │ Status Page(/status/<slug>)  │
 │   │ 匹配已绑定的 Notification      │      │ Badge / Push API / 证书到期  │
 │   ▼                                │      └──────────────────────────────┘
 │ 通知渠道: 邮件/企微/钉钉/Slack/Webhook │
 └────────────────────────────────────┘

核心链路：monitor（声明目标与调度）→ heartbeat（按间隔实际拨测、记录 RTT 与状态）→ event（状态翻转且通过重试去抖后生成）→ notification（按监控项绑定的渠道投递，DOWN/UP 各一次）→ 展示层（Dashboard、Status Page、Badge）。通知按事件而非按心跳发送，避免刷屏；维护窗口期间暂停事件或通知。

数据模型：单体 Node.js 服务（Express + Socket.IO），元数据与心跳历史存本地 ./data（V2 可选 SQLite 或 MariaDB/MySQL，首次启动向导选择，配置落在 db-config.json）。官方主要交互是 Web UI 与 Socket.IO，公开 REST 端点集中在 Push、Status Page、Badge 与（部分版本提供的）指标导出；监控项的增删改以 UI/Socket.IO 为主，批量自动化建议用社区封装的 Socket.IO 客户端或导入/导出功能，端点与参数以官方文档为准，勿臆造 CRUD API。

3. 安装与部署

3.1 环境准备

3.2 多种安装方式

# A. Docker（官方 README 形态）
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma \
  louislam/uptime-kuma:2
# 生产建议仅绑定本地回环，由反向代理对外（Docker 发布端口会绕过 ufw/firewalld）
docker run -d --restart=unless-stopped -p 127.0.0.1:3001:3001 \
  -v /opt/uptime-kuma/data:/app/data -e TZ=Asia/Shanghai --name uptime-kuma \
  louislam/uptime-kuma:2

# B. Docker Compose（推荐；也可用官方 compose.yaml）
mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
# 自写最小 compose.yaml：
# services:
#   uptime-kuma:
#     image: louislam/uptime-kuma:2
#     container_name: uptime-kuma
#     restart: unless-stopped
#     ports: ["127.0.0.1:3001:3001"]
#     volumes: ["./data:/app/data"]
#     environment: [TZ=Asia/Shanghai]
docker compose up -d && docker compose ps && docker compose logs -f uptime-kuma

# C. 源码 + PM2 / systemd（无 Docker；项目无预编译二进制，用 Node 源码跑）
git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma-src
cd /opt/uptime-kuma-src && npm run setup
npm install -g pm2 && pm2 start server/server.js --name uptime-kuma && pm2 save
# systemd 单元 /etc/systemd/system/uptime-kuma.service：
# [Service]
# Type=simple
# WorkingDirectory=/opt/uptime-kuma-src
# ExecStart=/usr/bin/node server/server.js
# Restart=on-failure
# User=uptime-kuma
# Environment=DATA_DIR=/opt/uptime-kuma/data
sudo systemctl daemon-reload && sudo systemctl enable --now uptime-kuma

# D. K8s：官方未提供独立 Helm Chart（以官方仓库为准）；可用社区 chart 或自建
# Deployment：image louislam/uptime-kuma:2，containerPort 3001，PVC 挂 /app/data（ReadWriteOnce）
# Service + Ingress：Ingress 需开启 WebSocket 支持（nginx.ingress.kubernetes.io/proxy-read-timeout 等）
kubectl apply -f deployment.yaml && kubectl get pod -l app=uptime-kuma

精确版本号、镜像 tag 以官方最新稳定版为准（当前大版本线 2.x，见 GitHub Releases）；V1 → V2 涉及数据库变更，升级前务必看官方升级说明。

3.3 首次启动与验证

curl -I http://127.0.0.1:3001                       # HTTP 200
docker compose logs uptime-kuma | grep -i "Uptime Kuma Version"
docker ps --filter name=uptime-kuma --format '{{.Status}}'
# 浏览器 http://<主机>:3001：V2 首次向导选择数据库（SQLite 最简单）→ 创建管理员账号
# ⚠️ 若端口对公网开放，务必启动后第一时间建管理员，否则任何人都能抢注
# 验证：新建 HTTP(s) 监控指向一个可达 URL，等一个间隔后看到绿色 UP 与 RTT 曲线

4. 配置文件详解

Uptime Kuma 没有传统 ini/yaml 主配置，配置主要存在数据库与 Web UI 中；容器场景用环境变量与卷控制运行参数。

最小可运行示例 compose.yaml：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"     # 仅本机可达，由 nginx 反代对外
    volumes:
      - ./data:/app/data           # 必须本地盘，勿 NFS/SMB
    environment:
      - TZ=Asia/Shanghai
      # - UPTIME_KUMA_PORT=3001

反向代理示例（WebSocket 必须透传，否则实时曲线与登录 400）：

server {
    listen 443 ssl;
    server_name status.example.com;
    ssl_certificate     /etc/ssl/certs/status.crt;
    ssl_certificate_key /etc/ssl/private/status.key;
    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

5. 核心使用方法

各类 Monitor 配置参数（UI：Dashboard → Add New Monitor）：

通用参数：Friendly Name、Heartbeat Interval（默认 60s，最小 20s）、Retries（失败重试次数）、Heartbeat Retry Interval、Request Timeout、Upside Down Mode（反转状态，用于「期望不可达」）、证书到期提醒、Maintenance 绑定、Notifications（可勾 Default enabled / Apply on all existing monitors）。

公开 API / 状态页用法：

BASE=http://127.0.0.1:3001
# 1 Push 心跳（Push Monitor；参数以官方文档为准）
curl -s "$BASE/api/push/<pushToken>?status=up&msg=OK&ping=12"
curl -s "$BASE/api/push/<pushToken>?status=down&msg=disk%20full"
# 2 状态页数据（JSON，供第三方渲染）
curl -s "$BASE/api/status-page/<slug>" | jq .
# 3 状态页页面（浏览器/iframe）
curl -I "$BASE/status/<slug>"
# 4 徽章（状态 / uptime / 响应时间，路径参数以官方 API 文档为准）
curl -s "$BASE/api/badge/<monitorId>/status" -o status.svg
curl -s "$BASE/api/badge/<monitorId>/uptime" -o uptime.svg
curl -s "$BASE/api/badge/<monitorId>/ping" -o ping.svg
# 5 健康检查（无独立 /health 时用首页）
curl -s -o /dev/null -w '%{http_code}\n' "$BASE/"
# 6 证书到期（UI 展示；也可在状态页 JSON 中查看相关字段）
curl -s "$BASE/api/status-page/<slug>" | jq '. | keys'
# 7 备份数据目录（⚠️ 先停容器再拷，避免 SQLite 写一半）
docker compose stop uptime-kuma && tar czf kuma_$(date +%F).tgz ./data && docker compose start uptime-kuma
# 8 容器运维
docker compose ps ; docker compose logs -f uptime-kuma ; docker compose restart uptime-kuma
# 9 非 Docker 服务
sudo systemctl {start|stop|restart|status} uptime-kuma ; pm2 logs uptime-kuma
# 10 查看版本
docker exec uptime-kuma cat /app/package.json | grep '"version"'
# 11 清理旧镜像/查看卷
docker volume ls ; docker system df
# 12 进入容器排查网络（容器内 localhost 是自身）
docker exec -it uptime-kuma sh -c "curl -I https://<目标域名>"
# 13 查看容器资源占用
docker stats --no-stream uptime-kuma
# 14 端口监听确认
ss -lntp | grep 3001
# 15 查看 V2 数据库配置
docker exec uptime-kuma cat /app/data/db-config.json
# 16 查看 SQLite 表（确认心跳表存在）
sqlite3 ./data/kuma.db ".tables"
# 17 从容器内测试通知网关连通性
docker exec -it uptime-kuma sh -c "curl -I https://oapi.dingtalk.com"
# 18 验证目标可达性与耗时
docker exec -it uptime-kuma sh -c "curl -sS --connect-timeout 5 -o /dev/null -w '%{http_code}\n' https://<目标域名>"
# 19 查看镜像元数据
docker image inspect louislam/uptime-kuma:2 --format '{{.Config.Labels}}'
# 20 容器内时区与当前时间
docker exec uptime-kuma date
# 21 确认数据卷挂载点（备份前核对）
docker inspect uptime-kuma --format '{{json .Mounts}}' | jq .
# 22 升级前拉取新镜像（tag 以官方 Releases 为准）
docker compose pull uptime-kuma

API 使用说明：监控项的创建/编辑/删除没有官方稳定的 REST CRUD（走 Socket.IO 事件），上表端点为公开可用的 Push / Status Page / Badge / 首页探测；若需批量自动化，请用 UI 的导入导出或社区 Socket.IO 客户端，具体事件名以官方仓库与 Wiki 为准。

Web UI 操作路径：Add New Monitor；Settings → Notifications（新建渠道并 Test）；Settings → Maintenance；Status Pages → Add New Status Page（slug、域名、展示监控、事件公告）；Settings → Security（改密、2FA、禁用登录）；Settings → Monitor History（清理历史）；Settings → Proxies；Settings → General（时区/主题）。每个监控详情页可看 24h/30d uptime、Ping 图表、证书信息与历史事件。

6. 告警与通知

触发逻辑：心跳失败 → 达到 Retries 次数且重试间隔内仍失败 → 生成 DOWN 事件 → 向该 Monitor 已绑定的 Notification 投递（默认只发一次状态变化）→ 恢复时发 UP/Recovery 通知。阈值由「超时 + 可接受状态码 + 关键字/Json 期望值 + 重试次数」共同构成。

# Webhook 自定义 body 示例（模板变量语法以官方通知文档为准）
# 企业微信：{"msgtype":"markdown","markdown":{"content":"**{{ monitor.name }} {{ status }}**\n> {{ msg }}"}}
# 钉钉：{"msgtype":"text","text":{"content":"[{{ status }}] {{ monitor.name }}: {{ msg }}"}}
# 通用 Webhook 可把同一 payload POST 到值班平台/IM 网关，实现升级与工单联动

静默 / 升级 / 去重：

• 去重：Retries + Heartbeat Retry Interval 抑制瞬时抖动；通知只在状态翻转时发送，恢复另发一条，不会每个心跳都推。
• 静默：Maintenance 窗口按 cron/时间段暂停拨测或静默通知，状态页自动显示维护公告；也可临时停用某条通知或解绑监控。
• 多渠道：同一 Monitor 绑定多个 Notification（如邮件 + 企微 + Webhook）并行投递；Settings → Notifications 可设 Default enabled 与 Apply on all existing monitors 批量绑定。
• 升级：原生无多级升级/值班轮换路由，复杂升级通过 Webhook 把事件转发到 On-call/工单平台实现；重复提醒可在部分通知类型中配置，以界面提供项为准。
• 测试：每个通知渠道都有 Test 按钮，配置后务必先发测试消息再绑定到生产监控。

7. 实战场景

场景一：核心站点 HTTP 拨测 + 钉钉告警 + 对外状态页

# 目标：每 60s 探 https://www.example.com/health，2 次重试后 DOWN 发钉钉，客户看状态页
# 步骤1：UI Add New Monitor → HTTP(s)
#   URL=https://www.example.com/health；Heartbeat Interval=60；Retries=2；
#   Heartbeat Retry Interval=60；Request Timeout=10；Accepted Status Codes=200-299
# 步骤2：Settings → Notifications → 新建钉钉（Webhook URL + 加签/关键字）→ Test 通过
# 步骤3：回监控详情勾选该通知；Status Pages → Add，slug=public，勾选该监控与证书信息
# 验证
curl -s -o /dev/null -w '%{http_code}\n' "$BASE/status/public"
curl -s "$BASE/api/status-page/public" | jq .
# 用防火墙临时阻断目标，或在测试环境停掉服务，确认 2 次重试后收到 DOWN、恢复后收到 UP
# 回滚：停用该 Monitor（Pause）→ 删除通知绑定 → 删除状态页；数据不受影响

场景二：内网设备用 Ping / TCP / DNS 组合拨测

# 目标：交换机、数据库端口、DNS 解析三合一可用性
# 步骤：分别 Add New Monitor
#   Ping：Hostname=10.0.0.1，Interval=60，Retries=3
#   TCP Port：Hostname=10.0.0.2，Port=3306，Timeout=5
#   DNS Record：Hostname=api.example.com，Resolver Server=10.0.0.53，Record Type=A，期望结果=10.0.1.10
# 注意：容器内 localhost 指向自身，内网目标写实际 IP；拨测端防火墙放行 ICMP/53/3306
# 验证：docker exec -it uptime-kuma sh 内用 ping / nc / nslookup 复测连通性
# 回滚：Pause 或删除三条 Monitor；导出配置备份 ./data 后再做批量变更

场景三：无法被主动访问的目标用 Push 心跳

# 目标：NAT 后的定时任务/边缘设备主动上报存活，超时未报即告警
# 步骤1：UI Add New Monitor → Push，记下生成的 Push URL 与 token，设 Heartbeat Interval=300（5 分钟）
# 步骤2：被监控端加 crontab
# */5 * * * * curl -fsS "https://status.example.com/api/push/<pushToken>?status=up&msg=cron-ok" >/dev/null
# 步骤3：绑定邮件 + Webhook 通知
# 验证：等一个周期看 UP；手工停 crontab 超过一个周期后应转 DOWN 并告警
# 回滚：停用 crontab 条目并 Pause 该 Monitor；⚠️ token 等同凭据，泄露后需在 UI 重置

8. 日常运维与故障排查

docker compose {up -d|ps|logs -f|restart|stop|start} uptime-kuma   # 容器服务管理
sudo systemctl {start|stop|restart|status} uptime-kuma              # 源码/systemd 安装
pm2 logs uptime-kuma ; pm2 restart uptime-kuma                      # PM2 方式
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/     # 健康检查
docker compose logs uptime-kuma | grep -iE 'error|version'            # 日志关键字
du -sh ./data && df -h ./data                                        # 数据目录容量
sqlite3 ./data/kuma.db "select count(*) from heartbeat;"              # 心跳条数（SQLite）

9. 性能、容量与高可用

• 规模：官方给出的参考配置（约 25 个混合探针）为 1 vCPU / 1GB 起、2 vCPU / 2GB 更稳；探针越多、间隔越短、心跳历史越长，CPU/磁盘增长越明显。
• 查询/大盘性能：Dashboard 曲线与状态页按时间范围聚合，缩短默认范围、减少单页监控数；定期在 Settings → Monitor History 清理旧心跳。
• 数据库选型：SQLite 适合单实例小规模；V2 可选 MariaDB/MySQL 以支撑更多并发写入与更大历史量（首次启动向导选择，配置存 db-config.json）。⚠️ SQLite 数据目录必须本地盘。
• 缓存与 HA：单体应用、无内置集群与原生 HA；生产用「单实例 + 本地持久卷 + 反代 TLS」，通过定期备份与快速重建实现恢复；不建议多实例共写同一 SQLite。更高可用可评估外部数据库 + 主备实例，以官方说明为准。
• 自监控：给 Uptime Kuma 自身建一个 HTTP 监控（指向 /）与一个 Push 心跳；另用外部监控告警「监控自身失联」，避免单点盲区。
• 容量：./data 预留 20GB+ 并监控 df -h；心跳历史是主要增长源，配合保留策略与归档。

10. 安全加固、备份与升级

• 首次与认证：启动后立刻创建管理员；开启 2FA 并妥善保存恢复码；关闭不必要的注册/登录入口；密码用强口令。
• 网络暴露：容器端口绑 127.0.0.1:3001:3001，由反代对外；⚠️ Docker 发布端口会绕过 ufw/firewalld，切勿把未初始化实例直接暴露公网。
• TLS 与代理：反代终结 TLS（第 4 章）；状态页自定义域名配证书；出向拨测可走 Proxy；仅放行必要来源访问管理后台。
• 最小权限：容器以非 root 用户运行、只挂 ./data；db-config.json 与 kuma.db 权限收紧；Push token、机器人 token、SMTP 密码视为凭据，泄露即重置。
• 备份与恢复：

# ⚠️ 必须停服后再打包，否则 SQLite 可能处于写入中间状态
docker compose stop uptime-kuma
tar czf /backup/kuma_$(date +%F).tgz -C /opt/uptime-kuma ./data
docker compose start uptime-kuma
# 恢复：停服 → 移走新 data → 解压备份到 ./data → 启动 → 登录核对监控与历史
# 也可在 UI 用 Settings → Backup（导入/导出配置，以界面提供项为准）

• 升级与回滚：先在测试环境验证；备份 ./data；改 compose 中的镜像 tag（如 :2 指向的新版本，具体 tag 以官方 Releases 为准）→ docker compose pull && up -d → 登录核对监控数量、通知与状态页。回滚 =「停服 + 恢复 ./data 备份 + 装回旧镜像」，⚠️ V1→V2 或跨大版本的数据库结构升级通常不可逆，旧版本打不开新库；官方未提供 LDAP/OAuth 原生集成（如版本提供以官方文档为准），统一认证用反代前置 SSO。

11. 常见坑

12. 速查表

13. 选型建议与同类对比

何时选：自建服务、边缘节点、小团队想零成本拿到「可用性拨测 + 多通知 + 对外状态页」，且不想维护 Prometheus/ES；需要 20s 级快速发现与证书到期提醒。 何时不选：已有成熟 Prometheus 体系、要把拨测进 PromQL/统一告警路由（用 Blackbox Exporter + Alertmanager）；需要成百上千探针的企业级 HA、多租户与审计（考虑商业 SaaS 或一体化平台）；需要主机指标、日志、APM 全栈观测（Uptime Kuma 只做黑盒可用性，需与 Prometheus/Loki 组合）。

14. 参考链接

• 官网：https://uptime.kuma.pet
• GitHub 仓库：https://github.com/louislam/uptime-kuma
• 官方 Wiki：https://github.com/louislam/uptime-kuma/wiki
• README：https://github.com/louislam/uptime-kuma/blob/master/README.md
• Releases（版本与升级说明）：https://github.com/louislam/uptime-kuma/releases
• 官方 compose.yaml：https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
• Docker Hub 镜像：https://hub.docker.com/r/louislam/uptime-kuma
• Issues（故障排查）：https://github.com/louislam/uptime-kuma/issues