【实用的开源工具】Uptime Kuma：网站宕机第一时间发到你的 Telegram

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-30，具体版本以官方为准。

项目信息卡

它能做什么

• 多种检查方式：网页（HTTP/HTTPS）、端口、Ping、DNS 等。
• 宕机通知：挂了和恢复了都会通知。可以发到 Telegram，手机上马上能看到。
• 状态页：可以生成一个公开的状态页，给客户看服务是否正常。
• 图形界面：在网页里点着配置，不用写配置文件。

这个工具和你的业务直接相关：给客户做的网站、机器人后台，挂了你要比客户先知道。

部署

官方提供了 Compose 文件。先建目录：

mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma

compose.yaml（内容与官方仓库一致，我只改了端口绑定）：

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

启动：

docker compose up -d

打开 http://127.0.0.1:3001（远程服务器可以先用 SSH 端口转发看），第一次访问会让你创建管理员账号。

官方也给了不用 Compose 的单行命令：

docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

Nginx 反向代理（必须带 WebSocket）

Uptime Kuma 靠 WebSocket 通信，官方说明需要 Upgrade 和 Connection 两个头，否则页面打不开或一直转圈：

server {
    listen 443 ssl http2;
    server_name status.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

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

如果域名走了 Cloudflare，官方要求在 Cloudflare 后台打开 WebSockets（Network 里）。

接上 Telegram 通知

1. 在 Telegram 找 @BotFather 创建机器人，拿到 Token；再取得你的 chat id。做法在我之前那篇 表单推送到 Telegram 里写过。
2. 在 Uptime Kuma 的设置里找到“通知”，新建一个 Telegram 类型的通知，填入 Token 和 chat id，点测试。界面文字以你的版本为准。
3. 新建监控时勾选这个通知，就会在状态变化时推送。

升级与备份

cd /opt/uptime-kuma
cp -a data data.bak-$(date +%F)    # 先备份
docker compose pull
docker compose up -d

踩坑清单

1. 数据目录不能放在 NFS 上。 官方明确写了不支持 NFS 之类的网络文件系统，要映射到本地目录或 Docker 卷。
2. 反向代理缺了 WebSocket 头，页面会一直加载。 这是最常见的问题，检查 Upgrade 和 Connection 两行。
3. Cloudflare 要手动开 WebSockets。 自己服务器配好了，经过 Cloudflare 还是不行，就看这一项。
4. 不支持子路径。 官方说明不能部署成 example.com/uptime 这种形式，要用单独的域名或子域名。
5. 镜像标签选 :2。 官方现在写的就是 louislam/uptime-kuma:2。从旧版本升级前先备份数据目录，并去看官方的迁移说明，我这里没有逐项核对旧版升级的细节。
6. Docker 发布的端口会绕过 ufw 之类的防火墙。 所以我绑定到了 127.0.0.1，只让 Nginx 访问。官方示例默认是对所有网卡开放的，如果你不套反向代理，要自己想好怎么保护这个登录页。
7. 监控和被监控不要在同一台机器上。 服务器整个挂了，装在上面的监控也一起挂，不会有人通知你。最好把 Uptime Kuma 放在另一台机器上，或者再用一个外部的免费监控兜底。
8. 别随便把 Docker socket 挂进去。 想监控其他容器时，有人会把 /var/run/docker.sock 映射给它，这等于给了它很高的权限。没有必要就不要这么做。

出处

• Uptime Kuma 官方仓库（Docker 部署、许可证、通知渠道）
• 官方 Wiki：Reverse Proxy
• 官方 Compose 文件