API 概览与接口索引
HyperZoneFRP Panel 开发者 API 完整索引:面向开发者的 83 个开放接口,按 6 个路由域成章。基础地址、统一响应包络与错误码见 通用约定;JWT 鉴权语义与两步验证登录流见 鉴权方式。
收录范围
本文档只收录开发者可用的用户侧接口(/api/auth、/api/users、/api/nodes、/api/proxies 路由域)。以下不在开发者文档范围:/api/admin/* 管理后台接口;节点端 FRPS 机器协议(/api/frps/*,节点与面板间通信);官网内容与系统运维接口(/api/public/*、/api/system/*、/api/utils/*、/api/update/*、/api/client-errors 及根级别探针)。各章内容以 backend-Go handler 源码为权威依据逐字段核对。
速览
| 章节 | 路由前缀 | 接口数 | 鉴权 |
|---|---|---|---|
| 认证与会话 | /api/auth | 12 | 公开 7 + JWT 5 |
| 用户资料与账户 | /api/users | 25 | JWT |
| 实名认证与两步验证 | /api/users/profile/verify*、/api/users/2fa* | 7 | JWT |
| 套餐 | /api/users/packages | 5 | JWT |
| 节点与监控 | /api/nodes | 8 | JWT |
| 隧道管理 | /api/proxies | 26 | JWT |
| 合计 | 83 |
阅读每一章的姿势
每个接口小节按固定模板展开:一句话职责 → 鉴权/限流/缓存一行 → 请求体(或查询参数)字段表 → curl 请求示例 → 响应字段表 → 响应示例 → 错误场景 → 注意事项。文件下载类端点(审计导出、配置下载)以二进制流返回,无统一包络,响应示例节改为文字说明。
接口索引
认证与会话
路由前缀:/api/auth
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /api/auth/email-code | 向指定邮箱发送 6 位数字验证码,验证码按用途隔离,用于注册或找回密码。 |
POST | /api/auth/register | 使用邮箱验证码注册新账号,注册成功后直接完成登录(返回令牌与用户信息)。 |
POST | /api/auth/login | 账号密码登录。普通用户直接返回令牌;已开启两步验证的用户返回临时令牌,需继续调用 POST /api/a…… |
POST | /api/auth/2fa/verify | 提交两步验证验证码完成登录,成功后返回与登录接口一致的令牌和用户信息。 |
POST | /api/auth/client/authorize | Windows 客户端网页授权:控制台授权页确认后签发 60 秒一次性授权码(回环地址 + PKCE),开启两步验证的账号需提交验证码。 |
POST | /api/auth/client/token | Windows 客户端用授权码与 codeVerifier 换取登录令牌,响应与登录接口同构。 |
PUT | /api/auth/reset-password | 通过邮箱验证码重置密码。成功后该用户全部会话被吊销、旧 JWT 全部失效,需重新登录。 |
POST | /api/auth/logout | 登出并删除当前令牌对应的服务端会话。该接口被有意放在公开路由:即使 JWT 已过期也能删除会话,避免会话…… |
GET | /api/auth/me | 查询当前登录用户的完整信息(含预载的用户组)。 |
GET | /api/auth/sessions | 查询当前用户在所有设备上的登录会话列表。 |
DELETE | /api/auth/sessions/:sessionId | 吊销(下线)当前用户的指定会话。 |
POST | /api/auth/sessions/heartbeat | 当前会话保活:刷新最近活跃时间并滑动会话有效期。 |
用户资料与账户
路由前缀:/api/users/*
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/users/profile | 获取当前登录用户的完整资料,含用户组、配额、流量余额与偏好设置。 |
PUT | /api/users/profile | 更新当前用户的基本资料,支持修改用户名、QQ 号与头像 URL。 |
PUT | /api/users/profile/avatar | 上传头像文件,替换旧头像并落库新路径。 |
PUT | /api/users/profile/password | 修改登录密码;成功后账户 authVersion 递增,该用户所有已签发的 JWT 立即失效,全部设备需…… |
POST | /api/users/profile/wallpaper | 上传控制台壁纸,替换该用户此前上传的全部旧壁纸,返回新壁纸 URL。 |
PUT | /api/users/profile/preferences | 更新偏好设置。合并语义:与既有偏好做顶层键浅合并——请求体中出现的键逐个覆盖,未出现的键保留原值;不做嵌…… |
POST | /api/users/profile/speed-boost/check | 检查当前用户全部隧道所涉节点是否满足「极速模式」条件,供开启极速模式前预检。 |
POST | /api/users/reset-access-key | 轮换 FRP 客户端访问密钥,并强制下线该用户全部隧道(含非运行中,用于清理历史不一致状态)。 |
POST | /api/users/checkin | 每日签到,随机发放积分与流量奖励;同一自然日(服务器本地时区)只能签到一次。 |
POST | /api/users/force-unregister-all | 强制下线本人全部隧道:数据库层原子递增该用户全部隧道的持久强制下线代次并置为 stopped,再经 Re…… |
GET | /api/users/audit-logs | 分页查询本人操作审计日志,支持按操作类型、状态、IP 与时间范围过滤。 |
GET | /api/users/audit-logs/export | 导出本人审计日志文件。该端点不走统一响应包络,直接以附件形式返回文件流。 |
GET | /api/users/traffic-history | 按时间粒度聚合当前用户的流量历史。 |
GET | /api/users/traffic-history/:period | 上一接口的别名路由:与 GET /api/users/traffic-history 共用同一 hand…… |
GET | /api/users/nodes | 获取对用户可见的节点列表(is_visible 为 true),按创建时间倒序;返回节点模型的原样数组。 |
GET | /api/users/nodes/:id | 获取单个节点详情;返回 handler 手工构造的字段子集(与列表接口不同,非整模型序列化)。 |
GET | /api/users/nodes/:id/traffic-history | 按时间粒度聚合指定节点的流量历史,参数与响应结构同用户维度流量历史,聚合范围按 node_id 过滤。 |
GET | /api/users/announcements/:id | 获取单个已发布公告的详情;未发布或不存在的公告一律 404。 |
GET | /api/users/waf-logs | 分页查询本人隧道的防护拦截日志(节点侧 CC 限流/连接层拒绝/行为封禁/DPI 阻断)。归属按面板权威字段过滤,只返回 userId 等于当前用户的记录。 |
GET | /api/users/waf-logs/stats | 与查询接口同一套可见范围与筛选条件,返回按来源/原因/动作的分布、Top 攻击方 IP 与 24 小时分布。 |
POST | /api/users/redeem | 兑换一张福利兑换码,按码配置发放权益:切换用户组、加积分或加流量。只认 JWT,不接受访问密钥。 |
GET | /api/users/redeem/history | 分页查询本人兑换记录,按兑换时间倒序;每条带发放当时的权益快照。 |
实名认证与两步验证
路由前缀:/api/users/profile/verify*, /api/users/2fa*
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /api/users/profile/verify/manual | 以人工审核方式提交实名认证:上传身份证照片并填写姓名、身份证号,进入 pending 状态等待管理员审核…… |
POST | /api/users/profile/verify/face | 调用外部「身份证二要素核验」服务实时比对姓名与身份证号:匹配即实名成功(approved),不匹配或服务…… |
POST | /api/users/profile/verify | 自动二要素核验。与 POST /api/users/profile/verify/face 调用同一个外…… |
GET | /api/users/profile/verification-status | 查询当前用户的实名认证状态与脱敏结果。 |
POST | /api/users/2fa/enable | 生成新的 TOTP 密钥与 5 枚恢复码并暂存,返回密钥与 otpauth:// URI 供验证器绑定。 |
POST | /api/users/2fa/confirm | 提交一枚 TOTP 动态码确认开启两步验证,成功后一次性返回 5 枚恢复码。 |
POST | /api/users/2fa/disable | 关闭两步验证:提交一枚 TOTP 动态码校验通过后关闭开关、删除服务端密钥数据(未用完的恢复码一并销毁)…… |
套餐
路由前缀:/api/users/packages*
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/users/packages/available | 获取当前在售(isActive 为 true)的套餐列表,按价格从低到高排序,供购买前浏览与选型。 |
GET | /api/users/packages/my | 获取当前用户的全部套餐记录(含所有状态),按创建时间倒序,每个元素内嵌完整的套餐对象。 |
GET | /api/users/packages/active | 获取当前用户 status 为 active 的套餐记录,按到期时间升序(最先到期的在前)。 |
POST | /api/users/packages/purchase | 用账户余额购买指定套餐:扣费、叠加账户总流量、创建一条生效中的用户套餐记录,并在套餐配置了目标用户组时切…… |
GET | /api/users/packages/history | 获取当前用户的套餐购买历史(全部状态),按创建时间倒序,返回精简字段视图。 |
节点与监控
路由前缀:/api/nodes*
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/nodes | 返回所有对用户可见的节点,按地区(region)分组,并附带一份面板全局统计(在线节点数、在线用户数、今…… |
GET | /api/nodes/:id | 返回单个节点的完整配置与运行状态,即原始 Node 模型的 JSON 序列化结果(含 FRPS 配置参数…… |
GET | /api/nodes/:id/cpu-history | 返回节点 CPU 占用率的历史曲线,元素为 {time, value}。 |
GET | /api/nodes/:id/memory-history | 返回节点内存占用率的历史曲线,结构与 cpu-history 完全一致。 |
GET | /api/nodes/:id/disk-history | 返回节点磁盘占用率的历史曲线,结构与 cpu-history 完全一致。 |
GET | /api/nodes/:id/network-history | 返回节点网络速率的历史曲线。每个时间桶产出两条记录(入站 / 出站各一条),通过 type 字段区分。 |
GET | /api/nodes/:id/metrics | 一次请求返回四类指标的聚合历史(CPU / 内存 / 磁盘 / 网络双向),字段名为 snake_cas…… |
POST | /api/nodes/:id/probe | WebRTC 延迟探针的信令中转:浏览器把本地 SDP offer 提交给面板(同源 HTTPS),面板…… |
隧道管理
路由前缀:/api/proxies*
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/proxies | 返回当前登录用户的全部隧道(不分页),按创建时间倒序排列。 |
GET | /api/proxies/search | 分页搜索当前用户的隧道,支持关键词、类型、节点、启用状态与运行状态过滤,以及白名单字段排序。响应返回完整…… |
POST | /api/proxies | 创建一条属于当前用户的隧道。服务端在事务内对用户与节点行加锁后完成全部校验并写入,避免并发创建下的端口 …… |
POST | /api/proxies/batch-delete | 批量删除当前用户名下的隧道。非本人或不存在的 ID 会被静默忽略(不报错),返回实际删除数量;仅当一条都…… |
POST | /api/proxies/batch-status | 批量启用 / 禁用当前用户名下的隧道(写 enabledUser 开关)。非本人或不存在的 ID 静默忽…… |
GET | /api/proxies/random-port/:nodeId | 为指定节点随机取一个当前未被占用的远程端口,供创建隧道时预填。端口不会预留,创建时仍会做占用校验。 |
GET | /api/proxies/:id | 获取单条隧道详情。仅能查看本人隧道;隧道不存在或属于他人时一律按 404 处理(权限隐藏,不区分两种情况…… |
PUT | /api/proxies/:id | 更新本人隧道。字符串字段「空串 / 未提交 = 不修改」;布尔字段用指针语义「未提交 = 不修改」;提交…… |
DELETE | /api/proxies/:id | 删除本人的一条隧道。隧道不存在或属于他人时按 404 处理(权限隐藏)。 |
PUT | /api/proxies/:id/status | 切换本人隧道的用户侧启用开关(enabledUser)。禁用时同时把 status 置为 stopped…… |
PUT | /api/proxies/:id/bind-domain | 为本人隧道绑定(更换)路由域名。仅 http / https 类型可用;tcpmux 类型需走更新接口。…… |
GET | /api/proxies/:id/config-preview | 生成本人隧道的 FRPC 客户端配置预览,同时返回 INI(legacy 格式)与 TOML(新格式)两…… |
POST | /api/proxies/:id/quick-start-command | 生成三平台的一键启动命令(使用下载站分发的官方 frpc 客户端拉起指定隧道)。命令内嵌用户访问密钥与面板…… |
GET | /api/proxies/:id/events | 查询本人隧道启停日志(上线/离线历史),按时间倒序。事件由转发核心上报落库、按运行实例去重,保留 30 天;runId 只回显前 8 位。 |
GET | /api/proxies/:id/traffic-history | 查询本人隧道最近 N 分钟流量历史,按 10 秒桶聚合升序返回(零流量无桶、调用方补零);current 为最近一桶折算的当前带宽。 |
POST | /api/proxies/:id/force-unregister | 对本人单条隧道执行强制下线:事务内原子递增持久强制下线代次(forceOfflineGeneration…… |
GET | /api/proxies/tls-certs | 查询当前用户全部已上传的 HTTPS 隧道证书(证书管理页列表,一次返回不分页;不含 PEM 与私钥)。 |
POST | /api/proxies/tls-certs | 上传一张未绑定证书(先上传、创建 HTTPS 隧道时再通过 tls_cert_id 选择绑定;配对/有效期校验,暂不校验域名覆盖)。 |
GET | /api/proxies/tls-certs/unbound/:certId | 查询单张未绑定证书详情(结构与绑定证书详情一致,隧道/节点归属为空)。 |
DELETE | /api/proxies/tls-certs/unbound/:certId | 删除本人一张未绑定证书(已绑定到隧道的证书走按隧道删除端点)。 |
GET | /api/proxies/tls-certs/:proxyId | 查询单张托管证书详情(主题/颁发者/序列号/SAN/证书链/公钥 PEM;公钥证书为公开件,私钥永不返回;未上传 data 为 null)。 |
PUT | /api/proxies/:id/tls-cert | 上传/替换本人 HTTPS 隧道保存在平台的证书与私钥(配对/有效期/域名覆盖校验通过后私钥加密落库,版本+1,节点自动换用)。 |
GET | /api/proxies/:id/tls-cert | 查询本人隧道保存在平台的证书状态(仅指纹/有效期/版本,未上传时 data 为 null;证书与私钥内容永不回显)。 |
DELETE | /api/proxies/:id/tls-cert | 删除本人隧道保存在平台的证书(幂等)。删除后节点自动恢复为不解密的原样转发。 |
GET | /api/proxies/config/download/:id/:format | 下载本人单条隧道的 FRPC 配置文件。 |
GET | /api/proxies/config/download/merged/:nodeId/:format | 下载本人指定节点下全部已启用隧道(enabledUser=true 且 statusAdmin=true…… |