跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像AI 生图工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
JavaScriptNode.js

Uptime Kuma 部署安装运维指南

Uptime Kuma 是一款开源自托管监控工具，支持 HTTP、TCP、Ping 等多种协议监控及 90+ 种通知渠道。详细介绍基于 Docker Compose、Docker 命令及非 Docker 环境的三种安装部署方式，涵盖环境变量配置、Nginx/Caddy/Apache 反向代理设置（含 WebSocket 支持）、日常运维更新、数据备份恢复、密码重置及常见问题排查方案，帮助用户快速搭建并维护服务可用性监控体系。

日志猎手发布于 2026/3/16更新于 2026/7/2754 浏览

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 安装方式（推荐）
组件最低版本
Docker20.10+
Docker Composev2.0+
内存512MB+
磁盘1GB+
非 Docker 安装方式
组件最低版本
Node.js20.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_PORT3001监听端口
DATA_DIR./data数据存储目录
TZUTC时区设置
SSL 相关变量
变量名说明
UPTIME_KUMA_SSL_KEYSSL 私钥文件路径
UPTIME_KUMA_SSL_CERTSSL 证书文件路径
数据库配置（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

目录

  1. Uptime Kuma 部署安装运维指南
  2. 1. 项目简介
  3. 什么是 Uptime Kuma？
  4. 主要功能
  5. 2. 环境要求
  6. Docker 安装方式（推荐）
  7. 非 Docker 安装方式
  8. 端口要求
  9. 3. 安装部署
  10. 方式一：Docker Compose（推荐）
  11. 步骤 1：创建目录
  12. 创建项目目录
  13. 步骤 2：创建 docker-compose.yml 文件
  14. 步骤 3：启动服务
  15. 启动容器（后台运行）
  16. 查看运行状态
  17. 查看日志
  18. 步骤 4：访问 Web 界面
  19. 方式二：Docker 命令
  20. 一键启动命令
  21. 常用管理命令
  22. 查看容器状态
  23. 查看日志
  24. 停止容器
  25. 启动容器
  26. 重启容器
  27. 删除容器（数据不会丢失）
  28. 方式三：非 Docker 安装
  29. 步骤 1：安装 Node.js
  30. Ubuntu/Debian
  31. CentOS/RHEL
  32. 验证安装
  33. 步骤 2：安装 PM2
  34. 全局安装 PM2
  35. 步骤 3：下载 Uptime Kuma
  36. 创建目录
  37. 克隆代码
  38. 切换到最新稳定版
  39. 步骤 4：安装依赖并启动
  40. 安装依赖
  41. 使用 PM2 启动（后台运行）
  42. 设置开机自启
  43. 步骤 5：验证运行
  44. 查看运行状态
  45. 查看日志
  46. 4. 环境变量配置
  47. 常用环境变量
  48. SSL 相关变量
  49. 数据库配置（v2.0.0+）
  50. Docker Compose 配置示例（带环境变量）
  51. 非 Docker 环境变量配置
  52. 5. 反向代理配置
  53. Nginx 配置
  54. 基础配置（HTTP）
  55. HTTPS 配置（推荐）
  56. 使用 Certbot 自动申请证书
  57. 安装 Certbot
  58. 申请证书（自动配置 Nginx）
  59. 测试自动续期
  60. Caddy 配置（最简单）
  61. 创建 Caddyfile
  62. 重载配置
  63. Apache 配置
  64. 配置完成后
  65. 6. 日常运维
  66. 6.1 更新升级
  67. Docker Compose 方式
  68. 拉取最新镜像
  69. 重新创建容器
  70. 查看版本
  71. Docker 命令方式
  72. 停止并删除旧容器
  73. 拉取最新镜像
  74. 重新启动（使用相同的启动命令）
  75. 非 Docker 方式
  76. 停止服务
  77. 拉取最新代码
  78. 替换为最新版本号
  79. 安装依赖
  80. 启动服务
  81. 6.2 数据备份
  82. 备份数据目录
  83. 创建备份目录
  84. 备份数据（建议先停止服务）
  85. 自动备份脚本
  86. 保留最近 7 天的备份
  87. 设置定时备份（每天凌晨 3 点）
  88. 编辑 crontab
  89. 添加以下行
  90. 6.3 数据恢复
  91. 停止服务
  92. 恢复数据
  93. 启动服务
  94. 6.4 密码重置
  95. Docker 方式
  96. 进入容器
  97. 执行密码重置
  98. 按提示输入新密码后退出
  99. 非 Docker 方式
  100. 6.5 查看日志
  101. Docker 方式
  102. 实时查看日志
  103. 查看最近 100 行
  104. 查看指定时间段
  105. 非 Docker 方式
  106. 6.6 健康检查
  107. 检查服务是否运行
  108. 检查容器状态
  109. 7. 常见问题
  110. Q1: 无法访问 Web 界面
  111. 1. 检查容器是否运行
  112. 2. 检查端口是否监听
  113. 3. 检查防火墙
  114. Ubuntu/Debian
  115. CentOS/RHEL
  116. 4. 检查日志
  117. Q2: WebSocket 连接失败
  118. Q3: 数据库损坏
  119. 停止服务
  120. 备份当前数据
  121. 尝试修复
  122. 如果无法修复，从备份恢复
  123. Q4: 忘记管理员密码
  124. Q5: 如何迁移到新服务器
  125. 旧服务器：备份数据
  126. 将备份文件传输到新服务器
  127. 新服务器：恢复数据
  128. 创建 docker-compose.yml（参考安装步骤）
  129. 启动服务
  130. Q6: 如何修改监听端口
  131. Q7: 通知发送失败
  132. 附录
  133. 常用 Docker 命令速查
  134. 相关链接
  • 免费图片AI生成工具免费生成了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 免费图片视频在线生成30秒，将你的创意变成现实开始设计
  • X/Twitter免费视频下载器免登陆无限额度免费视频解析下载了解详情
  • 100+免费在线小游戏爽一把
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • Bidili SDXL Generator 快速部署与使用指南
  • Webnovel Writer：基于 Claude Code 的长篇网文 AI 创作系统
  • LLaMA Factory 实现 LLMs 指令监督微调 (SFT) 完整工作流程
  • JDK 25 安装指南：Windows 与 Linux 系统
  • 国内主流 AI 工具对比：豆包、元宝、千问等七款应用
  • GitHub Copilot 接入第三方模型 API 实战
  • MATLAB Copilot_AI 工具箱：对接多款 AI 大模型辅助编程
  • 基于 SpringBoot 的艺术展览网站设计与实现
  • CentOS 7 部署 Docker、PostgreSQL 与 Redis 实战指南
  • C++ 轻量级搜索引擎实战：正/倒排索引构建指南
  • DeepSeek 隐藏玩法与高阶提示词应用指南
  • 手机端 Stable Diffusion 开源工具使用指南
  • Windows 环境 llama.cpp 编译与 Qwen 模型本地部署
  • VS Code 远程配置 GitHub Copilot 无法使用排查指南
  • 在 VMware 中搭建 macOS 15 并解决 Apple ID 登录错误
  • Java 滑动窗口算法实战：LeetCode 经典题目解析
  • Copilot 核心功能、版本区别及使用场景
  • 论文笔记：DiT 可扩展扩散模型与 Transformer 架构
  • CentOS 7.6 国内镜像下载地址
  • Java JUnit NoSuchMethodError 错误排查与 Spring Boot 版本兼容修复

相关免费在线工具

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online

  • JavaScript 压缩与混淆

    Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online