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。