Uptime Kuma 部署安装运维指南

1. 项目简介

什么是 Uptime Kuma？

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

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

主要功能

功能	说明
多协议监控	HTTP(s)、TCP、Ping、DNS、WebSocket、Docker 容器等
监控频率	最低 20 秒间隔
通知渠道	支持 90+ 种通知方式（Telegram、Discord、Slack、邮件、钉钉、企业微信等）
状态页面	可创建多个公开状态页，支持自定义域名
SSL 证书监控	自动检测证书过期时间
双因素认证	支持 2FA 增强安全性
代理支持	支持通过代理进行监控

---

2. 环境要求

Docker 安装方式（推荐）

组件	最低版本
Docker	20.10+
Docker Compose	v2.0+
内存	512MB+
磁盘	1GB+

非 Docker 安装方式

组件	最低版本
Node.js	20.4+
Git	任意版本
PM2	最新版（用于后台运行）

端口要求

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

---

3. 安装部署

方式一：Docker Compose（推荐）

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

步骤 1：创建目录

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

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

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

步骤 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
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. 环境变量配置

常用环境变量

变量名	默认值	说明
UPTIME_KUMA_HOST	::	监听地址
UPTIME_KUMA_PORT	3001	监听端口
DATA_DIR	./data	数据存储目录
TZ	UTC	时区设置

SSL 相关变量

变量名	说明
UPTIME_KUMA_SSL_KEY	SSL 私钥文件路径
UPTIME_KUMA_SSL_CERT	SSL 证书文件路径

数据库配置（v2.0.0+）

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

变量名	说明
UPTIME_KUMA_DB_TYPE	数据库类型（sqlite 或 mariadb）
UPTIME_KUMA_DB_HOSTNAME	数据库主机地址
UPTIME_KUMA_DB_PORT	数据库端口
UPTIME_KUMA_DB_NAME	数据库名称
UPTIME_KUMA_DB_USERNAME	数据库用户名
UPTIME_KUMA_DB_PASSWORD	数据库密码

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"

然后重启：docker compose up -d

Q7: 通知发送失败

检查步骤：

1. 在 设置 → 通知 中点击 测试 按钮
2. 检查通知配置是否正确（API Token、Webhook URL 等）
3. 检查服务器网络是否能访问通知服务（如 Telegram API）
4. 查看日志中的错误信息

---

附录

常用 Docker 命令速查

操作	命令
启动	docker compose up -d
停止	docker compose stop
重启	docker compose restart
查看状态	docker compose ps
查看日志	docker compose logs -f
更新	docker compose pull && docker compose up -d
进入容器	docker exec -it uptime-kuma bash

相关链接

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