API 概览与调用约定

本分类根据新版 RustMinerSystem 前端的实际请求代码整理，覆盖矿池代理管理、观察者、群控、WebSocket 和内置 PoolNode 管理接口。

当前开放状态

对外 API 的设计方式是“无需登录、每次请求携带自定义鉴权请求头”。自定义请求头功能尚未完成，因此：

• 外部 API 客户端不需要调用后台登录接口，也不需要获取后台登录 TOKEN。
• 文档只把登录接口作为新版前端内部调用记录，不把登录流程作为 API 前置条件。
• 自定义请求头完成后，需要补充密钥生成、权限范围、吊销、过期、来源限制和调用频率。
• 接口字段和响应结构应以正在运行的后端版本为准。

调用地址

接口基址是 RustMinerSystem 后台访问地址，并且必须包含安全访问路径。

https://主机:Web端口/{安全路径}/api/...

例如后台地址为 https://miner.example.com/rms-admin/，端口列表接口为：

https://miner.example.com/rms-admin/api/ports

未配置安全路径时，接口位于网站根路径。反向代理必须原样转发安全路径和自定义 API 请求头。

API 鉴权请求头

API 调用无需登录。自定义请求头完成后，每个请求直接发送：

<自定义请求头名称>: <API 凭据>
Content-Type: application/json

正式请求头名称和凭据格式将在后端功能完成后补充。第三方程序不应使用管理后台的 Authorization: Bearer <登录 TOKEN> 代替 API 凭据。

观察者只读接口使用独立请求头：

X-OB-TOKEN: <观察者 TOKEN>

注意：新版后台前端拦截器中还会写入名为 ContentType 的非标准字段。这是后台内部实现，第三方调用应使用标准的 Content-Type。

响应和错误

矿池代理接口通常直接在 HTTP 响应体中返回对象、数组、字符串或数字。部分 PoolNode 管理接口会返回包装结构：

{
  "status": 0,
  "error": null,
  "data": {}
}

前端重点处理以下状态：

错误响应可能使用 message、error 或业务 status 表示原因。调用端不应只根据 HTTP 200 判断所有业务操作都已成功。

接口范围

新版前端共定义 146 个接口标识，其中 140 个有实际引用。文档按以下模块整理：

• API 请求头、权限和后台内部会话接口边界。
• 仪表盘、版本和系统配置。
• 代理端口与抽水钱包。
• 矿工、钱包统计、图表和日志。
• 安全、证书、防火墙和运行日志。
• 观察者只读查询。
• 群控转发。
• PoolNode 项目、网站、收益和子账号管理。
• WebSocket 实时数据与错误处理。

安全建议

• API 只应通过 HTTPS 暴露。
• 不要把 API 凭据、观察者 TOKEN 或群控 API 写入 URL、日志和截图。
• 修改端口、钱包、白名单、证书和安全路径前先备份配置。
• 自动化程序应设置连接、读取和总请求超时，并限制重试频率。
• 自定义 API 请求头完成前，不建议把这些内部管理接口直接开放到公网。