🚀 使用 Docker 搭建 Uptime Kuma 并解析状态页数据

本文以轻松风格介绍如何在已有 Docker 环境中部署 Uptime Kuma，并解析其状态页数据 ✨。假设 Docker 已安装完成，我们直接从配置 Docker Compose 开始。以下示例会用到上海时区(Asia/Shanghai)、network_mode: host、数据卷挂载等，并演示如何访问后台界面及解析状态页 API 数据。

Docker Compose 配置示例

创建一个 docker-compose.yml 文件，示例配置如下：

version: '3.8'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime_kuma
    # 使用主机网络（network_mode: host）无需手动映射端口 ([Uptime Kuma | Mike Polinowski](https://mpolinowski.github.io/docs/DevOps/Provisioning/2024-01-18--uptime-kuma-monitoring/2024-01-18#:~:text=container_name%3A%20monitor%20restart%3A%20unless,%2Fopt%2Fuptime%3A%2Fapp%2Fdata))
    network_mode: host
    # 挂载数据卷：将本地目录 ./data 挂载到容器的 /app/data 保存监控数据 ([安装Uptime Kuma监控_安装 uptime kuma-CSDN博客](https://blog.csdn.net/uplookingwang/article/details/128932432#:~:text=container_name%3A%20uptime_kuma%20volumes%3A%20,%223001%3A3001))
    volumes:
      - ./data:/app/data:rw
      - /etc/localtime:/etc/localtime:ro
    # 设置时区为上海时间
    environment:
      - TZ=Asia/Shanghai      # 容器使用上海时区 ([安装Uptime Kuma监控_安装 uptime kuma-CSDN博客](https://blog.csdn.net/uplookingwang/article/details/128932432#:~:text=container_name%3A%20uptime_kuma%20volumes%3A%20,%223001%3A3001))
    restart: always

• 数据卷挂载：- ./data:/app/data 将主机的 ./data 目录挂载到容器内部，用于持久化存储监控数据。
• 时区设置：通过环境变量 TZ=Asia/Shanghai 指定上海时区，确保日志和时间显示正确。
• 网络模式：使用 network_mode: host 让容器使用宿主机网络，无需再映射端口 (Uptime Kuma | Mike Polinowski)。如果不使用主机网络，也可使用 ports: - "3001:3001" 映射到宿主机端口。
• 重启策略：restart: always 确保容器在机器重启后自动启动。

配置完成后，在该目录执行 docker-compose up -d 即可启动 Uptime Kuma 服务。🎉

启动并访问 Uptime Kuma 后台

启动成功后，即可通过浏览器访问 Uptime Kuma 后台界面。假设域名为 example.com，则访问地址为 http://example.com:3001（端口号为默认的 3001）。你也可以使用服务器 IP 加端口访问，比如 http://<服务器IP>:3001。正如某教程所述，完成安装后使用 http://服务器IP:端口 访问。

登录后台后，按照提示创建管理员账号并登录，就可以开始添加监控项了 👍。

状态页（Status Page）及 Slug 设置

Uptime Kuma 支持创建 公开状态页（Status Page），用于向公众展示服务状态。状态页常见于 API 平台、开发者平台等场景，可以直观地展示网站或服务的运行健康状态，减少用户对运维情况的询问。

在创建状态页时，需要设置一个唯一的 Slug，即状态页的 URL 路径名。在后台点击 “Status Pages” → “+ New Status Page” 时，会要求填写状态页名称和 Slug。Slug 就是访问该状态页的路径，例如设置为 yyszone 后，状态页网址类似 http://example.com/status/yyszone。例如官方文档示例中提到的 Slug 名称：“status-page”。我们这里使用 yyszone 作为示例 Slug。

示例： 设置 Title 为 “My Status”，Slug 为 yyszone，然后添加监控项并保存。此后即可通过 http://example.com/status/yyszone 公开查看监控状态。

构造状态页 API 接口

Uptime Kuma 内部提供了状态页的 REST API，可返回 JSON 格式的数据。常用接口包括：

提示： 在以上接口中，将 yyszone 替换为你的状态页 Slug。通过调用 /api/status-page/{slug} 可以得到状态页当前的配置和监控列表；调用 /api/status-page/heartbeat/{slug} 可以得到每个监控项的心跳历史数据 

例如，对应 yyszone 状态页的 API 地址为：

• 状态页信息接口：http://example.com/api/status-page/yyszone
• 心跳数据接口：http://example.com/api/status-page/heartbeat/yyszone 

这些接口不需要额外认证即可访问，可供脚本定期抓取或其它系统集成使用。

JSON 数据示例与解析

下面给出一个简化后的 JSON 结构示例，以说明接口返回的数据格式（已省略不相关字段）：

{
  "incident": null,
  "maintenanceList": [],
  "publicGroupList": [
    {
      "id": 62,
      "name": "Services",
      "monitorList": [
        {"id": 192, "name": "Google", "type": "http", "status": 1},
        {"id": 193, "name": "Gmail",  "type": "http", "status": 1}
      ]
    }
  ],
  "slug": "google",
  "title": "Google Status"
}

如上所示，publicGroupList 列表下包含一个或多个监控分组（group），每个组下的 monitorList 列出了监控项（名称、类型、状态等） (Status pages — kumaone 0.0.1-alpha.10 documentation)。注意，实际返回的字段可能更多，比如监控的间隔、URL 等，此处为简化示例。

心跳数据（Heartbeat）接口示例如下：

{
  "heartbeatList": {
    "192": [
      {"time": "2025-04-26T07:32:00.000Z", "status": 1, "ping": 120},
      {"time": "2025-04-26T07:33:00.000Z", "status": 1, "ping": 115}
    ],
    "193": [
      {"time": "2025-04-26T07:32:00.000Z", "status": 1, "ping": 98}
    ]
  }
}

在 heartbeatList 中，每个监控项 ID 对应一个数组，数组里是该监控项的历史心跳记录。字段说明：

• time：心跳时间戳（UTC 格式），
• status：状态码（1 表示正常），
• ping：响应时延（毫秒）。

解析提示： 返回的时间 time 字段默认为 UTC 时间，例如示例中的 "2025-04-26T07:32:00.000Z"。若需要以上海时区显示，请将时间加上 8 小时（UTC+8）。在 Python 中可用 datetime.strptime 或 dateutil 解析后加上 timedelta(hours=8)。例如：

from datetime import datetime, timedelta
utc_time = datetime.fromisoformat("2025-04-26T07:32:00.000Z".replace("Z", "+00:00"))
bj_time = utc_time + timedelta(hours=8)
print(bj_time)  # 对应上海时间

其他字段的解析也类似，可根据需要提取监控项名称、状态等信息进行后续处理 🚀。