Uptime Kuma 自托管监控体系搭建指南：HTTP、TCP 与 Push 监控

自托管环境往往同时运行多个服务，不能每次都靠人肉检查「还活着吗」。本文讲 Uptime Kuma 监控体系的搭建——从 v1 升级到 v2、三种监控类型的设计、SSH 探针的 Push 监控，以及 TCP Monitor 的一个前端坑。

为什么选 Uptime Kuma

选型标准很直接：开源、自托管、Docker 部署、支持多种监控类型、有告警通知。Uptime Kuma 完全满足，而且 UI 做得不错。

部署很简单，一个 Docker 容器，数据持久化到命名卷：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    volumes:
      - uptime-kuma-data:/app/data
    ports:
      - "127.0.0.1:3001:3001"   # 只监听本地，由 Traefik 反代

注意端口绑定到 127.0.0.1——Uptime Kuma 只通过 Traefik 反代到 status.example.com 访问，受 Authelia 保护，不直接暴露。

从 v1 升级到 v2

升级很简单：镜像标签从 louislam/uptime-kuma:1 改为 louislam/uptime-kuma:2，然后 docker compose up -d。数据卷兼容，配置自动迁移。

但有一个细节：v2 的 API 路径变了，之前用浏览器自动化脚本建的 Monitor 需要确认是否正常工作。升级后逐一检查所有 Monitor 状态，确认无异常。

三种监控类型

1. HTTP(S) 监控：域名可达性

最基础的监控类型——定期 curl 域名，检查返回状态码。

为所有对外域名各建立一条 HTTP 监控即可，下面是几条典型示例：

注意：Uptime Kuma 监控的是经过 Traefik 反代 + Authelia 认证的完整链路。如果 Authelia 挂了，所有受保护域名的监控都会告警——这正是我们想要的，因为 Authelia 挂了意味着用户无法访问所有管理面板。

对于需要认证的域名，Uptime Kuma 的 HTTP 监控会收到 302 跳转（到 Authelia 登录页），这是正常的。可以把期望状态码设为可接受 200/301/302/303/307/308/401/403/404 中的任何一个——只要不是连接失败（000）或 5xx 服务器错误，都算正常。

2. TCP Port 监控：内网服务可达性

有些服务不对外暴露 HTTP 端口，但需要确认端口在监听：

为什么不能直接用 127.0.0.1？因为 Uptime Kuma 运行在 Docker 容器里，容器内的 127.0.0.1 是容器自己，不是宿主机。要访问宿主机端口，需要用 host.docker.internal（在 compose 中通过 extra_hosts 映射）或 Docker 桥接网络的网关地址（即宿主机在 Docker 网络中的地址）。

3. Push 监控：SSH 探针

这是最特殊的一种——不是 Uptime Kuma 主动去检查，而是外部探针主动推送心跳。

原理：
1. Uptime Kuma 创建一个 Push 类型的 Monitor，生成一个带 token 的 Push URL。
2. 宿主机上的探针脚本每 2 分钟执行一次 SSH 连接测试，成功后向 Push URL 发送 HTTP 请求。
3. Uptime Kuma 记录心跳。如果超过 3 分钟没收到心跳，判定为宕机并告警。

crontab (*/2) → ssh-probe.sh → SSH 连接 probe@localhost
                                    ↓ 成功
                              curl "$PUSH_URL"
                                    ↓
                              Uptime Kuma 记录心跳

这种设计的好处在前面的安全加固一文里讲过——探针验证的是完整 SSH 认证链路。

TCP Monitor 类型选择 Bug

用浏览器自动化脚本批量建 Monitor 时，容易踩到 Uptime Kuma 的一个前端 bug。

现象：点击「Monitor Type」下拉框选择「TCP Port」后，下拉框显示的值没变，提交后 Monitor 的类型字段为空或报 "Unknown Monitor Type"。

根因：Uptime Kuma 前端是 Vue 3 + 自定义表单处理。标准的 DOM click 事件不触发 Vue 的响应式更新——下拉框视觉上选了，但底层数据模型没绑定上。

修复：绕过 UI 层，直接操作底层 <select> 元素：

const select = document.querySelector('select.form-select');
select.value = 'port';                       // TCP Port 的内部值
select.dispatchEvent(new Event('change'));   // 手动触发 Vue 响应式

区分两类错误：
- 报 "Unknown Monitor Type"：内部记录的 type ID 损坏 → 删掉重建。
- 报 "Request timeout"：配置正确但服务不可达 → 查网络/服务状态，不用改配置。

可复用经验：自动化操作 Vue/React 等响应式框架的表单时，click 不一定触发数据绑定。直接改 DOM value + dispatchEvent 对应事件更可靠。

告警通知

Uptime Kuma 支持多种通知渠道（邮件、Telegram、Webhook 等）。通常会配置邮件通知，关键服务宕机时发邮件告警。

告警策略：
- HTTP 监控：连续 2 次失败后告警（避免网络抖动误报）。
- TCP 监控：连续 3 次失败后告警。
- Push 监控：超过间隔的 1.5 倍未收到心跳后告警。

监控看板

Uptime Kuma 的状态页面功能可以创建公开的看板，展示所有服务的可用性和历史状态。这对自托管来说很有价值——不用登录管理面板就能看到整体健康状况。

看板地址通过 Traefik 反代到 status.example.com，受 Authelia 保护。如果需要公开状态页（比如给团队成员看），可以创建一个不需要认证的公开状态页，只展示关键服务的可用性百分比，不暴露内部细节。

与 health-check.sh 的关系

Uptime Kuma 和 health-check.sh 是互补的：

Uptime Kuma 负责持续监控 + 告警，health-check.sh 负责深度巡检。日常靠 Uptime Kuma 看板巡视，每周跑一次 health-check.sh 做全面体检。

小结

Uptime Kuma 监控体系的三条经验：

1. HTTP 监控覆盖所有域名，验证的是完整链路（DNS → Traefik → Authelia → 后端服务），任何一环断裂都能捕获。
2. Push 监控适合无法主动探测的场景（如 SSH 认证链路），探针受限用户 + 心跳推送的设计既安全又可靠。
3. 自动化操作响应式框架的表单时，直接改 DOM value + dispatchEvent 比 click 更可靠——这是 Uptime Kuma TCP Monitor 踩坑的核心教训。