概述

Uptime Kuma 是一款开源的自托管服务监控工具，由 louislam 开发并维护。它能替代 UptimeRobot、Pingdom 等 SaaS 产品，让你完全掌控自己的监控数据。

和商业监控工具动辄按探测器数量收费不同，Uptime Kuma 完全免费，且功能极其丰富：

  • ✅ 服务状态监测 — HTTP(s)、TCP、Ping、DNS、关键字、端口检测等多种监控类型
  • ✅ 实时状态页面 — 可对外公开的 PWA 状态页面，支持自定义域名
  • ✅ 多通知渠道 — 邮件、Telegram、Slack、Discord、企业微信、钉钉、飞书、PushDeer 等 90+ 通知方式
  • ✅ SSL 证书到期监控
  • ✅ 多语言支持 — 包括简体中文
  • ✅ Docker 一键部署 — 启动即用
  • ✅ 自动备份与恢复
  • ✅ 干净美观的 UI — 基于 Vue 3 + Vite，界面现代流畅

安装方式

Uptime Kuma 提供了多种安装方式，最推荐的是 Docker 部署。

方式一：Docker 部署（推荐）

前提条件

  • Docker Engine ≥ 20.x
  • Docker Compose (V2) 或 docker compose 插件

使用 Docker Compose（推荐）

创建 docker-compose.yml：

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"  # 左侧端口可按需修改
    volumes:
      - ./uptime-kuma-data:/app/data  # 持久化数据
    environment:
      - TZ=Asia/Shanghai  # 设置时区

启动：

docker compose up -d

访问 http://你的服务器IP:3001 即可看到设置页面。

使用 docker run

docker run -d \
  --restart=always \
  --name uptime-kuma \
  -p 3001:3001 \
  -v /path/to/uptime-kuma-data:/app/data \
  -e TZ=Asia/Shanghai \
  louislam/uptime-kuma:latest

使用 Nginx 反代（可选）

如果你有域名，推荐用 Nginx 反代并开启 HTTPS：

server {
    listen 443 ssl;
    server_name status.yourdomain.com;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        # 重要：WebSocket 支持
        proxy_read_timeout 86400;
    }
}

注意：WebSocket 支持是关键，Uptime Kuma 的实时更新依赖它。如果反代没配好 WebSocket，页面不会自动刷新状态。

方式二：Node.js 直接部署

如果不方便用 Docker，也可以通过 npm 直接运行。

前提条件

  • Node.js ≥ 18.x（推荐 20 LTS）
  • npm 或 yarn
  • Git

安装步骤

# 1. 克隆仓库
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma

# 2. 安装依赖并构建
npm install
npm run build

# 3. 启动（生产模式）
npm run start

默认监听 0.0.0.0:3001。

使用 PM2 守护进程：

npm install -g pm2
pm2 start npm --name "uptime-kuma" -- run start
pm2 save
pm2 startup

方式三：Docker 将数据存到当前目录

# macOS 或 Linux
mkdir uptime-kuma
cd uptime-kuma
docker run -d --restart=always -p 3001:3001 -v $(pwd)/data:/app/data louislam/uptime-kuma:latest

数据持久化关键：/app/data 目录包含 SQLite 数据库、配置文件和 SSL 证书。务必挂载到宿主机，否则容器销毁后数据全丢。

方式四：宝塔面板 / 1Panel

国内用户如果使用宝塔面板或 1Panel，可以直接在应用商店搜索 "Uptime Kuma" 一键安装。这两个面板的应用商店都已收录。

1Panel 的安装入口：应用商店 → 运维工具 → Uptime Kuma

初始化配置

1. 首次访问

打开浏览器访问 http://IP:3001，你会看到：

  • 设置管理员账号 — 输入用户名、密码，点击创建

![设置页面文字描述：用户名 + 密码 + 重复密码表单，创建后自动登录]

⚠️ 首次部署建议立即修改默认端口或添加 Nginx 反代+HTTPS，因为 Uptime Kuma 默认不加密。

2. 界面概览

登录后的主界面包含几个核心区域：

区域 说明
左侧边栏 监控列表、状态页面、设置入口
顶部状态条 总体监控状态（正常/异常数量）
主区域 单个监控项的实时状态卡片
右下角 + 按钮 添加新的监控项

3. 语言设置

右上角用户头像 → 设置 → 界面语言 → 选择 简体中文 → 保存。

添加第一个监控项

点击右下角的 「添加监控项」 按钮：

基本信息

字段 示例值 说明
监控类型 HTTP(s) 最常用
显示名称 我的博客 显示在状态页面的名称
URL https://example.com 要监控的地址
监控间隔 60 秒 检测频率 —— 越短越灵敏，但负载更高

高级选项

字段 说明
超时时间 请求超时后视为失败（默认 30s）
关键字 检查响应中是否包含指定文本（如 "正常"）
最大重试次数 连续失败 N 次后才标记为 "宕机"，避免误报
请求方法 GET / POST / 自定义请求体
HTTP 认证 对需要登录的页面添加 Basic Auth 或 Bearer Token
请求头 自定义 HTTP 请求头

监控类型科普

类型 适用场景
HTTP(s) 网站可用性、API 端点
Ping 服务器连通性（ICMP）
TCP 端口 数据库端口、SSH 等服务是否活着
DNS 域名解析是否正常
关键字 页面内容健康检查（如 "200 OK" 是否存在）
Docker 监控容器运行状态
游戏服务器 Minecraft、Valheim 等游戏服务器
Steam Steam Game Server 状态

通知方式

创建监控时或之后，可以绑定通知。先需要配置「通知渠道」：

设置 → 通知 → 添加通知：

![通知设置界面：选择类型，填入 API Key / Webhook URL]

常用通知配置示例（企业微信机器人）：

名称：企业微信告警
类型：企业微信机器人
Webhook URL：https://qyapi.weixin.qq.com/cgi-bin/......

状态页面

Uptime Kuma 最吸引人的功能之一就是对外公开的状态页面，类似 Atlassian Statuspage。

创建状态页面

左侧边栏 → 状态页面 → 「新建状态页面」

配置项

配置 说明
标题 如 "我的服务状态"
主题色 自定义外观
图标 页面左上角 Logo
子域名 https://your-domain/status/xxx
是否公开 无需登录即可查看
选择监控项 选择哪些服务显示在状态页上
维护窗口 预定维护时段，页面显示 "维护中"

示例效果

公开状态页面会展示：

  • ✅ 所有服务的实时状态（绿色=正常 / 红色=宕机）
  • 📊 过去 30 天的可用性百分比
  • 📈 响应时间趋势图
  • ⏱ 历史事件时间线

你可以把状态页面设置为其子域名（如 status.yourdomain.com），对外透明展示服务健康度 —— 这在面对客户时非常有用。

高级用法

1. 分组管理

当监控项变多后，使用「分组」归类：

📁 生产环境
  ├── 主站 API
  ├── 用户数据库
  └── CDN 边缘节点
📁 开发环境
  ├── Staging API
  └── 测试数据库

2. 同时监控多个端口

同一台服务器可以添加多个 TCP 端口的监控：

  • tcp://192.168.1.1:22 → SSH 服务
  • tcp://192.168.1.1:3306 → MySQL
  • tcp://192.168.1.1:6379 → Redis

3. SSL 证书监控

选择监控类型为 「SSL 证书」，填入域名：

  • 会检测证书剩余天数
  • 在证书到期前 7/14/30 天自动触发通知告警
  • 🔑 这是很多团队用 Uptime Kuma 的核心场景之一

4. 备份与迁移

数据文件在容器内的 /app/data/ 目录下：

# 备份整个数据目录
tar -czf uptime-kuma-backup-$(date +%Y%m%d).tar.gz ./uptime-kuma-data/

# 迁移时只需在新服务器挂载这个备份目录即可

Uptime Kuma 也内置了备份功能：设置 → 备份 → 导出 JSON 文件。

5. API 接口

Uptime Kuma 提供了 API，可以集成到其他系统：

# 获取所有监控状态
curl http://your-server:3001/api/status

6. 使用 Traefik 反代（Docker 标签方式）

# 如果已经在用 Traefik，配上自动 SSL
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.uptime.rule=Host(`status.yourdomain.com`)"
  - "traefik.http.services.uptime.loadbalancer.server.port=3001"

典型场景与最佳实践

场景 1：个人博客 / 独立站点

镜像: louislam/uptime-kuma
端口: 3001 → 反代 → 443
监控: 1 个 HTTP 监控（博客主页）
通知: Telegram Bot
状态页: 公开

场景 2：团队内部服务

监控项: 30+（API、数据库、Redis、队列、CDN……）
分组: 按服务/环境分
通知: 企业微信机器人 → 全员群/值班群
SSL: 证书监控，提前 14 天告警

场景 3：面向客户的状态页

使用独立域名 status.company.com
只公开面向客户的服务（API、前端）
背后监控的是完整内部架构
维护窗口功能用于预订发版

常见问题

Q：Uptime Kuma 占用资源大吗？

极小。实测在 1 核 512MB 内存 的 VPS 上监控 20 个服务，CPU 占用不到 5%，内存约 80-120MB。非常适合部署在低配服务器或树莓派上。

Q：会不会发出大量误报？

建议设置 「最大重试次数」≥ 2。默认重试 0 次意味着一次超时就告警，网络抖动会造成误报。设成 2 次以上，连续失败才告警，大幅减少半夜被吵醒的概率。

Q：支持多节点探测吗？

目前 Uptime Kuma 不支持分布式多节点探测（默认从部署机器发起请求）。如果你的服务在中国，部署机器在海外，延迟高会被误判为宕机。解决方案：

  • 在国内服务器也部署一个 Uptime Kuma 作为辅助
  • 注意，官方有计划在 2.0 中加入多节点功能

Q：数据存在哪里？

SQLite 数据库，文件在 /app/data/kuma.db。数据不会丢失，也不需要额外安装数据库服务。

Q：如何升级？

# Docker 方式
docker compose pull
docker compose up -d

# 查看更新日志后才决定是否升级
docker compose logs uptime-kuma

Uptime Kuma 更新很活跃，建议每月升级一次。升级前先备份数据。

总结

维度 评价
上手难度 ⭐ 极低，Docker 一键启动
功能完整度 ⭐⭐⭐⭐⭐ 监控类型、通知渠道、状态页一应俱全
界面体验 ⭐⭐⭐⭐⭐ 现代化 PWA，支持移动端
资源占用 ⭐⭐⭐⭐⭐ 百 MB 内存，轻量级首选
社区活跃度 ⭐⭐⭐⭐ GitHub 5 万+ Star，更新频繁
适合人群 个人开发者 → 中小团队 → 企业状态页

一句话总结：如果你需要一个自托管的监控系统，要求部署简单、功能够用、界面漂亮、完全免费 —— Uptime Kuma 是目前最好的选择，没有之一。

参考链接