基于 Docker 的 Uptime Kuma 部署：自定义警报钩子和多站点故障转移机制

在自托管环境中，监控多站点服务的可用性至关重要。Uptime Kuma 作为一款开源的自托管监控工具，能够有效跟踪 HTTP、TCP、Ping 等多种协议的站点状态，并通过自定义警报钩子及时通知异常。本文聚焦于基于 Docker 的部署方式，结合自定义警报钩子和故障转移机制，提供可落地的工程化参数和配置清单，帮助读者构建容错的多站点监控系统。

Docker 部署基础配置

Uptime Kuma 的 Docker 部署简单高效，利用官方镜像 louislam/uptime-kuma 即可快速启动。核心观点是优先使用 Docker Compose 管理容器，确保数据持久化和自动重启，从而降低运维门槛。

部署步骤如下：

创建项目目录：mkdir uptime-kuma && cd uptime-kuma。
下载官方 compose.yaml：curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml。
启动服务：docker compose up -d。

默认配置将 Uptime Kuma 运行在 3001 端口，数据存储在本地卷 /app/data。为自托管环境优化，建议自定义 docker-compose.yml 文件：

version: '3.8'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro  # 可选，用于监控 Docker 容器
    environment:
      - NODE_ENV=production
    networks:
      - monitoring-net

networks:
  monitoring-net:
    driver: bridge

关键参数解释：

端口映射：3001 是默认监听端口，可根据环境调整为 80 或 443 以支持 HTTPS（需结合 Nginx 反向代理）。
数据卷：./data:/app/data 确保 SQLite 数据库持久化。生产环境中，推荐迁移到 PostgreSQL 以支持多实例共享，避免单点故障。
重启策略：always 确保容器在崩溃时自动恢复，阈值设置为 5 次重启失败后警报。
网络：自定义 bridge 网络，便于与其他服务集成，如 Prometheus 导出指标。

部署后，通过 http://your-ip:3001 访问界面，首次登录需创建管理员账号。初始配置包括设置语言为中文和启用 2FA 以提升安全性。

自定义警报钩子实现

Uptime Kuma 支持 90+ 种通知服务，其中 Webhook 是自定义警报钩子的核心机制。通过 Webhook，用户可将警报事件推送到企业微信、钉钉或自定义脚本，实现灵活的集成。

观点：自定义钩子能将监控与 CI/CD 或日志系统联动，例如异常时触发自动回滚脚本。证据：官方文档显示 Webhook 支持 JSON Payload，包括 status（up/down）、monitor 和 msg 字段。

配置清单：

进入 Settings > Notifications > Add Notification。
选择 "Webhook" 类型。
URL：例如 https://your-webhook-endpoint.com/alert，支持 HTTP/HTTPS。
方法：POST，Content-Type: application/json。

自定义 Payload 示例：

{
  "status": "{{status}}",
  "monitor": "{{monitorName}}",
  "site": "{{monitorUrl}}",
  "timestamp": "{{date}}",
  "ping": "{{ping}}",
  "response": "{{responseTime}}"
}

阈值参数：响应时间 > 500ms 或 uptime < 99% 时触发。证书到期前 30 天警报。
测试：点击 "Send Test Notification" 验证集成。

落地参数：Webhook 超时设为 10s，重试 3 次。结合企业微信机器人，配置 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your-key，Payload 适配 Markdown 格式，确保通知包含站点详情和历史 uptime 图表链接。

对于多警报场景，启用 "Ignore TLS Errors" 以兼容自签名证书，但生产中优先使用 Let's Encrypt。

多站点故障转移机制

多站点监控是 Uptime Kuma 的强项，支持无限添加监控项，但单实例部署易成瓶颈。观点：通过多 Docker 实例 + 共享数据库实现故障转移，确保监控系统自身高可用。证据：社区实践显示，使用 PostgreSQL 作为后端 DB，结合负载均衡，可实现 99.99% uptime。

实施步骤：

数据库迁移：默认 SQLite 不支持 HA，切换到 PostgreSQL。
- 部署 PostgreSQL：docker run -d --name postgres -e POSTGRES_PASSWORD=secret -p 5432:5432 -v ./pgdata:/var/lib/postgresql/data postgres:14。
- 配置 Uptime Kuma：环境变量 TYPE=postgres、POSTGRES_HOST=postgres、POSTGRES_PORT=5432、POSTGRES_DB=uptime_kuma、POSTGRES_USER=postgres、POSTGRES_PASSWORD=secret。
- 更新 docker-compose.yml 添加 postgres 服务。

多实例部署：运行 2-3 个 Uptime Kuma 容器，共享 DB。

services:
  uptime-kuma-1:
    # ... 基础配置
    ports: ["3001:3001"]
  uptime-kuma-2:
    # ... 相同配置
    ports: ["3002:3001"]

负载均衡与 failover：使用 Traefik 或 Nginx 作为前端代理。
- Nginx 示例配置：
```
upstream uptime {
  server uptime-kuma-1:3001;
  server uptime-kuma-2:3001;
}
server {
  listen 80;
  location / {
    proxy_pass http://uptime;
    health_check interval=10 fails=3 passes=2 uri=/;
  }
}
```
- 参数：健康检查间隔 10s，失败 3 次切换。启用 sticky sessions 以保持 WebSocket 连接（用于实时更新）。
多站点监控配置：
- 添加监控组：按地域或服务类型分组，例如 "APAC Sites" 包含多个 HTTP 监控。
- 参数：检查间隔 20s（最小值），关键词匹配（如 "error" 在响应体），JSON 查询验证 API 输出。
- Failover 测试：模拟站点 downtime，验证警报在 60s 内触发，并通过多实例确保监控不中断。

风险与限值：

资源消耗：每个实例需 512MB RAM，监控 100+ 站点时 CPU > 20%。
回滚策略：更新镜像前备份 DB，测试 failover 切换时间 < 30s。

最佳实践与监控要点

为确保系统稳定，集成 Prometheus 导出 Uptime Kuma 指标（如 /metrics 端点），设置警报规则：实例 downtime > 5min 通知运维。

最后，维护清单：

每日检查日志：docker logs uptime-kuma。
备份：每周 rsync 数据卷。
升级：docker compose pull && docker compose up -d，验证 failover。

通过以上配置，自托管 Uptime Kuma 不仅实现多站点实时监控，还具备容错能力，适用于中小型基础设施。

资料来源：https://github.com/louislam/uptime-kuma