文档

API Key、Access Token 与鉴权

RustMinerSystem API 开关、API Key、Access Token、X-ACCESS-TOKEN 请求头、生成、轮换与安全使用。

API Key、Access Token 与鉴权

RustMinerSystem 对外 API 使用 API Key 生成短期 Access Token，再通过 X-ACCESS-TOKEN 请求头调用开放接口。

1. 开启 API

在 rust-config 中设置：

ENABLE_CONTROL_API=1

重启 RustMinerSystem 后，进入后台“设置 → API”并点击“重新检测”。脚本安装用户也可以重新运行安装命令并选择“开启 API”。

功能未开启时，前端会把 status: -3 或消息 Api Control Disable 识别为 API 已禁用。

2. 获取或刷新 API Key

API 设置页面使用以下接口：

方法	路径	用途
GET	`/api/access/key`	读取当前 API Key 和 API 开关状态。
POST	`/api/refresh/access/key`	首次生成或刷新 API Key。成功响应为 `Ok`。

读取成功的响应：

{
  "key": "<API_KEY>"
}

这两个接口由后台 API 设置页面管理。API Key 应通过安全渠道提供给调用方。

刷新 API Key 是全局轮换操作：旧 Key 和由旧 Key 生成的所有 Access Token 会立即失效。当前前端没有为不同调用方生成多个 Key 的功能。

3. 生成 Access Token

POST /{安全路径}/api/generate/access/token
Content-Type: application/json

{
  "k": "<API_KEY>"
}

成功响应：

{
  "access_token": "<ACCESS_TOKEN>"
}

Access Token 的有效期约为 2 小时。过期后使用当前 API Key 重新生成。每次生成新的 Access Token，旧 Access Token 都会失效，因此同一实例上的调用方需要同步更新。

API Key 只用于生成 Access Token，不应作为普通接口的请求头值。前端仅在当前页面内展示生成结果，应立即复制并保存到安全的密钥存储中。

4. 调用开放接口

每次请求直接发送前端配置中定义的正式请求头：

GET /{安全路径}/api/ports
X-ACCESS-TOKEN: <ACCESS_TOKEN>
Content-Type: application/json

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

curl 示例：

curl --request GET \
  --url 'https://miner.example.com/rms-admin/api/ports' \
  --header 'X-ACCESS-TOKEN: <ACCESS_TOKEN>' \
  --header 'Accept: application/json'

凭据生命周期

操作	影响
重新生成 Access Token	新 Token 生效，旧 Token 立即失效。
Access Token 到期	使用当前 API Key 重新生成，约每 2 小时一次。
刷新 API Key	旧 Key 和全部旧 Access Token 立即失效。
将 `ENABLE_CONTROL_API` 设为 `0` 并重启	API 功能关闭，现有凭据停止使用。

当前前端没有展示只读/管理权限范围、来源 IP、CORS 或调用频率配置。部署方应把 Access Token 视为高权限凭据，并在反向代理或防火墙层补充来源限制和限流。

特殊只读凭据

观察者模式继续使用独立的：

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

它只用于观察者页面提供的只读接口，不等同于通用的 X-ACCESS-TOKEN。

常见问题

现象	处理
API 设置页显示“未启用”	确认 `ENABLE_CONTROL_API=1`，重启程序后重新检测。
生成 Token 没有返回 `access_token`	确认 API Key 未刷新、请求体字段为小写 `k`，并检查响应中的 `message`。
普通接口返回 `401` / `403`	检查请求头名称和值，随后用当前 Key 重新生成 Token。
多个调用方突然同时失效	检查是否刷新了 Key，或是否有调用方生成了新的 Access Token。

安全建议

API 凭据只通过 HTTPS 传输。
不把凭据写入 URL、查询参数、日志或截图。
当前实例只有一套前端可见的 Key/Token 流程；多个调用方共享时必须协调轮换。
自动化程序通过环境变量或密钥管理服务读取凭据。
Access Token 泄漏后立即重新生成；API Key 泄漏后立即刷新 Key。
对修改端口、钱包、证书和防火墙的接口，在反向代理层增加更严格的来源限制。