Uptime Kuma 部署安装运维手册

Uptime Kuma 部署安装运维手册

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

目录

1. 项目简介
2. 环境要求
3. 安装部署
   • 方式一：Docker Compose（推荐）
   • 方式二：Docker 命令
   • 方式三：非 Docker 安装
4. 环境变量配置
5. 反向代理配置
6. 日常运维
7. 常见问题

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 

常用管理命令

# 查看容器状态dockerps|grep uptime-kuma # 查看日志docker logs -f uptime-kuma # 停止容器docker stop uptime-kuma # 启动容器docker start uptime-kuma # 重启容器docker restart uptime-kuma # 删除容器（数据不会丢失）dockerrm -f uptime-kuma 

方式三：非 Docker 安装

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

步骤 1：安装 Node.js

# Ubuntu/Debiancurl -fsSL https://deb.nodesource.com/setup_20.x |sudo -E bash - sudoapt-getinstall -y nodejs # CentOS/RHELcurl -fsSL https://rpm.nodesource.com/setup_20.x |sudobash - sudo yum install -y nodejs # 验证安装node -v # 应显示 v20.x.xnpm -v 

步骤 2：安装 PM2

# 全局安装 PM2sudonpminstall -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:2container_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 自动申请证书

# 安装 Certbotsudoaptinstall certbot python3-certbot-nginx # 申请证书（自动配置 Nginx）sudo certbot --nginx -d monitor.example.com # 测试自动续期sudo certbot renew --dry-run 

Caddy 配置（最简单）

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

# 创建 Caddyfilecat> /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 dockerrm 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" EOFchmod +x /opt/uptime-kuma/backup.sh 

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

# 编辑 crontabcrontab -e # 添加以下行03 * * * /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 方式

# 进入容器dockerexec -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. 检查容器是否运行dockerps|grep uptime-kuma # 2. 检查端口是否监听netstat -tlnp |grep3001# 3. 检查防火墙# Ubuntu/Debiansudo ufw status sudo ufw allow 3001# CentOS/RHELsudo 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: 通知发送失败

检查步骤：

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

附录

常用 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