Uptime Kuma VPS 部署：Docker Compose、Caddy、告警

Uptime Kuma 是一款开源、可自托管的监控工具，支持 HTTP(S)、TCP、ping、DNS、WebSocket 等多种检查。把它放在独立的 VPS 上，生产服务器宕机时它仍会继续检查，而不会随之一起消失。

本文这套 Uptime Kuma 的 VPS 部署方案用 Docker Compose 安装 v2，把 3001 端口限制在回环地址上，通过 Caddy 启用 HTTPS，把告警发送到 Telegram、Discord 和 Slack，并发布一个状态页。

前置条件与所需材料

一台至少 1 vCPU、1 GB 内存和 10 GB 本地 SSD 存储的 VPS
Ubuntu 24.04 LTS，或 Docker 支持的其他当前 Ubuntu 版本
VPS 上已安装 Docker Engine 和 Docker Compose
一个通过 A 记录指向该 VPS 的域名或子域名（例如 status.example.com）
SSH 访问权限，以及基本的命令行操作能力

如果尚未安装 Docker，请参考 Docker 的 Ubuntu 安装指南。它会安装 Docker Engine 以及下文用到的 Compose 插件。

为什么监控用的 VPS 必须与被监控对象分开

Production in Region A has failed and its website, API and database are down, while Uptime Kuma on a separate VPS in Region B stays online, keeps probing those services and routes alerts to Telegram, Discord and Slack. An external watchdog checks Uptime Kuma itself.

生产环境和监控跑在同一台服务器上，就共享同一个故障域。这台服务器一停，应用和本该发出告警的系统会一起消失。

有两种实用的部署方式可以改善这一点：

同一家服务商，不同机房。 把生产环境和监控放在不同机房的独立主机上。这样可以降低单台服务器或单个数据中心故障带来的风险，但并不能防住服务商全局的网络或控制平面故障。
换一家完全不同的服务商。 把监控托管到别处，还能防住波及整家服务商的故障。代价是多一个账号、多一张账单、多一块要维护的面。

单个 Uptime Kuma 实例本身仍然没有外部看门狗。给它的公开状态页加一个外部 HTTP(S) 检查。 UptimeRobot 的免费套餐目前包含 50 个监控项，检查间隔为五分钟。这并不会让 Uptime Kuma 变成高可用，但能在监控本身消失时告诉你。

同样的道理也适用于公开状态页：负责告诉你出故障的那个东西，不能和出故障的东西处在同一个故障域里。

在拥有 root 权限、NVMe 与 AMD EPYC 强大性能的 Linux VPS 上构建应用。

查看 Linux 套餐

VPS 配置怎么选

Uptime Kuma 没有一个靠谱的「监控数量对应多少内存」的公式，因为负载会随监控类型、检查间隔、重试设置和历史保留时长而变化。简单的 HTTP(S)、TCP、ping 和 DNS 检查，比要启动 Chromium 的 Browser Engine 检查轻得多。

如果只跑少量基础检查，从 1 vCPU、1 GB 内存和本地 SSD 存储起步即可。实际占用可以用 docker stats uptime-kuma 查看，数据库增长则可以用 du -sh /opt/uptime-kuma/data查看。当占用长期居高不下、容器出现 OOM kill，或者你开始使用 Browser Engine 检查时，就该加内存了。

完整版 v2 镜像内置了 Chromium 和 MariaDB， Docker 标签文档解释了完整版和精简版镜像的区别。

用 Docker Compose 部署 Uptime Kuma

把下面的内容保存为 /opt/uptime-kuma/ 目录下的 docker-compose.yml：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      # Bind to localhost only. The reverse proxy will expose it on 443.
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data

有三行值得单独说一下：

image: louislam/uptime-kuma:2 把主版本固定住。:2 标签跟随稳定的 2.x 发布线。不要用 :latest。
127.0.0.1:3001:3001 让容器只绑定到本机回环地址。公网绝不能直接访问 3001 端口。TLS 证书和对外主机名都由反向代理持有。
data 卷里存放着数据库、监控配置和历史记录。请把它放在本地存储上，因为 Uptime Kuma 的安装文档明确警告：缺乏可靠 POSIX 文件锁的文件系统（包括很多 NFS 配置）可能损坏 SQLite。在做文件系统级别的备份之前，请先停掉整套服务。

启动并验证：

sudo install -d -o "$USER" -g "$USER" /opt/uptime-kuma
cd /opt/uptime-kuma
# Paste the docker-compose.yml file above.
sudo docker compose up -d
sudo docker compose ps

docker compose ps 的预期输出：

NAME          IMAGE                       STATUS                   PORTS
uptime-kuma   louislam/uptime-kuma:2      Up (healthy)             127.0.0.1:3001->3001/tcp

第一次进入面板时，哪怕只是一小会儿，也不要把 3001 端口暴露到公网。用 SSH 隧道连过去：

ssh -L 3001:127.0.0.1:3001 [email protected]

在浏览器里打开 http://localhost:3001，创建管理员账号，设置一个强密码，然后关掉隧道。之后你就通过反向代理以 HTTPS 访问面板了。

如果你不需要手动折腾 Compose，我们也提供 Uptime Kuma 一键应用。当前应用页面标注的是 v1，与本文的 v2 Compose 方案并不一致。如果你明确需要 v2，请走手动 Compose 这条路。

反向代理与 TLS

Public traffic reaches Caddy on the host or an Nginx Proxy Manager container over HTTPS on port 443. Caddy forwards to Uptime Kuma on 127.0.0.1:3001 while the NPM container uses a shared Docker network instead. Public access to port 3001 is blocked, and first-time setup runs through an SSH tunnel to localhost:3001.

不要把 Uptime Kuma 直接暴露出去。在它前面放一个反向代理，用来处理 TLS、规范 URL，并提供唯一的对外入口。有两条路。

Caddy。 如果还没装 Caddy，按官方的 Ubuntu 软件包步骤装上即可。当 Caddy 作为宿主机服务运行时，下面这份 Caddyfile 会把请求代理到回环地址上的 Uptime Kuma，并自动完成证书签发和续期。

小提示：如果监控 VPS 上只跑 Uptime Kuma，就用 Caddy。Caddyfile 只有三行，证书签发和续期 Caddy 全自动搞定。不用 Certbot，也没有需要你凌晨四点爬起来盯的续期定时器。

把它保存为 /etc/caddy/Caddyfile：

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

重载 Caddy：

sudo systemctl reload caddy

验证：

curl -I https://status.example.com

你应当收到一个 2xx 或 3xx 的成功响应，并带有有效证书。如果连不上，请确认域名的 A 或 AAAA 记录指向这台 VPS、80 和 443 端口可达，且 Caddy 能同时绑定这两个端口。这些都属于 Caddy 自动 HTTPS 的前提条件.

Nginx Proxy Manager。 如果 NPM 直接跑在宿主机上，就为 status.example.com 添加一个 Proxy Host，转发到 127.0.0.1 的 3001 端口，申请 Let's Encrypt 证书，并打开 Websockets Support。如果 NPM 跑在 Docker 里，127.0.0.1 指的是 NPM 容器自己。这时应该把 NPM 和 Uptime Kuma 接到同一个 Docker 网络，再把代理主机转发到 uptime-kuma 的 3001 端口。

告警分发：Telegram、Discord、Slack

Uptime Kuma 可以把同一个监控事件分发到多个通知渠道。每个渠道只需配置一次，之后按「谁需要收到这条告警」把一个或多个渠道挂到监控项上。

通知在 设置 > 通知里统一配置，然后再分配给各个监控项。每个监控项可以触发一个或多个渠道。同一条告警可以同时发到值班工程师的 Telegram、团队的 Slack，以及用于审计留痕的邮箱，全都来自同一个事件。

Telegram

在 Telegram 里给 @BotFather 发消息并执行 /newbot。取一个名字和用户名，BotFather 会回复一个 bot token，把它存好。
给新建的 bot 随便发一条消息，然后在浏览器里打开 https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates，找到 chat.id 字段，那就是你的 chat ID。
在 Uptime Kuma 中： 设置 > 通知 > 添加通知 > Telegram。粘贴 bot token 和 chat ID，然后点击测试，确认 bot 发出了那条测试告警。
如果测试消息没到，检查 bot token 和 chat ID 是否正确，并确认 VPS 防火墙放行了到 api.telegram.org 的出站 HTTPS。

Discord

打开你想接收告警的 Discord 服务器，右键点击目标频道，然后依次进入 编辑频道 > 整合 > Webhook > 新建 Webhook。给它起个名字（比如「Uptime Kuma」），选好频道，复制 webhook URL。
在 Uptime Kuma 中： 设置 > 通知 > 添加通知 > Discord。粘贴 webhook URL。愿意的话还可以设置用户名和头像。
点击测试，确认 webhook 把那条测试告警发到了频道里。

Slack

在 Slack 里，为你想接收告警的频道创建一个 Incoming Webhook 。Slack 会返回一个形如 https://hooks.slack.com/services/T.../B.../.... 的 webhook URL。
在 Uptime Kuma 中： 设置 > 通知 > 添加通知 > Slack。粘贴 webhook URL。愿意的话还可以配置图标和覆盖频道。
点击测试.

所有测试都通过之后，逐个编辑监控项，选好它要用的通知渠道。把 Max Retries（最大重试次数） 和 Retry Interval（重试间隔） 设好，免得一次短暂的失败就立刻触发告警。

内置状态页（以及什么时候它会不够用）

Uptime Kuma 自带公开状态页，支持自定义 slug、监控项分组、自定义域名、事故公告和计划维护通知。你还可以从同一个实例发布多个状态页，面向不同的服务或不同的受众。

它更大的短板在于对客户的沟通。访客目前还无法直接在状态页上用邮箱订阅更新，而且这个公开页面仍然和运维人员的面板同属一个 Uptime Kuma 应用。访客自助订阅至今仍是一个尚未关闭的功能请求.

如果你需要让客户订阅，或者想要一套与监控面板分离的状态系统，Kener 是一个可选项。我们那篇自托管监控栈的文章讲了这两个工具怎么搭配使用。

常见问题

当 VPS 防火墙拦掉出站 HTTPS 时，通知会悄无声息地失败。 现象：Test 按钮在部分渠道能用、另一些不行。处理：确认放行了出站 HTTPS 连接，并且在 VPS 上执行 curl -I https://api.telegram.org 能成功。

浏览器报「ERR_TOO_MANY_REDIRECTS」 ，通常出现在启用代理之后。检查 Caddy、Nginx Proxy Manager 或上游 CDN 里是否有重复的 HTTP 跳 HTTPS 规则。Uptime Kuma 应该继续在 3001 端口上以 HTTP 提供服务，由对外的反向代理负责终结 TLS。如果你要启用受信任的代理头，当前的路径是 设置 > Reverse Proxy > HTTP Headers > Trust Proxy。

容器每隔几分钟就重启一次。 先确认容器是不是因为内存不足被干掉的，再用 docker stats uptime-kuma 观察当前占用。如果确实是 OOM kill，或者内存一直贴着 VPS 上限，那就加内存、减少重型检查，或者把它们的检查间隔拉长。

状态页在 localhost 上正常，但通过对外主机名就不行。 确认反向代理原样转发根路径、保留 Host 头，并且支持 WebSockets。Uptime Kuma 不支持装在子目录下，所以请用独立的域名或子域名，而不是 example.com/uptime-kuma 这种路径。

小结

把 Uptime Kuma 放在独立 VPS 上，你就掌握了检查项、告警路由和公开状态页；但更新、备份、系统打补丁，以及给监控本身找一个外部看门狗，也都归你管了。挑一台和生产环境不在同一地点的 VPS，用 Docker Compose 部署 v2，或者在确认过标注版本后使用一键应用，前面架上 Caddy，再把团队真正会看的渠道接上。

常见问题

Uptime Kuma 需要多少内存？

Uptime Kuma 没有靠谱的「监控数量对应多少内存」的公式，因为占用会随监控类型、检查间隔、重试设置、历史保留时长以及是否使用 Browser Engine 而变化。如果只有少量基础检查，先给 1 GB 内存，再用 docker stats uptime-kuma 观察实际占用。若占用长期贴着上限，或者容器被 OOM kill，就加内存。

该把 Uptime Kuma 和我的应用放在同一台服务器上吗？

不该。监控工具和应用挤在同一台服务器上，服务器一挂两边同时下线，你恰恰在最需要告警的时候失去了告警。把 Uptime Kuma 放在独立的 VPS 上，最好还在另一个数据中心。

Uptime Kuma 能把告警发到 Telegram、Discord 和 Slack 吗？

可以。Telegram、Discord 和 Slack 都是内置的通知渠道，此外还有邮件、通用 webhook、PagerDuty、ntfy、Mattermost 等等。Telegram 用的是 bot token 加 chat ID，Discord 和 Slack 用的是 webhook URL。同一个监控项可以同时挂多个通知渠道。