在运营网站、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 --versionBash二、方式一:Docker Compose 安装(推荐)
Docker Compose 适合长期维护,配置清晰,升级和备份都非常方便。
2.1 创建工作目录
mkdir -p /opt/uptime-kuma
cd /opt/uptime-kumaBash2.2 编写配置文件
创建 docker-compose.yml 文件:
vim docker-compose.ymlBash写入以下内容:
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/ShanghaiYAML配置说明:
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 -dBash2.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:1Bash该方式效果与 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 -vBash4.2 克隆项目并安装依赖
cd /opt
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setupBash4.3 前台启动测试
访问 http://服务器IP:3001 ,确认页面正常打开后,按 Ctrl+C 停止。
4.4 配置 Systemd 开机自启
创建服务文件:
vim /etc/systemd/system/uptime-kuma.serviceBash写入以下内容:
[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.targetINI启动服务并设置开机自启:
systemctl daemon-reload
systemctl enable --now uptime-kuma
# 查看运行状态
systemctl status uptime-kumaBash五、初始化配置与核心功能
5.1 首次打开
打开 http://服务器IP:3001 ,首次访问会进入创建管理员账户页面,设置用户名和密码后点击「Create」即可进入后台。
5.2 添加第一个监控
- 点击左侧「添加监控项」
- 选择监控类型:最常用的是 HTTP(s),适合监控网站、接口
- 填写监控名称、目标 URL
- 设置检测间隔(默认 60 秒,可根据需求调整)
- 配置重试次数与超时时间
- 勾选告警通知方式(需先在「设置 → 通知」中添加渠道)
- 点击「保存」,监控立即生效
5.3 配置告警通知
Uptime Kuma 支持近 50 种通知渠道,以 Telegram 为例:
- 向 @BotFather 发送
/newbot创建机器人,获取 Bot Token - 向 @userinfobot 发送任意消息,获取自己的 Chat ID
- 在 Uptime Kuma 后台「设置 → 通知 → 添加通知」,选择「Telegram」
- 填入 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.comBash6.2 服务更新方法
Docker Compose 方式
cd /opt/uptime-kuma
docker compose pull
docker compose up -dBash手动 Node.js 方式
cd /opt/uptime-kuma
git pull
npm run setup
systemctl restart uptime-kumaBash6.3 数据备份
Uptime Kuma 的所有数据(监控配置、用户信息、历史记录)都存储在 data 目录中,定期备份该目录即可:
# 备份命令示例
tar -zcvf uptime-kuma-backup-$(date +%Y%m%d).tar.gz /opt/uptime-kuma/dataBash七、常见问题排查
- 1. 无法访问页面
- 检查服务器防火墙、云服务商安全组是否开放 3001 端口
- 执行
docker ps确认容器正常运行 - 查看容器日志:
docker logs uptime-kuma
- 反向代理后页面提示连接断开
- 99% 是 Nginx 未配置 WebSocket 升级头,检查
Upgrade和Connection配置
- 99% 是 Nginx 未配置 WebSocket 升级头,检查
- 忘记管理员密码
- Docker 方式:
docker exec -it uptime-kuma npm run reset-password - 手动方式:进入项目目录执行
npm run reset-password
- Docker 方式:
- 监控一直显示离线但服务正常
- 检查服务器网络是否能访问目标地址- 尝试调整超时时间,或关闭 HTTPS 证书验证(仅测试用)
写在最后
Uptime Kuma 的优势不仅在于功能全面,更在于轻量化和高度可定制。无论是个人站长监控几个站点,还是团队监控数十个服务,它都能很好地胜任。配合公开状态页,还能向用户透明展示服务可用性,提升信任感。
部署完成后,建议搭配邮件 + 即时通讯工具的双通道告警,确保服务异常时能第一时间收到通知。如果有更多监控节点需求,还可以部署多实例实现分布式监控。

Comments NOTHING