网站打不开时,如果最先发现问题的是访客,而不是维护者,通常不是因为故障太复杂,而是缺少一条可靠的告警链路。家里的 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 | 域名解析结果 | 应明确预期结果,并考虑记录变更 |
| 推送式监控 | 定时任务、备份脚本 | 由任务主动发送心跳,超时未收到才判定异常 |
例如,要监控一个网站:
- 选择 HTTP(s) 类型,填写容易识别的名称,例如“个人博客—公网”。
- 输入访客实际访问的 HTTPS 地址。API 可以使用专门的健康检查端点,避免让监控请求触发写入或其他业务操作。
- 将检查间隔先设为 60 秒,并根据界面设置超时和重试次数;对于容易偶发抖动的网络,可先尝试两三次重试。
- 保存后观察状态和响应时间,确认监控实例确实能够访问目标。
对于 HTTPS 站点,使用域名而非直接使用 IP,更有利于检查服务器返回的目标证书。需要证书到期提醒时,检查对应通知选项;不要为了消除报错而随意忽略 TLS 错误,否则会削弱证书问题的可见性。
如果监控家庭服务,注意容器里的 localhost 指向容器自身,不是宿主机上的其他服务。应填写从 Uptime Kuma 容器实际可达的地址,并确认防火墙、端口和网络路由允许访问。
配置告警渠道,并验证整条链路
Uptime Kuma 可接入邮件、Telegram、Discord、Webhook 等通知方式;具体可选项和字段以所用版本的界面为准。先选一个日常确实会查看的渠道,重要服务再考虑准备第二条相对独立的通知路径。
以 Webhook 类渠道为例:
- 在接收端创建专用 Webhook,取得地址。
- 在 Uptime Kuma 的通知设置中选择相应渠道,粘贴地址并填写必要参数。
- 点击测试,确认接收端收到消息,再保存设置。
- 回到监控项,确认该通知渠道已启用并关联到这个监控项。
Webhook 地址、机器人令牌和邮件凭据都应视为敏感信息,不要放进公开仓库或截图。通用 Webhook 的消息格式也未必符合每个接收端的要求,必要时先确认接收端能正确处理测试消息。
测试按钮成功只是第一步。它证明当前配置能发送测试消息,却不能保证监控项关联正确、故障判定符合预期,也不能保证手机会提醒你。
建议用一个不影响真实用户的测试服务完成端到端验证:
- 为测试服务添加监控项,并关联刚配置的通知渠道。
- 确认状态正常后,停止测试服务,或让测试地址暂时不可达。
- 等待检查、超时和重试完成,确认收到故障通知。
- 恢复测试服务,确认状态恢复;如果配置包含恢复通知,也检查是否收到。
- 记录从故障发生到收到消息的大致时间,判断是否符合自己的需求。
如果没收到消息,先看监控项是否真的变成异常,再检查通知渠道是否已关联、测试消息是否能送达,以及接收端是否被静音或过滤。
设置状态页,让其他人也能查看
告警是通知维护者,状态页则是向访客或团队展示服务状态。进入状态页管理界面,创建页面、填写名称,再把需要公开的监控项加入分组并保存。
建议只展示读者需要知道的服务,例如“网站”“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、域名解析和网络访问策略;本例默认只监听主机回环地址,本身不会直接对公网开放。
搭建轻量可用性监控的关键,不是添加多少个绿色方块,而是形成一条经过验证的链路:检查能发现问题,通知能到达维护者,恢复后也能确认状态。从一个重要服务和一次真实的故障演练开始,再逐步扩展,比配置完就放在那里更有价值。

评论列表 (3条):
加载更多评论 Loading...