API 概览与接口索引
HyperZoneFRP Panel 开发者 API 完整索引:面向开发者的 64 个开放接口,按 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 | 10 | 公开 6 + JWT 4 |
| 用户资料与账户 | /api/users | 18 | JWT |
| 实名认证与两步验证 | /api/users/profile/verify*、/api/users/2fa* | 7 | JWT |
| 套餐 | /api/users/packages | 5 | JWT |
| 节点与监控 | /api/nodes | 8 | JWT |
| 隧道管理 | /api/proxies | 16 | JWT |
| 合计 | 64 |
阅读每一章的姿势
每个接口小节按固定模板展开:一句话职责 → 鉴权/限流/缓存一行 → 请求体(或查询参数)字段表 → 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 | 提交两步验证验证码完成登录，成功后返回与登录接口一致的令牌和用户信息。 |
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。 |
实名认证与两步验证
路由前缀:/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 | 生成三平台的一键启动命令（使用官方 hyperfrpc 客户端拉起指定隧道）。命令内嵌用户访问密钥与面板…… |
POST | /api/proxies/:id/force-unregister | 对本人单条隧道执行强制下线：事务内原子递增持久强制下线代次（forceOfflineGeneration…… |
GET | /api/proxies/config/download/:id/:format | 下载本人单条隧道的 FRPC 配置文件。 |
GET | /api/proxies/config/download/merged/:nodeId/:format | 下载本人指定节点下全部已启用隧道（enabledUser=true 且 statusAdmin=true…… |