Uptime Kuma 是一个开源的服务监控工具，可以定时检查网站、服务器端口和网络设备是否正常，并在故障时发送通知。它还可以生成公开的服务状态页。

• 项目源地址：https://github.com/louislam/uptime-kuma
• 部署方式：Docker Compose（用一个配置文件管理多个容器）
• HTTPS：Caddy（一个可以自动申请和续期 HTTPS 证书的 Web 服务器）

本文以 status.example.com 作为示例域名，以 203.0.113.10 作为示例 IP。它们都只是示例，操作时必须替换成自己的域名和 VPS 公网 IP。

一、准备工作

推荐配置：

• Debian 12，或 Ubuntu 22.04/24.04
• 1 核 CPU
• 至少 512 MB 内存，推荐 1 GB
• 至少 5 GB 可用硬盘
• 一个域名
• VPS 的 root 权限

还需要在 VPS 服务商的防火墙或安全组（服务商控制台中的网络防火墙）中放行以下端口：

• 22/TCP：SSH 登录
• 80/TCP：HTTP 和申请证书
• 443/TCP：HTTPS

如果 SSH 使用的不是 22 端口，请放行实际使用的端口。

二、设置域名解析

进入域名 DNS 管理页面，添加一条 A 记录：

类型	主机记录	记录值
A	status	VPS 的公网 IPv4 地址

例如，域名是 example.com，添加后完整地址就是 status.example.com。

只有在 VPS 已正确配置公网 IPv6，并且外部设备可以访问它时，才添加 AAAA 记录（指向 IPv6 地址的 DNS 记录）。错误的 AAAA 记录可能导致部分用户无法打开状态页。

DNS 解析生效通常需要几分钟，少数情况下可能更久。

三、登录 VPS

在电脑终端中执行下面这一条命令。请把示例 IP 换成自己的 VPS IP：

ssh root@203.0.113.10

本文后面的命令都在 VPS 的 SSH 终端中执行，并假定当前用户是 root。如果使用普通用户，需要在需要管理员权限的命令前加 sudo。

重要：本文每个 Bash 代码框都是一条独立命令，请逐条复制并执行。看到命令执行完成并重新出现终端提示符后，再执行下一条。

四、更新系统并安装基础工具

刷新软件列表：

apt update

升级已安装的软件：

apt upgrade -y

安装本教程需要的工具：

apt install -y ca-certificates curl nano ufw

五、配置系统防火墙

先允许 SSH，避免启用防火墙后无法登录：

ufw allow OpenSSH

如果 SSH 使用自定义端口，例如 2222，还要执行下面这条命令，并将端口改成实际端口：

ufw allow 2222/tcp

允许 HTTP：

ufw allow 80/tcp

允许 HTTPS：

ufw allow 443/tcp

启用防火墙：

ufw enable

出现确认提示时输入 y，然后按回车。最后查看规则：

ufw status

六、可选：给小内存 VPS 添加 Swap

Swap（交换空间）是在内存不足时临时使用的一部分硬盘空间。它不能代替真实内存，但能降低小内存 VPS 因内存耗尽而中止程序的概率。

先检查是否已经存在 Swap：

swapon --show

如果命令显示了已有的 Swap，请跳过本节。没有任何输出时，可以继续创建 1 GB Swap。

创建文件：

fallocate -l 1G /swapfile

限制文件权限：

chmod 600 /swapfile

格式化为 Swap：

mkswap /swapfile

立即启用：

swapon /swapfile

设置为开机自动启用：

echo '/swapfile none swap sw 0 0' >> /etc/fstab

检查结果：

free -h

七、安装 Docker 和 Docker Compose

下面使用 Docker 官方软件源安装，不使用系统仓库中的旧版本。

创建密钥目录：

install -m 0755 -d /etc/apt/keyrings

读取当前系统信息：

source /etc/os-release

下载 Docker 软件源的签名密钥：

curl -fsSL "https://download.docker.com/linux/$ID/gpg" -o /etc/apt/keyrings/docker.asc

允许系统读取密钥：

chmod a+r /etc/apt/keyrings/docker.asc

添加 Docker 官方软件源：

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$ID $VERSION_CODENAME stable" > /etc/apt/sources.list.d/docker.list

再次刷新软件列表：

apt update

安装 Docker、Compose 插件及相关组件：

apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

设置 Docker 开机自动运行，并立即启动：

systemctl enable --now docker

检查 Docker 版本：

docker --version

检查 Docker Compose 版本：

docker compose version

两条检查命令都能正常显示版本号，就说明安装成功。

八、创建 Uptime Kuma 配置

创建项目目录：

mkdir -p /opt/uptime-kuma

进入项目目录：

cd /opt/uptime-kuma

打开 Compose 配置文件：

nano compose.yaml

此时终端会进入 Nano 文本编辑器。下面是配置文件内容，不是终端命令。请一次性粘贴到 Nano 编辑器中：

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data

  caddy:
    image: caddy:2-alpine
    container_name: uptime-kuma-caddy
    restart: unless-stopped
    depends_on:
      - uptime-kuma
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-data:/data
      - ./caddy-config:/config

保存方法：

1. 按 Ctrl + O。
2. 按回车确认文件名。
3. 按 Ctrl + X 退出编辑器。

YAML（常用于保存配置的文本格式）对缩进非常敏感。请使用空格，不要使用 Tab 键，也不要删除行尾的冒号。

九、创建 Caddy 配置

确认仍位于项目目录：

cd /opt/uptime-kuma

打开 Caddy 配置文件：

nano Caddyfile

下面同样是配置文件内容，不是终端命令。请把 status.example.com 替换成自己的完整状态页域名，然后粘贴到 Nano 编辑器中：

status.example.com {
    encode zstd gzip
    reverse_proxy uptime-kuma:3001
}

按 Ctrl + O，按回车，再按 Ctrl + X 保存并退出。

这里的 reverse_proxy 是反向代理，即由 Caddy 接收外部访问，再把请求转发给 Uptime Kuma。域名必须和浏览器中访问的域名完全相同。

不要把上面的三行 Caddy 配置直接粘贴到 Bash 终端，否则会出现 command not found。它们只能写入 /opt/uptime-kuma/Caddyfile。

十、检查配置并启动

检查 Compose 文件语法：

docker compose config

如果命令正常输出整理后的配置，而且没有报错，再检查 Caddyfile：

docker compose run --rm caddy caddy validate --config /etc/caddy/Caddyfile

看到 Valid configuration 后启动服务：

docker compose up -d

-d 表示让服务在后台运行。

检查两个容器的状态：

docker compose ps

正常情况下，uptime-kuma 和 uptime-kuma-caddy 都应显示为运行状态。

查看 Uptime Kuma 日志：

docker compose logs --tail=100 uptime-kuma

查看 Caddy 日志和 HTTPS 证书申请情况：

docker compose logs --tail=100 caddy

十一、完成首次设置

在浏览器中打开自己的状态页域名，例如：

https://status.example.com

首次打开时需要：

1. 选择界面语言。
2. 创建管理员账号和强密码。
3. 登录管理后台。

建议先添加一个 HTTPS 监控：

1. 点击“添加监控项”。
2. 监控类型选择 HTTP(s)。
3. 填写名称和需要检查的网址。
4. 心跳间隔可先使用 60 秒。
5. 保存后等待第一次检测。

常见监控类型包括：

• HTTP(s)：检查网站能否访问。
• TCP Port：检查指定服务器端口能否连接。
• Ping：检查主机网络是否可达。
• DNS：检查域名解析是否正常。

在“设置 → 通知”中可以配置邮件、Telegram、Discord 等通知渠道。请使用“测试”按钮确认通知能够收到。

如果需要公开展示运行情况，可以进入“状态页”创建一个页面，再把已有监控项加入状态页。后台管理地址和公开状态页不是同一个页面。

十二、日常更新

进入项目目录：

cd /opt/uptime-kuma

拉取新镜像：

docker compose pull

使用新镜像重新创建容器：

docker compose up -d

确认服务状态：

docker compose ps

容器重新创建不会删除 data 目录中的监控数据。

十三、备份与恢复

Uptime Kuma 的重要数据保存在 /opt/uptime-kuma/data。备份时短暂停止服务，可以避免复制到一半时数据发生变化。

进入项目目录：

cd /opt/uptime-kuma

停止服务：

docker compose down

创建压缩备份：

tar -czf "/root/uptime-kuma-backup-$(date +%F-%H%M).tar.gz" compose.yaml Caddyfile data caddy-data caddy-config

重新启动：

docker compose up -d

请定期把备份文件下载到另一台设备。只把备份留在同一台 VPS 上，无法防范硬盘损坏或 VPS 被删除。

恢复时，应先停止服务，把备份中的文件解压回 /opt/uptime-kuma，再重新启动。恢复操作会覆盖现有数据，执行前应额外备份一次当前数据。

十四、常见问题

1. 出现 command not found

如果输入以下内容后出现错误：

status.example.com: command not found
encode: command not found
reverse_proxy: command not found

说明把 Caddyfile 的内容粘贴到了 Bash 终端。请执行：

cd /opt/uptime-kuma

然后打开文件：

nano Caddyfile

把 Caddy 配置粘贴到编辑器中，而不是粘贴到终端提示符后面。

2. docker compose config 报 YAML 错误

类似下面的错误通常由缩进不一致、缺少冒号或使用 Tab 键造成：

could not find expected ':'

打开文件重新检查：

nano /opt/uptime-kuma/compose.yaml

建议直接和本文的完整配置逐行对照。服务名 uptime-kuma:、caddy: 及字段后的冒号都不能遗漏。

修改后再次检查：

cd /opt/uptime-kuma

docker compose config

3. 浏览器显示 ERR_SSL_PROTOCOL_ERROR

依次检查：

• DNS 的 A 记录是否指向当前 VPS。
• Caddyfile 中的域名是否与实际访问的域名完全一致。
• VPS 服务商防火墙和 UFW 是否都放行了 80、443 端口。
• 80、443 端口是否被其他面板、Nginx 或 Apache 占用。
• 是否添加了错误或不可用的 AAAA 记录。

查看端口占用：

ss -lntp | grep -E ':80|:443'

查看 Caddy 的报错：

cd /opt/uptime-kuma

docker compose logs --tail=100 caddy

如果修改了 Caddyfile，重新加载配置：

docker compose restart caddy

4. 域名打不开，但容器正在运行

先检查容器：

cd /opt/uptime-kuma

docker compose ps

再从 VPS 测试 HTTPS：

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

执行时要把示例域名换成自己的域名。如果仍失败，结合 Caddy 日志判断是 DNS、端口还是证书问题。

5. 是否需要开放 3001 端口

不需要。本教程让 Caddy 和 Uptime Kuma 在 Docker 内部通信，对公网只开放 80 和 443 端口。这样更简单，也能减少不必要的公开入口。

6. 为什么不建议只监控这台 VPS 自己

Uptime Kuma 可以监控本机服务，但如果整台 VPS 断电或网络中断，它也无法发送故障通知。重要服务最好再由另一台服务器或第三方监控服务进行外部检测。

十五、完成后的安全建议

• 管理员密码使用随机强密码，不要与其他网站共用。
• 定期更新系统、Uptime Kuma 和 Caddy 镜像。
• 定期备份 data 目录，并把备份保存到其他设备。
• 不要公开 3001 端口。
• 不要随意把 Docker Socket（Docker 的管理接口）挂载进容器。
• 只为真正配置成功的 IPv6 添加 AAAA 记录。

至此，Uptime Kuma 已经通过 HTTPS 运行。之后可以逐步添加网站、服务器端口和网络设备，并按需要配置通知与公开状态页。