# yaml-language-server: $schema=https://schema.zeabur.app/template.json apiVersion: zeabur.com/v1 kind: Template metadata: name: kuma-extended spec: description: A small, focused API proxy that turns a published Uptime Kuma status page into a stable, cacheable JSON API. icon: https://raw.githubusercontent.com/sk5s/kuma-extended/refs/heads/main/docs/logo.jpg variables: - key: KUMA_BASE_URL type: STRING name: Uptime Kuma Base URL description: The internal URL of your Uptime Kuma instance (e.g. http://uptime-kuma.zeabur.internal:3001) - key: KUMA_STATUS_PAGE_SLUG type: STRING name: Status Page Slug description: The slug of the Uptime Kuma status page to proxy - key: ALLOWED_ORIGIN type: STRING name: Allowed CORS Origin description: The origin allowed for CORS requests (empty disables CORS) tags: - API - Monitoring - Networking readme: | # kuma-extended A small, focused API proxy that turns a published [Uptime Kuma](https://github.com/louislam/uptime-kuma) status page into a stable, cacheable JSON API for web and mobile clients. `kuma-extended` is designed to live on the same internal network as Uptime Kuma. It wraps Kuma's public `/api/status-page/:slug` endpoint behind a fixed contract with TTL caching, per-IP rate limiting, security headers, and an opt-in CORS surface. ## Prerequisites This template deploys **only** the `kuma-extended` proxy. You must already have an [Uptime Kuma](https://github.com/louislam/uptime-kuma) instance running and reachable from the `kuma-extended` service. On Zeabur, the easiest way is to deploy Uptime Kuma as another service in the same project. The two services can then reach each other using the internal hostname, e.g. `http://uptime-kuma..zeabur.internal:3001`. ## Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `KUMA_BASE_URL` | Yes | — | URL of the upstream Uptime Kuma instance | | `KUMA_STATUS_PAGE_SLUG` | No | `default` | Slug of the Kuma status page to proxy | | `ALLOWED_ORIGIN` | No | *(empty)* | CORS origin; empty disables CORS | | `CACHE_TTL_SECONDS` | No | `60` | TTL for cached Kuma responses | | `KUMA_TIMEOUT_MS` | No | `10000` | Timeout when calling Kuma | | `RATE_LIMIT_PER_MINUTE` | No | `120` | Per-IP refill rate for the token bucket | | `RATE_LIMIT_BURST` | No | `20` | Token bucket capacity (burst ceiling) | ## API All responses share the same envelope: ```json { "ok": true, "data": { ... }, "meta": { ... } } { "ok": false, "error": { "code": "...", "message": "..." } } ``` - `GET /api/v1/status` — Merged incident and maintenance feed for the configured status page. - `GET /healthz` — Proxy liveness and Kuma's most recent sync state (not rate-limited). ## License MIT — see [kuma-extended](https://github.com/sk5s/kuma-extended) on GitHub. services: - name: kuma-extended icon: https://raw.githubusercontent.com/sk5s/kuma-extended/refs/heads/main/docs/logo.jpg template: PREBUILT_V2 spec: id: kuma-extended source: image: sk5sapp/kuma-extended:latest ports: - id: web port: 3000 type: HTTP instructions: - title: API status endpoint content: ${ZEABUR_WEB_URL}api/v1/status - title: Health endpoint content: ${ZEABUR_WEB_URL}healthz env: ALLOWED_ORIGIN: default: ${ALLOWED_ORIGIN} expose: false CACHE_TTL_SECONDS: default: "60" expose: false KUMA_BASE_URL: default: ${KUMA_BASE_URL} expose: false KUMA_STATUS_PAGE_SLUG: default: ${KUMA_STATUS_PAGE_SLUG} expose: false KUMA_TIMEOUT_MS: default: "10000" expose: false PORT: default: "3000" RATE_LIMIT_BURST: default: "20" expose: false RATE_LIMIT_PER_MINUTE: default: "120" expose: false configs: [] healthCheck: type: HTTP port: web http: path: /healthz portForwarding: enabled: false localization: zh-CN: description: 一个轻量、专注的 API 代理，将已发布的 Uptime Kuma 状态页转换为稳定、可缓存的 JSON API。 readme: | # kuma-extended 一个轻量、专注的 API 代理，将已发布的 [Uptime Kuma](https://github.com/louislam/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..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 所有响应使用统一的信封结构： ```json { "ok": true, "data": { ... }, "meta": { ... } } { "ok": false, "error": { "code": "...", "message": "..." } } ``` - `GET /api/v1/status` — 返回所配置状态页的故障与维护事件汇总。 - `GET /healthz` — 代理存活状态与 Kuma 最近一次同步信息（不受速率限制）。 ## 许可证 MIT — 详情见 GitHub 上的 [kuma-extended](https://github.com/sk5s/kuma-extended)。 zh-TW: description: 一個輕量、專注的 API 代理，將已發佈的 Uptime Kuma 狀態頁轉換為穩定、可快取的 JSON API。 readme: | # kuma-extended 一個輕量、專注的 API 代理，將已發佈的 [Uptime Kuma](https://github.com/louislam/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..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 所有回應使用統一的信封結構： ```json { "ok": true, "data": { ... }, "meta": { ... } } { "ok": false, "error": { "code": "...", "message": "..." } } ``` - `GET /api/v1/status` — 回傳所設定狀態頁的故障與維護事件彙總。 - `GET /healthz` — 代理存活狀態與 Kuma 最近一次同步資訊（不受速率限制）。 ## 授權 MIT — 詳情見 GitHub 上的 [kuma-extended](https://github.com/sk5s/kuma-extended)。