Uptime Kuma 完整安装教程:搭建自托管网站监控与状态页

Youutaku 发布于 2026-10-22 430 次阅读


AI 摘要

想摆脱第三方监控的额度限制与数据焦虑?Uptime Kuma 开源自托管,支持多类型监控、数十种告警和公开状态页。本文从零讲透三种安装、反向代理、备份与排错,512MB 内存即可运行。

在运营网站、API 服务或在线应用的过程中,服务可用性是最核心的指标之一。传统第三方监控工具往往存在免费额度有限、数据不自主、告警渠道受限等问题,而 Uptime Kuma 作为一款开源、轻量、功能强大的自托管监控工具,完美解决了这些痛点。

Uptime Kuma 支持 HTTP、HTTPS、TCP、Ping、DNS、Docker 容器等多种监控类型,内置邮件、Telegram、Discord、企业微信、飞书等数十种告警通知渠道,还支持生成美观的公开状态页,界面简洁现代,部署门槛极低,是替代 Uptime Robot、StatusCake 等商业工具的绝佳选择。

本文将从环境准备开始,详细讲解三种主流安装方式、初始化配置、反向代理、数据备份与常见问题,帮你从零搭建一套完全自主的服务监控系统。

一、前置准备

1.1 服务器要求

Uptime Kuma 资源占用极低,最低配置即可流畅运行:

  • - 系统:Debian 11+/Ubuntu 20.04+(推荐)、CentOS 7+、Windows、macOS​
  • 架构:x86_64、ARM64(支持树莓派)​
  • 配置:1 核 CPU、512MB 内存、1GB 磁盘空间​
  • 网络:公网服务器可监控外网服务,内网服务器可监控内部服务

1.2 环境说明

本文推荐使用 Docker + Docker Compose 方式部署,这也是官方首推的方案,具有环境隔离、升级简单、数据持久化方便的优势。若你尚未安装 Docker,可先执行以下命令一键安装:

# Debian/Ubuntu 一键安装 Docker
curl -fsSL https://get.docker.com | bash
# 启动 Docker 并设置开机自启
systemctl enable --now docker
# 验证安装
docker --version
Bash

二、方式一:Docker Compose 安装(推荐)

Docker Compose 适合长期维护,配置清晰,升级和备份都非常方便。

2.1 创建工作目录

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

2.2 编写配置文件

创建  docker-compose.yml  文件:

vim docker-compose.yml
Bash

写入以下内容:

version: '3.3'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
YAML

配置说明:

  • image: louislam/uptime-kuma:1 :使用官方稳定版镜像, 1  标签对应 1.x 稳定分支​
  • ports: "3001:3001" :宿主机 3001 端口映射容器 3001 端口,可自行修改宿主机端口
  • volumes: ./data:/app/data :将监控数据、配置持久化到本地  data  目录,防止容器重建丢失数据​
  • TZ=Asia/Shanghai :设置时区为上海,避免时间显示错误

2.3 启动服务

docker compose up -d
Bash

2.4 验证运行

查看容器状态:

docker compose 
Bash

若状态显示  Up ,说明启动成功。此时在浏览器访问  http://服务器IP:3001  即可进入 Uptime Kuma 初始化页面。

三、方式二:Docker 单命令快速启动

如果你只需要快速体验,不想编写配置文件,可直接执行一条命令启动:

docker run -d \
  --name uptime-kuma \
  --restart always \
  -p 3001:3001 \
  -v /opt/uptime-kuma/data:/app/data \
  -e TZ=Asia/Shanghai \
  louislam/uptime-kuma:1
Bash

该方式效果与 Compose 完全一致,只是后续管理需要通过  docker  命令操作。

四、方式三:手动 Node.js 安装(无 Docker 环境)

若服务器无法使用 Docker,也可以直接通过 Node.js 源码部署,适合有定制开发需求的场景。

4.1 安装 Node.js

Uptime Kuma 要求 Node.js 18 LTS 及以上版本,推荐使用 20 LTS:

# 安装 Node.js 20.x(Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs git
# 验证版本
node -v
Bash

4.2 克隆项目并安装依赖

cd /opt
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
Bash

4.3 前台启动测试

访问  http://服务器IP:3001 ,确认页面正常打开后,按  Ctrl+C  停止。

4.4 配置 Systemd 开机自启

创建服务文件:

vim /etc/systemd/system/uptime-kuma.service
Bash

写入以下内容:

[Unit]
Description=Uptime Kuma - Self-hosted monitoring tool
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/uptime-kuma
ExecStart=/usr/bin/node server/server.js
Restart=always
RestartSec=5
Environment=TZ=Asia/Shanghai

[Install]
WantedBy=multi-user.target
INI

启动服务并设置开机自启:

systemctl daemon-reload
systemctl enable --now uptime-kuma
# 查看运行状态
systemctl status uptime-kuma
Bash

五、初始化配置与核心功能

5.1 首次打开

打开  http://服务器IP:3001 ,首次访问会进入创建管理员账户页面,设置用户名和密码后点击「Create」即可进入后台。

5.2 添加第一个监控

  1. 点击左侧「添加监控项」
  2. 选择监控类型:最常用的是 HTTP(s),适合监控网站、接口​
  3. 填写监控名称、目标 URL​
  4. 设置检测间隔(默认 60 秒,可根据需求调整)​
  5. 配置重试次数与超时时间​
  6. 勾选告警通知方式(需先在「设置 → 通知」中添加渠道)​
  7. 点击「保存」,监控立即生效

5.3 配置告警通知

Uptime Kuma 支持近 50 种通知渠道,以 Telegram 为例:

  1. 向 @BotFather 发送  /newbot  创建机器人,获取 Bot Token​
  2. 向 @userinfobot 发送任意消息,获取自己的 Chat ID​
  3. 在 Uptime Kuma 后台「设置 → 通知 → 添加通知」,选择「Telegram」​
  4. 填入 Bot Token 和 Chat ID,点击「测试」,收到消息即配置成功

5.4 创建公开状态页

点击左侧「状态页 → 新建状态页」,自定义标题、域名、要展示的监控项,保存后即可生成公开可访问的状态页面,对外展示服务可用性。

六、进阶配置

6.1 Nginx 反向代理 + 域名 + HTTPS

直接用 IP+端口访问不够优雅,建议绑定域名并配置 HTTPS。假设域名为  status.example.com ,配置如下:

server {
    listen 80;
    server_name status.example.com;
    return 301 https://$host$request_uri;
}

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_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;
        
        # 必须配置 WebSocket 支持,否则页面会断开连接
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
Nginx

证书可使用 Certbot 一键申请免费 Let's Encrypt 证书:

apt install -y certbot python3-certbot-nginx
certbot --nginx -d status.example.com
Bash

6.2 服务更新方法

Docker Compose 方式

cd /opt/uptime-kuma
docker compose pull
docker compose up -d
Bash

手动 Node.js 方式

cd /opt/uptime-kuma
git pull
npm run setup
systemctl restart uptime-kuma
Bash

6.3 数据备份

Uptime Kuma 的所有数据(监控配置、用户信息、历史记录)都存储在  data  目录中,定期备份该目录即可:

# 备份命令示例
tar -zcvf uptime-kuma-backup-$(date +%Y%m%d).tar.gz /opt/uptime-kuma/data
Bash

七、常见问题排查

  1. 1. 无法访问页面​
    • 检查服务器防火墙、云服务商安全组是否开放 3001 端口​
    • 执行  docker ps  确认容器正常运行​
    • 查看容器日志: docker logs uptime-kuma
  2. ​反向代理后页面提示连接断开​
    • 99% 是 Nginx 未配置 WebSocket 升级头,检查  Upgrade  和  Connection  配置​
  3. 忘记管理员密码​
    • Docker 方式: docker exec -it uptime-kuma npm run reset-password
    • 手动方式:进入项目目录执行  npm run reset-password
  4. 监控一直显示离线但服务正常​
    • 检查服务器网络是否能访问目标地址​- 尝试调整超时时间,或关闭 HTTPS 证书验证(仅测试用)

写在最后

Uptime Kuma 的优势不仅在于功能全面,更在于轻量化和高度可定制。无论是个人站长监控几个站点,还是团队监控数十个服务,它都能很好地胜任。配合公开状态页,还能向用户透明展示服务可用性,提升信任感。

部署完成后,建议搭配邮件 + 即时通讯工具的双通道告警,确保服务异常时能第一时间收到通知。如果有更多监控节点需求,还可以部署多实例实现分布式监控。