Uptime Kuma 部署安装运维手册

Uptime Kuma 部署安装运维手册

后续 会有脚本 直接监控服务器的内存、磁盘、cpu等向Uptime Kuma 进行PUSH

目录

1. 项目简介

什么是 Uptime Kuma？

Uptime Kuma 是一个开源的、自托管的监控工具，用于监控网站、服务器和各种服务的可用性。

• GitHub 地址：https://github.com/louislam/uptime-kuma
• 官方 Wiki：https://github.com/louislam/uptime-kuma/wiki
• 开源协议：MIT License

主要功能

2. 环境要求

Docker 安装方式（推荐）

非 Docker 安装方式

端口要求

• 默认端口：3001
• 确保防火墙放行该端口

3. 安装部署

方式一：Docker Compose（推荐）

这是最简单、最推荐的安装方式。

步骤 1：创建目录

# 创建项目目录
mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

步骤 2：创建 docker-compose.yml 文件

# 创建配置文件
cat > docker-compose.yml << 'EOF'
version: "3.8"

services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
ports:
– "3001:3001"
volumes:
– ./data:/app/data
environment:
– TZ=Asia/Shanghai
EOF

步骤 3：启动服务

# 启动容器（后台运行）
docker compose up -d

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f

步骤 4：访问 Web 界面

打开浏览器访问：http://你的服务器IP:3001

首次访问需要创建管理员账号。

方式二：Docker 命令

如果不想使用 Docker Compose，可以直接使用 Docker 命令。

一键启动命令

docker run -d \\
–name uptime-kuma \\
–restart=unless-stopped \\
-p 3001:3001 \\
-v /opt/uptime-kuma/data:/app/data \\
-e TZ=Asia/Shanghai \\
louislam/uptime-kuma:2

常用管理命令

# 查看容器状态
docker ps | grep uptime-kuma

# 查看日志
docker logs -f uptime-kuma

# 停止容器
docker stop uptime-kuma

# 启动容器
docker start uptime-kuma

# 重启容器
docker restart uptime-kuma

# 删除容器（数据不会丢失）
docker rm -f uptime-kuma

方式三：非 Docker 安装

适用于没有 Docker 环境的服务器。

步骤 1：安装 Node.js

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash –
sudo apt-get install -y nodejs

# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash –
sudo yum install -y nodejs

# 验证安装
node -v # 应显示 v20.x.x
npm -v

步骤 2：安装 PM2

# 全局安装 PM2
sudo npm install -g pm2

步骤 3：下载 Uptime Kuma

# 创建目录
mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

# 克隆代码
git clone https://github.com/louislam/uptime-kuma.git .

# 切换到最新稳定版
git checkout 2.0.0-beta.2 # 或查看最新版本号

步骤 4：安装依赖并启动

# 安装依赖
npm run setup

# 使用 PM2 启动（后台运行）
pm2 start server/server.js –name uptime-kuma

# 设置开机自启
pm2 save
pm2 startup

步骤 5：验证运行

# 查看运行状态
pm2 status

# 查看日志
pm2 logs uptime-kuma

4. 环境变量配置

常用环境变量

SSL 相关变量

数据库配置（v2.0.0+）

从 v2.0.0 开始支持 MariaDB 数据库。

Docker Compose 配置示例（带环境变量）

version: "3.8"

services:
uptime-kuma:
image: louislam/uptime–kuma:2
container_name: uptime–kuma
restart: unless–stopped
ports:
– "3001:3001"
volumes:
– ./data:/app/data
environment:
– TZ=Asia/Shanghai
– UPTIME_KUMA_PORT=3001
# 如需修改其他配置，在此添加

非 Docker 环境变量配置

在项目根目录创建 .env 文件：

cat > /opt/uptime-kuma/.env << 'EOF'
UPTIME_KUMA_PORT=3001
TZ=Asia/Shanghai
EOF

5. 反向代理配置

重要提示：Uptime Kuma 基于 WebSocket，反向代理必须正确配置 WebSocket 支持！

注意：不支持子目录部署（如 http://example.com/uptime-kuma），必须使用独立域名或子域名。

Nginx 配置

基础配置（HTTP）

server {
listen 80;
server_name monitor.example.com;

location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;

# WebSocket 支持（必须）
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

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;
}
}

HTTPS 配置（推荐）

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

server {
listen 443 ssl http2;
server_name monitor.example.com;

# SSL 证书配置
ssl_certificate /etc/nginx/ssl/monitor.example.com.crt;
ssl_certificate_key /etc/nginx/ssl/monitor.example.com.key;

# SSL 安全配置
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off;

location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;

# WebSocket 支持（必须）
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

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;
}
}

使用 Certbot 自动申请证书

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 申请证书（自动配置 Nginx）
sudo certbot –nginx -d monitor.example.com

# 测试自动续期
sudo certbot renew –dry-run

Caddy 配置（最简单）

Caddy 会自动申请和续期 SSL 证书。

# 创建 Caddyfile
cat > /etc/caddy/Caddyfile << 'EOF'
monitor.example.com {
reverse_proxy 127.0.0.1:3001
}
EOF

# 重载配置
sudo systemctl reload caddy

Apache 配置

<VirtualHost *:80>
ServerName monitor.example.com

ProxyPreserveHost On
ProxyPass / http://127.0.0.1:3001/
ProxyPassReverse / http://127.0.0.1:3001/

# WebSocket 支持
RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://127.0.0.1:3001/$1 [P,L]
</VirtualHost>

需要启用的 Apache 模块：

sudo a2enmod proxy proxy_http proxy_wstunnel rewrite
sudo systemctl restart apache2

配置完成后

在 Uptime Kuma 的 设置 → 通用 中，启用 Trust Proxy 选项，以正确记录客户端 IP。

6. 日常运维

6.1 更新升级

Docker Compose 方式

cd /opt/uptime-kuma

# 拉取最新镜像
docker compose pull

# 重新创建容器
docker compose up -d

# 查看版本
docker compose logs | head -20

Docker 命令方式

# 停止并删除旧容器
docker stop uptime-kuma
docker rm uptime-kuma

# 拉取最新镜像
docker pull louislam/uptime-kuma:2

# 重新启动（使用相同的启动命令）
docker run -d \\
–name uptime-kuma \\
–restart=unless-stopped \\
-p 3001:3001 \\
-v /opt/uptime-kuma/data:/app/data \\
-e TZ=Asia/Shanghai \\
louislam/uptime-kuma:2

非 Docker 方式

cd /opt/uptime-kuma

# 停止服务
pm2 stop uptime-kuma

# 拉取最新代码
git fetch –all
git checkout 2.0.0-beta.2 # 替换为最新版本号

# 安装依赖
npm run setup

# 启动服务
pm2 restart uptime-kuma

6.2 数据备份

备份数据目录

# 创建备份目录
mkdir -p /backup/uptime-kuma

# 备份数据（建议先停止服务）
docker compose stop
cp -r /opt/uptime-kuma/data /backup/uptime-kuma/data_$(date +%Y%m%d_%H%M%S)
docker compose start

自动备份脚本

cat > /opt/uptime-kuma/backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backup/uptime-kuma"
DATA_DIR="/opt/uptime-kuma/data"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/uptime-kuma_$DATE.tar.gz -C $DATA_DIR .

# 保留最近 7 天的备份
find $BACKUP_DIR -name "uptime-kuma_*.tar.gz" -mtime +7 -delete

echo "Backup completed: uptime-kuma_$DATE.tar.gz"
EOF

chmod +x /opt/uptime-kuma/backup.sh

设置定时备份（每天凌晨 3 点）

# 编辑 crontab
crontab -e

# 添加以下行
0 3 * * * /opt/uptime-kuma/backup.sh >> /var/log/uptime-kuma-backup.log 2>&1

6.3 数据恢复

# 停止服务
docker compose stop

# 恢复数据
rm -rf /opt/uptime-kuma/data/*
tar -xzf /backup/uptime-kuma/uptime-kuma_20240101_030000.tar.gz -C /opt/uptime-kuma/data/

# 启动服务
docker compose start

6.4 密码重置

Docker 方式

# 进入容器
docker exec -it uptime-kuma bash

# 执行密码重置
npm run reset-password

# 按提示输入新密码后退出
exit

非 Docker 方式

cd /opt/uptime-kuma
npm run reset-password

6.5 查看日志

Docker 方式

# 实时查看日志
docker logs -f uptime-kuma

# 查看最近 100 行
docker logs –tail 100 uptime-kuma

# 查看指定时间段
docker logs –since "2024-01-01" uptime-kuma

非 Docker 方式

pm2 logs uptime-kuma

6.6 健康检查

# 检查服务是否运行
curl -s http://localhost:3001/api/status-page/heartbeat | head

# 检查容器状态
docker inspect uptime-kuma –format='{{.State.Status}}'

7. 常见问题

Q1: 无法访问 Web 界面

检查步骤：

# 1. 检查容器是否运行
docker ps | grep uptime-kuma

# 2. 检查端口是否监听
netstat -tlnp | grep 3001

# 3. 检查防火墙
# Ubuntu/Debian
sudo ufw status
sudo ufw allow 3001

# CentOS/RHEL
sudo firewall-cmd –list-ports
sudo firewall-cmd –add-port=3001/tcp –permanent
sudo firewall-cmd –reload

# 4. 检查日志
docker logs uptime-kuma

Q2: WebSocket 连接失败

症状：页面显示 “Connecting…” 或实时数据不更新

解决方案：检查反向代理配置，确保包含以下 WebSocket 头：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Q3: 数据库损坏

症状：启动报错 “database is locked” 或 “database disk image is malformed”

解决方案：

# 停止服务
docker compose stop

# 备份当前数据
cp /opt/uptime-kuma/data/kuma.db /opt/uptime-kuma/data/kuma.db.bak

# 尝试修复
sqlite3 /opt/uptime-kuma/data/kuma.db "PRAGMA integrity_check;"

# 如果无法修复，从备份恢复

预防措施：不要将数据目录放在 NFS 存储上，SQLite 需要 POSIX 文件锁支持。

Q4: 忘记管理员密码

参考 6.4 密码重置

Q5: 如何迁移到新服务器

# 旧服务器：备份数据
cd /opt/uptime-kuma
docker compose stop
tar -czf uptime-kuma-data.tar.gz data/

# 将备份文件传输到新服务器
scp uptime-kuma-data.tar.gz user@new-server:/opt/

# 新服务器：恢复数据
cd /opt
mkdir uptime-kuma && cd uptime-kuma
tar -xzf ../uptime-kuma-data.tar.gz

# 创建 docker-compose.yml（参考安装步骤）
# 启动服务
docker compose up -d

Q6: 如何修改监听端口

Docker Compose 方式：修改 docker-compose.yml

ports:
– "8080:3001" # 将外部端口改为 8080

然后重启：docker compose up -d

Q7: 通知发送失败

检查步骤：

附录

常用 Docker 命令速查

相关链接

• 官方文档：https://github.com/louislam/uptime-kuma/wiki
• 问题反馈：https://github.com/louislam/uptime-kuma/issues
• Docker Hub：https://hub.docker.com/r/louislam/uptime-kuma