使用 Uptime Kuma 监控您的服务
使用 Docker Compose 在 Debian 或 Ubuntu 上安装 Uptime Kuma,通过 HTTPS 保护其访问,创建监控项和通知,并管理更新与备份。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
Uptime Kuma 是一款自托管的监控工具。它会定期检查您的网站、端口和服务,保存其可用性历史记录,并在发生故障时通知您。
完成本指南后,Uptime Kuma 将运行在 Docker 中,只监听服务器的本地地址,并在 Caddy 之后通过 HTTPS 响应,访问也受到保护。您将创建第一个监控项和一条通知,并掌握如何更新和备份该实例。
订购服务器
本指南适用于由您自行管理的服务器:
前提条件
- 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的服务器
- 使用具有
sudo权限的用户进行 SSH 访问 - Docker Engine 和 Docker Compose,按照指南安装 Docker Engine 和 Docker Compose安装
- Caddy,按照指南使用 Caddy 反向代理并自动启用 HTTPS安装
- 一条将
uptime.您的域名.com指向您的服务器IP的 A 记录 - 用于存放数据的本地磁盘:不支持 NFS 等网络共享
docker 命令假定您的用户属于 docker 组。否则,请在命令前加上 sudo。
本指南使用 2.5.12 版本,这是撰写本文时最新的稳定版本。请在 Uptime Kuma 版本页面查看当前版本。第 3 版分支仍处于 Beta 阶段:请勿在生产环境中使用。
使用的端口
| 端口 | 方向 | 作用 | 是否需要开放 |
|---|---|---|---|
| 80/tcp | 入站 | 证书以及重定向到 HTTPS,经由 Caddy | 是 |
| 443/tcp | 入站 | HTTPS 访问,经由 Caddy | 是 |
| 3001/tcp | 本地 | Uptime Kuma 界面,位于 127.0.0.1 |
否 |
服务器还必须能够通过出站连接访问被监控的服务和您的通知服务。
步骤 1:创建 Compose 项目
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yaml粘贴以下配置:
services:
uptime-kuma:
image: louislam/uptime-kuma:2.5.12
container_name: uptime-kuma
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- ./data:/app/data启动容器:
docker compose config --quiet
docker compose up -d
docker compose ps容器应显示为已启动(Up)。其健康检查在最初几分钟内可能一直处于 starting 状态。
步骤 2:通过 SSH 隧道创建账户
第一位访问者将创建管理员账户。因此,请在发布站点之前完成此操作。在您的电脑上的终端中运行:
ssh -N -L 3001:127.0.0.1:3001 您的用户名@您的服务器IP该命令会保持运行,不输出任何内容。然后打开 http://localhost:3001,并执行以下操作:
- 选择您的语言。
- 选择 SQLite 数据库,它适合规模不大的安装。
- 等待数据库准备完成。
- 使用长且唯一的密码创建管理员账户。
步骤 3:加强账户安全
在 Settings(设置)中:
| 部分 | 设置 | 值 |
|---|---|---|
| Security | 2FA Settings | 使用 TOTP 应用启用双重身份验证 |
| Security | Disable Auth | 请勿启用 |
| Reverse Proxy | Trust Proxy | Yes,因为该服务只能通过 Caddy 访问 |
Trust Proxy 可在日志中显示访客的真实地址。仅当 3001 端口仍限制在 127.0.0.1 时才启用此选项。
步骤 4:使用 Caddy 发布界面
请选择适合您用途的模式。
仅限您的地址访问(推荐)
只有您的 IP 地址可以访问界面。/api/push/ URL 仍可访问,以便您的计划任务发送信号。请将以下站点添加到 /etc/caddy/Caddyfile:
uptime.您的域名.com {
@push path /api/push/*
@allowed client_ip 您的IP
handle @push {
reverse_proxy 127.0.0.1:3001
}
handle @allowed {
reverse_proxy 127.0.0.1:3001
}
handle {
abort
}
}如果您的地址经常变化,建议改用 WireGuard 或 Tailscale。
带状态页面的公开访问
状态页面必须对您的用户可见。在这种情况下,登录界面同样可以访问:步骤 3 的双重身份验证就变得必不可少。
uptime.您的域名.com {
reverse_proxy 127.0.0.1:3001
}应用配置
Caddy 会自行转发 Uptime Kuma 所需的 WebSocket。由于 Caddy 安装在服务器上而不是 Docker 中,UFW 对其端口生效:
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy验证结果
您可以用 Ctrl+C 关闭隧道。打开 https://uptime.您的域名.com:应显示登录页面且证书有效。在服务器上检查端口:
docker ps --filter name=uptime-kuma --format '{{.Names}} {{.Status}} {{.Ports}}'输出应包含 127.0.0.1:3001->3001/tcp。从另一台机器上检查时,3001 端口不应处于开放状态:
nmap -Pn -p 3001 您的服务器IP在受限访问模式下,来自您地址以外的连接应被断开。
步骤 5:添加第一个监控项
- 单击 Add New Monitor。
- 在 Monitor Type 中选择 HTTP(s)。
- 填写 Friendly Name,然后在 URL 中填写要监控的地址,例如
https://www.您的域名.com。 - 设置 Heartbeat Interval(两次检查之间的间隔)和 Retries(发出警报前的重试次数)。
- 启用 Certificate Expiry Notification,以便在证书到期前收到通知。
- 单击 Save。
最实用的监控项类型:
| 类型 | 用途 |
|---|---|
| HTTP(s) | 网站或 API,并检查响应代码 |
| HTTP(s) - Keyword | 检查页面中是否存在某个词 |
| TCP Port | 监听某个端口的服务,例如 SSH 或数据库 |
| Ping | 机器的网络响应 |
| DNS | 域名解析 |
| Push | 由计划任务自行上报其执行情况 |
监控计划任务
创建一个 Push 监控项并复制其 Push URL。在脚本末尾调用它,且仅在脚本成功时调用:
/usr/local/bin/my-backup.sh && curl -fsS -m 10 --retry 3 "https://uptime.您的域名.com/api/push/您的令牌?status=up&msg=OK"将 您的令牌 替换为您 URL 中的值。如果在预定时间内没有收到信号,该监控项会变为 DOWN 状态。请将此 URL 视为机密信息。
步骤 6:配置通知
打开 Settings > Notifications,然后单击 Set Up Notification。Uptime Kuma 支持众多服务。下面的示例使用 Telegram:
- 在 Telegram 中联系 @BotFather,发送
/newbot,然后复制获得的令牌。 - 向您的新机器人发送一条消息。
- 在 Uptime Kuma 的 Notification Type 中选择 Telegram。
- 将令牌粘贴到 Bot Token 中。
- 单击 Auto Get 以填写 Chat ID。
- 启用 Default enabled 以将其应用于今后创建的监控项,并启用 Apply on all existing monitors 以应用于现有监控项。
- 单击 Test。如果收到消息,请单击 Save。
如需使用电子邮件,请选择 Email (SMTP) 并填写您的邮件服务提供的参数,最好使用专用账户。
通知只有与监控项关联后才会生效。请在每个监控项详情的 Notifications 栏中进行确认。
创建状态页面
在 Status Pages 中单击 New Status Page,选择名称和地址,然后添加要显示的监控项。该页面可通过 /status/your-page 访问。它专为公开访问而设计,其数据会缓存 5 分钟。
使用步骤 4 的受限访问时,只有您的地址才能看到该页面。若要将其公开,请使用第二个 Caddy 配置块。
更新 Uptime Kuma
请先备份 data 文件夹并阅读发行说明。然后替换 compose.yaml 中的标签,并执行:
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose ps在阅读迁移到第 3 版的指南之前,请继续使用第 2 版分支。此迁移会修改数据库,没有备份就无法回退。
备份与恢复
除 compose.yaml 外,data 文件夹是唯一需要备份的内容。这是该项目支持的方法:旧的 JSON 导出功能已在第 2 版中移除。
cd /opt/uptime-kuma
mkdir -p backups
docker compose stop
sudo tar -czf "backups/uptime-kuma-$(date +%F).tar.gz" data compose.yaml
docker compose start
sudo chmod 600 backups/*.tar.gz该归档包含数据库、账户和通知令牌。请将其复制到服务器之外的加密位置。
要恢复归档,请将 YYYY-MM-DD 替换为其日期:
cd /opt/uptime-kuma
docker compose down
sudo mv data "data.old-$(date +%F)"
sudo tar -xzf backups/uptime-kuma-YYYY-MM-DD.tar.gz
docker compose up -d请使用与备份时相同的镜像版本,或同一分支的更新版本。
故障排除
Cannot connect to the socket server
界面无法建立 WebSocket 连接。请确认容器正在运行并查看其日志:
docker compose ps
docker compose logs --tail=50 uptime-kuma如果 Caddy 前面还有其他代理(例如 Cloudflare),请确认其中已启用 WebSocket,并且原始域名被正确传递。
Caddy 出现 502 错误
Caddy 无法连接到应用。请检查本地端口:
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50服务正常响应,但监控项显示 DOWN
检查是从容器发起的,其网络与您电脑的网络不同。请在容器内进行测试,并根据实际情况调整地址:
docker exec uptime-kuma node -e "fetch('https://www.您的域名.com').then(r => console.log(r.status)).catch(console.error)"另外,请确认被监控的服务没有屏蔽服务器的地址,例如通过防火墙或 CrowdSec。
IPv6 监控项失败
默认情况下,容器的 Docker 网络不使用 IPv6。如果该服务只能通过 IPv6 访问,请在 compose.yaml 中添加一个启用 IPv6 的网络:
services:
uptime-kuma:
networks:
- uptime-kuma-net
networks:
uptime-kuma-net:
enable_ipv6: true将这些键与您现有的服务合并,然后重新运行 docker compose up -d。
未收到 Push 信号
请在运行任务的机器上使用 curl -i 测试该 URL。连接被断开通常表示 Caddy 中缺少 @push 配置块。响应中应包含 "ok":true。
未收到任何通知
请使用 Test 按钮并阅读错误消息。然后确认该通知已在监控项上启用。对于 SMTP 发送,请向您的邮件服务核实主机、端口和用户名。
密码丢失或无法使用双重身份验证
运行相应的命令,然后按照显示的说明操作:
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fadatabase is locked 或数据库损坏
请确认 data 位于本地磁盘而不是 NFS 上,并用 df -h 确认磁盘空间充足。如果数据库已损坏,请恢复最近一次备份。
port is already allocated
另一个服务占用了 3001 端口。请用 sudo ss -ltnp | grep ':3001 ' 找出它。若要更改端口,只需修改左侧部分,例如 127.0.0.1:3002:3001,然后相应调整 Caddy 配置。