文档

WebSocket、错误处理与兼容性

RustMinerSystem 实时 Stratum WebSocket 协议、订阅消息、错误状态、兼容性和未使用接口说明。

WebSocket 地址

实时矿工 Stratum 数据使用：

ws://主机:端口/{安全路径}/api/ws
wss://主机:端口/{安全路径}/api/ws

HTTPS 页面必须使用 wss://。安全路径的拼接规则与 HTTP API 相同。

以下是新版后台前端当前使用的内部 WebSocket 握手帧。它不是外部 API 的登录前置流程；外部 WebSocket 如何使用免登录 API 凭据仍待后端实现。

{
  "type": "login",
  "key": "<当前内部 WebSocket 会话凭据>"
}

然后订阅矿工组：

{
  "type": "subscribe",
  "group_id": "<矿工 gid>"
}

前端每 10 秒发送一次心跳：

{
  "type": "ping"
}

服务端可以返回字符串 pong、{ "type": "pong" }，或在 body 中包含 pong。

取消订阅和关闭：

{
  "type": "unsubscribe",
  "group_id": "<矿工 gid>"
}

{
  "type": "close"
}

消息可能是字符串、JSON 对象，或 { type, body } 包装结构。矿工标识可能位于 workerID、workerId、worker_id、sid 或 id。

调用端至少应处理：

情况	建议
无 HTTP 响应	视为网络中断、服务重启或跨域失败；使用有限次数退避重试。
`401` / `403`	清除失效会话并重新登录。
`423`	当前后台 UI 要求 TOTP；外部免登录 API 的错误行为待确认。
`404`	检查后端版本是否支持该接口。
`5xx`	记录请求 ID、路径和脱敏错误，不要无限重试。
HTTP 200 + 业务失败	检查 PoolNode `status`、`error` 和操作特定返回值。

修改 Web 端口、安全路径、TLS 或证书时，服务重启可能让当前请求没有响应。此类接口需要结合新地址是否可访问判断最终状态。

路径	状态
`/api/_/captcha`	定义了滑动验证码常量，但新版前端没有调用点。
`/api/port/{id}/workers`	旧矿工列表路径；当前使用 `/api/port/{id}/g/workers`。
`/api/sysinfo`	旧系统信息路径；当前使用 `/api/sys/base/info`。
`/api/pump/t`	抽水时间读取常量，当前未调用。
`/api/pump/t/{pump_t}`	抽水时间设置常量，当前未调用。
`/api/poolnode/rewards`	`p_get_fee_log` 是未使用别名，但相同路径由收益记录接口实际调用。

这些接口不能仅凭前端常量判断 HTTP 方法、权限和响应结构。正式开放前应从 Rust 后端路由再次核对。