你会遇到什么

你搭了个服务（博客、API、家里的小型服务器、公司内网系统），平时好好的，直到某天用户说「打不开了」你才知道。你想有个东西每 30 秒帮你去探一次活，挂了立刻告诉你，还想有个公开状态页让用户自己看「服务是否正常」。你搜到 uptime-kuma，但照着 README 拉镜像时可能卡在 ghcr.io 超时；装好之后照着别人的配置写监控地址，又发现全是 DOWN——因为容器里的 127.0.0.1 不是你的宿主机（2026-09-01 实测踩坑）。 这篇指南是实测过的完整路径：镜像走 ghcr 国内镜像（ghcr.nju.edu.cn，实测 2.48GB 拉取成功），监控宿主机服务用网关地址 172.17.0.1。装完你得到：一个 http://localhost:3001 的监控台，加监控器、看心跳、配通知、出状态页。 什么时候用：

• 你有自托管服务/网站，想知道它「活着吗、响应多快」，挂了能收到提醒；
• 你要给用户一个公开的「服务状态页」（uptime-kuma 自带）；
• 你有多个内网/公网端点（HTTP、TCP 端口、Ping），想一个面板全看住。

什么时候别用：只要看日志/链路追踪/性能指标，那是 logfire 的活（uptime-kuma 只探活不采指标）；要云托管免维护，用 UptimeRobot/StatusPage 等 SaaS（数据出网）。

本文路径：快速修复（一条命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）→ 日常使用（长期操作）→ 卸载。赶时间直接跳到「快速修复」。

为什么会这样

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

• 心跳（heartbeat）：每次探测产生一条记录（status: 1=up / 0=down + ping 耗时），这是「监控」的全部真相来源；状态页和告警都基于心跳。
• 容器网络隔离：uptime-kuma 官方推荐 Docker 形态（数据在 /app/data）。容器内的 127.0.0.1 指向容器自己——监控宿主机上的服务（如 open-webui、ollama）必须用 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 才丢。 与 logfire 的分工：logfire = 应用遥测（日志/追踪/指标，配合 OpenAI SDK 等）；uptime-kuma = 存活探活（服务在不在、响应快不快）。两个互补，不重复。

一步步来

第 1 步：拉镜像 + 起容器

uptime-kuma 官方镜像在 ghcr.io（GitHub Container Registry）。国内直连 ghcr.io 容易超时，实测 ghcr.nju.edu.cn 前缀可拉（2026-09-01，镜像 2.48GB）。 `agent docker pull ghcr.nju.edu.cn/louislam/uptime-kuma:2.5.3 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

>>

预期输出: pull 输出 15 层 Pull complete；run 输出容器 ID

装好确认：

• docker ps 里 uptime-kuma 状态 Up ... (healthy)；
• curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3001/ 返回 302（跳登录/设置页，正常）。

卡住怎么办：

• 拉取超时 → 检查网络（直连 ghcr.io 不通时走 nju 前缀）；再不行换 Docker 全局镜像加速配置。
• 端口 3001 被占 → 换宿主端口 -p 3002:3001，访问地址同步换。

第 2 步：初始化数据库 + 建管理员

首次访问 http://localhost:3001 会进入初始化（v2.5 是独立的 setup-database 服务）。默认 SQLite 即可，不需要外部数据库。

1. 浏览器打开 http://localhost:3001 → 初始化页 → 数据库类型选 SQLite → 提交；
2. 页面自动切换到主服务 → 创建管理员账号（用户名 + 密码，弱口令会被拒，实测）；
3. 登录进控制台。

命令行等价操作（实测通过，供自动化/复测）： `agent curl -s -X POST http://127.0.0.1:3001/setup-database -H "Content-Type: application/json" -d '{"dbConfig":{"type":"sqlite"}}'

等待约 10 秒（setup-database 服务关闭、主服务启动），然后走 socket.io：

socket "setup"(username, password) -> {"ok":true}

socket "login"({username,password}) -> {"ok":true, token}

>>

预期输出: {"ok":true}；登录返回 188 字符 token（2026-09-01 实测）

卡住怎么办：

• 初始化页打不开 → 等 10 秒再刷（setup-database 切主服务有延迟）；还不行 docker logs uptime-kuma --tail 30 看日志。
• 提交 SQLite 报错 → 确认 volume 挂载正常（docker inspect uptime-kuma 看 Mounts）；数据目录 /app/data 不可写会初始化失败。
• 弱口令被拒 → 密码至少 8 位且含大小写/数字（passwordStrength 校验，实测）。

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

登录后左侧「监控器」→「新增监控器」：类型选 HTTP(s)、URL 填目标、间隔 30 秒、状态码 200-299、保存。 监控宿主机上的服务（open-webui 3000 / ollama 11434 / 自己的 API）时，URL 填 http://172.17.0.1:<端口>（2026-09-01 实测：172.17.0.1 网关地址可达宿主机，127.0.0.1 全部 DOWN）。 命令行等价操作（socket.io "add" 事件，实测通过）： `agent 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 → 先确认目标地址从 uptime-kuma 容器内可达：docker exec uptime-kuma wget -qO- http://172.17.0.1:8080/health（容器内没有 wget 就临时 docker run --rm --network container:uptime-kuma curlimages/curl -s http://172.17.0.1:8080/health）；127.0.0.1 必 DOWN（见 FAQ 2）。
• 监控器保存报错 → v2.5 的 add 事件要求 accepted_statuscodes/conditions/rabbitmqNodes/kafka 字段齐（缺 conditions 报 NOT NULL，实测）；UI 操作不会遇到，API 方式才注意。
• 状态一直 PENDING → 首次心跳有延迟，等一个 interval（30s）再看。

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

• 通知：左侧「通知」→「新增通知」→ 选渠道（Telegram/Webhook/邮件等）→ 填 webhook 地址/凭证 → 在监控器里关联。未实测（零账号红线，未配置任何外部通知；Webhook 渠道不需要账号，可自行按官方文档配）。
• 状态页：左侧「状态页」→ 新建 → 勾选要公开的监控器 → 得到一个 /status/<slug> 公开地址。未实测（需在 UI 配置，核心监控链已实测闭环）。

卡住怎么办：

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

怎么确认修好了

1. 监控器卡片出现第一条心跳且为 UP（绿点）：

`agent

心跳查询（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）

1. 故意测试 DOWN 判定：临时停掉被监控服务，30 秒内该监控器变红点（DOWN），重启后恢复 UP（实测 down-probe 正确判 DOWN）。
2. 服务重启后监控数据不丢：docker restart uptime-kuma，登录后历史心跳还在（数据在 volume）。

其它环境的表现

• Docker Desktop（Windows/macOS）：容器内访问宿主机用 host.docker.internal:<端口>（本项目 open-webui 同口径实测）；镜像同 ghcr.nju.edu.cn 前缀。
• 群晖/软路由/树莓派：有 Docker 就能跑，同一条 run 命令；ARM 架构镜像 nju 前缀同路径（未实测，架构不同注意选 tag）。
• 二进制形态：GitHub Release 有 dist.tar.gz 源码包（7.3MB），需 Node.js 20+ 运行（npm run start 之类，未实测，本项目推荐 Docker 形态）。
• k8s：官方有 Helm chart（未实测）；核心就一个 StatefulSet + PVC，数据目录 /app/data。

日常使用（装完不是终点）

启动与入口

• docker start uptime-kuma；入口 http://localhost:3001。
• 看日志：docker logs uptime-kuma --tail 20（启动时能看到 Version: 2.5.3）。

常用操作

• 加监控器：左侧「监控器」→「新增监控器」→ 选类型（HTTP/TCP/Ping/DNS/关键字等 12 种）→ 填目标 → 保存。
• 看心跳详情：点进监控器 → 「心跳记录」页，能看到每次探测的 up/down 与响应耗时（socket "getMonitorBeats"(id, 24) 实测可查）。
• 批量管理：监控器列表支持分组（按 tag/状态页分组）、暂停/恢复单个监控器。
• 改间隔：编辑监控器 → 间隔（秒）——调小更灵敏但请求更多，调大省资源；实测 30s 正常。
• 数据备份：docker run --rm -v uptime-kuma:/app/data -v $(pwd):/backup alpine tar czf /backup/uptime-kuma-data.tar.gz -C /app/data .（volume 打包）。

数据与目录

• 全部数据：volume uptime-kuma 的 /app/data（kuma.db SQLite + 上传资源）。备份 = 打包这个目录。

卸载与清理

`agent docker stop uptime-kuma docker rm uptime-kuma

数据目录（监控器配置与历史心跳，删了不可恢复）

docker volume rm uptime-kuma

>>

预期输出: stop/rm 无输出；volume rm 打印卷名 uptime-kuma

note: uptime-kuma volume 是监控配置 + 历史心跳本体，确认不再需要再删。

依赖警告与冲突

• 版本：v2.5.3（2026-08-22 发布，latest）；Docker >= 20.10。
• 环境：镜像 2.48GB（实测）；运行内存 512MB-1GB 足够（Node 进程）；端口 3001（默认，可换宿主端口）。
• 环境（实测坑）：容器内 127.0.0.1 = 容器自己——监控宿主机服务必须用 172.17.0.1（Linux/WSL bridge 网关）或 host.docker.internal（Docker Desktop）；用 127.0.0.1 会全部 DOWN（2026-09-01 实测 #1/#2 全 DOWN、改网关后 UP）。
• 冲突：与 logfire 定位不同（探活 vs 遥测），互补不冲突；与本站其余工具均为无共享写面（uptime-kuma 只读目标端点 + 写自己 volume），compatible（open-webui/ollama 两对已实测联动 UP，其余推断）。
• 国内网络：镜像走 ghcr.nju.edu.cn（实测）；监控目标走你的网络环境（宿主机可达即可）。

FAQ（常见问题）

• 问：为什么用 uptime-kuma 而不是 logfire？
• 答：logfire 管应用遥测（日志/追踪/性能），uptime-kuma 管「服务活着吗」的探活与告警；监控存活用 uptime-kuma，排查性能用 logfire，互补。
• 问：监控器一直 DOWN，但服务明明能访问？
• 答：八成是地址写错了：容器内 127.0.0.1 指向容器自己，监控宿主机服务要写 http://172.17.0.1:<端口>（Docker Desktop 用 host.docker.internal）。2026-09-01 实测：127.0.0.1 全 DOWN，改网关地址立即 UP。
• 问：能监控内网/公网哪些目标？
• 答：HTTP(s)/TCP/Ping/DNS/关键字等 12 种；只要 uptime-kuma 容器网络能到目标即可（内网目标 = 容器与目标同网络/网关可达）。
• 问：数据会出网吗？
• 答：监控数据全在本地 volume；只有通知渠道（Telegram/Webhook）把「告警事件」发出去（不配置就不出网）。
• 问：通知怎么配？
• 答：左侧「通知」→ 新增 → 选渠道填凭证。Telegram 需要 bot token（零账号红线未实测）；Webhook 无账号需求，按官方文档自行配置即可。
• 问：状态页要暴露给用户，安全吗？
• 答：状态页默认只读展示 up/down，不含管理功能；但不要把它当唯一监控入口，管理端仍需强密码。
• 问：多用户怎么管？
• 答：支持多用户与权限（管理员已实测创建/登录）；默认首个账号是管理员。
• 问：容器重启后监控数据还在吗？
• 答：在。数据在 volume（/app/data），删容器不丢；删 volume 才丢。