基础部署#

创建项目目录和 docker-compose.yml：

1
mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma

1
services:
2
  uptime-kuma:
3
    image: louislam/uptime-kuma:2
4
    container_name: uptime-kuma
5
    restart: unless-stopped
6
    volumes:
7
      - ./data:/app/data
8
    ports:
9
      - "3001:3001"
10
    environment:
11
      - TZ=Asia/Shanghai

1
docker compose up -d

访问 http://<服务器IP>:3001，首次进入会提示创建管理员账户。

使用 louislam/uptime-kuma:2 标签（而非 latest）跟踪 v2.x 的最新稳定版（当前为 v2.3.2），避免跨大版本升级（如 v2 → v3）的兼容性问题。latest 标签已废弃，v2.0 起必须显式指定版本。

生产环境部署（Nginx 反向代理 + 本地端口绑定）#

生产环境中不应直接暴露 3001 端口。改进后的配置：

1
services:
2
  uptime-kuma:
3
    image: louislam/uptime-kuma:2
4
    container_name: uptime-kuma
5
    restart: unless-stopped
6
    volumes:
7
      - /opt/uptime-kuma/data:/app/data
8
    ports:
9
      - "127.0.0.1:3001:3001"  # 仅监听本地，通过 Nginx 反代访问
10
    environment:
11
      - TZ=Asia/Shanghai
12
    deploy:
13
      resources:
14
        limits:
15
          memory: 512m
16
          cpus: "1.0"

127.0.0.1:3001:3001 确保端口仅绑定本地回环地址，即使服务器防火墙规则有疏漏，外部也无法直接访问 Uptime Kuma。Docker 默认会绕过 iptables 规则，直接暴露到公网——绑在 localhost 可避免此问题。

Nginx 反向代理配置#

Uptime Kuma 必须支持 WebSocket，否则实时数据不更新。完整 Nginx 配置：

1
server {
2
    listen 443 ssl;
3
    server_name status.example.com;
4

5
    ssl_certificate     /etc/ssl/certs/status.example.com.pem;
6
    ssl_certificate_key /etc/ssl/private/status.example.com.key;
7

8
    location / {
9
        proxy_pass http://127.0.0.1:3001;
10
        proxy_http_version 1.1;
11

12
        proxy_set_header Host              $host;
13
        proxy_set_header X-Real-IP         $remote_addr;
14
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
15
        proxy_set_header X-Forwarded-Proto $scheme;
16

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

21
        # 超时设置（长连接）
22
        proxy_read_timeout 86400s;
23
        proxy_send_timeout 86400s;
24
    }
25
}

启用站点：

1
ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
2
nginx -t && systemctl reload nginx

最后，在 Uptime Kuma 的 设置 → 反向代理 中将”信任代理”设为”是”，使其正确读取 X-Forwarded-* 头。

1
environment:
2
  - UPTIME_KUMA_WS_ORIGIN_CHECK=cors-like  # 默认值，强制源验证
3
  # UPTIME_KUMA_WS_ORIGIN_CHECK=bypass     # 禁用源验证（不推荐，除非调试反代问题）

开启 Ping 监控支持（ICMP）#

如果需要在 Docker 容器中使用 Ping 监控，需添加 NET_RAW 能力：

1
services:
2
  uptime-kuma:
3
    # ...
4
    cap_add:
5
      - NET_RAW

HTTP(s) 监控#

最常用的监控类型，检查网站或 API 的可达性和响应状态码。

常用场景：

• 网站可用性：GET https://example.com，期望 200-299
• API 健康检查：GET https://api.example.com/health，期望 200
• 关键字检查（HTTP Keyword 类型）：验证页面是否包含特定文字，用于检测页面是否被篡改或被错误页面替换
• JSON 查询（HTTP JSON Query 类型）：对 JSON API 响应做字段级验证，如检查 {"status": "ok"}

TCP 端口监控#

检查 TCP 端口是否开放，适用于数据库、SSH、SMTP 等非 HTTP 服务。

常用端口清单：

Ping 监控#

通过 ICMP 检测网络延迟和丢包率，适合监控路由器、交换机、内网设备的基础网络连通性。

Docker 部署需要 cap_add: [NET_RAW]，非 Docker 部署需要 setcap cap_net_raw=+ep。如果无法获取 ICMP 权限，可用 TCP 监控端口 22 作为替代方案。

DNS 记录监控#

验证 DNS 记录是否存在且值正确。

典型场景：

• 监控 MX 记录确保邮件服务正常
• 监控 A 记录检查域名解析是否正确（可设期望值做对比）
• 使用内网 DNS 服务器（如 10.0.0.1）解析内网域名

Docker 容器监控#

直接检查 Docker 容器运行状态。

1
volumes:
2
  - /var/run/docker.sock:/var/run/docker.sock:ro  # 只读挂载

配置时填写容器名称或 ID，Uptime Kuma 会调用 Docker API 检查容器状态（running / stopped / unhealthy）。

安全提醒：挂载 Docker socket 意味着容器获得了控制宿主机 Docker 的能力。生产环境建议使用 docker-socket-proxy 做中间代理，限制 Uptime Kuma 只能调用 /containers/*/json 等只读端点。

Push 心跳监控#

被动型监控——你的定时任务或脚本主动向 Uptime Kuma 推送心跳，如果在指定时间窗口内未收到推送，则触发告警。适合 Cron 任务、备份脚本等没有常驻端口可监控的场景。

创建 Push 监控后，Uptime Kuma 生成一个推送 URL：

1
https://status.example.com/api/push/abc123xyz?status=up&msg=OK&ping=

在 Cron 脚本末尾添加：

1
# 备份脚本执行完毕后推送心跳
2
0 3 * * * /opt/scripts/backup.sh && curl -s "https://status.example.com/api/push/abc123xyz?status=up&msg=Backup+OK"

Telegram#

1. 向 @BotFather 发送 /newbot，创建机器人并获取 Bot Token
2. 给机器人发一条消息，然后访问 https://api.telegram.org/bot<TOKEN>/getUpdates 获取 Chat ID
3. 在 Uptime Kuma → 设置通知 → Telegram 中填入 Token 和 Chat ID
4. 点击”测试”确认能收到消息

建议创建一个专门的监控告警群组，将机器人拉入群组，用群组 Chat ID 接收通知。这样团队成员都能看到告警信息。

企业微信#

在企业微信中创建群机器人，获取 Webhook URL，直接在 Uptime Kuma 中选择”企业微信”通知类型填入即可。

飞书 / 钉钉#

飞书和钉钉的配置方式与企业微信类似——在对应平台创建群机器人，复制 Webhook URL，在 Uptime Kuma 中选择对应通知类型即可。

邮件（SMTP）#

使用 Gmail 需要开启”应用专用密码”（App Password）；使用自建邮箱（如 Poste.io）注意检查 SMTP 端口是否开放。

通知绑定到监控项#

创建通知后，进入每个监控项 → 编辑 → 通知，勾选该监控项需要触发的通知渠道。同一个通知可绑定多个监控项，一个监控项也可绑定多个通知渠道。

告警降噪建议#

• 设置合理的重试次数（建议 3 次），避免网络抖动导致误报
• 利用维护窗口功能（见下文），在计划维护期间暂停告警
• 关键服务使用即时通知（Telegram），非关键服务可仅用邮件
• 不同监控项使用不同通知渠道，按严重程度分组

创建状态页#

1. 进入 状态页 → 添加状态页
2. 填写名称（如”我的服务”）和 slug（URL 标识，如 status）
3. 选择公开的监控组
4. 可选：设置自定义域名、自定义 CSS、页脚文字
5. 设置为”已发布”

发布后状态页地址为 https://status.example.com/status/<slug>。

状态页高级配置#

维护策略#

创建维护窗口#

1. 进入 维护 → 计划维护
2. 填写标题和描述
3. 选择受影响的监控项
4. 选择要展示维护信息的状态页
5. 选择维护策略并设置时间
6. 保存

维护窗口生效期间，监控项继续正常检查，但状态显示为”维护中”而非”已离线”，通知不会发送。

方案一：SQLite 在线导出（推荐，无需停服）#

.dump 导出为 SQL 文本，可跨版本恢复，且不锁库：

1
docker exec uptime-kuma sqlite3 /app/data/kuma.db ".dump" | gzip > \
2
  /backup/uptime-kuma/kuma-$(date +%Y%m%d-%H%M).sql.gz

.dump 在数据库写入频繁时可能产生不一致快照（SQLite 不隔离长查询）。数据量极大（>1 GB）或写入密集场景下，建议选择方案三（停机备份）。

方案二：SQLite .backup 在线热备份#

1
# .backup 使用在线备份 API，保证原子性，但执行期间持有读锁（阻塞写入）
2
docker exec uptime-kuma sqlite3 /app/data/kuma.db ".backup /tmp/kuma_backup.db"
3
docker cp uptime-kuma:/tmp/kuma_backup.db /backup/uptime-kuma/kuma-$(date +%Y%m%d).db
4
docker exec uptime-kuma rm /tmp/kuma_backup.db

.backup 保证数据一致性优于 .dump，但执行期间所有写入操作会被阻塞。中小规模数据库（<500 MB）的阻塞时间通常在秒级，可接受。

方案三：停机备份（最安全）#

1
docker stop uptime-kuma
2
cp /opt/uptime-kuma/data/kuma.db /backup/uptime-kuma/kuma-$(date +%Y%m%d).db
3
docker start uptime-kuma

自动化备份脚本#

1
#!/bin/bash
2
BACKUP_DIR="/backup/uptime-kuma"
3
RETENTION_DAYS=14
4
mkdir -p "$BACKUP_DIR"
5

6
docker exec uptime-kuma sqlite3 /app/data/kuma.db ".dump" | gzip > \
7
  "$BACKUP_DIR/kuma-$(date +%Y%m%d-%H%M).sql.gz"
8

9
# 清理旧备份
10
find "$BACKUP_DIR" -name "*.sql.gz" -mtime +$RETENTION_DAYS -delete
11

12
echo "Backup completed: $(date)"

加入 Cron 定时执行：

1
0 4 * * * /opt/scripts/backup-uptime-kuma.sh >> /var/log/uptime-kuma-backup.log 2>&1

数据库文件损坏是 Uptime Kuma 最常见的故障场景之一。以下情况容易导致 SQLite 数据库损坏：非正常关闭容器、使用 NFS/Ceph 等网络存储、Docker Swarm 多副本、磁盘空间满。务必定期备份。

数据恢复#

1
# 解压备份并恢复
2
gunzip /backup/uptime-kuma/kuma-20260528-0400.sql.gz
3
docker stop uptime-kuma
4
docker cp /backup/uptime-kuma/kuma-20260528-0400.sql uptime-kuma:/tmp/restore.sql
5
docker exec uptime-kuma sh -c "cat /tmp/restore.sql | sqlite3 /app/data/kuma.db"
6
docker start uptime-kuma

全新 MariaDB 部署（推荐）#

如果接受重新设置监控项，直接配置 MariaDB 全新启动：

1. 停止现有容器，备份 /app/data 目录
2. 在 /opt/uptime-kuma/data/ 下创建 db-config.json 或在 Docker Compose 中使用环境变量
3. 启动后 Uptime Kuma 自动连接 MariaDB，重新创建监控项即可

1
services:
2
  uptime-kuma:
3
    image: louislam/uptime-kuma:2
4
    restart: unless-stopped
5
    volumes:
6
      - /opt/uptime-kuma/data:/app/data
7
    ports:
8
      - "127.0.0.1:3001:3001"
9
    environment:
10
      - TZ=Asia/Shanghai
11
      - UPTIME_KUMA_DB_TYPE=mariadb
12
      - UPTIME_KUMA_DB_HOSTNAME=mariadb
13
      - UPTIME_KUMA_DB_PORT=3306
14
      - UPTIME_KUMA_DB_NAME=uptime_kuma
15
      - UPTIME_KUMA_DB_USERNAME=kuma
16
      - UPTIME_KUMA_DB_PASSWORD=<your-password>
17
    depends_on:
18
      mariadb:
19
        condition: service_healthy
20

21
  mariadb:
22
    image: mariadb:11
23
    restart: unless-stopped
24
    volumes:
25
      - /opt/uptime-kuma/mariadb:/var/lib/mysql
26
    environment:
27
      - MARIADB_ROOT_PASSWORD=<root-password>
28
      - MARIADB_DATABASE=uptime_kuma
29
      - MARIADB_USER=kuma
30
      - MARIADB_PASSWORD=<your-password>
31
    healthcheck:
32
      test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
33
      interval: 10s
34
      timeout: 5s
35
      retries: 5

环境变量名支持连字符格式（如 UPTIME-KUMA-DB-TYPE），功能等价。所有密码占位符（<your-password>、<root-password>）需替换为实际值。