GitHub经典项目Uptime Kuma：Docker 部署网站监控、告警与状态页

GitHub经典项目Uptime Kuma：Docker部署监控与告警

网站打不开了，通常不是最麻烦的事；真正麻烦的是，用户已经在反馈，而维护者还不知道故障是什么时候开始的。

Uptime Kuma 是一个开源、自托管的服务可用性监控工具。截至 2026 年 8 月 10 日，其 GitHub 仓库页面显示 90,028 Star。它可以监控 HTTP(S)、TCP 端口、Ping、DNS、关键字、WebSocket 等目标，并提供通知、证书信息和公开状态页。

本文不只完成安装，还会搭建一条可重复验证的故障链路：

Uptime Kuma ──HTTP检查──> 演示网站
│
└──故障/恢复通知──> 本地 Webhook 接收器

我们会主动停止演示网站，确认仪表盘变红、Webhook 收到通知，再恢复服务并检查恢复消息。这样才能证明“监控与告警”确实工作，而不是只看到容器处于 Up 状态。

一、本次实际验证结果

本文配套配置在 Windows 11、Docker Desktop Linux 容器环境中完成了真实运行。核验日期为 2026 年 8 月 10 日。

Star 数、镜像内容和界面会变化。本文把核验日期和实际版本单独写出来，不把动态信息伪装成永久不变的事实。

二、Uptime Kuma 适合解决什么问题

它适合个人开发者、小团队、家庭实验室和内部系统维护者，用一个 Web 界面监控：

• 网站首页和 REST API；
• NAS、软路由或家庭服务器；
• 数据库、缓存和消息服务的 TCP 端口；
• 域名解析、Ping 和 HTTPS 证书；
• Docker Compose 网络中的其他容器；
• 对外公开的服务状态页。

它不是日志分析平台，也不能代替 Prometheus、Grafana、APM 或完整的事件响应体系。Uptime Kuma 擅长回答的是“服务现在能否从指定位置访问”，而不是解释某个请求为什么慢、哪条 SQL 消耗最高。

三、准备项目目录

本文使用以下目录：

027-uptime-kuma/
├── compose.yaml
├── demo/
│ └── webhook.conf
└── data/ # 首次启动后生成

先确认 Docker 和 Compose 可用：

docker —version
docker compose version
docker info

前两条命令只能证明客户端存在，docker info 成功返回，才说明 Docker daemon 已经运行。Windows 用户如果看到无法连接 dockerDesktopLinuxEngine，先启动 Docker Desktop，并确认当前使用 Linux 容器。

四、编写教学用 Compose

保存下面的 compose.yaml：

services:
uptime-kuma:
image: ${UPTIME_KUMA_IMAGE:–louislam/uptime–kuma:2}
restart: unless–stopped
ports:
– "127.0.0.1:${UPTIME_KUMA_PORT:-3001}:3001"
volumes:
– ./data:/app/data

demo-web:
image: nginx:alpine
restart: unless–stopped
ports:
– "127.0.0.1:${DEMO_WEB_PORT:-8088}:80"

webhook-receiver:
image: nginx:alpine
restart: unless–stopped
volumes:
– ./demo/webhook.conf:/etc/nginx/conf.d/default.conf:ro

三个服务分别承担不同职责：

官方 Compose 使用 louislam/uptime-kuma:2，把数据挂载到 /app/data，并映射 3001 端口。本文额外把宿主机地址限定为 127.0.0.1，避免第一次启动时直接监听所有网卡。

4.1 Webhook 接收器配置

保存 demo/webhook.conf：

server {
listen 80;
server_name _;

location = /webhook {
return 204;
}

location / {
return 404;
}
}

它不会解析或保存通知正文，只返回 HTTP 204，并在 Nginx 访问日志中留下请求记录。它的目的只是回答一个问题：Uptime Kuma 是否真的发出了 Webhook。

五、启动并检查容器

先让 Compose 展开配置，检查变量、路径和 YAML 缩进：

docker compose config

然后拉取并启动：

docker compose pull
docker compose up –d
docker compose ps

查看 Uptime Kuma 日志：

docker compose logs —tail 100 uptime-kuma

本次实际输出包含：

Uptime Kuma Version: 2.5.0

等待健康检查通过后，docker compose ps 中应出现：

uptime-kuma Up … (healthy) 127.0.0.1:3001->3001/tcp
demo-web Up … 127.0.0.1:8088->80/tcp

再做两个 HTTP 检查：

curl.exe –I http://127.0.0.1:3001
curl.exe –I http://127.0.0.1:8088

首次访问 Uptime Kuma 时，返回 /setup-database 跳转是正常现象；演示网站应返回 HTTP 200。

六、首次初始化：数据库和管理员账户

浏览器打开：

http://127.0.0.1:3001

Uptime Kuma 2 首次启动会先要求选择数据库。本文选择 SQLite，因为当前界面明确把它描述为适合小规模部署的简单数据库文件。随后创建管理员账户，并使用一个独立的强密码。

不要照抄文章中的示例密码，也不要把密码提交到 Compose 文件或公开仓库。公网部署还应在设置中启用双因素认证。

如果准备做多实例、高可用或已有外部数据库，需要重新评估数据库方案；本文的 SQLite 流程只服务于单实例入门和中小规模自托管场景。

七、添加第一个 HTTP 监控

点击“添加监控项”，填写：

保存后，本文实际记录到：

200 – OK

为什么 URL 不是 http://127.0.0.1:8088？因为监控请求是从 Uptime Kuma 容器内部发出的。容器中的 127.0.0.1 指向容器自己，而 demo-web 是同一个 Compose 网络中的服务名，Docker DNS 可以把它解析到演示容器。

这个区别很重要：

宿主机访问演示站点： http://127.0.0.1:8088
Kuma 容器访问演示站点：http://demo-web

正式环境不要为了追求“越快越好”而盲目设置 20 秒。检查间隔越短，请求量越大；重试次数为 0 也更容易因瞬时抖动触发告警。生产环境应根据业务容忍度设置间隔、超时和重试，并用一次真实故障演练验证结果。

八、配置并验证 Webhook 告警

编辑刚才的监控项，在“通知”区域点击“设置通知”，选择：

先点击“测试”。界面显示 Sent Successfully. 后，再查看接收器日志：

docker compose logs —tail 20 webhook-receiver

本次实际日志为：

"POST /webhook HTTP/1.1" 204 0 "-" "Uptime-Kuma/2.5.0"

保存通知后，确认监控项旁边的“本地 Webhook”复选框已经选中。只创建通知但没有关联到监控项，是“测试发送成功、真实故障却没有消息”的常见原因。

真实使用时可以把本地 Webhook 换成 SMTP、Telegram、Discord、飞书、钉钉、企业微信或其他受支持方式。不同渠道所需的令牌、机器人地址和权限不同，应使用对应平台的官方配置，并妥善保管凭据。

九、主动制造一次故障

停止演示网站：

docker compose stop demo-web

本文把心跳间隔设为 20 秒、重试次数设为 0，因此等待一个检查周期后，仪表盘出现：

状态：故障
消息：connect EHOSTUNREACH …:80

同时，Webhook 接收器新增了一条请求：

"POST /webhook HTTP/1.1" 204 0 "-" "Uptime-Kuma/2.5.0"

恢复服务：

docker compose start demo-web

再次等待检查周期，监控项恢复为：

状态：正常
消息：200 – OK

Webhook 日志中也出现了新的恢复通知请求。至此，我们验证了完整链路：

正常检查 → 服务停止 → 故障检测 → 故障通知
↓
正常检查 ← 服务恢复 ← 恢复检测 ← 恢复通知

正式上线前，至少要对每个关键通知渠道做一次类似演练。能够点击“测试”不等于真实故障时一定能送达。

十、HTTP 之外还能监控什么

添加监控项时，可以根据目标选择不同类型：

“端口打开”不等于“业务正常”。例如数据库端口可以连接，但查询可能已经失败；网站返回 200，也可能只是错误页面。因此关键业务最好同时设置连通性检查和内容检查。

十一、创建公开状态页

状态页适合给用户或团队成员查看服务状态，不需要向他们开放管理后台。

操作流程：

官方 Wiki 明确说明，状态页面向公开访问者，会缓存结果并按周期刷新，因此它不会像管理员仪表盘一样实时。本文当前界面的默认完全刷新间隔为 300 秒。

如果要给不同系统分别提供状态页，可以创建多个页面并使用不同路径。把状态页绑定到域名时，反向代理还需要正确转发 Host 或 X-Forwarded-Host。

十二、持久化、备份与恢复

真正需要保护的是：

宿主机 ./data → 容器 /app/data

删除并重新创建容器不会自动删除这个绑定目录，但误删 data 会丢失账号、监控项、通知和历史数据。官方 README 还明确警告：Uptime Kuma 不支持把该数据目录放到 NFS 文件系统，应使用本地目录或本地 volume。

在 Windows PowerShell 中，可以先停止写入，再压缩备份：

docker compose stop uptime-kuma

$backupDir = ".\\backups"
New-Item –ItemType Directory –Force –Path $backupDir | Out-Null
$archive = Join-Path $backupDir ("uptime-kuma-" + (Get-Date –Format "yyyyMMdd-HHmmss") + ".zip")
Compress-Archive –Path ".\\data" –DestinationPath $archive

docker compose start uptime-kuma

恢复时不要直接覆盖正在使用的数据目录。更稳妥的流程是：

停止 Uptime Kuma
→ 保留当前 data 目录副本
→ 将备份解压到临时目录
→ 检查目录层级
→ 替换 data
→ 启动并登录验证
→ 检查监控项和通知

备份中包含账号、通知配置和可能的访问凭据，应按照敏感数据保存。一次没有做过恢复演练的压缩包，不能算已经验证的备份方案。

十三、升级与回滚

官方更新 Wiki 给出的 Compose 更新方式是重新拉取镜像并强制重建：

docker compose pull
docker compose up –d —force-recreate

升级前先做三件事：

升级后检查：

docker compose ps
docker compose logs —tail 100 uptime-kuma
curl.exe –I http://127.0.0.1:3001

然后再做一次“停止演示目标—收到故障通知—恢复目标”的完整演练。

:2 会跟随 Uptime Kuma 2 的后续镜像更新。对稳定性要求较高的环境，应在测试后固定明确版本或镜像 digest，并保留回退所需的旧镜像与数据备份。不要把删除 data 当作升级失败后的修复办法。

十四、公网访问不要直接暴露 3001

本文使用：

ports:
– "127.0.0.1:3001:3001"

它只允许本机访问。局域网访问可以改成 3001:3001，但必须同步配置管理员强密码、防火墙和可信网段。

公网部署更适合使用独立子域名：

浏览器 ──HTTPS──> Nginx/Caddy/Traefik ──> 127.0.0.1:3001

官方反向代理 Wiki 提醒了三个关键点：

• Uptime Kuma 使用 WebSocket，代理需要转发 Upgrade 和 Connection；
• 官方不支持把管理界面部署在 /uptime-kuma 这类子目录下，应使用域名或子域名；
• 公网访问应使用 HTTPS。

Nginx 的核心代理段可以写成：

location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

这段配置只解决转发问题，不会自动完成证书签发、防火墙、登录保护和备份。公网部署需要把这些措施一起完成。

十五、常见问题排查

1. 容器一直处于 health: starting

docker compose logs —tail 200 uptime-kuma
docker compose ps

首次初始化数据库会需要一些时间。持续失败时先看日志，不要直接删除 data。

2. 在浏览器中能打开，Kuma 却检测失败

确认监控请求从哪里发出。宿主机地址和容器内地址不是同一个概念：本文在浏览器中使用 127.0.0.1:8088，在 Kuma 中使用 http://demo-web。

3. 测试通知成功，故障时没有通知

检查通知是否已经保存并勾选到对应监控项；再检查重试次数、检查间隔和通知渠道日志。

4. 状态页比仪表盘慢

这是设计差异。官方文档说明状态页会缓存并周期刷新，不能把它当作管理员仪表盘的实时替代品。

5. 重建容器后配置消失

检查 Compose 是否仍然包含：

– ./data:/app/data

还要确认执行命令时使用的是原来的项目目录。相对路径变化会让 Compose 指向另一套空数据目录。

十六、删除教学服务，保留正式监控

完成故障演练后，demo-web 和 webhook-receiver 都可以删除。正式 Compose 最小配置如下：

services:
uptime-kuma:
image: louislam/uptime–kuma:2
restart: unless–stopped
ports:
– "127.0.0.1:3001:3001"
volumes:
– ./data:/app/data

停止并删除教学容器时，不要删除 data：

docker compose down

绑定挂载的 ./data 会保留。修改为正式 Compose 后重新执行 docker compose up -d 即可。

总结

安装 Uptime Kuma 并不难，真正有价值的是把下面这条链路跑通：

持久化部署 → 创建监控 → 配置通知 → 主动制造故障
↓ ↓
备份升级 ← 恢复验证 ← 收到恢复通知 ← 收到故障通知

本文的演示目标和本地 Webhook 接收器不是生产组件，而是一套可重复执行的验收方法。只有亲手停止一次服务、看到故障记录、确认通知到达并完成恢复，才能知道监控系统在真正出问题时是否有用。

参考资料

• Uptime Kuma 官方仓库与 README
• Uptime Kuma 官方 compose.yaml
• 官方 Wiki：How to Install
• 官方 Wiki：How to Update
• 官方 Wiki：Notification Methods
• 官方 Wiki：Status Page
• 官方 Wiki：Reverse Proxy
• Docker 官方文档：Compose Networking