Skip to content

通用约定 ​

本文档汇总 HayFrp OpenAPI 的基础地址、认证方式、请求格式与错误码约定。各模块的接口细节见左侧「API 文档」下的子页面。

基础地址与故障转移 ​

顺序端点
主节点https://api.hayfrp.1zyq1.com
备用 1https://v2.api.hayfrp.1zyq1.com
备用 2https://api.hayfrp.com

前端 src/services/api.ts 通过 requestWithFallback() 实现自动故障转移:

  • 触发条件:ERR_NETWORK(网络错误)或 HTTP status >= 500
  • 最多尝试 3 个端点,每次请求使用独立 axios 实例,避免并发覆盖 baseURL
  • 请求超时:15 秒

必加请求头 ​

http
waf: off

WARNING

所有 API 调用必须带 waf: off,用于绕过雷池(SafeLine)WAF,否则请求会被拦截。前端已在 axios 实例的默认 headers 中统一配置。

认证方式 ​

模块凭证获取方式
用户接口(/user、/proxy、/oh.php、/esirun.php、/traffic.php、/rwmc.php、/bind)CSRF TokenPOST /user type=login 返回的 token
服务商接口(/dashboard/*)服务商 Token用户信息中的 token(/user type=info),经 /dashboard/login 验证
简单启动(/esirun.php type=config)隧道级 CSRFtype=create / type=get 返回的 csrf

CSRF 有效期 7 天,每次重新登录会使旧 Token 失效(keepcsrf=true 时保留已有有效 CSRF)。

Content-Type 规则 ​

Content-Type使用场景请求体构造
application/json;charset=UTF-8/user、/proxy、/oh.php、/esirun.php、/traffic.php、/bind普通 JS 对象
application/x-www-form-urlencoded/rwmc.php、/chat、/dashboard/*、proxy type=forcedownnew URLSearchParams({...})

响应格式 ​

status 不统一 ​

多数接口成功返回 status: 200,部分接口(如 /user type=info)返回 status: true。判定成功时两种都要接受:

typescript
if (res.status === 200 || res.status === true) {
  // 成功
}

数据结构 ​

  • 带鉴权的列表接口通常返回 { status, data: [...] } 或 { status, proxies: [...] }、{ status, servers: [...] }
  • 单条操作返回 { status, message }
  • 用户信息接口的 status: true 时,字段可能直接平铺在根对象,也可能包在 data 内,前端已做兼容

错误码 ​

状态码含义
200成功
202二维码登录等待扫码
204无内容(如房间暂无聊天)
401HTTP 层未授权:前端清除 Token 并跳转 /login
403权限错误 / 密码错误 / Token 无效或已过期
404参数缺失 / 用户或资源不存在
500服务器异常(触发端点故障转移)
502 / 503 / 504网关 / 服务不可用(触发端点故障转移)

前端调用方式 ​

typescript
import { api } from '@/services/api'

// 登录
const res = await api.login('demo@example.com', '123456')

// 用户信息
const info = await api.getUserInfo(csrf)

// 隧道
const list = await api.listProxies(csrf)
await api.addProxy(csrf, { proxy_name: 'my-web', proxy_type: 'http', /* ... */ })

// 公共信息(无需登录)
const nodes = await api.getNodeList()
const version = await api.getVersion()

状态字段的字符串布尔值 ​

后端不少字段以字符串返回布尔语义("true" / "false" / "1" / "0"),例如:

  • /user type=info 的 realname、sprovider
  • /proxy type=list 的 status、use_encryption、use_compression

前端 userStore 已对 realname / sprovider 做归一化;其他字段请显式比较字符串或转换后再判断。

接口模块索引 ​

模块端点文档
用户账号/user用户账号 API
隧道管理/proxy隧道管理 API
联机大厅/oh.php联机大厅 API
简单启动/esirun.php简单启动 API
云控设备/rwmc.php云控 (RWMC) API
流量趋势/traffic.php流量趋势 API
服务商/dashboard/*服务商 API
全站聊天/chat全站聊天 API
公共信息/node、/nodes、/notice、/info、/downlist、/version、/splist公共 API

基于 MIT 许可证发布