中文

应用程序

使用 Uptime Kuma 监控您的服务

使用 Docker Compose 在 Debian 或 Ubuntu 上安装 Uptime Kuma,通过 HTTPS 保护其访问,创建监控项和通知,并管理更新与备份。

阅读约 9 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

Uptime Kuma 是一款自托管的监控工具。它会定期检查您的网站、端口和服务,保存其可用性历史记录,并在发生故障时通知您。

完成本指南后,Uptime Kuma 将运行在 Docker 中,只监听服务器的本地地址,并在 Caddy 之后通过 HTTPS 响应,访问也受到保护。您将创建第一个监控项和一条通知,并掌握如何更新和备份该实例。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

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

粘贴以下配置:

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,并执行以下操作:

  1. 选择您的语言。
  2. 选择 SQLite 数据库,它适合规模不大的安装。
  3. 等待数据库准备完成。
  4. 使用长且唯一的密码创建管理员账户。

步骤 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:

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 的双重身份验证就变得必不可少。

caddyfile
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:添加第一个监控项

  1. 单击 Add New Monitor。
  2. 在 Monitor Type 中选择 HTTP(s)。
  3. 填写 Friendly Name,然后在 URL 中填写要监控的地址,例如 https://www.您的域名.com。
  4. 设置 Heartbeat Interval(两次检查之间的间隔)和 Retries(发出警报前的重试次数)。
  5. 启用 Certificate Expiry Notification,以便在证书到期前收到通知。
  6. 单击 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:

  1. 在 Telegram 中联系 @BotFather,发送 /newbot,然后复制获得的令牌。
  2. 向您的新机器人发送一条消息。
  3. 在 Uptime Kuma 的 Notification Type 中选择 Telegram。
  4. 将令牌粘贴到 Bot Token 中。
  5. 单击 Auto Get 以填写 Chat ID。
  6. 启用 Default enabled 以将其应用于今后创建的监控项,并启用 Apply on all existing monitors 以应用于现有监控项。
  7. 单击 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 的网络:

YAML
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-2fa

database is locked 或数据库损坏

请确认 data 位于本地磁盘而不是 NFS 上,并用 df -h 确认磁盘空间充足。如果数据库已损坏,请恢复最近一次备份。

port is already allocated

另一个服务占用了 3001 端口。请用 sudo ss -ltnp | grep ':3001 ' 找出它。若要更改端口,只需修改左侧部分,例如 127.0.0.1:3002:3001,然后相应调整 Caddy 配置。

参考资料