文档

API 概览与调用约定

RustMinerSystem 后台接口的调用地址、X-ACCESS-TOKEN 鉴权、响应结构、开放条件与安全约定。

本分类根据新版 RustMinerSystem 前端请求和后端接口契约整理，覆盖矿池代理管理、观察者、群控、WebSocket 和内置 PoolNode 管理接口。文档中的地址、钱包、凭据和标识均为脱敏示例，实际字段仍以正在运行的版本为准。

开放条件与凭据流程

新版前端已经提供完整的 API 凭据管理页面。使用前需要：

在 rust-config 中将 ENABLE_CONTROL_API 设置为 1，然后重启 RustMinerSystem。脚本安装用户也可以重新运行安装命令并选择“开启 API”。
在后台“设置 → API”中获取或首次生成 API Key。
使用 API Key 生成 Access Token。
在每个开放 API 请求中发送 X-ACCESS-TOKEN。

Access Token 的有效期约为 2 小时。生成新的 Access Token 后，旧 Token 立即失效；刷新 API Key 会同时让旧 Key 和由它生成的全部 Access Token 失效。

接口字段和响应结构仍应以正在运行的 RustMinerSystem 版本为准。

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

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

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

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

未配置安全路径时，接口位于网站根路径。反向代理必须原样转发安全路径和 X-ACCESS-TOKEN 请求头。

API 调用使用前端已公布的正式请求头：

X-ACCESS-TOKEN: <Access Token>
Content-Type: application/json

X-ACCESS-TOKEN 的值直接填写生成的 Access Token，不添加额外前缀。

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

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

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

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

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

前端重点处理以下状态：

状态	含义
`200`	请求成功，仍需检查业务数据或 PoolNode 的 `status`。
`401` / `403`	Access Token 缺失、无效、已过期，或当前接口不接受该凭据。重新生成 Token 后再试。
PoolNode `status: 4`	PoolNode 项目尚未激活。

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

文档使用以下返回类型记法：

记法	含义
`Foo`	单个 JSON 对象，字段在同章的 `Foo` 模型中说明。
`Foo[]`	JSON 数组，每项为 `Foo`。
`string` / `number`	响应体直接是 JSON 字符串或数字，不带 `{ data }`。
“成功标量或 HTTP 200”	前端只判断成功状态，不依赖响应体；写入后应重新 GET 验证。
PoolNode 包装	`{ status, error, data }`；只有 `status=0` 时读取 `data`。

表格中的 null 表示运行中确实可能缺少数据，不能强制转换成 0 或空字符串。响应允许出现文档未列出的新增字段，调用方应保持宽松解析。

文档按以下模块整理：