开发指南
公开 API
主题和外部集成只依赖这几个接口。完整响应结构、错误码表和字段类型见仓库里的 API.md。
站点配置
GET /api/config
站点级配置。在线阈值、访客历史范围、默认主题与语言、线路显示名、主题自身配置都在这里。见主题开发。
服务器列表
GET /api/servers
当前用户可见的服务器列表。字段随后台开关变化——价格、到期、流量在开关关闭时可能整个不存在。
主题不要假设字段一定在。用可选链 / 默认值兜底，而不是直接 .map 或直接渲染。
单台详情
GET /api/servers/:id
历史指标
GET /api/servers/:id/history?hours=24
hours 决定查询范围。long_history_points 决定返回的采样点数（60/120/180/240），主题按实际返回点数渲染，不要写死。
hours | 谁可以查 |
|---|---|
≤ public_history_hours（默认 24） | 访客 |
| > 访客范围，到 720 | 登录用户 |
| > 720 | 400 |
原版主题请求 336 / 720 小时会直接 400。本面板支持到 720，访客上限由设置决定。
实时推送
WSS /
前端订阅实时数据。行为：
- 只在有前端活跃时广播——没浏览器的时段不推，这是省内存的关键
- 详情页单台订阅秒级更新（默认 2 秒）
- 订阅达到
frontend_ws_timeout_minutes后关闭连接，由用户明确选择是否续订 - 消息格式与原版一致
保存主题配置
POST /api/theme_options
响应约定
- 成功：
{ "success": true, ... } - 失败：
{ "success": false, "error": "..." } - HTTP 状态码同时反映结果（400 / 401 / 403 / 500）
字段的完整类型定义在 API.md 的「类型定义」一节。