很多人买 VPS 以后,最容易忽略的一件事是:机器挂了,你可能是最后一个知道的人。
我以前就踩过这个坑。一个小网站半夜证书续期失败,Nginx 直接不工作了。第二天早上打开后台才发现,网站已经挂了 7 个小时。访问量不大,但搜索引擎、用户、客户都会看到错误页面,这种损失很烦。
Uptime Kuma 适合解决这个问题。它不是那种复杂到要先学一堆概念的监控系统,而是一个比较轻量的自托管监控面板:能看网站是否在线,能监控端口,能 Ping 机器,能发 Telegram、邮件、Webhook 通知,还能做一个公开状态页。
这篇按 VPS 实战来写:用 Docker Compose 部署 Uptime Kuma,用 Caddy 做 HTTPS,数据怎么备份,通知怎么配,哪些服务值得监控,哪些误报不用太紧张。
Uptime Kuma 适合这些场景:
- 你有几个网站、API、后台服务要盯着。
- 你想要宕机后立刻收到 Telegram、邮件或企业微信通知。
- 你需要一个简单状态页,告诉用户哪些服务正常、哪些服务故障。
- 你不想上 Prometheus + Grafana 那套比较重的东西。
- 你只有一台低配 VPS,也希望跑得动。
不太适合这些场景:
- 你要做复杂指标分析,比如 CPU、内存、磁盘、慢查询趋势。
- 你要保存几年级别的时序数据。
- 你需要多租户权限、复杂报表和企业审计。
我的建议是:Uptime Kuma 用来做“服务是否活着”的监控,Prometheus/Grafana 用来做“为什么变慢”的监控。 两者不是一类东西。
Uptime Kuma 很轻,个人使用不挑机器。
| 规模 | 推荐配置 |
|---|---|
| 5-20 个监控项 | 1 vCPU / 512MB RAM / 10GB SSD |
| 20-100 个监控项 | 1 vCPU / 1GB RAM / 20GB SSD |
| 多状态页 + 多通知渠道 | 2 vCPU / 2GB RAM / 40GB SSD |
真正要注意的是:监控面板最好不要和所有业务放在同一台机器上。
比如你只有一台 VPS,网站和 Uptime Kuma 都跑在这台机器上。机器宕机时,Uptime Kuma 也一起挂了,它当然没法通知你。所以更好的做法是:
- 主业务在 A 机器。
- Uptime Kuma 放在 B 机器。
- 如果预算有限,B 机器买一台便宜年付 VPS 就够。
如果暂时只有一台机器,也不是不能部署,至少可以先监控域名、证书、端口和 Docker 容器状态。以后业务变重要了,再把监控面板迁到另一台 VPS。
本文默认环境:
- Ubuntu 22.04 / 24.04 或 Debian 12。
- 已安装 Docker 和 Docker Compose。
- 有一个域名,例如
status.example.com。 - 80/443 端口可以访问。
- 已经安装 Caddy,或者准备按本文配置。
先确认 Docker 可用:
docker version
docker compose version
确认域名已经解析到 VPS:
dig status.example.com +short
如果还没装 Caddy,可以先看这篇:VPS 用 Caddy 反向代理完全指南。
我习惯把这类服务放到 /opt:
sudo mkdir -p /opt/uptime-kuma
sudo chown -R "$USER":"$USER" /opt/uptime-kuma
cd /opt/uptime-kuma
创建数据目录:
mkdir -p data
Uptime Kuma 的监控项、通知配置、状态页、用户信息都在 /app/data 里。这个目录一定要持久化,不然后面删容器、升级镜像时数据会丢。
创建 docker-compose.yml:
nano docker-compose.yml
写入:
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
volumes:
- ./data:/app/data
ports:
- "127.0.0.1:3001:3001"
这里我故意只绑定 127.0.0.1:3001,不让 3001 端口直接暴露公网。
原因很简单:公网只开放 80/443,Uptime Kuma 放在 Caddy 后面。这样证书、HTTPS、访问控制都更好处理。
如果你还想用 Uptime Kuma 监控同一台 VPS 上的 Docker 容器,需要额外挂 Docker socket:
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
volumes:
- ./data:/app/data
- /var/run/docker.sock:/var/run/docker.sock:ro
ports:
- "127.0.0.1:3001:3001"
注意这行:
- /var/run/docker.sock:/var/run/docker.sock:ro
没有它,Uptime Kuma 通常看不到宿主机上的 Docker 容器,也就没法添加 Docker Container 类型的监控。
但也别随手给所有容器挂 Docker socket。它能读取 Docker 状态,本身就是一个高敏感入口。只建议在你确实需要 Docker 容器监控时开启,并且继续保持 Uptime Kuma 只通过 HTTPS 访问,不要把 3001 端口直接暴露公网。
启动服务:
docker compose up -d
看状态:
docker compose ps
docker compose logs -f --tail=100
本机测试:
curl -I http://127.0.0.1:3001
如果有响应,说明容器已经跑起来了。
编辑 Caddyfile:
sudo nano /etc/caddy/Caddyfile
加入:
status.example.com {
encode zstd gzip
header {
X-Content-Type-Options nosniff
Referrer-Policy strict-origin-when-cross-origin
}
reverse_proxy 127.0.0.1:3001
}
检查配置并重载:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
浏览器打开:
https://status.example.com
第一次访问会让你创建管理员账号。密码不要用弱密码,监控面板里通常会保存通知渠道的 Token、Webhook 地址和服务信息,被扫到也挺麻烦。
登录后点 Add New Monitor,先从网站监控开始。
常用配置:
- Monitor Type:HTTP(s)
- Friendly Name:主站
- URL:
https://example.com - Heartbeat Interval:60 秒或 120 秒
- Retries:2-3 次
- Accepted Status Codes:
200-299
我一般不会把间隔设得太短。很多小 VPS、便宜线路、海外网络,偶尔抖一下很正常。你设成 20 秒检测一次,最后可能是自己吓自己。
比较稳的设置是:
间隔:60 秒
重试:3 次
失败后再通知
这样可以过滤掉一些短暂网络抖动。
别一上来就加 100 个监控项,先盯真正重要的。
建议从这几类开始:
| 类型 | 例子 | 目的 |
|---|---|---|
| HTTP(s) | 官网、后台、API | 看页面是否能打开 |
| TCP Port | 22、443、5432、6379 | 看端口是否存活 |
| Ping | VPS IP、网关 | 看机器或线路是否通 |
| Keyword | 页面里必须出现某个词 | 避免“返回 200 但页面错误” |
| Docker Container | Nginx、Postgres、Redis | 看容器是否还在跑 |
我最常用的是 HTTP(s) + Keyword。因为有些网站即使报错,也可能返回 200。比如应用框架显示错误页,HTTP 状态码正常,但页面内容已经不是你想要的东西。
这时可以设置 Keyword:
必须包含:网站标题、品牌名、某个固定文字
如果页面不再包含这个词,Uptime Kuma 就会判定异常。
如果要加 Docker Container 监控,先确认前面的 Compose 已经挂载了 /var/run/docker.sock。否则你在 Uptime Kuma 里选择 Docker 类型时,大概率会连不上 Docker 守护进程。
Telegram 是我最推荐的通知方式之一,快、免费、配置简单。
大致流程:
- 找
@BotFather创建 Bot。 - 拿到 Bot Token。
- 给 Bot 发一条消息。
- 获取 Chat ID。
- 在 Uptime Kuma 里添加 Telegram 通知。
如果不会拿 Chat ID,可以访问:
https://api.telegram.org/bot你的TOKEN/getUpdates
找到里面的 chat.id。
Uptime Kuma 里进入:
Settings -> Notifications -> Setup Notification
选择 Telegram,填 Bot Token 和 Chat ID,然后点 Test。
测试成功后,记得把这个通知渠道设置为默认,或者手动绑定到重要监控项。
邮件通知适合做兜底。Telegram 有时会被手机系统静音,邮件至少能留下记录。
常见 SMTP 配置:
Host: smtp.example.com
Port: 587
Security: STARTTLS
Username: [email protected]
Password: 邮箱授权码
From: [email protected]
注意几个坑:
- 很多邮箱不能用登录密码,要用应用专用密码。
- VPS 商可能限制 25 端口,优先用 587 或 465。
- 发件邮箱最好配置 SPF、DKIM、DMARC,否则容易进垃圾箱。
- 不要把个人主邮箱密码填进去。
如果只是个人用,Telegram + 邮件已经够了。企业场景可以再接 Slack、Discord、Webhook、企业微信等。
Uptime Kuma 的状态页很实用。比如你有几个服务:
- 官网
- API
- 文档站
- 下载站
- 后台管理
你可以建一个公开页面:
https://status.example.com/status/main
用户或客户打开后能看到哪些服务正常,哪些服务故障。
不过我不建议把所有内部服务都公开。状态页只放用户需要知道的东西,例如官网、API、下载服务。数据库、Redis、内部后台这些不要放出去,没必要给别人看你的内部结构。
这点很多人会忘。
如果 Uptime Kuma 只监控别人,自己挂了没人知道。更稳的方式是:
- 用另一个免费监控服务监控
status.example.com。 - 或者再找一台低价 VPS 跑第二个 Kuma,相互监控。
- 或者用第三方服务做兜底,比如 Better Stack、Healthchecks、UptimeRobot 之类。
个人项目不用搞得太复杂,但至少要知道一个事实:单点监控只能发现别人的问题,发现不了自己完全宕机的问题。
Uptime Kuma 的数据在 /opt/uptime-kuma/data。备份这个目录就行。
最简单的备份:
cd /opt/uptime-kuma
mkdir -p /opt/backups/uptime-kuma
tar czf /opt/backups/uptime-kuma/uptime-kuma-$(date +%F-%H%M).tar.gz data
如果你已经用 restic、rclone 或对象存储做备份,把这个目录加入备份清单即可。
建议至少备份:
data/kuma.dbdata/upload/- 整个
/opt/uptime-kuma/data
恢复时先停服务:
cd /opt/uptime-kuma
docker compose down
mv data data.broken.$(date +%F-%H%M)
tar xzf /opt/backups/uptime-kuma/uptime-kuma-你的日期.tar.gz
docker compose up -d
恢复后检查:监控项还在不在,通知渠道能不能测试,状态页链接是否正常。
升级前先备份:
cd /opt/uptime-kuma
tar czf /opt/backups/uptime-kuma/before-upgrade-$(date +%F-%H%M).tar.gz data docker-compose.yml
拉新镜像并重启:
docker compose pull
docker compose up -d
看日志:
docker compose logs -f --tail=100
如果你不想每次都跟最新版本走,可以固定镜像版本。个人项目用 louislam/uptime-kuma:2 比较省心,生产环境更建议先在测试机升级一遍。
先看容器是否正常:
docker compose ps
curl -I http://127.0.0.1:3001
如果本机能访问,问题通常在 Caddy 配置。检查反代端口是否写对:
reverse_proxy 127.0.0.1:3001
然后:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
检查这个通知渠道有没有绑定到监控项。
Uptime Kuma 里通知可以设置默认,也可以只绑定某几个监控项。很多人只创建了通知渠道,但忘了给监控项启用。
先别急着怀疑服务挂了,可能是检测策略太激进。
可以调整:
- Heartbeat Interval 从 20 秒改到 60 秒。
- Retries 从 0 改到 2 或 3。
- 超时时间适当放宽。
- 不要用单个海外节点监控国内线路质量。
如果你的网站用户主要在国内,而 Uptime Kuma 放在欧洲 VPS 上,它看到的网络情况不一定代表国内用户体验。
用 Keyword 监控。
比如你的首页正常时一定有:
VPScost
那就让 Uptime Kuma 检查这个关键词。页面只要变成错误页、维护页、空白页,哪怕状态码还是 200,也能发现问题。
先看容器里有没有 Docker socket:
docker compose exec uptime-kuma ls -l /var/run/docker.sock
如果提示不存在,说明 Compose 没挂载这行:
- /var/run/docker.sock:/var/run/docker.sock:ro
改完后重启:
docker compose up -d
如果 socket 存在但仍然连不上,再检查 Docker 权限和 Uptime Kuma 里的 Docker Host 配置。个人 VPS 上最常见的问题就是:文章照着部署了基础版 Compose,但后面又想加 Docker Container 监控,结果忘了给 Kuma 访问 Docker 的入口。
正式使用前建议确认:
-
data目录已持久化。 - 3001 端口只绑定
127.0.0.1。 - 域名使用 HTTPS。
- 管理员密码足够强。
- 至少配置一个即时通知渠道。
- 重要监控项绑定了通知。
- 如果要监控 Docker 容器,已挂载
/var/run/docker.sock。 - 状态页没有暴露内部服务。
- 数据目录已纳入备份。
- 做过一次通知测试。
- 做过一次恢复演练。
Uptime Kuma 最适合做“第一层监控”:网站打不开、API 挂了、端口不通、证书快过期、关键词不见了,它能很快提醒你。
但它不是万能的。它告诉你“服务有问题”,不一定告诉你“为什么有问题”。如果你还想看 CPU、内存、磁盘、容器指标,可以再接 Prometheus + Grafana;如果只是个人项目、小团队网站、几个自托管应用,Uptime Kuma 已经够用了。
我自己的习惯是:重要服务先加 Uptime Kuma,至少保证宕机有人提醒;等服务变复杂,再补日志、指标和链路追踪。别一开始就把监控系统搞得比业务还复杂。
