公开 API

/api/v1 是面向替代前端、公开面板、主题、插件和服务端集成的稳定只读接口。读取不需要 Token，写入能力不对第三方开放。

连接自己的部署

Worker API 地址

https://api.example.com/api/v1

地址只保存在当前标签页，不会发送管理凭据。

本站只在当前标签页的 sessionStorage 中保存地址。检测请求使用 credentials: 'omit'，不会读取或发送管理员凭据。

端点清单

方法	路径	用途	默认速率限制
GET	/api/v1	版本、能力和端点发现	公共读取策略
GET	/api/v1/status	目标、当前状态、汇总和遥测	120 次/分钟/IP
GET	/api/v1/checks	单个目标的可用性历史	120 次/分钟/IP
GET	/api/v1/metrics	单个 Agent 的指标历史	30 次/分钟/IP
GET	/api/v1/pings	Agent TCP Ping 历史	30 次/分钟/IP
GET	/api/v1/latency	外部 Latency Agent 历史	60 次/分钟/IP

限制是当前生产默认值，部署者可以在未来版本调整。客户端不应把它们当作并发目标；状态页通常只需按缓存周期刷新。

基本请求

export API_BASE='https://YOUR-API'
curl -fsSL "$API_BASE/api/v1"
curl -fsSL "$API_BASE/api/v1/status?days=30&lite=1"

const response = await fetch(`${apiBase}/api/v1/status?days=30&lite=1`, {
  method: 'GET',
  credentials: 'omit',
  headers: { accept: 'application/json' },
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)
const status = await response.json()

CORS

服务端集成不受浏览器 CORS 限制。浏览器替代前端必须把精确 Origin 加入 Worker 的 DEVELOPER_API_ORIGINS：

DEVELOPER_API_ORIGINS = "https://status.example.com,http://localhost:5173"

规则如下：

• 只接受完整 Origin，不包含路径和尾部 /；
• 生产 Origin 必须使用 HTTPS；
• HTTP 只允许 localhost 开发地址；
• * 会被忽略，不会打开通配符访问；
• 该变量只影响 /api/v1，不会开放 Admin 或 Agent 写接口。

响应约定

成功响应使用 JSON，并包含 ok: true。错误通常包含 ok: false 与 error。v1 响应带有版本响应头：

X-NStatus-API-Version: v1

这是兼容性线协议字段，客户端应按字面读取。产品与文档名称始终为 NIE-SLA。

缓存与刷新

各端点可能返回 Cache-Control，状态与历史接口也可能命中 Cloudflare Cache API。客户端应尊重缓存头，不要用高频轮询制造无意义请求。

建议公开面板：

• 当前状态每 20–60 秒刷新；
• 图表仅在打开详情或切换时间范围时请求；
• 页面隐藏时暂停轮询；
• 网络恢复后加入随机延迟，避免所有客户端同时重试。

稳定性规则

在 v1 中，服务端可以增加新的可选字段、数组成员和能力标识，但不会无公告删除或重命名既有字段。客户端必须忽略未知字段，并处理 null、空数组、无历史和暂时过期的数据源。

需要统一错误策略时，继续阅读错误处理。