Skip to content

用户资料与账户 ​

本章覆盖用户侧「个人资料与账户」全部 22 个接口,前缀均为 /api/users,全部要求 JWT 鉴权(Authorization: Bearer <token>,校验链与失败形态见鉴权方式)。统一响应包络、错误码、字节单位等全局约定见通用约定。

鉴权链路要点:每个请求依次校验 Bearer 令牌签名 → Redis 会话有效性 → 用户存在与状态(active)→ authVersion 匹配。修改密码会使 authVersion 递增,该账户所有旧 JWT 立即失效(下一次请求即返回 401,需重新登录)。被封禁账户返回 403 并附带 data.isBanned=true 与封禁原因。

各接口没有更细粒度的专用限流中间件,全站 WAF 防护照常生效。缓存策略按路由分两级:no-store, no-cache, must-revalidate, private(下文简称 no-store)与 public, max-age=60, s-maxage=60(下文简称 short-cache 60s)。

方法路径说明缓存策略
GET/api/users/profile当前用户资料no-store
PUT/api/users/profile更新用户名/QQ/头像 URLno-store
PUT/api/users/profile/avatar上传头像文件no-store
PUT/api/users/profile/password修改登录密码no-store
POST/api/users/profile/wallpaper上传控制台壁纸no-store
PUT/api/users/profile/preferences更新偏好设置(浅合并)no-store
POST/api/users/profile/speed-boost/check极速模式资格检查no-store
POST/api/users/reset-access-key轮换访问密钥并下线全部隧道no-store
POST/api/users/checkin每日签到领奖励no-store
POST/api/users/force-unregister-all强制下线本人全部隧道no-store
POST/api/users/redeem兑换福利码发放权益no-store
GET/api/users/redeem/history本人兑换记录no-store
GET/api/users/audit-logs查询本人操作审计日志no-store
GET/api/users/audit-logs/export导出审计日志(CSV/JSON)no-store
GET/api/users/waf-logs查询本人隧道的防护拦截日志no-store
GET/api/users/waf-logs/stats防护拦截日志统计汇总no-store
GET/api/users/traffic-history用户维度流量历史no-store
GET/api/users/traffic-history/:period同上(路径参数被忽略的别名路由)no-store
GET/api/users/nodes可见节点列表short-cache 60s
GET/api/users/nodes/:id单节点详情short-cache 60s
GET/api/users/nodes/:id/traffic-history节点维度流量历史no-store
GET/api/users/announcements/:id已发布公告详情short-cache 60s

个人资料 ​

GET /api/users/profile ​

获取当前登录用户的完整资料,含用户组、配额、流量余额与偏好设置。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

响应字段 ​

字段类型说明
idnumber用户 ID
usernamestring用户名
emailstring注册邮箱
rolestring角色:user / admin / superadmin
statusstring账户状态:active / banned / inactive
groupIdnumber所属用户组 ID;0 表示未分组
groupobject用户组对象,恒返回;未分组时为零值对象(见下表)
accessKeystringFRP 客户端访问密钥,32 位十六进制字符串;历史空密钥账户首次调用时自动补发并落库
balancenumber账户余额(积分),浮点数
trafficnumber恒为 0(遗留占位字段,库中无此列)
usedTrafficnumber恒为 0(遗留占位字段,实际用量见 remainingTrafficBytes 口径)
remainingTrafficBytesnumber剩余流量,单位字节(float64)
realNamestring实名姓名;为空时该键省略(omitempty)
isVerifiedboolean是否已通过实名认证
avatarstring头像 URL;默认为占位图地址
lastLoginDatestring 或缺省最近登录时间(RFC 3339);从未登录时省略(omitempty)
lastLoginIpstring最近登录 IP
maxProxiesnumber有效隧道数量上限(用户与用户组取大者);-1 表示不限制
proxyCountnumber当前隧道数量(实时统计 proxies 表,非冗余列)
preferencesobject偏好设置键值对,至少为 {}
remarkstring恒为空串(handler 固定写死,不回传管理员备注)
createdAtstring注册时间(RFC 3339)
lastSignInDatestring 或 null最近签到时间;从未签到时为 null
qqstring恒为空串(handler 固定写死)
bandwidthInKbpsnumber有效入站带宽上限,单位 kbps;仅取自用户组,未分组时为 0
bandwidthOutKbpsnumber有效出站带宽上限,单位 kbps;仅取自用户组,未分组时为 0
realNameVerificationStatusstring恒为空串(handler 固定写死)
twoFactorEnabledboolean是否已开启两步验证

group 对象字段(用户组模型原样序列化):

字段类型说明
idnumber用户组 ID;未分组时为 0
namestring组名
descriptionstring组描述
badgeColorstring徽章颜色,默认 #808080
isDefaultboolean是否默认组
maxProxiesnumber组隧道数上限
bandwidthOutKbpsnumber组出站带宽,单位 kbps
bandwidthInKbpsnumber组入站带宽,单位 kbps
addedTrafficBytesnumber组附加流量,单位字节
addedBalancenumber组附加余额
isVisibleboolean是否在组列表可见
isJoinableboolean是否可自行加入
linkedPackageIdnumber 或 null关联套餐 ID
createdAtstring创建时间
updatedAtstring更新时间

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/profile'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/profile', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/profile',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/profile", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 1024,
    "username": "alice",
    "email": "alice@example.com",
    "role": "user",
    "status": "active",
    "groupId": 2,
    "group": {
      "id": 2,
      "name": "会员组",
      "description": "付费会员",
      "badgeColor": "#f0ad4e",
      "isDefault": false,
      "maxProxies": 10,
      "bandwidthOutKbps": 20480,
      "bandwidthInKbps": 20480,
      "addedTrafficBytes": 10737418240,
      "addedBalance": 0,
      "isVisible": true,
      "isJoinable": false,
      "linkedPackageId": 3,
      "createdAt": "2026-01-10T09:00:00+08:00",
      "updatedAt": "2026-08-01T12:00:00+08:00"
    },
    "accessKey": "5f8a9c0d1e2b3a4f6c7d8e9a0b1c2d3e",
    "balance": 320,
    "traffic": 0,
    "usedTraffic": 0,
    "remainingTrafficBytes": 53687091200,
    "isVerified": true,
    "avatar": "/uploads/avatars/1024-1726723200000.png",
    "lastLoginIp": "203.0.113.7",
    "maxProxies": 10,
    "proxyCount": 4,
    "preferences": { "theme": "dark", "sidebarCollapsed": true },
    "remark": "",
    "createdAt": "2026-03-15T20:11:32+08:00",
    "lastSignInDate": "2026-09-19T08:02:11+08:00",
    "qq": "",
    "bandwidthInKbps": 20480,
    "bandwidthOutKbps": 20480,
    "realNameVerificationStatus": "",
    "twoFactorEnabled": false
  }
}

错误场景 ​

场景HTTP说明
上下文中无用户401返回「未认证」(正常携带有效令牌不会出现)
用户记录不存在404返回「用户不存在」
令牌/会话/版本失效401见章首鉴权链路说明

注意事项 ​

  • traffic / usedTraffic 为遗留占位键,恒为 0;真实剩余流量以 remainingTrafficBytes 为准。
  • maxProxies 是「用户与用户组取大者」的有效值,可能与用户组标称值不同;任一侧为 -1 时结果为 -1(不限制)。
  • bandwidthInKbps / bandwidthOutKbps 完全来自用户组,未分组用户恒为 0,不代表节点实际限速。

PUT /api/users/profile ​

更新当前用户的基本资料,支持修改用户名、QQ 号与头像 URL。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求体 ​

字段类型必填说明
usernamestring否新用户名;空串或与当前相同则跳过;修改时做全局唯一性校验
qqstring否QQ 号;仅非空时更新(传空串不会清空已有值)
avatarstring否新头像 URL;仅非空且以 http 开头时生效

请求示例 ​

bash
curl -X PUT -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice2","qq":"12345678"}' \
  'https://api.hyperfrp.com/api/users/profile'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/profile', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <token>',
  },
  body: JSON.stringify({"username":"alice2","qq":"12345678"})
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.put(
    'https://api.hyperfrp.com/api/users/profile',
    headers={'Authorization': 'Bearer <token>'},
    json={
        'username': 'alice2',
        'qq': '12345678'
    },
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	var payload bytes.Buffer
	json.NewEncoder(&payload).Encode(map[string]any{
		"username": "alice2",
		"qq": "12345678",
	})

	req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/users/profile", &payload)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
idnumber用户 ID
usernamestring更新后的用户名
emailstring注册邮箱(不可经本接口修改)
avatarstring更新后的头像 URL

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 1024,
    "username": "alice2",
    "email": "alice@example.com",
    "avatar": "/uploads/avatars/1024-1726723200000.png"
  }
}

错误场景 ​

场景HTTP说明
请求体非法 JSON400返回「无效的请求数据」
用户名已被占用400返回「用户名已被使用」
用户记录不存在404返回「用户不存在」

注意事项 ​

  • 用户名修改写入审计日志(actionType 为 update_profile,details 含 changedUsername)。
  • avatar 传本站上传路径(非 http 开头)会被忽略;把原头像从本站上传文件换成 http URL 时,旧头像文件会从磁盘删除。
  • qq 无法通过本接口清空(空串跳过)。

PUT /api/users/profile/avatar ​

上传头像文件,替换旧头像并落库新路径。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求体(multipart/form-data) ​

字段类型必填说明
avatarfile是图片文件;扩展名限 jpg/jpeg/png/gif/webp,Part 的 Content-Type 须与扩展名匹配,且做文件头魔数校验;≤ 2MiB

请求示例 ​

bash
curl -X PUT -H 'Authorization: Bearer <token>' \
  -F 'avatar=@/path/to/avatar.png;type=image/png' \
  'https://api.hyperfrp.com/api/users/profile/avatar'
javascript
const form = new FormData();
form.append('avatar', fileInput.files[0]); // 待上传的文件:/path/to/avatar.png

const res = await fetch('https://api.hyperfrp.com/api/users/profile/avatar', {
  method: 'PUT',
  headers: { 'Authorization': 'Bearer <token>' }, // 不手动设 Content-Type,由浏览器自动写入 boundary
  body: form
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.put(
    'https://api.hyperfrp.com/api/users/profile/avatar',
    headers={'Authorization': 'Bearer <token>'},
    files={'avatar': open('/path/to/avatar.png', 'rb')},
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

func main() {
	var buf bytes.Buffer
	writer := multipart.NewWriter(&buf)
	file, _ := os.Open('/path/to/avatar.png')
	defer file.Close()
	part, _ := writer.CreateFormFile('avatar', filepath.Base('/path/to/avatar.png'))
	io.Copy(part, file)
	writer.Close()

	req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/users/profile/avatar", &buf)
	req.Header.Set("Content-Type", writer.FormDataContentType())
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
messagestring固定为「头像上传成功」
avatarstring新头像访问路径,形如 /uploads/avatars/<用户ID>-<毫秒时间戳><扩展名>

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "message": "头像上传成功",
    "avatar": "/uploads/avatars/1024-1726723200000.png"
  }
}

错误场景 ​

场景HTTP说明
缺少 avatar 文件400返回「未检测到头像文件」
扩展名/Content-Type/魔数不匹配400返回「只允许上传有效的图片文件」
文件超过 2MiB413返回「文件大小不能超过2MiB」
请求体超过服务端动态上限413返回「请求体不能超过 xxMiB」
读取请求体超时408返回「读取上传请求超时」
创建目录/保存文件失败500返回「创建上传目录失败」/「保存文件失败」
用户记录不存在404返回「用户不存在」,已落盘文件会删除

注意事项 ​

  • 上传成功后删除旧的本站上传头像(http 外链头像不删文件);旧 URL 立即失效。

PUT /api/users/profile/password ​

修改登录密码;成功后账户 authVersion 递增,该用户所有已签发的 JWT 立即失效,全部设备需重新登录。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求体 ​

字段类型必填说明
currentPasswordstring见说明当前密码;与 oldPassword 二选一,同时提供时优先 currentPassword
oldPasswordstring见说明当前密码的兼容字段名;currentPassword 为空时回退使用
newPasswordstring见说明新密码;与 password 二选一,同时提供时优先 newPassword
passwordstring见说明新密码的兼容字段名;newPassword 为空时回退使用

两组字段解析后均会去除首尾空白;任一组解析结果为空即报错。

请求示例 ​

bash
curl -X PUT -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"currentPassword":"OldPass123","newPassword":"NewPass456"}' \
  'https://api.hyperfrp.com/api/users/profile/password'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/profile/password', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <token>',
  },
  body: JSON.stringify({"currentPassword":"OldPass123","newPassword":"NewPass456"})
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.put(
    'https://api.hyperfrp.com/api/users/profile/password',
    headers={'Authorization': 'Bearer <token>'},
    json={
        'currentPassword': 'OldPass123',
        'newPassword': 'NewPass456'
    },
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	var payload bytes.Buffer
	json.NewEncoder(&payload).Encode(map[string]any{
		"currentPassword": "OldPass123",
		"newPassword": "NewPass456",
	})

	req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/users/profile/password", &payload)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
messagestring固定为「密码更新成功」

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "message": "密码更新成功"
  }
}

错误场景 ​

场景HTTP说明
请求体非法或两组字段解析后均为空400返回「请提供当前密码和新密码」
当前密码错误401返回「当前密码不正确」
用户记录不存在404返回「用户不存在」
落库失败500返回「密码更新失败」

注意事项 ​

  • 失效语义是「版本失效」而非「删除会话」:Redis 会话记录不主动删除,但鉴权中间件逐请求比对 JWT 载荷中的 authVersion 与用户当前值,不一致即拒绝(401「账户状态或认证版本已变更,请重新登录」),等效于全部会话立即失效。
  • 本操作写入审计日志(actionType 为 update_password)。

POST /api/users/profile/wallpaper ​

上传控制台壁纸,替换该用户此前上传的全部旧壁纸,返回新壁纸 URL。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求体(multipart/form-data) ​

字段类型必填说明
wallpaperfile是图片文件;扩展名限 jpg/jpeg/png/gif/webp,Content-Type 须匹配,做魔数校验;≤ 10MiB

请求示例 ​

bash
curl -X POST -H 'Authorization: Bearer <token>' \
  -F 'wallpaper=@/path/to/wallpaper.jpg;type=image/jpeg' \
  'https://api.hyperfrp.com/api/users/profile/wallpaper'
javascript
const form = new FormData();
form.append('wallpaper', fileInput.files[0]); // 待上传的文件:/path/to/wallpaper.jpg

const res = await fetch('https://api.hyperfrp.com/api/users/profile/wallpaper', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <token>' }, // 不手动设 Content-Type,由浏览器自动写入 boundary
  body: form
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.post(
    'https://api.hyperfrp.com/api/users/profile/wallpaper',
    headers={'Authorization': 'Bearer <token>'},
    files={'wallpaper': open('/path/to/wallpaper.jpg', 'rb')},
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

func main() {
	var buf bytes.Buffer
	writer := multipart.NewWriter(&buf)
	file, _ := os.Open('/path/to/wallpaper.jpg')
	defer file.Close()
	part, _ := writer.CreateFormFile('wallpaper', filepath.Base('/path/to/wallpaper.jpg'))
	io.Copy(part, file)
	writer.Close()

	req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/users/profile/wallpaper", &buf)
	req.Header.Set("Content-Type", writer.FormDataContentType())
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
messagestring固定为「壁纸上传成功」
urlstring新壁纸访问路径,形如 /uploads/wallpapers/wp-<用户ID>-<毫秒时间戳><扩展名>

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "message": "壁纸上传成功",
    "url": "/uploads/wallpapers/wp-1024-1726723200000.jpg"
  }
}

错误场景 ​

场景HTTP说明
缺少 wallpaper 文件400返回「未检测到壁纸文件」
扩展名/Content-Type/魔数不匹配400返回「只允许上传有效的图片文件」
文件超过 10MiB413返回「文件大小不能超过10MiB」
请求体超过服务端动态上限413返回「请求体不能超过 xxMiB」
读取请求体超时408返回「读取上传请求超时」
创建目录/保存文件失败500返回「创建上传目录失败」/「保存文件失败」

注意事项 ​

  • 上传成功时先删除该用户所有旧壁纸文件(wp-<用户ID>- 前缀),一个用户只保留最新一张。
  • 壁纸 URL 不写入用户资料,接口仅返回 URL,由前端自行保存使用。

PUT /api/users/profile/preferences ​

更新偏好设置。合并语义:与既有偏好做顶层键浅合并——请求体中出现的键逐个覆盖,未出现的键保留原值;不做嵌套对象深合并,顶层键的整个值(含嵌套结构)整体替换。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求体 ​

字段类型必填说明
preferencesobject是任意键值对;显式传 null 或缺省视为非法

请求示例 ​

bash
curl -X PUT -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"preferences":{"theme":"dark","language":"zh-CN"}}' \
  'https://api.hyperfrp.com/api/users/profile/preferences'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/profile/preferences', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <token>',
  },
  body: JSON.stringify({"preferences":{"theme":"dark","language":"zh-CN"}})
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.put(
    'https://api.hyperfrp.com/api/users/profile/preferences',
    headers={'Authorization': 'Bearer <token>'},
    json={
        'preferences': {
            'theme': 'dark',
            'language': 'zh-CN'
        }
    },
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	var payload bytes.Buffer
	json.NewEncoder(&payload).Encode(map[string]any{
		"preferences": map[string]any{
			"theme": "dark",
			"language": "zh-CN",
		},
	})

	req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/users/profile/preferences", &payload)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
messagestring固定为「偏好设置已更新」
preferencesobject合并后的完整偏好设置

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "message": "偏好设置已更新",
    "preferences": {
      "theme": "dark",
      "language": "zh-CN",
      "sidebarCollapsed": true
    }
  }
}

错误场景 ​

场景HTTP说明
请求体非法 JSON400返回「无效的请求数据」
preferences 缺失或为 null400返回「偏好设置数据不能为空」
用户记录不存在404返回「用户不存在」
落库失败500返回「保存偏好设置失败」

POST /api/users/profile/speed-boost/check ​

检查当前用户全部隧道所涉节点是否满足「极速模式」条件,供开启极速模式前预检。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

判定条件(对用户隧道关联的每个去重节点):节点带宽 bandwidthLimitKbps > 102400(即 > 100 Mbps)、CPU 负载 cpuUsage < 50(百分比)、节点状态为 online 或 api_only。任一不满足即列入 ineligibleNodes 并给出原因。

响应字段 ​

字段类型说明
eligibleboolean全部节点是否符合条件
messagestring结论描述;全部符合为「所有节点都满足极速模式条件」,否则「有 N 个节点不满足极速模式条件」
totalNodesnumber去重后涉及的节点总数
eligibleNodesnumber符合条件的节点数(计数,非数组)
ineligibleNodesarray 或 null不符合条件的节点明细;全部符合时为 null,用户没有隧道时为 []

ineligibleNodes 元素字段:

字段类型说明
nodeIdnumber节点 ID
nodeNamestring节点名称
bandwidthnumber节点带宽上限,单位 kbps
loadnumber节点 CPU 负载,百分比数值
statusstring节点状态
reasonsstring[]不达标原因列表(带宽不足 / 负载过高 / 节点状态异常)

请求示例 ​

bash
curl -X POST -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/profile/speed-boost/check'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/profile/speed-boost/check', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.post(
    'https://api.hyperfrp.com/api/users/profile/speed-boost/check',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/users/profile/speed-boost/check", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "eligible": false,
    "message": "有 1 个节点不满足极速模式条件",
    "totalNodes": 2,
    "eligibleNodes": 1,
    "ineligibleNodes": [
      {
        "nodeId": 7,
        "nodeName": "华东-1",
        "bandwidth": 102400,
        "load": 63.5,
        "status": "online",
        "reasons": ["带宽不足 (102400 Kbps <= 100Mbps)", "负载过高 (63.5% >= 50%)"]
      }
    ]
  }
}

错误场景 ​

场景HTTP说明
隧道查询失败500返回「查询隧道失败」

注意事项 ​

  • 用户当前没有隧道时返回 eligible: true、totalNodes: 0、eligibleNodes: 0、ineligibleNodes: []。
  • totalNodes / eligibleNodes 是计数;不合条件明细只出现在 ineligibleNodes 中。

账户操作 ​

POST /api/users/reset-access-key ​

轮换 FRP 客户端访问密钥,并强制下线该用户全部隧道(含非运行中,用于清理历史不一致状态)。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

处理语义:在单事务内生成新密钥(32 位十六进制,唯一性校验)并落库,同时把该用户全部隧道原子递增持久强制下线代次、状态置为 stopped;随后用旧密钥向 Redis 推送强制下线信号(键 force-offline:<旧accessKey>.<隧道名>,TTL 90 秒)作为低延迟通知——信号失败不阻断轮换,持久代次会在节点下次状态检查时兜底关闭实例。

响应字段 ​

字段类型说明
messagestring按真实推送结果拼接的提示,如「访问密钥已成功重置,该用户原有隧道已被强制下线,请用新密钥重新配置客户端」
accessKeystring新访问密钥,32 位十六进制字符串
proxyCountnumber该用户隧道总数(含非运行中)
runningCountnumber轮换时处于 running 状态的隧道数
signaledCountnumber成功写入 Redis 强制下线信号的隧道数
forceOfflineFailedboolean即时信号推送是否失败(Redis 未初始化或写入失败);true 时由持久代次兜底

请求示例 ​

bash
curl -X POST -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/reset-access-key'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/reset-access-key', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.post(
    'https://api.hyperfrp.com/api/users/reset-access-key',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/users/reset-access-key", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "message": "访问密钥已成功重置,该用户原有隧道已被强制下线,请用新密钥重新配置客户端",
    "accessKey": "3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b",
    "proxyCount": 4,
    "runningCount": 2,
    "signaledCount": 4,
    "forceOfflineFailed": false
  }
}

错误场景 ​

场景HTTP说明
用户记录不存在404返回「用户不存在」
密钥生成重试耗尽或落库失败500返回「重置访问密钥失败」

注意事项 ​

  • 强制下线信号以旧密钥构造:运行中的客户端仍持旧密钥,用新密钥构造的键永远匹配不上。
  • 原访问密钥为空的历史账户跳过信号推送,不视为失败(signaledCount 为 0,forceOfflineFailed 为 false)。
  • 轮换成功后必须用新密钥重新配置全部 FRP 客户端,否则无法重连。
  • 本操作写入审计日志(actionType 为 reset_access_key,details 含 proxyCount / runningCount)。

POST /api/users/checkin ​

每日签到,随机发放积分与流量奖励;同一自然日(服务器本地时区)只能签到一次。

鉴权:JWT Bearer 或访问密钥(X-Access-Key 头,二选一,见下) · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求体 ​

字段类型必填说明
captchaTicketstring否预留的验证码票据字段(结构体已定义);当前 handler 未读取、未校验,可省略

访问密钥鉴权(可选) ​

本接口是全站唯一支持用访问密钥替代 JWT 的接口,供脚本/定时任务免登录自动签到:

bash
curl -X POST -H 'X-Access-Key: <访问密钥>' \
  'https://api.hyperfrp.com/api/users/checkin'
  • 访问密钥即「安全设置 → 密码与访问密钥」展示的 32 位小写 hex 字符串,与 frpc 配置内嵌凭证同源(users.access_key);只允许走请求头,不接受 URL Query / 请求体传递;
  • 请求同时携带 Authorization: Bearer 时一律按 JWT 校验,失败不回退访问密钥——避免会话过期被静默换道掩盖;
  • 无效或格式非法的密钥统一 401「访问密钥无效」(不区分密钥不存在与格式非法);封禁账户 403(含 isBanned);非 active 账户 401「账户状态异常,无法使用访问密钥」;
  • 重置访问密钥后旧密钥立即失效——签到脚本与 frpc 配置同时失效,需同步更新;
  • 该替代通道仅对签到开放:/api/users/* 其余接口仍只认 JWT,访问密钥不因此获得改密码、关 2FA 等会话权限。

请求示例 ​

bash
curl -X POST -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  'https://api.hyperfrp.com/api/users/checkin'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/checkin', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <token>',
  },
  body: JSON.stringify({})
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.post(
    'https://api.hyperfrp.com/api/users/checkin',
    headers={'Authorization': 'Bearer <token>'},
    json={},
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	var payload bytes.Buffer
	json.NewEncoder(&payload).Encode(map[string]any{})

	req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/users/checkin", &payload)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
messagestring如「签到成功!您获得了 128 积分和 3 GB 流量。」
rewardsobject奖励明细,见下表

rewards 字段:

字段类型说明
pointsnumber积分奖励,随机 50~200(含两端),直接累加进 balance
trafficGBnumber流量奖励(GB),随机 1~5(含两端)
trafficBytesnumber流量奖励的字节数,即 trafficGB × 1073741824,累加进 remainingTrafficBytes

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "message": "签到成功!您获得了 128 积分和 3 GB 流量。",
    "rewards": {
      "points": 128,
      "trafficGB": 3,
      "trafficBytes": 3221225472
    }
  }
}

错误场景 ​

场景HTTP说明
未携带任何凭证401返回「未提供认证令牌或访问密钥」;JWT 与访问密钥二选一
访问密钥无效或格式非法401仅使用 X-Access-Key 鉴权时;统一返回「访问密钥无效」,不区分密钥不存在与格式非法
访问密钥鉴权但账户非 active401返回「账户状态异常,无法使用访问密钥」
访问密钥鉴权但账户被封禁403响应体 data 含 isBanned: true 与 ban_reason,与 JWT 封禁响应同构
JWT 鉴权但账户被封禁403响应体 data 含 isBanned: true 与 ban_reason
当日已签到400返回「您今天已经签到过了」;判定依据为 lastSignInDate 是否落在今天(服务器本地时区)
事务执行失败500返回「签到失败,请稍后重试」

注意事项 ​

  • 防重复依赖数据库事务 + SELECT ... FOR UPDATE 行锁,并发重复签到只有一个请求成功,其余落入「当日已签到」分支;本路由无更细粒度的专用限流中间件。
  • 随机数使用 crypto/rand,奖励在请求处理前预生成,与落库同事务生效。
  • 本操作写入审计日志(actionType 为 checkin,details 含 points / trafficGB / authMethod,后者为 jwt 或 access_key,便于管理员区分签到来源)。

POST /api/users/force-unregister-all ​

强制下线本人全部隧道:数据库层原子递增该用户全部隧道的持久强制下线代次并置为 stopped,再经 Redis 推送即时信号。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

响应字段 ​

字段类型说明
successboolean恒为 true(到达此响应即已受理)
messagestring如「操作完成。已向 4 个隧道发送强制下线指令,其中 2 个记录为在线。」
forceOfflineFailedbooleanRedis 即时通知是否失败;true 时追加提示「即时通知失败,已由持久下线记录兜底,将在节点下次状态检查时生效」
summaryobject汇总,见下表

summary 字段:

字段类型说明
successnumber成功写入即时信号的隧道数
failednumber恒为 0(信号失败归入 forceOfflineFailed 兜底语义,不计失败)

请求示例 ​

bash
curl -X POST -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/force-unregister-all'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/force-unregister-all', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.post(
    'https://api.hyperfrp.com/api/users/force-unregister-all',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/users/force-unregister-all", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "success": true,
    "message": "操作完成。已向 4 个隧道发送强制下线指令,其中 2 个记录为在线。",
    "forceOfflineFailed": false,
    "summary": {
      "success": 4,
      "failed": 0
    }
  }
}

错误场景 ​

场景HTTP说明
隧道查询失败500返回「查询隧道失败」
递增持久下线代次失败500返回「强制下线失败,请稍后重试」

注意事项 ​

  • 没有任何隧道时返回 success: true、message「当前账户没有可下线的隧道。」、summary: {"success": 0, "failed": 0}。
  • 持久代次先行:即使 Redis 不可用(forceOfflineFailed: true),FRPS 也会在下次状态检查时依据代次变化关闭运行实例。
  • 本操作写入审计日志(actionType 为 force_unregister_all_proxies)。

兑换码 ​

兑换码(福利码)由管理员生成并线下发放,一码一类型:类型决定唯一权益——切换到某个用户组、加积分或加流量。同一码可被多名用户各兑换一次,但同一用户对同一码仅能兑换一次。

POST /api/users/redeem ​

兑换一张兑换码并按其配置发放权益。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求体 ​

字段类型必填说明
codestring是兑换码原文。服务端先 trim 再转大写后精确匹配,大小写与首尾空格不影响结果;合法形态为 6~32 位大写字母/数字/连字符且以字母或数字开头。字段本身无 binding 约束,空值由业务校验返回「请输入兑换码」

响应字段 ​

字段类型说明
messagestring中文提示,形如「兑换成功!您获得了积分 +100。」
resultobject发放明细,见下表

result 字段:

字段类型说明
codeIdnumber兑换码 ID
codestring归一化(大写)后实际命中的兑换码
typestring权益类型:user_group / points / traffic
benefitobject权益明细,键集合随 type 变化,见下表
groupExpiresAtstring仅 user_group 类型有意义:切换后用户组的到期时间(RFC 3339);未设置有效天数或其余类型为 null

benefit 按类型:

type键说明
pointspoints本次累加进账户余额(balance)的积分数,与签到积分同源
traffictrafficBytes、trafficMb本次累加进 remainingTrafficBytes 的字节数,以及折算后的整 MB 数值
user_groupgroupId、groupName、groupDays目标用户组 ID 与名称;groupDays 仅在配置了有效天数时出现,缺省表示切换后不过期

请求示例 ​

bash
curl -X POST -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"code":"HZ2026-AB12CD"}' \
  'https://api.hyperfrp.com/api/users/redeem'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/redeem', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <token>',
  },
  body: JSON.stringify({"code":"HZ2026-AB12CD"})
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.post(
    'https://api.hyperfrp.com/api/users/redeem',
    headers={'Authorization': 'Bearer <token>'},
    json={
        'code': 'HZ2026-AB12CD'
    },
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	var payload bytes.Buffer
	json.NewEncoder(&payload).Encode(map[string]any{
		"code": "HZ2026-AB12CD",
	})

	req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/users/redeem", &payload)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "message": "兑换成功!您获得了流量 +2048 MB。",
    "result": {
      "codeId": 17,
      "code": "HZ2026-AB12CD",
      "type": "traffic",
      "benefit": {
        "trafficBytes": 2147483648,
        "trafficMb": 2048
      },
      "groupExpiresAt": null
    }
  }
}

错误场景 ​

业务判定全部在服务端事务内完成,按下表自上而下的顺序短路返回,首个不满足项即为响应文案:

场景HTTP说明
请求体不是合法 JSON400返回「无效的请求数据」
兑换码为空400返回「请输入兑换码」
兑换码格式不合法400返回「兑换码格式不正确」;按归一化后的大写值校验 ^[A-Z0-9][A-Z0-9-]{5,31}$
兑换码不存在400返回「兑换码不存在或无效」;不区分码不存在与类型字段异常,不泄露码是否存在于其他状态
已停用400返回「该兑换码已停用」
已作废400返回「该兑换码已作废」
未到生效时间400返回「兑换活动尚未开始」;validFrom 为空表示创建即生效
已过期400返回「该兑换码已过期」;expiresAt 为空表示永久有效
总次数已用完400返回「该兑换码已被兑完」;maxUses 为 0 表示不限总次数
账户实名状态不符400限定「仅已实名」时返回「该兑换码仅限已完成实名认证的用户兑换」;限定「仅未实名」时返回「该兑换码仅限未完成实名认证的用户兑换」。判定权威取账户 isVerified 单布尔,实名认证的审核过程态不参与判定
本人已兑换过该码400返回「您已兑换过该兑换码」
码配置的用户组缺失400返回「兑换码配置的用户组不存在,请联系管理员」
未知错误500返回「兑换失败,请稍后重试」
未提供有效令牌401统一未认证响应

注意事项 ​

  • 只认 JWT,不接受访问密钥:X-Access-Key 是 FRPS 客户端凭证,全站唯一支持它的用户侧路由是 POST /api/users/checkin;兑换码发放权益属敏感写操作,不接入该双模通道。
  • 并发安全:整个兑换走单个事务,锁序固定为「兑换码行 → 用户行」,used_uses 用 UPDATE ... + 1 原子递增;「每人一次」的友好提示走预查,真正的兜底是兑换记录表 (code_id, user_id) 复合唯一索引——并发双花会有一笔落入「您已兑换过该兑换码」。
  • 权益按发放当时的配置生效并快照入库,管理员事后改配置不影响已发放结果与历史记录的可解释性。
  • user_group 类型会真实切换账户用户组(影响配额等权益)并写一条用户组切换历史(changeType 为 redeem_code),管理员可在兑换码明细中追溯;配置了 groupDays 时到期时间为兑换时刻起算的 N 天,未配置则清空到期时间(不过期)。
  • 积分累加进 balance、流量累加进 remainingTrafficBytes,与签到奖励同一套账户字段,可用 GET /api/users/profile 复核。
  • 本操作写入审计日志(actionType 为 redeem,details 含 codeId / code / type / benefit)。
  • 失败日志中的兑换码按首尾 4 位保留、中段打码,不整码回显。

GET /api/users/redeem/history ​

分页查询本人的兑换记录,按兑换时间倒序。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

查询参数 ​

参数类型必填说明
pagenumber否页码,默认 1;小于 1 按 1 处理
pageSizenumber否每页条数,默认 20;解析失败、小于 1 或大于 200 时回退为 20

响应字段 ​

字段类型说明
listobject[]兑换记录,按 createdAt 倒序(同秒按记录 ID 倒序)
totalnumber本人兑换记录总数
pagenumber回显实际生效的页码
pageSizenumber回显实际生效的每页条数

list 元素:

字段类型说明
idnumber兑换记录 ID
codestring兑换时命中的兑换码(大写形态)
typestring权益类型:user_group / points / traffic
benefitobject发放当时的权益快照,键集合同 POST /api/users/redeem 的 benefit
createdAtstring兑换时间,RFC 3339

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/redeem/history?page=1&pageSize=20'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/redeem/history?page=1&pageSize=20', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/redeem/history?page=1&pageSize=20',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/redeem/history?page=1&pageSize=20", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 88,
        "code": "HZ2026-AB12CD",
        "type": "traffic",
        "benefit": {
          "trafficBytes": 2147483648,
          "trafficMb": 2048
        },
        "createdAt": "2026-09-24T10:12:33+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

错误场景 ​

场景HTTP说明
未提供有效令牌401统一未认证响应
记录查询失败500返回「获取兑换历史失败」

注意事项 ​

  • 只返回当前用户自己的记录,查询范围由令牌推断,没有任何用户维度的过滤参数——传入的额外参数会被忽略。
  • 元素不含 username(该字段仅管理端明细接口填充,用户视角为空即 omitempty 省略)。
  • 从未兑换过的用户返回空数组 list: []、total: 0,不是 404。
  • 兑换记录是终态账:兑换码被管理员作废(voided)后记录仍在此列出,作废是终态而非软删,正是为了保留可追溯性。

审计日志 ​

用户操作审计日志来自按用户分文件的 JSONL 日志(user_<用户ID>.log),查询时按时间倒序分页返回。

GET /api/users/audit-logs ​

分页查询本人操作审计日志,支持按操作类型、状态、IP 与时间范围过滤。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

查询参数 ​

参数类型必填说明
pagenumber否页码,默认 1;小于 1 时按 1 处理
limitnumber否每页条数,默认 15;解析失败、小于 1 或大于 100 时回退为 20
pageSizenumber否每页条数的别名;仅在未提供 limit 时生效,回退规则同上
actionTypestring否操作类型过滤,不区分大小写的子串匹配,如 checkin、update_password
statusstring否状态精确匹配:success / failure
ipAddressstring否IP 子串匹配
startDatestring否起始时间,RFC 3339 格式;解析失败时忽略该条件
endDatestring否结束时间,RFC 3339 格式;解析失败时忽略该条件

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/audit-logs?page=1&limit=20&actionType=checkin&status=success'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/audit-logs?page=1&limit=20&actionType=checkin&status=success', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/audit-logs?page=1&limit=20&actionType=checkin&status=success',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/audit-logs?page=1&limit=20&actionType=checkin&status=success", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
logsarray当前页日志条目,字段见下表
totalLogsnumber满足过滤条件的日志总数
pagenumber当前页码(回填后的实际值)
pageSizenumber当前每页条数(回填后的实际值)

logs 元素字段:

字段类型说明
idnumber恒为 0(文件日志条目无自增 ID)
userIdnumber用户 ID
usernamestring操作时的用户名
timestampstring操作时间(RFC 3339)
ipAddressstring操作来源 IP
locationstringIP 归属地(ip2region 查询;库未加载时为空串)
ipLocationstring同 location(冗余字段)
actionTypestring操作类型,如 update_profile / update_avatar / upload_wallpaper / update_preferences / checkin / reset_access_key / force_unregister_all_proxies / update_password
actionTypeZhstring恒为空串(本接口不回填中文类型)
resourceTypeZhstring恒为空串
targetResourcestring恒为空串
targetIdnumber恒为 0
detailsstring操作详情的 JSON 字符串(如 "{\"points\": 128}"),无详情时为 "{}"
statusstringsuccess / failure;条目缺失状态时按 success 回填
statusDetailstring恒为空串
userAgentstring操作时的 User-Agent
actionDetailZhstring详情的中文拼接串(形如 points: 128, trafficGB: 3),无详情时为空串

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "logs": [
      {
        "id": 0,
        "userId": 1024,
        "username": "alice",
        "timestamp": "2026-09-19T08:02:11.532+08:00",
        "ipAddress": "203.0.113.7",
        "location": "中国 上海",
        "ipLocation": "中国 上海",
        "actionType": "checkin",
        "actionTypeZh": "",
        "resourceTypeZh": "",
        "targetResource": "",
        "targetId": 0,
        "details": "{\"points\": 128, \"trafficGB\": 3}",
        "status": "success",
        "statusDetail": "",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "actionDetailZh": "points: 128, trafficGB: 3"
      }
    ],
    "totalLogs": 42,
    "page": 1,
    "pageSize": 20
  }
}

错误场景 ​

场景HTTP说明
日志文件读取失败500返回「查询日志失败」

注意事项 ​

  • 日志文件不存在时视为空集,返回空 logs 与 totalLogs: 0,不报错。
  • details 是字符串而非对象,前端需二次 JSON.parse。

GET /api/users/audit-logs/export ​

导出本人审计日志文件。该端点不走统一响应包络,直接以附件形式返回文件流。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

查询参数 ​

参数类型必填说明
actionTypestring否同列表接口(子串匹配,不区分大小写)
statusstring否success / failure 精确匹配
ipAddressstring否IP 子串匹配
startDatestring否起始时间,RFC 3339
endDatestring否结束时间,RFC 3339
formatstring否json 导出 JSON;缺省或其它值导出 CSV

导出条数固定为按过滤条件匹配的前 1000 条(时间倒序),无分页参数。

请求示例 ​

bash
# 默认导出 CSV
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/audit-logs/export?status=success' \
  -o audit-logs.csv

# 导出 JSON
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/audit-logs/export?format=json' \
  -o audit-logs.json
javascript
// 导出 JSON:GET /api/users/audit-logs/export?format=json
const res = await fetch('https://api.hyperfrp.com/api/users/audit-logs/export?status=success', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const blob = await res.blob(); // 浏览器可用 URL.createObjectURL(blob) 触发保存
python
import requests

# 导出 JSON:GET /api/users/audit-logs/export?format=json
res = requests.get(
    'https://api.hyperfrp.com/api/users/audit-logs/export?status=success',
    headers={'Authorization': 'Bearer <token>'},
)
with open('audit-logs.csv', 'wb') as f:
    f.write(res.content)
go
// 导出 JSON:GET /api/users/audit-logs/export?format=json
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/audit-logs/export?status=success", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := os.Create('audit-logs.csv')
	defer out.Close()
	io.Copy(out, res.Body)
	fmt.Println("saved audit-logs.csv")
}

响应说明(文件下载) ​

CSV 格式(默认):

  • 响应头:Content-Type: text/csv; charset=utf-8、Content-Disposition: attachment; filename=audit-logs.csv
  • 正文以 UTF-8 BOM(EF BB BF)开头,表头为 时间,操作类型,操作详情,IP地址,状态;时间格式 2006-01-02 15:04:05,操作详情列含逗号/引号/换行时按 CSV 规则转义加引号

JSON 格式(format=json):

  • 响应头:Content-Type: application/json; charset=utf-8、Content-Disposition: attachment; filename=audit-logs.json
  • 正文为 AuditLog 对象的裸数组(元素字段与列表接口 logs 元素一致),无 code/message/data 包络

两种格式均附带导出上限响应头:

响应头说明
X-Audit-Logs-Limit导出条数上限,固定 1000
X-Audit-Logs-Truncatedtrue 表示匹配总数超过 1000 条已被截断;false 表示完整导出

错误场景 ​

场景HTTP说明
日志文件读取失败500返回「导出日志失败」(此时仍为统一包络 JSON)

隧道防护日志 ​

节点侧防护闸(CC 限流 / 连接层并发拒绝 / 行为检测封禁 / DPI 阻断 / 隧道级 SQL/XSS 请求防护)在拦下请求时会聚合成拦截事实上报面板,面板把它们按「节点 + 日期」落到本地 JSONL 文件(不落数据库)。本组接口让用户查看自己隧道的拦截记录。

可见性口径

返回范围由面板权威归属决定:只返回 userId 等于当前登录用户的记录。归属在日志入库时由面板补齐(按面板下发的隧道主键 + (nodeId, proxyName) 与隧道台账交叉校验),未归属记录与其他用户记录一律不返回。隧道名跨用户可重名,因此不接受按隧道名过滤——参数里只有隧道 ID(proxyIds),不存在的名字过滤不会生效,别人的隧道 ID 会被忽略。

GET /api/users/waf-logs ​

分页查询本人隧道的防护拦截日志。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

查询参数 ​

参数类型必填说明
proxyIdsstring否隧道 ID 过滤,多个用英文逗号分隔(如 7,9);仅接受属于本人的隧道 ID,不属于本人的会被忽略,全部不属于时返回空结果
startstring否开始时间,接受 RFC 3339、YYYY-MM-DD 或 Unix 秒/毫秒时间戳
endstring否结束时间,格式同上
datestring否单日查询(YYYY-MM-DD),等价于该日 00:00:00 - 23:59:59.999;与 start/end 同时出现时以 date 为准
sourcestring否拦截来源:cc_http / cc_conn / cc_behavior / dpi / http_waf(不区分大小写;http_waf 为隧道级 SQL/XSS 请求防护命中,动作恒为 http_403)
reasonstring否拦截原因:global / tunnel / ip / ip_path / behavior / max_conns / dpi / unknown / sql / xss(后两者为请求防护的命中链路)
actionstring否拦截动作:http_429 / conn_close / ip_ban / dpi_drop / http_403
ipstring否攻击方 IP 精确匹配
keywordstring否关键词,匹配隧道名 / IP / Host / 路径 / UserAgent(不区分大小写)
pagenumber否页码,默认 1;小于 1 按 1 处理
pageSizenumber否每页条数,默认 50,上限 200
orderstring否asc / desc,按拦截窗口结束时间排序,默认倒序

时间范围缺省为当天 00:00 至当前时刻;跨度上限 90 天,超出部分会被自动收窄到最近 90 天。

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/waf-logs?proxyIds=7&page=1&pageSize=20&source=cc_http'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/waf-logs?proxyIds=7&page=1&pageSize=20&source=cc_http', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/waf-logs?proxyIds=7&page=1&pageSize=20&source=cc_http',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/waf-logs?proxyIds=7&page=1&pageSize=20&source=cc_http", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
itemsarray当前页拦截记录,字段见下表
pagenumber当前页码(回填后的实际值)
pageSizenumber当前每页条数(回填后的实际值)
hasMoreboolean是否还有下一页;本组接口基于文件扫描,不提供精确总数
scanTruncatedboolean是否因扫描上限(50 万行 / 128 MB / 2 秒)被截断;为 true 时结果不完整
scannedFilesnumber本次扫描的文件数
scannedLinesnumber本次扫描的行数

items 元素字段:

字段类型说明
receivedAtnumber面板接收该批次的毫秒时间戳
nodeIdnumber上报节点 ID
proxyIdnumber归属的面板隧道 ID(未归属时为 0,此时该记录不会出现在用户端结果中)
eventIdstring节点侧事件标识(bootId:序号)
firstTsnumber聚合窗口开始(毫秒时间戳)
lastTsnumber聚合窗口结束(毫秒时间戳)
countnumber窗口内被拦截的次数(聚合值)
sourcestring拦截来源
actionstring拦截动作
reasonstring拦截原因
proxyNamestring隧道名
clientIpstring攻击方 IP(节点侧识别结果,未经面板可信代理校验)
hoststring窗口内样本 Host
methodstring窗口内样本 HTTP 方法
samplePathstring窗口内样本路径
pathsarray窗口内路径样本(最多 3 条)
userAgentstring窗口内样本 User-Agent
protocolstringDPI 识别到的协议名
featuresarray结构化特征(k:v 形式,如 CC 速率/阈值/行为窗口、请求防护的命中链路/位置/规则/分值等)

Host / Method / SamplePath / UserAgent 是窗口内样本,不是全集。响应不回传 userId(归属用户)字段。

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "items": [
      {
        "receivedAt": 1789000035000,
        "nodeId": 3,
        "proxyId": 7,
        "eventId": "b1:1",
        "firstTs": 1789000000000,
        "lastTs": 1789000030000,
        "count": 42,
        "source": "cc_http",
        "action": "http_429",
        "reason": "ip",
        "proxyName": "web-1",
        "clientIp": "203.0.113.7",
        "host": "a.example.com",
        "method": "GET",
        "samplePath": "/api/x",
        "paths": ["/api/x", "/api/y"],
        "userAgent": "curl/8.0",
        "features": ["cc_rate:10", "cc_burst:20"]
      }
    ],
    "page": 1,
    "pageSize": 20,
    "hasMore": false,
    "scanTruncated": false,
    "scannedFiles": 1,
    "scannedLines": 1
  }
}

错误场景 ​

场景HTTP说明
隧道 ID 非法(非数字或 0)400「无效的隧道ID」
分页 / 时间 / 排序参数非法400「无效的分页参数」「无效的开始时间」「无效的排序参数」等
未提供有效令牌401统一未认证响应
查询失败500「查询防护日志失败」
日志存储未初始化或不可用503「节点 WAF 日志存储暂不可用」(失败关闭)

注意事项 ​

  • 数据保留期由面板配置(WAF_LOG_RETENTION_DAYS,默认 14 天),超期文件每日定时清理;更早的记录查不到属正常。
  • 用户没有隧道时返回空结果,且不会扫描任何日志目录(服务端按本人隧道所在节点推导扫描范围)。
  • 结果被扫描上限截断时 scanTruncated 为 true,应缩小时间范围或减少隧道数量后重试。
  • 本接口不提供导出;需要导出请由管理员在后台完成。
  • source=http_waf 的记录来自隧道级 SQL/XSS 请求防护(在创建/编辑隧道接口以 sql_protection_enabled / xss_protection_enabled 开启):features 携带 waf_chain(命中链路 sql/xss)、waf_field(命中位置:path / header:<小写头名> / body)、waf_rule(规则标签)与 waf_score(分值),不回传命中的请求内容。

GET /api/users/waf-logs/stats ​

返回本人隧道拦截日志的聚合统计,可见范围与筛选条件与查询接口完全一致(同一份归属过滤逻辑)。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

查询参数 ​

与 GET /api/users/waf-logs 相同的过滤参数(除分页参数外):proxyIds、start、end、date、source、reason、action、ip、keyword。

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/waf-logs/stats?proxyIds=7&source=cc_http'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/waf-logs/stats?proxyIds=7&source=cc_http', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/waf-logs/stats?proxyIds=7&source=cc_http',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/waf-logs/stats?proxyIds=7&source=cc_http", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
bySourceobject按来源分布,键为来源枚举,值为记录数
byReasonobject按原因分布
byActionobject按动作分布
topIpsarray攻击方 IP Top 10,元素为 { "key": "203.0.113.7", "count": 3 }
topProxiesarray隧道 Top 10,元素结构同上(键为隧道名)
hourlyarray24 个元素的数组,按窗口开始时间落在本地的整点分布记录数
totalRecordsnumber命中的聚合记录数
totalEventsnumber命中的拦截事件总数(各记录 count 之和)
scanTruncatedboolean是否被扫描上限截断
scannedFilesnumber本次扫描的文件数
scannedLinesnumber本次扫描的行数

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "bySource": { "cc_http": 1 },
    "byReason": { "ip": 1 },
    "byAction": { "http_429": 1 },
    "topIps": [{ "key": "203.0.113.7", "count": 1 }],
    "topProxies": [{ "key": "web-1", "count": 1 }],
    "hourly": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
    "totalRecords": 1,
    "totalEvents": 42,
    "scanTruncated": false,
    "scannedFiles": 1,
    "scannedLines": 1
  }
}

错误场景 ​

场景HTTP说明
参数非法400同查询接口
未提供有效令牌401统一未认证响应
统计失败500「防护日志统计失败」
日志存储未初始化或不可用503「节点 WAF 日志存储暂不可用」

注意事项 ​

  • hourly 按窗口开始时间所在小时计数,与 firstTs 对应。
  • 统计与列表是两次独立扫描,数据在两次请求之间可能新增记录(不保证严格一致)。

域名白名单 ​

把你的域名加入平台白名单:提交域名后平台会查询其 ICP 备案信息(先查免费备案库,查不到时调付费实时库复核,整个查询可能需要十几秒),查询通过即自动进入白名单。只展示与操作「你自己添加」的域名;管理员手动添加的记录不属于任何用户,不会出现在你的列表里。

配额与重复口径

每个账号最多 10 个域名;每天最多成功添加 2 个(以审计为记账依据,删除不返还当日额度)。域名全平台唯一——已被任何人加入白名单的域名会报「该域名已在白名单中」。添加请求必须携带 Cap.js 人机验证 ticket(与注册/登录同源,ticket 一次性,失败后需重新验证)。

GET /api/users/icp-whitelist ​

查询我的白名单域名。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/icp-whitelist'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/icp-whitelist', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/icp-whitelist',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/icp-whitelist", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
itemsarray白名单记录列表,按添加时间倒序
items[].idnumber记录 ID(删除时使用)
items[].domainstring域名(归一化后的小写形式)
items[].notestring备注,可能为空
items[].icpStatusstring备案状态:approved(备案有效) / not_approved(未备案) / revoked(已撤销)
items[].icpNumberstring备案号
items[].icpUnitstring备案主体
items[].lastCheckedAtstring最近一次备案检查时间,可能为 null
items[].createdAtstring添加时间
totalnumber记录条数
maxDomainsnumber每账号域名总量上限(当前 10)
dailyMaxAddsnumber每账号每天最多成功添加次数(当前 2)

错误场景 ​

场景状态码响应 message
未提供有效令牌401统一未认证响应

POST /api/users/icp-whitelist ​

添加域名:平台自动查询备案,查询通过即进入白名单。

鉴权:JWT Bearer · 限流:人机验证前置,备案查询本身逐次限速(排队等待属预期) · 缓存:no-store

请求参数 ​

参数类型必填说明
domainstring是要加入白名单的域名;自动去除协议/路径/端口并转小写
notestring否备注
captchaTicketstring是Cap.js 人机验证 ticket(一次性)

请求示例 ​

bash
curl -X POST -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"domain":"example.com","note":"个人博客","captchaTicket":"<ticket>"}' \
  'https://api.hyperfrp.com/api/users/icp-whitelist'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/icp-whitelist', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <token>',
  },
  body: JSON.stringify({"domain":"example.com","note":"个人博客","captchaTicket":"<ticket>"})
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.post(
    'https://api.hyperfrp.com/api/users/icp-whitelist',
    headers={'Authorization': 'Bearer <token>'},
    json={
        'domain': 'example.com',
        'note': '个人博客',
        'captchaTicket': '<ticket>'
    },
)
data = res.json()
print(data)
go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	var payload bytes.Buffer
	json.NewEncoder(&payload).Encode(map[string]any{
		"domain": "example.com",
		"note": "个人博客",
		"captchaTicket": "<ticket>",
	})

	req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/users/icp-whitelist", &payload)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

字段类型说明
messagestring「添加成功,域名已进入白名单」
itemobject新建的白名单记录(字段同列表项)

错误场景 ​

场景状态码响应 message
人机验证未通过400「人机验证未通过,请重新验证后再提交」
域名格式不正确400「域名格式不正确」
已在白名单中400「该域名已在白名单中」
未备案400「该域名未备案或已取消备案」
备案查询失败(限流/凭证/网络)400「查询失败: <上游原因>」
超出配额400「每个账号最多添加 10 个域名」/「每个账号每天最多添加 2 个域名」
未提供有效令牌401统一未认证响应

注意事项 ​

  • 备案查询不校验域名归属:备案通过即放行,请只添加你有权使用的域名。
  • 删除域名不会返还当日添加额度。

DELETE /api/users/icp-whitelist/ ​

删除我自己的白名单域名。

鉴权:JWT Bearer · 限流:无专用限流 · 缓存:no-store

路径参数 ​

参数类型说明
idnumber记录 ID(来自列表)

请求示例 ​

bash
curl -X DELETE -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/icp-whitelist/12'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/icp-whitelist/12', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.delete(
    'https://api.hyperfrp.com/api/users/icp-whitelist/12',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.hyperfrp.com/api/users/icp-whitelist/12", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

错误场景 ​

场景状态码响应 message
记录不存在 / 属主不是当前用户(含管理员添加的记录)400「白名单记录不存在」
无效的ID400「无效的ID」
未提供有效令牌401统一未认证响应

流量历史 ​

流量历史按 MySQL traffic_histories 表聚合,进出流量单位均为字节(int64),负值在聚合时按 0 处理;结果按 period 倒序返回。

GET /api/users/traffic-history ​

按时间粒度聚合当前用户的流量历史。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

查询参数 ​

参数类型必填说明
intervalstring否聚合粒度:day(默认)/ hour / month;其它值按 day 处理
limitnumber否返回的周期数,默认 30;超过 365 时按 365 处理

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/traffic-history?interval=day&limit=30'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/traffic-history?interval=day&limit=30', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/traffic-history?interval=day&limit=30',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/traffic-history?interval=day&limit=30", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

data 为对象数组,元素字段:

字段类型说明
periodstring周期标识:day 为 2026-09-19,hour 为 2026-09-19 08:00:00,month 为 2026-09
totalTrafficInnumber该周期入站流量合计,单位字节
totalTrafficOutnumber该周期出站流量合计,单位字节
totalTrafficnumber入站 + 出站合计,单位字节

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "period": "2026-09-19",
      "totalTrafficIn": 1073741824,
      "totalTrafficOut": 2147483648,
      "totalTraffic": 3221225472
    },
    {
      "period": "2026-09-18",
      "totalTrafficIn": 536870912,
      "totalTrafficOut": 1073741824,
      "totalTraffic": 1610612736
    }
  ]
}

错误场景 ​

场景HTTP说明
——无业务错误分支;查询异常时返回空数组

GET /api/users/traffic-history/:period ​

上一接口的别名路由:与 GET /api/users/traffic-history 共用同一 handler,查询参数、响应结构完全一致。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

行为说明 ​

  • 路径参数 :period 被忽略,不影响查询结果。
  • 聚合粒度仍由查询参数 interval 决定(未提供时默认 day),即 query 优先。
  • limit 参数与上限规则同上。

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/traffic-history/2026-09?interval=month&limit=12'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/traffic-history/2026-09?interval=month&limit=12', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/traffic-history/2026-09?interval=month&limit=12',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/traffic-history/2026-09?interval=month&limit=12", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

与 GET /api/users/traffic-history 完全一致(见上)。

错误场景 ​

场景HTTP说明
——无业务错误分支;查询异常时返回空数组

用户视角节点与公告 ​

GET /api/users/nodes ​

获取对用户可见的节点列表(is_visible 为 true),按创建时间倒序;返回节点模型的原样数组。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:short-cache 60s(响应头 Cache-Control: public, max-age=60, s-maxage=60)

响应字段 ​

data 为节点对象数组,元素字段(节点模型全部 JSON 序列化字段):

字段类型说明
idnumber节点 ID
namestring节点名称,全局唯一
hoststring节点主机地址(IP 或域名)
domainstring节点域名
portnumberFRP 连接端口
bindAddressstringFRPS 监听地址
kcpBindPortnumberKCP 绑定端口,0 表示未启用
quicEnabledboolean是否启用 QUIC
quicBindPortnumberQUIC 绑定端口
vhostHTTPPortnumberHTTP 虚拟主机端口
vhostHTTPSPortnumberHTTPS 虚拟主机端口
speedTestPortnumber测速 HTTP 端口
probeEnabledboolean是否启用 WebRTC 延迟探针
probePortnumber探针端口(TCP 信令与 UDP 媒体同号)
requireRealnameboolean使用该节点是否要求先完成实名认证(默认 true)。当前唯一的用户侧准入判据:为 true 且账户 isVerified 为 false 时该节点不可选,创建/切换隧道会被拒绝;与 region 和用户组均无关
allowedGroupIdsnumber[]允许访问的用户组 ID 列表;空数组表示不限。保留字段,2026-09-22 起不再参与准入裁决
isGroupExclusiveboolean是否专属组节点。同上,不再影响隧道可选性
permissionMessagestring无权限提示文案。同上,客户端不应再依赖(实名拒绝语由服务端统一给出)
exclusiveTagTextstring专属标签文案,仅历史配置回显
exclusiveTagColorstring专属标签颜色
exclusiveTagIconstring专属标签图标
allowedPortsStartnumber允许端口范围起点
allowedPortsEndnumber允许端口范围终点
allowPortRangesarray允许端口段列表,元素为 {start, end}
locationstring节点位置描述
descriptionstring节点描述
statusstring节点状态:online / api_only / unreachable / frps_stopped / offline / maintenance
cpuInfostringCPU 型号信息
cpuTemperaturenumberCPU 温度(°C)
isVisibleboolean是否可见;本接口恒为 true
maxProxiesnumber节点隧道数上限
bandwidthLimitKbpsnumber节点带宽上限,单位 kbps
totalTrafficInBytesnumber节点累计入站流量,单位字节
totalTrafficOutBytesnumber节点累计出站流量,单位字节
networkPacketsSentnumber累计发送数据包数
networkPacketsRecvnumber累计接收数据包数
clientsOnlinenumber在线客户端数
proxiesCountnumber节点上隧道数
lastHeartbeatstring 或 null最近心跳时间
onlineSincestring 或 null本次上线起始时间
bootTimenumber 或 null节点系统启动时间(Unix 秒)
cpuUsagenumberCPU 占用率(百分比)
loadAveragestring负载均值(字符串)
systemLoadstring系统负载 JSON 串
memoryUsagenumber内存占用率(百分比)
memoryTotalnumber恒为 0(模型计算字段,本接口未填充)
memoryUsednumber恒为 0(同上)
diskUsagenumber磁盘占用率(百分比)
diskTotalnumber恒为 0(同上)
diskUsednumber恒为 0(同上)
networkSpeedInnumber实时入站速率,单位 B/s
networkSpeedOutnumber实时出站速率,单位 B/s
frpsReportedInBytesnumberFRPS 上报累计入站流量,单位字节
frpsReportedOutBytesnumberFRPS 上报累计出站流量,单位字节
logPathstring恒为空串(模型计算字段,本接口未填充)
frpsPathstring恒为空串(同上)
configPathstring恒为空串(同上)
dashboardPortnumberFRPS 仪表盘端口
webServerAddrstringFRPS web 服务监听地址
tcpMuxboolean是否启用 TCP 多路复用
tcpMuxHTTPConnectPortnumberTCP Mux HTTP Connect 端口
tcpKeepAlivenumberTCP keepalive,单位秒
heartbeatTimeoutnumber心跳超时,单位秒
maxPoolCountnumber最大连接池数
tlsForceboolean是否强制 TLS
logLevelstringFRPS 日志级别
logMaxDaysnumberFRPS 日志保留天数
disableLogColorboolean是否禁用日志颜色
regionstring地区(如 Overseas)
allowedProtocolsstring[]允许的隧道协议列表
bandwidthValuenumber带宽数值(与 bandwidthUnit 配合展示)
bandwidthUnitstring带宽单位:Mbps / Gbps
hyperzonefrpApiURLstring节点侧面板 API 基址
hyperzonefrpHeartbeatIntervalnumber心跳上报间隔,单位秒
hyperzonefrpResourceIntervalnumber资源上报间隔,单位秒
hyperzonefrpTrafficFlushIntervalnumber流量落盘间隔,单位秒
hyperzonefrpTunnelCheckIntervalnumber隧道检查间隔,单位秒
trafficQueuePathstring流量 WAL 路径
trafficQueueHighWatermarknumber流量队列高水位(条数)
upgradeEnabledboolean节点自动升级开关
panelFailureModestring面板不可用降级策略:fail-closed / fail-open
upgradeServiceNamestring升级服务名
upgradeInstallDirstring升级安装目录
upgradeSelfCheckWindownumber升级自检窗口,单位秒
createdAtstring创建时间(RFC 3339)
updatedAtstring更新时间(RFC 3339)

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/nodes'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/nodes', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/nodes',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/nodes", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 2,
      "name": "华东-1",
      "host": "cn-east-1.example.net",
      "domain": "cn-east-1.example.net",
      "port": 7000,
      "bindAddress": "0.0.0.0",
      "kcpBindPort": 0,
      "quicEnabled": false,
      "quicBindPort": 0,
      "vhostHTTPPort": 8080,
      "vhostHTTPSPort": 8443,
      "speedTestPort": 9001,
      "probeEnabled": true,
      "probePort": 27100,
      "requireRealname": true,
      "allowedGroupIds": [],
      "isGroupExclusive": false,
      "permissionMessage": "",
      "exclusiveTagText": "",
      "exclusiveTagColor": "#ff69b4",
      "exclusiveTagIcon": "",
      "allowedPortsStart": 10000,
      "allowedPortsEnd": 60000,
      "allowPortRanges": [],
      "location": "上海",
      "description": "华东电信节点",
      "status": "online",
      "cpuInfo": "Intel Xeon Platinum 8269CY",
      "cpuTemperature": 45.5,
      "isVisible": true,
      "maxProxies": 10,
      "bandwidthLimitKbps": 102400,
      "totalTrafficInBytes": 1099511627776,
      "totalTrafficOutBytes": 2199023255552,
      "networkPacketsSent": 123456789,
      "networkPacketsRecv": 987654321,
      "clientsOnline": 42,
      "proxiesCount": 128,
      "lastHeartbeat": "2026-09-19T09:00:02+08:00",
      "onlineSince": "2026-09-01T00:00:00+08:00",
      "bootTime": 1758600000,
      "cpuUsage": 23.4,
      "loadAverage": "0.52 0.48 0.45",
      "systemLoad": "{}",
      "memoryUsage": 61.2,
      "memoryTotal": 0,
      "memoryUsed": 0,
      "diskUsage": 55.0,
      "diskTotal": 0,
      "diskUsed": 0,
      "networkSpeedIn": 1048576,
      "networkSpeedOut": 2097152,
      "frpsReportedInBytes": 107374182400,
      "frpsReportedOutBytes": 214748364800,
      "logPath": "",
      "frpsPath": "",
      "configPath": "",
      "dashboardPort": 7500,
      "webServerAddr": "127.0.0.1",
      "tcpMux": true,
      "tcpMuxHTTPConnectPort": 0,
      "tcpKeepAlive": 7200,
      "heartbeatTimeout": 90,
      "maxPoolCount": 5,
      "tlsForce": false,
      "logLevel": "info",
      "logMaxDays": 7,
      "disableLogColor": false,
      "region": "Overseas",
      "allowedProtocols": ["tcp", "udp", "http", "https"],
      "bandwidthValue": 100,
      "bandwidthUnit": "Mbps",
      "hyperzonefrpApiURL": "https://api.hyperfrp.com/api",
      "hyperzonefrpHeartbeatInterval": 30,
      "hyperzonefrpResourceInterval": 15,
      "hyperzonefrpTrafficFlushInterval": 10,
      "hyperzonefrpTunnelCheckInterval": 30,
      "trafficQueuePath": "",
      "trafficQueueHighWatermark": 10000,
      "upgradeEnabled": false,
      "panelFailureMode": "fail-closed",
      "upgradeServiceName": "",
      "upgradeInstallDir": "",
      "upgradeSelfCheckWindow": 60,
      "createdAt": "2026-01-01T00:00:00+08:00",
      "updatedAt": "2026-09-19T09:00:05+08:00"
    }
  ]
}

错误场景 ​

场景HTTP说明
——无业务错误分支;无可见节点时返回空数组

注意事项 ​

  • 节点敏感凭证字段(token、hyperzonefrpApiToken、hyperzonefrpNodeToken、dashboardUser、dashboardPassword)在模型上标记为不序列化,永远不会出现在响应中。
  • 列表只按 is_visible 过滤,不按用户组做访问过滤;组权限判断由创建隧道等接口负责。

GET /api/users/nodes/:id ​

获取单个节点详情;返回 handler 手工构造的字段子集(与列表接口不同,非整模型序列化)。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:short-cache 60s

响应字段 ​

字段类型说明
idnumber节点 ID
namestring节点名称
addressstring节点地址(取自节点 host 字段)
portnumberFRP 连接端口
locationstring节点位置描述
descriptionstring节点描述
statusstring节点状态
cpuUsagenumberCPU 占用率(百分比)
memoryUsagenumber内存占用率(百分比)
diskUsagenumber磁盘占用率(百分比)
networkSpeedInnumber实时入站速率,单位 B/s
networkSpeedOutnumber实时出站速率,单位 B/s
clientsOnlinenumber在线客户端数
proxiesCountnumber节点上隧道数
lastHeartbeatstring 或 null最近心跳时间
createdAtstring创建时间(RFC 3339)
updatedAtstring更新时间(RFC 3339)

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/nodes/2'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/nodes/2', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/nodes/2',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/nodes/2", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 2,
    "name": "华东-1",
    "address": "cn-east-1.example.net",
    "port": 7000,
    "location": "上海",
    "description": "华东电信节点",
    "status": "online",
    "cpuUsage": 23.4,
    "memoryUsage": 61.2,
    "diskUsage": 55.0,
    "networkSpeedIn": 1048576,
    "networkSpeedOut": 2097152,
    "clientsOnline": 42,
    "proxiesCount": 128,
    "lastHeartbeat": "2026-09-19T09:00:02+08:00",
    "createdAt": "2026-01-01T00:00:00+08:00",
    "updatedAt": "2026-09-19T09:00:05+08:00"
  }
}

错误场景 ​

场景HTTP说明
节点 ID 非数字400返回「无效的节点ID」
节点不存在404返回「节点未找到」

注意事项 ​

  • 本接口按 ID 直查,不校验 is_visible,即隐藏节点同样可按 ID 查到详情。

GET /api/users/nodes/:id/traffic-history ​

按时间粒度聚合指定节点的流量历史,参数与响应结构同用户维度流量历史,聚合范围按 node_id 过滤。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:no-store

查询参数 ​

参数类型必填说明
intervalstring否聚合粒度:day(默认)/ hour / month;其它值按 day 处理
limitnumber否返回的周期数,默认 30;超过 365 时按 365 处理

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/nodes/2/traffic-history?interval=hour&limit=24'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/nodes/2/traffic-history?interval=hour&limit=24', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/nodes/2/traffic-history?interval=hour&limit=24',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/nodes/2/traffic-history?interval=hour&limit=24", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应字段 ​

data 为对象数组,元素字段:

字段类型说明
periodstring周期标识,格式随 interval:2026-09-19 / 2026-09-19 08:00:00 / 2026-09
totalTrafficInnumber该周期该节点入站流量合计,单位字节
totalTrafficOutnumber该周期该节点出站流量合计,单位字节
totalTrafficnumber入站 + 出站合计,单位字节

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "period": "2026-09-19 08:00:00",
      "totalTrafficIn": 104857600,
      "totalTrafficOut": 209715200,
      "totalTraffic": 314572800
    },
    {
      "period": "2026-09-19 07:00:00",
      "totalTrafficIn": 52428800,
      "totalTrafficOut": 104857600,
      "totalTraffic": 157286400
    }
  ]
}

错误场景 ​

场景HTTP说明
节点 ID 非数字400返回「无效的节点ID」
节点不存在404返回「节点未找到」

注意事项 ​

  • 聚合按 node_id 过滤,反映的是节点整体流量(含全部用户),并非当前用户个人的流量。

GET /api/users/announcements/:id ​

获取单个已发布公告的详情;未发布或不存在的公告一律 404。

鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:short-cache 60s

响应字段 ​

字段类型说明
idnumber公告 ID
titlestring公告标题
contentstring公告正文
contentTypestring内容类型,如 text / markdown
authorIdnumber作者用户 ID
visibleGroupIdsstring可见用户组 ID 的 JSON 串(如 "[1,2]";空数组通常表示全部可见)
isPublishedboolean是否发布;本接口恒为 true
publishDatestring发布时间(RFC 3339)
createdAtstring创建时间(RFC 3339)
updatedAtstring更新时间(RFC 3339)

请求示例 ​

bash
curl -H 'Authorization: Bearer <token>' \
  'https://api.hyperfrp.com/api/users/announcements/5'
javascript
const res = await fetch('https://api.hyperfrp.com/api/users/announcements/5', {
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
console.log(data);
python
import requests

res = requests.get(
    'https://api.hyperfrp.com/api/users/announcements/5',
    headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)
go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/users/announcements/5", nil)
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result map[string]any
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(result)
}

响应示例 ​

json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 5,
    "title": "9 月华东节点扩容公告",
    "content": "华东-1 节点已完成带宽扩容至 100Mbps。",
    "contentType": "markdown",
    "authorId": 1,
    "visibleGroupIds": "[]",
    "isPublished": true,
    "publishDate": "2026-09-10T10:00:00+08:00",
    "createdAt": "2026-09-10T09:55:00+08:00",
    "updatedAt": "2026-09-10T10:00:00+08:00"
  }
}

错误场景 ​

场景HTTP说明
公告 ID 非数字400返回「无效的公告ID」
公告不存在或未发布404返回「公告未找到」

注意事项 ​

  • 响应不含 author 对象(模型关联未预加载,omitempty 生效),作者信息仅有 authorId。
  • 本接口不按 visibleGroupIds 做用户组过滤,仅校验 is_published。

本站基于 VitePress 构建,文档内容以 backend-Go handler 源码为权威依据