kuma-extended

一个轻量、专注的 API 代理，将已发布的 Uptime Kuma 状态页转换为稳定、可缓存的 JSON API，供 Web 与移动端调用。

kuma-extended 设计为与 Uptime Kuma 部署在同一内网中。它在 Kuma 公开的 /api/status-page/:slug 接口之上加了一层固定契约，提供 TTL 缓存、按 IP 速率限制、安全响应头，以及可选的 CORS 配置。

前置条件

本模板仅部署 kuma-extended 代理服务。你必须先有一个可被 kuma-extended 访问的 Uptime Kuma 实例。

在 Zeabur 上，最简单的方式是在同一项目内再部署一个 Uptime Kuma 服务。两者之间可以通过内部主机名相互访问，例如 http://uptime-kuma.<container-hostname>.zeabur.internal:3001。

配置

变量	是否必填	默认值	说明
KUMA_BASE_URL	是	—	上游 Uptime Kuma 实例的 URL
KUMA_STATUS_PAGE_SLUG	否	default	要代理的 Kuma 状态页 slug
ALLOWED_ORIGIN	否	(空)	CORS 来源；留空则停用 CORS
CACHE_TTL_SECONDS	否	60	Kuma 响应缓存 TTL（秒）
KUMA_TIMEOUT_MS	否	10000	调用 Kuma 时的超时时间（毫秒）
RATE_LIMIT_PER_MINUTE	否	120	每个 IP 令牌桶的补充速率
RATE_LIMIT_BURST	否	20	令牌桶容量（突发上限）

API

所有响应使用统一的信封结构：

{ "ok": true,  "data": { ... }, "meta": { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

• GET /api/v1/status — 返回所配置状态页的故障与维护事件汇总。
• GET /healthz — 代理存活状态与 Kuma 最近一次同步信息（不受速率限制）。

许可证

MIT — 详情见 GitHub 上的 kuma-extended。