通用约定
本文档汇总 HayFrp OpenAPI 的基础地址、认证方式、请求格式与错误码约定。各模块的接口细节见左侧「API 文档」下的子页面。
基础地址与故障转移
| 顺序 | 端点 |
|---|---|
| 主节点 | https://api.hayfrp.1zyq1.com |
| 备用 1 | https://v2.api.hayfrp.1zyq1.com |
| 备用 2 | https://api.hayfrp.com |
前端 src/services/api.ts 通过 requestWithFallback() 实现自动故障转移:
- 触发条件:
ERR_NETWORK(网络错误)或 HTTPstatus >= 500 - 最多尝试 3 个端点,每次请求使用独立 axios 实例,避免并发覆盖
baseURL - 请求超时:15 秒
必加请求头
http
waf: offWARNING
所有 API 调用必须带 waf: off,用于绕过雷池(SafeLine)WAF,否则请求会被拦截。前端已在 axios 实例的默认 headers 中统一配置。
认证方式
| 模块 | 凭证 | 获取方式 |
|---|---|---|
用户接口(/user、/proxy、/oh.php、/esirun.php、/traffic.php、/rwmc.php、/bind) | CSRF Token | POST /user type=login 返回的 token |
服务商接口(/dashboard/*) | 服务商 Token | 用户信息中的 token(/user type=info),经 /dashboard/login 验证 |
简单启动(/esirun.php type=config) | 隧道级 CSRF | type=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=forcedown | new 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 | 无内容(如房间暂无聊天) |
401 | HTTP 层未授权:前端清除 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 |