开源工具 · 监控与可观测

Uptime Kuma

自托管的服务可用性监控工具，支持 HTTP、TCP、Ping、DNS 与 Push 检测，集中查看响应时间、接收故障通知并发布状态页。

Overview

工具定位

Uptime Kuma 是采用 MIT 许可证的开源自托管监控工具，适合为网站、接口、内网服务和定时任务建立可用性看板。它从部署实例所在的网络发起检测，帮助值班人员发现服务不可达、响应异常或心跳中断。本站按 L1 资料收录，尚未完成部署与通知链路验证。

核心能力

官方仓库列出的探测类型包括 HTTP(S)、页面关键词、JSON 查询、TCP、Ping、DNS、WebSocket、Push、Steam 游戏服务器和 Docker 容器。界面还可能随版本增加其他类型，以当前实例为准，不要把未出现的选项写成已交付能力。

看板：查看可用性、响应时间趋势和证书信息，最短检测间隔为 20 秒，界面支持多语言。
通知：内置 SMTP、Telegram、Slack、Discord、Gotify 等，并包含钉钉、飞书、企业微信、Server 酱、Bark、PushPlus 等渠道；源码通知组件超过 90 个，实际可用项以当前版本界面为准。
状态页：可建立多个状态页，映射到独立域名，仅展示选定分组。
其他：出站代理、两步验证、维护窗口，以及受 Basic Auth 保护的 Prometheus /metrics 接口。

适用场景与选型

适合小型团队的站点巡检、内部服务入口检测，以及通过 Push 心跳观察定时任务是否按时执行。建议先选一个业务健康检查接口作试点，明确检查内容、期望状态码、间隔、超时和重试，再逐步接入其他对象。完整流程见站点可用性探测，验收要点见可用性探测与通知验收。

HTTP 返回成功只代表该次探测符合规则，不能证明全部业务链路正常；容器处于运行状态也不等于应用可服务。需要主机指标、日志定位或复杂告警路由时，结合 Prometheus、Grafana 和 Alertmanager。

Docker Compose 快速开始

以下示例面向全新安装的 Uptime Kuma 2.x，需提前准备 Docker Engine 与 Compose 插件。官方仓库的 compose.yaml 默认把 3001 发布到全部网卡；下面改为只绑定本机，降低误暴露风险。

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data

mkdir uptime-kuma && cd uptime-kuma
# 将上一节内容保存为 compose.yaml 后：
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kuma

在部署主机访问 http://127.0.0.1:3001，创建管理员账号并添加首个监控项。远程访问使用 SSH 隧道或反向代理，不要把管理端口直接放到公网。数据必须落在本地磁盘或本地 volume，官方不支持 NFS。:2 是浮动主版本标签，正式部署应记录经过验证的镜像摘要。默认使用目录内 SQLite；若改用 MariaDB 等外部库，备份计划必须覆盖该库。

非 Docker 安装需要 Node.js ≥ 20.4，可用 PM2 托管 server/server.js。FreeBSD、OpenBSD、Replit 和 Heroku 不在官方支持范围。

监控、通知与状态页配置

添加 HTTP(S) 监控，填写探测实例能访问的健康检查地址，设置超时、重试和间隔。容器中的 localhost 指向容器自身。
仅检查状态码不够时，补充关键词或 JSON 查询。定时任务使用 Push 监控，把含令牌的回调地址当作秘密保管。
需要监视本机容器时，把 /var/run/docker.sock 挂进实例。这会把 Docker 控制权交给该容器，公网暴露时不要启用该探测类型。
配置通知渠道并绑定监控项，先向测试接收端发送，再在授权的测试对象上模拟一次失败与恢复。
为计划内发布设置维护窗口，写明范围、负责人和结束时间。
创建状态页，只加入适合公开的服务名称。用未登录视角检查页面，避免暴露内部地址或令牌。
定期复核接收人、对象和证书临期；降噪思路可参考告警治理知识。

反向代理与访问管理

对外使用独立域名或子域名，经 HTTPS 反代到 127.0.0.1:3001。Uptime Kuma 依赖 WebSocket，代理必须传递 Upgrade 与 Connection。官方不支持把完整应用放在 /uptimekuma 这类子路径。Nginx Proxy Manager 需打开 WebSockets 支持。

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-Real-IP $remote_addr;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 3600s;
}

若实例只能通过代理访问，在「设置 → Reverse Proxy → HTTP Headers」打开 Trust Proxy，以便日志记录真实客户端地址。建议开启两步验证，并限制管理入口来源。/metrics 使用首个管理员的 HTTP Basic Auth，抓取来源应单独限制。

备份、升级与恢复

升级前记录镜像版本和挂载路径。2.x 已移除 JSON 备份/恢复，唯一受支持的方式是停止实例后复制完整 data 目录，并在隔离环境验证可启动。

docker compose pull
docker compose up -d --force-recreate

同一主版本按官方说明重建容器、保留数据卷；升级后核对登录、监控、通知和状态页。v1 升 v2 会改写心跳表，耗时随历史增长，迁移期间不要中断；失败后用升级前备份加对应旧版本在隔离目录恢复，避免旧程序读取已迁移数据。

常见问题

页面能打开但无法登录或实时状态不刷新：优先检查反向代理是否转发 WebSocket。
探测结果与浏览器不一致：确认探测点网络、出站代理和目标地址，而不是在容器里填 localhost。
通知模板升级到 2.x 后变量不替换：SMTP 正文改用 LiquidJS，变量区分大小写。

使用边界与收录状态

单个探测点只反映它所在网络的可达性，不能把该点可用率解释成所有用户的体验。本站未完成部署与通知验证，在线体验关闭，发布版本留待实际核验。

官方资料

资料核对日期：2026-09-17。安装和升级前请再次查看对应版本说明。