工具与效率

Uptime Kuma 监控部署:把站点、接口和家用服务的可用性告警管起来

网站打不开时,如果最先发现问题的是访客,而不是维护者,通常不是因为故障太复杂,而是缺少一条可靠的告警链路。家里的 NAS、个人博客和对外提供的 API 也一样:服务停止后,没人主动检查,就可能一直处于无人知晓的离线状态。

Uptime Kuma 是一个可自行托管的开源可用性监控工具。它从部署所在的位置定期检查目标,并在判定服务异常时通过配置好的渠道发送通知,还能生成状态页。它适合个人站点、小型团队服务和家庭服务器,但不能代替日志分析、资源监控或完整的故障响应系统。

下面用 Docker Compose 搭建一个实例,依次完成监控、通知和状态页配置。在真正依赖它之前,务必模拟故障,确认告警能送到有人查看的地方。

部署前:先选好监控位置

Uptime Kuma 看到的是监控机器到目标之间的情况。如果它和网站部署在同一台服务器上,服务器断电或网络中断时,两者可能一起失联,告警也就发不出去。

  • 监控公网网站或 API:优先放在与目标不同的主机或网络中,尽量从用户访问服务的方向进行检查。
  • 监控家庭内网服务:放在能访问内网的设备上,或通过安全的私有网络连接。仅部署在公网的实例通常无法直接访问家庭内网地址。
  • 同时关注内外网:可以分别部署监控点。内网检查正常但公网检查失败时,有助于缩小排查范围。

准备一台已安装 Docker Engine 和 Docker Compose 插件的主机,并确认有可用磁盘空间。下面的示例将管理界面只绑定到主机回环地址,适合先通过 SSH 隧道访问,避免一开始就把管理端口暴露到公网。

用 Docker Compose 启动 Uptime Kuma

新建工作目录和配置文件:

纯文本
mkdir -p uptime-kuma
cd uptime-kuma

创建 compose.yaml:

纯文本
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.4.0
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:

这里使用明确的镜像标签,便于重建时获得一致的版本;2.4.0 是示例,并不表示它始终是最新版本。升级前应查看目标版本的发布说明、确认兼容性并备份数据。

启动并检查容器:

纯文本
docker compose up -d
docker compose ps
docker compose logs --tail=100

如果 Docker 主机就是当前电脑,在浏览器打开 http://127.0.0.1:3001。如果是远程服务器,可以在本地电脑建立 SSH 隧道:

纯文本
ssh -L 3001:127.0.0.1:3001 用户名@服务器地址

保持连接,再在本地浏览器访问 http://127.0.0.1:3001。首次进入时按界面提示创建管理员账号,使用强密码并妥善保存。

/app/data 对应的命名卷用于持久保存数据;删除容器不等于删除该卷。不要随意执行会删除卷的清理命令,否则可能丢失监控配置和历史记录。

如果需要远程长期访问,可通过 VPN,或使用带 HTTPS 的反向代理。公开状态页与管理界面的访问控制也应一并考虑,不要把“有登录页面”当作唯一安全措施。

添加第一个监控项

进入管理界面后选择添加监控项。具体按钮和字段名称可能随版本或界面语言略有不同。先从最重要、最容易验证的目标开始,而不是一次性把所有服务都加进去。

监控类型适合检查需要注意
HTTP(s)网站首页、健康检查接口返回成功状态不一定代表核心业务正常
TCP 端口SSH、数据库或其他监听端口端口可连接不代表应用能正常处理请求
Ping主机的网络可达性有些主机会禁用或限制 ICMP,失败不一定是服务故障
DNS域名解析结果应明确预期结果,并考虑记录变更
推送式监控定时任务、备份脚本由任务主动发送心跳,超时未收到才判定异常

例如,要监控一个网站:

  1. 选择 HTTP(s) 类型,填写容易识别的名称,例如“个人博客—公网”。
  2. 输入访客实际访问的 HTTPS 地址。API 可以使用专门的健康检查端点,避免让监控请求触发写入或其他业务操作。
  3. 将检查间隔先设为 60 秒,并根据界面设置超时和重试次数;对于容易偶发抖动的网络,可先尝试两三次重试。
  4. 保存后观察状态和响应时间,确认监控实例确实能够访问目标。

对于 HTTPS 站点,使用域名而非直接使用 IP,更有利于检查服务器返回的目标证书。需要证书到期提醒时,检查对应通知选项;不要为了消除报错而随意忽略 TLS 错误,否则会削弱证书问题的可见性。

如果监控家庭服务,注意容器里的 localhost 指向容器自身,不是宿主机上的其他服务。应填写从 Uptime Kuma 容器实际可达的地址,并确认防火墙、端口和网络路由允许访问。

配置告警渠道,并验证整条链路

Uptime Kuma 可接入邮件、Telegram、Discord、Webhook 等通知方式;具体可选项和字段以所用版本的界面为准。先选一个日常确实会查看的渠道,重要服务再考虑准备第二条相对独立的通知路径。

以 Webhook 类渠道为例:

  1. 在接收端创建专用 Webhook,取得地址。
  2. 在 Uptime Kuma 的通知设置中选择相应渠道,粘贴地址并填写必要参数。
  3. 点击测试,确认接收端收到消息,再保存设置。
  4. 回到监控项,确认该通知渠道已启用并关联到这个监控项。

Webhook 地址、机器人令牌和邮件凭据都应视为敏感信息,不要放进公开仓库或截图。通用 Webhook 的消息格式也未必符合每个接收端的要求,必要时先确认接收端能正确处理测试消息。

测试按钮成功只是第一步。它证明当前配置能发送测试消息,却不能保证监控项关联正确、故障判定符合预期,也不能保证手机会提醒你。

建议用一个不影响真实用户的测试服务完成端到端验证:

  1. 为测试服务添加监控项,并关联刚配置的通知渠道。
  2. 确认状态正常后,停止测试服务,或让测试地址暂时不可达。
  3. 等待检查、超时和重试完成,确认收到故障通知。
  4. 恢复测试服务,确认状态恢复;如果配置包含恢复通知,也检查是否收到。
  5. 记录从故障发生到收到消息的大致时间,判断是否符合自己的需求。

如果没收到消息,先看监控项是否真的变成异常,再检查通知渠道是否已关联、测试消息是否能送达,以及接收端是否被静音或过滤。

设置状态页,让其他人也能查看

告警是通知维护者,状态页则是向访客或团队展示服务状态。进入状态页管理界面,创建页面、填写名称,再把需要公开的监控项加入分组并保存。

建议只展示读者需要知道的服务,例如“网站”“API”和“文件访问”。内部主机名、管理地址等信息不必放上公开页面;发布前先在未登录或隐私窗口中检查实际展示内容。

如果状态页要对公网开放,需要为它规划可访问的域名、HTTPS 和反向代理,同时检查管理界面的暴露范围。还有一个容易忽略的问题:状态页和监控实例本身也可能离线。它们与被监控服务放在同一台故障主机上时,访客可能既看不到服务,也看不到状态页。

长期运行时,重点关注这四件事

监控频率与误报

60 秒是一个便于起步的间隔,不是统一标准。检查越频繁,越可能更早发现故障,也会增加目标服务、网络和通知渠道的负担。故障告警时间还取决于超时、重试和通知投递,不等于单次检查间隔。

先观察正常波动,再调整重试次数和超时。对计划内维护,使用维护窗口或按实际流程暂时暂停相关监控,并记得恢复。遇到告警时,也要区分目标故障与监控节点自身的 DNS、网络或出口问题。

数据保留与备份

检查界面中的历史数据保留设置,并结合磁盘空间和排障需要调整:保留越久,历史查询越方便,存储需求也可能越高。

定期备份 Compose 配置和持久化数据。对于本例使用的 SQLite 数据,较稳妥的简单做法是在维护窗口停止容器后备份数据卷,再启动容器;备份应存放在另一位置,并定期验证能否恢复。数据卷本身不是异地备份。

监控自身也需要被监控

restart: unless-stopped 有助于容器随 Docker 重启,但无法覆盖主机断电、磁盘故障、网络中断或通知渠道故障。

对重要服务,可以在不同主机或网络上部署独立监控点,或使用独立的外部检查来关注 Uptime Kuma 是否可达。两套监控应尽量避免共用同一台主机、网络和唯一通知渠道;否则看似有冗余,实际仍可能同时失效。

定期复测通知

通知令牌可能被撤销,Webhook 可能失效,邮箱规则和手机提醒设置也可能变化。定期重复一次测试故障流程,并在升级 Uptime Kuma、迁移主机或更换通知渠道后再次验证,比只看仪表盘上的绿色状态更可靠。

出现问题时先查哪里

  • 容器启动失败:运行 docker compose ps 和 docker compose logs --tail=100,检查端口冲突、镜像拉取和数据目录权限。
  • 监控一直异常:从监控主机及容器的网络视角检查目标地址、DNS、防火墙和路由;确认没有误用 localhost。
  • HTTPS 检查失败:核对域名、证书链及有效期,不要直接关闭证书校验来掩盖问题。
  • 状态异常但没有通知:确认监控项已关联通知渠道、重试流程已结束,并检查接收端的静音与过滤设置。
  • 状态页无法访问:检查反向代理、HTTPS、域名解析和网络访问策略;本例默认只监听主机回环地址,本身不会直接对公网开放。

搭建轻量可用性监控的关键,不是添加多少个绿色方块,而是形成一条经过验证的链路:检查能发现问题,通知能到达维护者,恢复后也能确认状态。从一个重要服务和一次真实的故障演练开始,再逐步扩展,比配置完就放在那里更有价值。

热门话题

52okp 是一名关注人工智能、开源软件与效率工具的技术内容创作者,长期实践 Stable Diffusion、ComfyUI、AI 智能体、MCP、Codex 和各类开源项目。通过实际安装、配置与测试,整理可复现的操作教程、问题排查方法和工具使用经验。

登录用户才能发表评论! 登录账户

取消回复

评论列表 (3条):

加载更多评论 Loading...

延伸阅读:

用 PowerToys 键盘管理器改键:设置映射并排查快捷键冲突

在 Windows 上遇到按键位置反人类、个别键位损坏,或者某些常用操作按起来特别别扭时,很多人第一时间会想到修改键位。...

52okp
2026-10-24

LinkGenie 自托管书签管理:自动标签、工作流自动化与 MCP 接入值得试吗

收藏夹里躺着八百个链接,标签却停留在“未分类”和“imported”两个上面——这大概是自托管书签用户最常见的失败现场。...

52okp
2026-11-08

LaVague 浏览器自动化评估:把自然语言查询变成 Selenium 代码靠谱吗

每次回归测试都要打开页面、找到入口、点击,再确认结果;如果页面改了,脚本里的元素定位也可能跟着失效。LaVague 的吸...

52okp
2026-10-20

IT-Tools:用 Docker 自托管一个无广告的开发者工具箱,集成近百种常用工具

开发者在 JSON 格式化、JWT 解析和 Base64 编解码间频繁切换,不仅耗时,也可能让配置片段或令牌暴露给陌生网...

52okp
2026-10-03

用 DropIt 建立自动文件整理流程:从整理规则到小批量验证

下载文件夹长期堆满压缩包、PDF 和截图,手动拖拽既费时又容易误放,而把这份苦差交给 DropIt 这款免费开源工具后,...

52okp
2026-10-07
    返回顶部