你搭了个服务（博客、API、家里的小型服务器、公司内网系统），平时好好的，直到某天用户说「打不开了」你才知道。你想有个东西每 30 秒帮你去探一次活，挂了立刻告诉你，还想有个公开状态页让用户自己看「服务是否正常」。uptime-kuma 就是干这个的：自托管、免费开源（MIT）、中文界面、一个 Docker 命令就能起。

什么时候用：

• 你有多台机器/多个服务，想要统一探活面板；
• 你要告警通知（Telegram/Webhook/邮件等）；
• 你要给用户一个公开状态页（服务挂了用户自己看，不用找你）；
• 你要知道服务响应变慢（心跳有 ping 耗时）。

什么时候别用：只需要应用内部遥测（日志/追踪/指标）——那是 logfire 的活；只需要临时 curl 一下——那不需要工具。

与 logfire 的分工：logfire = 应用遥测（配合 OpenAI SDK 等）；uptime-kuma = 存活探活。两个互补，不重复（矩阵判定 possible-compatible）。

一条命令起容器（国内实测路径：ghcr.nju.edu.cn 镜像前缀 + 挂载 volume）：

# 来源: Trove 详细指南 · 验证于 2026-09-01
docker run -d --name uptime-kuma --restart=always -p 3001:3001 -v uptime-kuma:/app/data ghcr.nju.edu.cn/louislam/uptime-kuma:2.5.3

预期输出: 一串容器 ID；docker ps 里 uptime-kuma 状态 Up（约 12 秒后转 healthy，2026-09-01 实测）

装完浏览器打开 http://localhost:3001：第一次访问进入初始化（选 SQLite → 创建管理员账号 → 登录）。然后左侧「新增监控器」：类型 HTTP(s)、URL 填目标、间隔 30 秒、保存——30 秒内出第一条心跳。

监控宿主机服务（open-webui/ollama/自己的 API）时，URL 用 http://172.17.0.1:<端口>，不要写 127.0.0.1（实测坑：容器内 127.0.0.1 = 容器自己，全部 DOWN；172.17.0.1 = docker bridge 网关可达宿主）。

装好确认：

• docker ps 显示 healthy；
• 浏览器 http://localhost:3001 出现初始化页；
• 添加第一个监控器后 30 秒内出现 UP 心跳（绿点）。

uptime-kuma 是 Node.js 应用（GitHub louislam/uptime-kuma，MIT，65k+ star）：一个守护进程按 interval 向目标发探测请求（HTTP GET / TCP 连接 / Ping / DNS 查询等），把每次结果（up/down、响应耗时）写进数据库，并渲染网页界面、触发通知。

两个关键机制：

• 心跳（heartbeat）：每次探测产生一条记录（status: 1=up / 0=down + ping 耗时），这是「监控」的全部真相来源；状态页和告警都基于心跳。
• 容器网络隔离：官方推荐 Docker 形态（数据在 /app/data）。容器内的 127.0.0.1 指向容器自己——监控宿主机服务必须用 172.17.0.1（docker bridge 网关，Linux/WSL）或 host.docker.internal（Docker Desktop）。2026-09-01 实测：127.0.0.1 全部 DOWN，改 172.17.0.1 后立即 UP。

装完它动哪里：Docker volume（数据目录 /app/data，含 SQLite kuma.db）。删容器不丢数据，删 volume 才丢。

第 1 步：初始化 + 建管理员

讲解：首次访问走初始化向导（选数据库 → 建管理员 → 登录）。

# 来源: Trove 详细指南 · 验证于 2026-09-01
docker ps --filter name=uptime-kuma

预期输出: 容器 Up（healthy，约 12 秒，2026-09-01 实测）

浏览器 http://localhost:3001 → SQLite → 创建管理员 → 登录进入仪表盘。

卡住怎么办：

• 容器起不来 → docker logs uptime-kuma 看尾部；端口 3001 被占则换 -p 3002:3001；
• 初始化重复出现 → volume 没挂好（数据没持久化）；确认 -v uptime-kuma:/app/data 在。

第 2 步：添加第一个监控器

讲解：监控器 = 探活目标；HTTP 类型最常用。

# 来源: Trove 详细指南 · 验证于 2026-09-01
docker exec uptime-kuma wget -qO- http://172.17.0.1:3000/api/health

预期输出: 目标服务正常响应（从 uptime-kuma 容器内先验证目标可达；2026-09-01 实测 open-webui /health 经 172.17.0.1 UP）

UI：左侧「监控器」→「新增监控器」→ 类型 HTTP(s) → URL http://172.17.0.1:<端口> → 间隔 30 秒 → 状态码 200-299 → 保存。

命令行等价（socket.io "add" 事件，实测通过）：

# 来源: Trove 详细指南 · 验证于 2026-09-01
# socket "add"({name:"my-api", type:"http", url:"http://172.17.0.1:8080/health",
#   interval:30, maxretries:1, accepted_statuscodes:["200-299"], conditions:[]})

预期输出: {"ok":true,"monitorID":1}；约 30 秒后该监控器显示 UP 绿点

卡住怎么办：

• 一直 DOWN → 先确认目标从容器内可达（wget 或临时 curl 容器）；127.0.0.1 必 DOWN（见「为什么会这样」）；
• 保存报错 → v2.5 的 add 事件要求 accepted_statuscodes/conditions 等字段齐（缺 conditions 报 NOT NULL，实测）；UI 操作不会遇到；
• 状态一直 PENDING → 等一个 interval（30s）再看。

第 3 步：验证心跳与 DOWN 判定

讲解：心跳是监控的真相；UP 和 DOWN 都要验证过才算闭环。

# 来源: Trove 详细指南 · 验证于 2026-09-01
# 心跳查询（socket.io "getMonitorBeats" 事件）
#   socket "getMonitorBeats"(monitorID, 24)  -> {"ok":true,"data":[{status:1,ping:16,time:"..."}]}

预期输出: data 里最新一条 status:1 且有 ping 耗时（实测 UP=status:1，ping 16/104ms）

# 来源: Trove 详细指南 · 验证于 2026-09-01
# 故意验证 DOWN：临时停掉被监控服务，30 秒内监控器变红点，重启后恢复
docker stop open-webui && sleep 35 && docker start open-webui

预期输出: 停止后监控器变 DOWN（红点），重启后恢复 UP（2026-09-01 实测 down-probe 正确判 DOWN）

卡住怎么办：

• 停服务后不 DOWN → 检查 interval 是否过了；心跳是定时探测，有延迟；
• 重启后数据还在 → volume 持久化正常（docker restart uptime-kuma 后历史心跳仍在，实测）。

第 4 步（可选）：配通知 + 公开状态页

讲解：通知渠道（Telegram/Webhook/邮件）；Webhook 免账号可自测。

# 来源: Trove 详细指南 · 验证于 2026-09-01
# Webhook 通知自测：先 curl 打自己的 webhook 地址验证可达（示例，实际地址自己配）
curl -s -X POST https://your-webhook.example/hook -H "Content-Type: application/json" -d '{"msg":"test"}'

预期输出: webhook 服务正常应答（200 或服务方规定的成功响应）

• 通知：左侧「通知」→「新增通知」→ 选渠道 → 填地址/凭证 → 监控器里关联。未实测（零账号红线；Webhook 渠道免账号可自行按官方文档配）。
• 状态页：左侧「状态页」→ 新建 → 勾选监控器 → 得到 /status/<slug> 公开地址。未实测（需 UI 配置）。

卡住怎么办：

• 通知测试不达 → 确认通知填在「通知」配置而非监控器内联；Webhook 先 curl 自测地址；
• 状态页空白 → 必须勾选至少一个监控器并保存；公开地址是 /status/<slug> 不是根路径。

与工具页矩阵同源；完整对子、状态与证据见 冲突对子（共装矩阵）。已知关联：

• open-webui × uptime-kuma = compatible（实测 verified）：2026-09-01 实测（uptime-kuma 探 open-webui /health 经 172.17.0.1 UP，ping 16ms）——探活与被探，天然互补；
• ollama × uptime-kuma = compatible（实测 verified）：2026-09-01 实测（探 ollama /api/version UP，ping 104ms）；
• logfire × uptime-kuma：分工互补（应用遥测 vs 存活探活），写面不重叠，静态判定可共存；
• 与其余工具：静态判定 possible-compatible（容器 volume 写面，不重叠）。

• 症状：监控器全部 DOWN → 检查 URL 是否写了 127.0.0.1（容器自指）；改 172.17.0.1（docker bridge 网关）
• 症状：容器 12 秒后仍未 healthy → docker logs uptime-kuma 看尾部；端口冲突换映射
• 症状：add 事件保存报错 → v2.5 需 accepted_statuscodes/conditions 字段齐（缺 conditions 报 NOT NULL，实测）；UI 操作无此问题
• 症状：状态一直 PENDING → 等一个 interval（30s）再看首次心跳
• 症状：重启后监控数据丢 → volume 没挂好；确认 -v uptime-kuma:/app/data

四段式全文（症状→原因→解法→验证证据）：站内文档（如已收录）

# 来源: Trove 详细指南 · 验证于 2026-09-01
docker stop uptime-kuma && docker rm uptime-kuma
docker volume rm uptime-kuma

预期输出: 容器停止/删除成功；volume 删除后 docker volume ls 不再显示 uptime-kuma

注意：volume 删除 = 全部监控器/心跳历史/状态页配置没了。想保留数据就只删容器不删 volume。

• 问：为什么监控宿主机服务全部 DOWN？答：容器内 127.0.0.1 = 容器自己。监控宿主机用 http://172.17.0.1:<端口>（docker bridge 网关，实测）或 host.docker.internal（Docker Desktop）。
• 问：镜像拉不动？答：ghcr.nju.edu.cn 实测可用（2.48GB 完整拉取）；不行换其他 ghcr 镜像或等代理窗口。
• 问：数据存哪、删容器会丢吗？答：SQLite 在 volume /app/data/kuma.db。挂 -v uptime-kuma:/app/data 后删容器不丢；删 volume 才丢。
• 问：和 logfire 重复吗？答：不重复。logfire = 应用内部遥测（日志/追踪/指标）；uptime-kuma = 服务存活探活 + 告警 + 状态页。可同时装。
• 问：通知要账号吗？答：Telegram/邮件要凭证（零账号未实测）；Webhook 渠道免账号，可自行配置。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：2.5.3（manifest 锁定；镜像实测 2026-09-01）。
• 环境：Docker 29.1.3（WSL2 Ubuntu 实测）；内存 ≥1GB（轻量，实测 12s healthy）。
• 网络：镜像 ghcr.nju.edu.cn 实测可用（2.48GB）。
• 写面：Docker volume uptime-kuma（/app/data，SQLite kuma.db）。
• 端口：3001（宿主映射示例；容器内 3001）。

• 条目签名：louislam/uptime-kuma（MIT，原样收录 2.5.3）

• 实测：`站内文档（2026-09-01：ghcr.nju 2.48GB 拉取 → 容器 12s healthy → POST /setup-database sqlite → socket setup 建管理员 + login（token）→ add 5 个 HTTP 监控器 → 心跳验证：open-webui UP ping 16ms / ollama UP ping 104ms / 坏目标正确 DOWN；127.0.0.1 自指坑全程复现）
• 未实测：通知渠道（Telegram/邮件需账号，零账号红线）；公开状态页（需 UI 配置）；裸机部署。