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

> 作者: Lazybones | 日期: 2026-09-07

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

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

## 为什么选 Uptime Kuma

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

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

```yaml
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 监控即可，下面是几条典型示例：

| 监控项 | 目标 | 检查间隔 | 期望状态码 |
|--------|------|----------|-----------|
| 主站 | `https://app.example.com` | 60s | 200 |
| 业务服务 | `https://service.example.com` | 60s | 200 |
| 管理面板 | `https://panel.example.com` | 60s | 200 |
| 监控状态页 | `https://status.example.com` | 60s | 200 |

**注意**：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 端口，但需要确认端口在监听：

| 监控项 | 目标 | 说明 |
|--------|------|------|
| 内部 API 服务 | `host.docker.internal:<自定义端口>` | 宿主机/内网上的服务端口 |
| 数据库管理界面 | `host.docker.internal:<自定义端口>` | 宿主机/内网上的服务端口 |

为什么不能直接用 `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 分钟没收到心跳，判定为宕机并告警。

```text
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>` 元素：

```javascript
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 |
|------|-------------|-----------------|
| 运行方式 | Docker 容器，常驻 | Bash 脚本，按需 |
| 检查频率 | 每 60 秒 | 手动或 crontab |
| 历史记录 | 有，带图表 | 无，只看当前 |
| 告警通知 | 有（邮件/Telegram 等） | 无 |
| 检查深度 | HTTP/TCP/Push | 更深（磁盘/内存/SSL/备份/数据库连接） |

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 踩坑的核心教训。