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

常用环境变量

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"

然后重启：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