隧道管理
本章覆盖 HyperFRP Panel 后端的隧道(proxy / frpc 隧道)管理接口,共 24 个:本人隧道列表、分页搜索、创建、批量删除、批量启停、随机远程端口、详情、更新、删除、启停开关、绑定域名、HTTPS 隧道证书的列表 / 详情 / 上传 / 查询 / 删除、未绑定证书的上传 / 详情 / 删除(先上传、创建 HTTPS 隧道时再选择绑定)、配置预览、快捷启动命令、单隧道强制下线,以及单隧道 / 合并两种格式的配置文件下载。
鉴权基调:本章全部 24 个接口都需要登录,通过 Authorization: Bearer <token> 请求头携带 JWT(仅支持请求头方式,不接受 URL 参数传递),Bearer 令牌的获取与使用方式详见认证指南。所有路由经过全站 WAF 防护,且逐一挂载 NoCache 缓存中间件(响应携带 Cache-Control: no-store, no-cache, must-revalidate, private,禁止任何缓存)。除两个配置下载端点直接返回二进制附件外,其余接口均返回统一包络 {"code": 0, "message": "...", "data": ...},错误码与 HTTP 状态码对齐;与具体接口无关的通用约定见通用约定。
以下各接口的「错误场景」表只列接口特有分支。所有接口共有的鉴权失败分支不再逐条重复:
| 场景 | HTTP | 说明 |
|---|---|---|
未携带 Authorization 请求头 | 401 | {"code":401,"message":"未提供认证令牌"} |
| JWT 无效或已过期 | 401 | {"code":401,"message":"无效的令牌或令牌已过期"} |
| 服务端会话失效 | 401 | {"code":401,"message":"会话无效或已过期,请重新登录"} |
| 账户已被封禁 | 403 | {"code":403,"message":"您的账户已被封禁","data":{"isBanned":true,"ban_reason":"..."}} |
| 认证版本或账户状态变更 | 401 | {"code":401,"message":"账户状态或认证版本已变更,请重新登录"} |
隧道对象模型
本章接口返回隧道对象时有两种形态,字段以源码 ProxyResponseDTO 与 models.Proxy 的 JSON 标签为准:
- 精简 DTO(下称「隧道 DTO」):仅
GET /api/proxies列表接口使用,隐藏 GORM 模型细节,node为精简节点对象; - 完整模型(下称「完整隧道」):创建、详情、更新、启停、绑定域名、搜索等接口返回,字段更多,
node为预载的节点对象。
隧道 DTO 字段(GET /api/proxies 列表专用)
| 字段 | 类型 | 说明 |
|---|---|---|
id | number | 隧道 ID |
name | string | 隧道名称 |
type | string | 隧道类型,枚举见创建接口 |
nodeId | number | 所属节点 ID |
localIp | string | 本地服务 IP |
localPort | number | 本地服务端口 |
remotePort | number | 远程端口(tcp/udp/stcp/sudp 使用);http/https/tcpmux 恒为 0 |
domain | string | 绑定域名,多个以英文逗号分隔(http/https/tcpmux 使用);其他类型为空串 |
comment | string | 备注 |
status | string | 隧道状态,枚举:pending / stopped / running / error / disabled |
enabledUser | boolean | 用户侧启用开关 |
statusAdmin | boolean | 管理员侧启用开关(为 false 时隧道无法运行) |
adminReason | string | 管理员处置原因(如禁用说明) |
trafficInBytes | number | 累计入站流量(字节) |
trafficOutBytes | number | 累计出站流量(字节) |
useEncryption | boolean | 是否启用传输加密 |
useCompression | boolean | 是否启用传输压缩 |
transportProtocol | string | 传输协议:tcp(默认)/ quic(节点开启 QUIC 时可用) |
proxyProtocolVersion | string | Proxy Protocol 版本:空串(不启用)/ v1 / v2;仅 tcp/udp 支持 |
ccProtectionEnabled | boolean | CC 防护开关 |
sqlProtectionEnabled | boolean | SQL 注入防护开关(仅 http 类型隧道,或 https 隧道上传证书并开启服务端 HTTPS 解密后可为 true,见下方「HTTPS 隧道证书」) |
xssProtectionEnabled | boolean | XSS 防护开关(窗口约束同上) |
tlsTerminateEnabled | boolean | HTTPS 服务端解密开关(仅 https 类型隧道可开启):开启并把证书上传到平台后(见下方「HTTPS 隧道证书」),由节点在服务端解开访客的 HTTPS 连接再转发;证书未上传或无效时自动保持不解密的原样转发 |
bandwidthLimit | string | 带宽上限(如 10MB),未设置为空串 |
maxConnections | number | 最大连接数,0 表示不限制 |
secretConfigured | boolean | 敏感配置(sk 等访问密钥)是否已设置;只回布尔,永不返回明文或密文 |
configurationComplete | boolean | 权威协议配置在最近一次写入时是否完整可消费 |
protocolConfig | object | 不出现 | 解析后的非敏感权威协议配置,结构见创建接口 protocolConfig 说明;未配置时省略 |
createdAt | string | 创建时间(RFC3339) |
updatedAt | string | 更新时间(RFC3339) |
node | object | 不出现 | 精简节点对象,结构见下;节点缺失时省略 |
精简节点对象 node(ProxyNodeDTO)字段:
| 字段 | 类型 | 说明 |
|---|---|---|
id | number | 节点 ID |
name | string | 节点名称 |
host | string | 节点主机地址(域名或 IP) |
port | number | FRPS 主连接端口 |
domain | string | 节点域名 |
location | string | 地理位置描述(如 中国 广东 广州) |
status | string | 节点状态:online / api_only / unreachable / frps_stopped / offline / maintenance |
完整隧道字段(创建 / 详情 / 更新 / 启停 / 绑定域名 / 搜索返回)
在隧道 DTO 字段之外,完整模型还有以下字段;两者重复的字段语义相同,不再重复列出。
| 字段 | 类型 | 说明 |
|---|---|---|
userId | number | 所属用户 ID(即当前登录用户) |
node | object | 不出现 | 嵌套节点对象。创建 / 详情 / 更新响应会预载完整节点模型;启停与绑定域名响应不预载(该键省略);搜索响应预载完整节点模型(含节点运行指标等全部非凭据字段,节点 token 等长期凭据字段从不外泄) |
subDomain | string | 恒为空串(历史兼容虚拟字段) |
locations | string | 恒为空串(路径路由经由 protocolConfig.locations 表达) |
hostHeaderRewrite | string | 恒为空串(经由 protocolConfig.hostHeaderRewrite 表达) |
headers | string | 恒为空串(经由 protocolConfig.headers 表达) |
plugin | string | 恒为空串(默认情况下 HTTPS 证书插件由配置生成器按 pluginCrtPath / pluginKeyPath 固定输出 https2http;开启服务端解密后不再使用证书插件、本地服务直连明文 HTTP) |
pluginParams | string | 恒为空串 |
pluginCrtPath | string | HTTPS 插件证书路径(仅 https 类型使用;开启服务端解密后不再使用) |
pluginKeyPath | string | HTTPS 插件私钥路径(仅 https 类型使用;开启服务端解密后不再使用) |
extraParams | string | 恒为空串(保留字段) |
lastActiveAt | null | 恒为 null(虚拟字段,未启用) |
forceOfflineGeneration | number | 持久强制下线代次:每次强制下线 / 强制注销 / 访问密钥重置时原子递增,FRPS 发现代次变化即关闭运行实例 |
tlsTerminateEnabled | boolean | HTTPS 服务端解密开关,语义同隧道 DTO |
cc_rules | object | 不出现 | CC 防护规则 { "rate": number, "burst": number }(rate 为每秒令牌数,burst 为突发容量);未开启 CC 防护时省略。注意这是对象中唯一使用下划线命名的键 |
protocolConfig | object | 不出现 | 同隧道 DTO;未配置或版本不受支持时省略 |
user | — | 恒不出现(omitempty 且不预载) |
列表与查询
GET /api/proxies
返回当前登录用户的全部隧道(不分页),按创建时间倒序排列。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求示例
curl https://api.hyperfrp.com/api/proxies \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies", 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 为隧道 DTO 数组(可为空数组),字段见「隧道 DTO 字段」总表。
响应示例
{
"code": 0,
"message": "成功",
"data": [
{
"id": 42,
"name": "web-ssh",
"type": "tcp",
"nodeId": 2,
"localIp": "127.0.0.1",
"localPort": 22,
"remotePort": 30001,
"domain": "",
"comment": "内网 SSH",
"status": "running",
"enabledUser": true,
"statusAdmin": true,
"adminReason": "",
"trafficInBytes": 1048576,
"trafficOutBytes": 2097152,
"useEncryption": true,
"useCompression": false,
"transportProtocol": "tcp",
"proxyProtocolVersion": "",
"ccProtectionEnabled": false,
"sqlProtectionEnabled": false,
"xssProtectionEnabled": false,
"bandwidthLimit": "",
"maxConnections": 0,
"secretConfigured": false,
"configurationComplete": true,
"createdAt": "2026-09-19T10:00:00+08:00",
"updatedAt": "2026-09-19T12:30:00+08:00",
"node": {
"id": 2,
"name": "华南-广东-01",
"host": "gd01.hyperfrp.com",
"port": 7000,
"domain": "gd01.hyperfrp.com",
"location": "中国 广东 广州",
"status": "online"
}
}
]
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 数据库查询失败 | 500 | {"code":500,"message":"获取隧道列表失败"} |
GET /api/proxies/search
分页搜索当前用户的隧道,支持关键词、类型、节点、启用状态与运行状态过滤,以及白名单字段排序。响应返回完整隧道模型(非 DTO)。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Query)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | 否 | 按隧道名称模糊匹配(SQL LIKE %keyword%) |
type | string | 否 | 按类型精确过滤(tcp / udp / http / https / stcp / sudp / xtcp / tcpmux) |
nodeId | number | 否 | 按节点 ID 精确过滤(大于 0 时生效) |
enabled | string | 否 | 按用户侧启用状态过滤:仅字符串 "true" 视为 true,其余任何值(含 "false")均按 false 过滤;留空不过滤 |
status | string | 否 | 按运行状态精确过滤(pending / stopped / running / error / disabled) |
page | number | 否 | 页码,默认 1,上限 10000 |
pageSize | number | 否 | 每页条数,默认 10,上限 100 |
sortBy | string | 否 | 排序字段,白名单:createdAt / updatedAt / name / type / status / enabled / localPort / remotePort;其他值一律回退 createdAt |
sortOrder | string | 否 | ASC(大小写均可)升序,其余一律降序(默认 DESC) |
请求示例
curl "https://api.hyperfrp.com/api/proxies/search?keyword=web&type=tcp&nodeId=2&enabled=true&page=1&pageSize=10&sortBy=updatedAt&sortOrder=DESC" \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/search?keyword=web&type=tcp&nodeId=2&enabled=true&page=1&pageSize=10&sortBy=updatedAt&sortOrder=DESC', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/search?keyword=web&type=tcp&nodeId=2&enabled=true&page=1&pageSize=10&sortBy=updatedAt&sortOrder=DESC',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/search?keyword=web&type=tcp&nodeId=2&enabled=true&page=1&pageSize=10&sortBy=updatedAt&sortOrder=DESC", 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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
proxies | array | 完整隧道模型数组,字段见「完整隧道字段」总表;node 为预载的完整节点对象。注意:搜索结果不会回填 secretConfigured 与 protocolConfig 虚拟字段——secretConfigured 恒为 false、protocolConfig 恒省略,需以详情接口为准 |
pagination.total | number | 过滤后的总条数 |
pagination.page | number | 当前页码(归一化后的实际值) |
pagination.pageSize | number | 每页条数(归一化后的实际值) |
pagination.totalPages | number | 总页数(向上取整) |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"proxies": [
{
"id": 42,
"userId": 1001,
"nodeId": 2,
"node": { "id": 2, "name": "华南-广东-01", "host": "gd01.hyperfrp.com" },
"name": "web-ssh",
"type": "tcp",
"localIp": "127.0.0.1",
"localPort": 22,
"remotePort": 30001,
"domain": "",
"subDomain": "",
"locations": "",
"hostHeaderRewrite": "",
"headers": "",
"plugin": "",
"pluginParams": "",
"pluginCrtPath": "",
"pluginKeyPath": "",
"useEncryption": true,
"useCompression": false,
"transportProtocol": "tcp",
"proxyProtocolVersion": "",
"extraParams": "",
"status": "running",
"enabledUser": true,
"statusAdmin": true,
"adminReason": "",
"trafficInBytes": 1048576,
"trafficOutBytes": 2097152,
"lastActiveAt": null,
"comment": "内网 SSH",
"createdAt": "2026-09-19T10:00:00+08:00",
"updatedAt": "2026-09-19T12:30:00+08:00",
"ccProtectionEnabled": false,
"sqlProtectionEnabled": false,
"xssProtectionEnabled": false,
"forceOfflineGeneration": 0,
"configurationComplete": true,
"secretConfigured": false
}
],
"pagination": {
"total": 1,
"page": 1,
"pageSize": 10,
"totalPages": 1
}
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 查询参数绑定失败 | 400 | {"code":400,"message":"无效的查询参数"} |
| 统计总数失败 | 500 | {"code":500,"message":"统计隧道数量失败"} |
| 查询列表失败 | 500 | {"code":500,"message":"搜索隧道失败"} |
创建与批量
POST /api/proxies
创建一条属于当前用户的隧道。服务端在事务内对用户与节点行加锁后完成全部校验并写入,避免并发创建下的端口 / 域名 / 配额竞争。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
隧道类型枚举(type)
| 值 | 说明 |
|---|---|
tcp | TCP 转发,需 remote_port |
udp | UDP 转发,需 remote_port |
http | HTTP 反向代理,需 domains(按域名路由) |
https | HTTPS 反向代理,需 domains,可选本地证书插件路径 |
stcp | 安全 TCP(secret key 访问),需 remote_port 与 secretConfig.sk |
sudp | 安全 UDP(secret key 访问),需 remote_port 与 secretConfig.sk |
xtcp | P2P 穿透 TCP,需 secretConfig.sk |
tcpmux | TCP 复用(httpconnect 多路复用器),需 domains 与 protocolConfig.multiplexer |
类型值大小写不敏感(服务端统一转小写),其余值一律拒绝。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 隧道名称,1–100 个字符,仅允许字母、数字、下划线与短横线;同一用户内唯一 |
type | string | 是 | 隧道类型,枚举见上表 |
local_ip | string | 是 | 本地服务地址,必须是 IP 地址(IPv4 / IPv6,如 127.0.0.1、::1)或合法主机名(如 localhost、nas.lan),不带端口与协议前缀,≤255 字符 |
local_port | number | 是 | 本地服务端口,1–65535 |
remote_port | number | 类型相关 | 远程端口。tcp/udp/stcp/sudp 必填:1–65535、在节点允许的端口范围内且未被该节点其他隧道占用;http/https/tcpmux 忽略(强制置 0) |
domains | string | 类型相关 | 绑定域名。注意是英文逗号分隔的字符串而非数组(如 "a.example.com,b.example.com")。http/https 必填、tcpmux 必填;tcp/udp/stcp/sudp 强制清空。每段域名 trim + 转小写、去重,单段 ≤253 字符,拼接后总长 ≤255 字符;仅允许字母 / 数字 / 连字符 / 点(不支持 * 通配符),拒绝 javascript: / data: / vbscript: / file: 前缀 |
comment | string | 否 | 备注,≤500 字符 |
nodeId | number | 是 | 目标节点 ID(注意此键为小驼峰) |
use_encryption | boolean | 否 | 是否启用传输加密,默认 false |
use_compression | boolean | 否 | 是否启用传输压缩,默认 false |
transport_protocol | string | 否 | 传输协议:空串视为 tcp;仅允许 tcp / quic。quic 要求目标节点已开启 QUIC |
proxy_protocol_version | string | 否 | Proxy Protocol 版本:空串或 disabled 视为不启用;tcp 仅允许 v1 / v2,udp 仅允许 v2,其他类型提交任何非空值均报错 |
plugin_crt_path | string | 否 | HTTPS 插件证书路径,仅 https 类型保留(其他类型强制清空),≤255 字符;允许 Windows 反斜杠与空格,不允许双引号与换行等控制字符 |
plugin_key_path | string | 否 | HTTPS 插件私钥路径,约束同上 |
cc_protection_enabled | boolean | 否 | CC 防护开关,默认 false。开启后未显式提交规则时套用默认规则 {"rate":20,"burst":40} |
sql_protection_enabled | boolean | 否 | SQL 注入防护开关,默认 false。仅 http 类型隧道,或已开启服务端 HTTPS 解密(tls_terminate_enabled,见下)的 https 隧道可开启,其余组合提交 true 返回 400;开启后 frps 对该隧道请求做高危 SQL 注入检测,命中直接返回 403 |
xss_protection_enabled | boolean | 否 | XSS 防护开关,默认 false,约束同上 |
tls_terminate_enabled | boolean | 否 | HTTPS 服务端解密开关,默认 false,仅 https 类型隧道可开启(其余类型提交 true 返回 400)。开启后需把证书与私钥上传到平台(见下方「HTTPS 隧道证书」),由节点在服务端解开访客的 HTTPS 连接再转发,本地服务直连明文 HTTP、无需本地证书路径;证书未上传或无效期间自动保持不解密的原样转发 |
tls_cert_id | number | 否 | 可选:HTTPS 隧道绑定一张本人已上传的未绑定证书(证书列表接口 data.certs[].id,未绑定行 proxyId 为 0)。绑定校验(属主、仍未绑定、证书覆盖全部绑定域名且在有效期内)在创建事务内完成,任一不通过整次创建失败回滚,错误信息与上传校验同文案;非 https 类型携带该字段同样返回 400。0 或不传表示走「创建后自行上传证书」路径 |
protocolConfig | object | 否 | 非敏感权威协议配置扩展字段(可选),结构见下 |
secretConfig | object | 类型相关 | 敏感参数配置,结构见下。stcp/sudp/xtcp 必填且 sk 非空(fail-closed);普通类型可选。提交后 AES-GCM 加密落库,任何接口不再返回明文 / 密文 |
protocolConfig(ProxyAuthorizedConfig)扩展字段:表字段(type / remote_port / domains / use_encryption 等)是权威来源,此对象只补充表内不存在的扩展项,全部可选、经规范化后落库——
| 字段 | 类型 | 说明 |
|---|---|---|
customDomains | string[] | 附加路由域名(会 trim / 小写 / 排序 / 去重) |
subdomain | string | 子域名 |
locations | string[] | http/https 路由路径 |
hostHeaderRewrite | string | Host 头重写 |
headers / responseHeaders | object | 附加请求 / 响应头(键做 canonical MIME 规范化,各 ≤20 条,键值不得含控制字符) |
routeByHTTPUser | string | 按用户路由 |
group | string | 负载均衡组名(组密钥走 secretConfig.groupKey) |
multiplexer | string | tcpmux 复用器,仅允许 httpconnect;tcpmux 类型必填 |
transportProtocol | string | 仅允许 tcp / quic |
bandwidthLimit / bandwidthLimitMode | string | 带宽上限及模式(client / server) |
allowUsers | string[] | stcp/sudp/xtcp 允许访问用户,≤50 条 |
pluginCrtPath / pluginKeyPath | string | HTTPS 插件证书 / 私钥路径 |
超限(单字段 >200 字符、配置 JSON >32KB)或含未知字段时整体拒绝。其余未列出的字段(version、remotePort、type 等)由服务端按表字段自动填充,客户端提交值以表字段为准。
secretConfig(ProxySecretConfig,仅出现在请求中):
| 字段 | 类型 | 说明 |
|---|---|---|
sk | string | stcp/sudp/xtcp 访问密钥(必填于这三类),≤128 字符且不得含控制字符 |
groupKey | string | 负载均衡组密钥,可选 |
httpUser / httpPwd | string | http/https 基础认证用户名 / 密码,可选 |
请求示例
curl -X POST https://api.hyperfrp.com/api/proxies \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "web-ssh",
"type": "tcp",
"local_ip": "127.0.0.1",
"local_port": 22,
"remote_port": 30001,
"nodeId": 2,
"use_encryption": true,
"use_compression": false,
"transport_protocol": "tcp",
"comment": "内网 SSH"
}'// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
const res = await fetch('https://api.hyperfrp.com/api/proxies', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
res = requests.post(
'https://api.hyperfrp.com/api/proxies',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/proxies", 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)
}校验流程与错误场景
服务端按以下顺序校验(都在同一事务内,行级锁保护)。注意:普通用户创建入口保持历史兼容,所有业务校验失败(含端口占用、域名冲突、配额已满等冲突类错误)统一返回 HTTP 400 + code: 400,并以 message 区分具体场景;HTTP 409 仅出现在更新 / 绑定域名 / 切换节点的冲突分支。
| 场景 | HTTP | 说明 |
|---|---|---|
| 请求体无法解析为 JSON | 400 | 无效的请求数据 |
| name / type / local_ip / local_port / nodeId 缺失或为零值 | 400 | 请填写所有必填字段:名称、类型、本地IP、本地端口、节点 |
| 名称不符合字符 / 长度规则;local_ip / comment / 证书路径超长 | 400 | 分别提示:隧道名称长度必须在 1-100 个字符之间、隧道名称只允许包含字母、数字、下划线和短横线、本地 IP 不能超过 255 个字符、备注不能超过 500 个字符、HTTPS 插件证书路径不能超过 255 个字符 |
local_ip 不是 IP 地址或合法主机名;证书路径含双引号或控制字符 | 400 | 本地 IP 必须是合法的 IP 地址或主机名 / HTTPS 插件证书路径不能包含引号或控制字符 |
local_port 越界 | 400 | 本地端口必须在 1-65535 之间 |
| 所选节点不存在 | 400 | 所选节点不存在 |
| 节点要求实名而当前账户未实名 | 400 | 使用节点 [节点名] 需要先完成实名认证;判据为节点开关 requireRealname(默认开启)× 账户 isVerified,与节点所在地区无关 |
| 隧道配额已满(用户 / 用户组配额取大者) | 400 | 隧道创建失败:隧道配额已满 (N个),无法创建更多隧道 |
| type 不在枚举内 | 400 | 不支持的隧道类型:<值>。允许的类型为: tcp, udp, http, https, stcp, sudp, xtcp, tcpmux |
节点配置了 allowedProtocols 且不含该类型 | 400 | 节点 [节点名] 不允许创建 <TYPE> 类型隧道 |
节点状态不可用(仅 online / api_only / unreachable 可建) | 400 | 节点 '节点名' 当前不在服务状态,请选择其他节点 |
| 名称与当前用户既有隧道重名 | 400 | 已存在名为 '<名称>' 的隧道,请使用其他名称 |
transport_protocol 非法 | 400 | 传输协议只支持 tcp 或 quic |
quic 但节点未开启 QUIC | 400 | 所选节点未开启 QUIC,无法使用 QUIC 传输协议 |
proxy_protocol_version 与类型不匹配 | 400 | TCP 类型仅支持 proxy protocol v1 或 v2 / UDP 类型仅支持 proxy protocol v2 / 仅 TCP 或 UDP 类型支持 Proxy Protocol |
remote_port 越界 | 400 | 远程端口必须在 1-65535 之间 |
remote_port 不在节点允许的端口范围 | 400 | 远程端口 <N> 不在节点允许的端口范围内 |
remote_port 已被该节点其他隧道占用 | 400 | 远程端口 <N> 在节点 <节点名> 上已被占用,请更换 |
http/https/tcpmux 未提供 domains | 400 | HTTP/HTTPS 类型隧道必须指定绑定域名 / TCPMUX 类型隧道必须指定路由域名 |
| 域名格式无效 / 总长超 255 | 400 | 域名格式无效: <域名> / 自定义域名总长度不能超过 255 个字符 |
| 域名已被同节点其他隧道占用 | 400 | 域名 <域名> 已被节点 [节点名] 上的隧道 [隧道名] 占用 |
tcpmux 未提供 protocolConfig.multiplexer | 400 | TCPMUX 类型隧道必须配置 multiplexer(httpconnect) |
stcp/sudp/xtcp 未提供 secretConfig.sk | 400 | STCP/SUDP/XTCP 类型隧道必须提供 sk 密钥 |
protocolConfig / secretConfig 含未知字段或超限 | 400 | 隧道权威配置格式无效或超出安全限制 / 隧道敏感配置格式无效或超出安全限制 |
| 敏感配置加密器不可用 / 加密失败 | 500 | 隧道敏感配置加密不可用,已拒绝操作 / 隧道敏感配置加密失败 / 创建隧道失败 |
响应字段
HTTP 201。data 为完整隧道模型(含预载 node,user 不返回),字段见「完整隧道字段」总表。新隧道初始态:enabledUser=true、statusAdmin=true、status="stopped",secretConfigured / configurationComplete 按实际配置计算。
响应示例
{
"code": 0,
"message": "创建成功",
"data": {
"id": 42,
"userId": 1001,
"nodeId": 2,
"node": { "id": 2, "name": "华南-广东-01", "host": "gd01.hyperfrp.com", "port": 7000 },
"name": "web-ssh",
"type": "tcp",
"localIp": "127.0.0.1",
"localPort": 22,
"remotePort": 30001,
"domain": "",
"subDomain": "",
"pluginCrtPath": "",
"pluginKeyPath": "",
"useEncryption": true,
"useCompression": false,
"transportProtocol": "tcp",
"proxyProtocolVersion": "",
"extraParams": "",
"status": "stopped",
"enabledUser": true,
"statusAdmin": true,
"adminReason": "",
"trafficInBytes": 0,
"trafficOutBytes": 0,
"lastActiveAt": null,
"comment": "内网 SSH",
"createdAt": "2026-09-19T10:00:00+08:00",
"updatedAt": "2026-09-19T10:00:00+08:00",
"ccProtectionEnabled": false,
"sqlProtectionEnabled": false,
"xssProtectionEnabled": false,
"forceOfflineGeneration": 0,
"configurationComplete": true,
"secretConfigured": false
}
}注意事项
domains字段虽然名字是复数,但类型是逗号分隔字符串,不是数组;提交数组会导致绑定失败。- 域名不支持
*通配符(格式正则不允许),泛域名场景请逐个提交具体子域名。 remote_port的节点允许范围判断优先级:节点配置了allowPortRanges(多段)时必须在任一段内;否则按allowedPortsStart–allowedPortsEnd(两者均 >0 时);两者都未配置则不限制范围。随机端口接口(见下)的取值范围只按allowedPortsStart–End计算,两者口径可能不同。secretConfig一经提交即 AES-GCM 加密落库;响应中只有secretConfigured布尔标记,sk 等明文不再可获取,请自行妥善保存。cc_protection_enabled=true且未提交规则时,服务端套用默认规则{"rate":20,"burst":40}并以cc_rules字段回显。sql_protection_enabled/xss_protection_enabled仅对type=http隧道生效:其余类型提交true返回 400「SQL/XSS 请求防护仅支持 HTTP 类型隧道(frps 只能检测 HTTP vhost 明文请求)」。- 开启请求防护后,frps 对该隧道的请求(路径与查询串、全部请求头、≤2MiB 的 POST 请求体)做高危 SQL/XSS 特征检测,命中直接返回 403,并产生
source=http_waf的拦截日志(见用户章「隧道防护日志」);拦截规则集由面板统一维护,节点每 5 分钟拉取新版本规则。
POST /api/proxies/batch-delete
批量删除当前用户名下的隧道。非本人或不存在的 ID 会被静默忽略(不报错),返回实际删除数量;仅当一条都删不到时返回 404。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ids | number[] | 是 | 待删除的隧道 ID 列表,不得为空数组 |
请求示例
curl -X POST https://api.hyperfrp.com/api/proxies/batch-delete \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "ids": [42, 43, 44] }'const res = await fetch('https://api.hyperfrp.com/api/proxies/batch-delete', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <token>',
},
body: JSON.stringify({ "ids": [42, 43, 44] })
});
const data = await res.json();
console.log(data);import requests
res = requests.post(
'https://api.hyperfrp.com/api/proxies/batch-delete',
headers={'Authorization': 'Bearer <token>'},
json={
'ids': [
42,
43,
44
]
},
)
data = res.json()
print(data)package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
var payload bytes.Buffer
json.NewEncoder(&payload).Encode(map[string]any{
"ids": []any{
42,
43,
44,
},
})
req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/proxies/batch-delete", &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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
message | string | 成功删除 N 个隧道(N 为实际删除数量,可能小于 ids 长度) |
响应示例
{
"code": 0,
"message": "成功",
"data": { "message": "成功删除 3 个隧道" }
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
ids 缺失或为空数组 | 400 | 请提供有效的隧道ID列表 |
| 列表中的 ID 均不属于当前用户(或不存在) | 404 | 没有找到任何属于您的隧道进行删除,请检查ID是否正确 |
| 数据库删除失败 | 500 | 批量删除隧道失败 |
POST /api/proxies/batch-status
批量启用 / 禁用当前用户名下的隧道(写 enabledUser 开关)。非本人或不存在的 ID 静默忽略;一条都更新不到时返回 404。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ids | number[] | 是 | 隧道 ID 列表,不得为空数组 |
enable | boolean | 是 | true 批量启用,false 批量禁用 |
请求示例
curl -X POST https://api.hyperfrp.com/api/proxies/batch-status \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "ids": [42, 43], "enable": false }'const res = await fetch('https://api.hyperfrp.com/api/proxies/batch-status', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <token>',
},
body: JSON.stringify({ "ids": [42, 43], "enable": false })
});
const data = await res.json();
console.log(data);import requests
res = requests.post(
'https://api.hyperfrp.com/api/proxies/batch-status',
headers={'Authorization': 'Bearer <token>'},
json={
'ids': [
42,
43
],
'enable': false
},
)
data = res.json()
print(data)package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
var payload bytes.Buffer
json.NewEncoder(&payload).Encode(map[string]any{
"ids": []any{
42,
43,
},
"enable": false,
})
req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/proxies/batch-status", &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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
message | string | 成功启用 N 个隧道 或 成功禁用 N 个隧道(N 为实际更新数量) |
响应示例
{
"code": 0,
"message": "成功",
"data": { "message": "成功禁用 2 个隧道" }
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
ids 缺失或为空数组 | 400 | 请提供有效的隧道ID列表 |
| 列表中的 ID 均不属于当前用户(或不存在) | 404 | 没有找到任何属于您的隧道进行更新,请检查ID是否正确 |
| 数据库更新失败 | 500 | 批量更新隧道状态失败 |
注意事项
- 无论启用还是禁用,本接口都会把
status置为stopped(启用后等待 FRPS 上报,回到running需要客户端重新连接)。 - 禁用不会修改
statusAdmin(管理员侧开关);管理员禁用的隧道即使用户启用也无法运行。
端口与详情
GET /api/proxies/random-port/:nodeId
为指定节点随机取一个当前未被占用的远程端口,供创建隧道时预填。端口不会预留,创建时仍会做占用校验。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
nodeId | number | 是 | 节点 ID |
请求示例
curl https://api.hyperfrp.com/api/proxies/random-port/2 \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/random-port/2', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/random-port/2',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/random-port/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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
port | number | 随机可用端口 |
响应示例
{
"code": 0,
"message": "成功",
"data": { "port": 30017 }
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
nodeId 非数字 | 400 | 无效的节点ID |
| 节点不存在 | 400 | 节点未找到 |
| 节点端口范围配置不正确(起始 ≥ 结束) | 400 | 节点的端口范围配置不正确,起始端口必须小于结束端口 |
| 连续 100 次随机均撞上已占用端口 | 400 | 尝试多次后仍未找到可用端口,请稍后重试或检查节点端口范围 |
注意事项
- 取值范围来自节点的
allowedPortsStart–allowedPortsEnd;未配置(≤0)时分别回退为 10000 与 65535。 - 返回的端口只保证「调用时刻未被占用」,不写入任何预留记录;高并发下仍可能与其他用户创建冲突,以创建接口的校验结果为准。
GET /api/proxies/:id
获取单条隧道详情。仅能查看本人隧道;隧道不存在或属于他人时一律按 404 处理(权限隐藏,不区分两种情况)。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | number | 是 | 隧道 ID |
请求示例
curl https://api.hyperfrp.com/api/proxies/42 \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/42',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/42", 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 为完整隧道模型(含预载 node,且已回填 secretConfigured / protocolConfig 虚拟字段),字段见「完整隧道字段」总表。
响应示例
{
"code": 0,
"message": "成功",
"data": {
"id": 42,
"userId": 1001,
"nodeId": 2,
"node": { "id": 2, "name": "华南-广东-01", "host": "gd01.hyperfrp.com", "port": 7000, "domain": "gd01.hyperfrp.com", "location": "中国 广东 广州", "status": "online" },
"name": "web-ssh",
"type": "tcp",
"localIp": "127.0.0.1",
"localPort": 22,
"remotePort": 30001,
"domain": "",
"useEncryption": true,
"useCompression": false,
"transportProtocol": "tcp",
"proxyProtocolVersion": "",
"status": "running",
"enabledUser": true,
"statusAdmin": true,
"adminReason": "",
"trafficInBytes": 1048576,
"trafficOutBytes": 2097152,
"comment": "内网 SSH",
"ccProtectionEnabled": false,
"sqlProtectionEnabled": false,
"xssProtectionEnabled": false,
"forceOfflineGeneration": 0,
"configurationComplete": true,
"secretConfigured": false,
"createdAt": "2026-09-19T10:00:00+08:00",
"updatedAt": "2026-09-19T12:30:00+08:00"
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 数据库查询失败 | 500 | 查询隧道失败 |
PUT /api/proxies/:id
更新本人隧道。字符串字段「空串 / 未提交 = 不修改」;布尔字段用指针语义「未提交 = 不修改」;提交 nodeId 且与现值不同时进入「切换节点」分支(此时其余字段全部忽略,只处理换节点)。更新成功后隧道 status 置为 stopped,等待客户端按新配置重连。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | number | 是 | 隧道 ID |
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 否 | 新名称。非空且与现值不同时校验:1–100 字符、仅字母 / 数字 / 下划线 / 短横线,且不得与本用户其他隧道重名 |
type | string | 否 | 切换隧道类型(转小写后校验枚举)。切换到 stcp/sudp/xtcp 时,若原隧道未设置过敏感配置且本次未提交 secretConfig,拒绝;切换到 tcpmux 时必须同时提交 protocolConfig.multiplexer |
local_ip | string | 否 | 非空才更新;与当前值不同时按创建接口的规则校验(IP 地址或合法主机名) |
local_port | number | 否 | 大于 0 才更新 |
remote_port | number | 否 | 仅 tcp/udp/stcp/sudp 生效:大于 0 且与现值不同时做节点内占用校验(冲突返回 409);http/https 忽略;tcpmux 强制置 0 |
domains | string | 否 | 仅 http/https/tcpmux 生效:非空且与现值不同时做域名冲突校验(冲突返回 409) |
use_encryption | boolean | 否 | 布尔指针语义:未提交不修改 |
use_compression | boolean | 否 | 布尔指针语义:未提交不修改 |
transport_protocol | string | 否 | 非空才更新;仅 tcp / quic,且目标节点须开启 QUIC |
proxy_protocol_version | string | 否 | 非空才更新;tcp 仅 v1 / v2,udp 仅 v2,其他类型报错。类型改为非 tcp/udp 时自动清空 |
plugin_crt_path / plugin_key_path | string | 否 | 仅 https 类型生效,非空才更新;不允许双引号与控制字符 |
cc_protection_enabled | boolean | 否 | 布尔指针语义:未提交不修改 |
sql_protection_enabled | boolean | 否 | 布尔指针语义:未提交不修改。仅 http 类型隧道,或已开启服务端 HTTPS 解密的 https 隧道可开启;校验按「合并后状态」进行——合并结果不在可开启范围内(如 https 隧道关闭该开关、或隧道切为其他类型)时,若原值开启且本次未显式提交 false,返回 400 |
xss_protection_enabled | boolean | 否 | 布尔指针语义:未提交不修改,约束同上 |
tls_terminate_enabled | boolean | 否 | HTTPS 服务端解密开关。布尔指针语义:未提交不修改,仅 https 类型隧道可开启;合并后为非 https 类型时提交 true 返回 400 |
nodeId | number | 否 | 非零且与现值不同时切换节点(见下) |
protocolConfig | object | 否 | 权威协议配置扩展字段,覆盖语义;未提交时沿用已保存值(不会丢失 locations / headers 等) |
secretConfig | object | 否 | 显式替换敏感配置(结构同创建接口);未提交时保留原值 |
clearSecretConfig | boolean | 否 | true 显式清空敏感配置(优先于 secretConfig) |
切换节点分支(nodeId 非零且变化)的校验顺序:目标节点存在(不存在返回 404)→ 目标节点状态须为 online / api_only / unreachable(否则 400)→ 当前账户有权使用目标节点(否则 403,判据同创建隧道:节点 requireRealname 开启而账户未实名即拒绝)→ 原隧道的远程端口(tcp/udp/stcp/sudp)或域名(http/https/tcpmux)在新节点上不冲突(冲突返回 409)。切换节点时 name / type / 地址端口等其余字段不会被处理。
请求示例
curl -X PUT https://api.hyperfrp.com/api/proxies/42 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"local_port": 2222,
"remote_port": 30002,
"use_encryption": true
}'// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
const res = await fetch('https://api.hyperfrp.com/api/proxies/42', {
method: 'PUT',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
res = requests.put(
'https://api.hyperfrp.com/api/proxies/42',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/proxies/42", 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 为完整隧道模型(含预载 node,已回填虚拟字段),字段见「完整隧道字段」总表。
响应示例
{
"code": 0,
"message": "成功",
"data": {
"id": 42,
"name": "web-ssh",
"type": "tcp",
"localIp": "127.0.0.1",
"localPort": 2222,
"remotePort": 30002,
"status": "stopped",
"enabledUser": true,
"statusAdmin": true,
"configurationComplete": true,
"secretConfigured": false,
"updatedAt": "2026-09-19T13:00:00+08:00"
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 请求体无法解析 | 400 | 无效的请求数据 |
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 名称 / 类型 / 传输协议 / Proxy Protocol 校验失败 | 400 | 消息同创建接口对应条目 |
local_ip 改为非法地址,或证书路径含双引号 / 控制字符 | 400 | 本地 IP 必须是合法的 IP 地址或主机名 / HTTPS 插件证书路径不能包含引号或控制字符 |
| 切换到需要 sk 的类型但无密钥 | 400 | STCP/SUDP/XTCP 类型隧道必须提供 sk 密钥 |
| 切换到 tcpmux 但缺 multiplexer / 路由域名 | 400 | TCPMUX 类型隧道必须配置 multiplexer(httpconnect) / TCPMUX 类型隧道必须指定路由域名 |
| 名称与本用户其他隧道重名 | 409 | 您已存在名为 '<名称>' 的隧道,请使用其他名称 |
| 新远程端口在当前节点被占用 | 409 | 远程端口 <N> 在当前节点上已被隧道 [<名称>] 占用 |
| 新域名被同节点其他隧道占用 | 409 | 服务端返回的冲突描述(域名 <域名> 已被节点 [节点名] 上的隧道 [隧道名] 占用) |
| 目标新节点不存在 | 404 | 目标新节点不存在 |
| 目标新节点状态不可用 | 400 | 新节点 '<名称>' 当前不可用,无法切换 |
| 目标新节点要求实名而账户未实名 | 403 | 使用节点 [<名称>] 需要先完成实名认证;判据与创建隧道一致(节点 requireRealname × 账户 isVerified),不再按用户组或地区裁决 |
| 目标新节点上端口 / 域名冲突 | 409 | 远程端口 <N> 在新节点 [<名称>] 上已被隧道 [<名称>] 占用 等 |
| QUIC 但节点未开启 | 400 | 当前节点未开启 QUIC,无法使用 QUIC 传输协议 |
| 已保存的 protocolConfig 损坏 / 版本不受支持 | 400 | 已保存的隧道权威配置无效,请重新提交 protocolConfig |
| 持久化失败(内部错误) | 500 | 更新隧道失败 |
注意事项
- 本接口不支持修改备注
comment:请求体中没有该字段,备注仅在创建时可设置。 secretConfig与clearSecretConfig的组合语义:只提交secretConfig= 替换;只提交clearSecretConfig: true= 清空;两者都不提交 = 保留原值。- 普通字段与敏感密文、权威配置重建在同一事务内原子提交,任一步失败整体回滚,不会出现部分更新。
DELETE /api/proxies/:id
删除本人的一条隧道。隧道不存在或属于他人时按 404 处理(权限隐藏)。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求示例
curl -X DELETE https://api.hyperfrp.com/api/proxies/42 \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.delete(
'https://api.hyperfrp.com/api/proxies/42',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("DELETE", "https://api.hyperfrp.com/api/proxies/42", 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 | string | 固定为 隧道已删除 |
响应示例
{
"code": 0,
"message": "成功",
"data": { "message": "隧道已删除" }
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 数据库删除失败 | 500 | 删除隧道失败 |
状态与域名
PUT /api/proxies/:id/status
切换本人隧道的用户侧启用开关(enabledUser)。禁用时同时把 status 置为 stopped;启用不改变 status(等 FRPS 上报后回到 running)。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enable | boolean | 是 | true 启用,false 禁用 |
请求示例
curl -X PUT https://api.hyperfrp.com/api/proxies/42/status \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "enable": false }'const res = await fetch('https://api.hyperfrp.com/api/proxies/42/status', {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <token>',
},
body: JSON.stringify({ "enable": false })
});
const data = await res.json();
console.log(data);import requests
res = requests.put(
'https://api.hyperfrp.com/api/proxies/42/status',
headers={'Authorization': 'Bearer <token>'},
json={
'enable': false
},
)
data = res.json()
print(data)package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
var payload bytes.Buffer
json.NewEncoder(&payload).Encode(map[string]any{
"enable": false,
})
req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/proxies/42/status", &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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
message | string | 隧道已启用 或 隧道已禁用 |
proxy | object | 更新后的完整隧道模型(字段见「完整隧道字段」总表;不预载 node) |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"message": "隧道已禁用",
"proxy": {
"id": 42,
"name": "web-ssh",
"type": "tcp",
"status": "stopped",
"enabledUser": false,
"statusAdmin": true
}
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 请求体无法解析 | 400 | 无效的请求数据 |
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 数据库保存失败 | 500 | 更新隧道状态失败 |
PUT /api/proxies/:id/bind-domain
为本人隧道绑定(更换)路由域名。仅 http / https 类型可用;tcpmux 类型需走更新接口。域名做冲突校验后以事务方式保存并重建权威配置,不会丢失既有扩展字段。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
domains | string | 是 | 新的绑定域名,英文逗号分隔的字符串(格式 / 长度规则同创建接口 domains) |
请求示例
curl -X PUT https://api.hyperfrp.com/api/proxies/43/bind-domain \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "domains": "blog.example.hyperfrp.com,www.example.hyperfrp.com" }'const res = await fetch('https://api.hyperfrp.com/api/proxies/43/bind-domain', {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <token>',
},
body: JSON.stringify({ "domains": "blog.example.hyperfrp.com,www.example.hyperfrp.com" })
});
const data = await res.json();
console.log(data);import requests
res = requests.put(
'https://api.hyperfrp.com/api/proxies/43/bind-domain',
headers={'Authorization': 'Bearer <token>'},
json={
'domains': 'blog.example.hyperfrp.com,www.example.hyperfrp.com'
},
)
data = res.json()
print(data)package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
var payload bytes.Buffer
json.NewEncoder(&payload).Encode(map[string]any{
"domains": "blog.example.hyperfrp.com,www.example.hyperfrp.com",
})
req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/proxies/43/bind-domain", &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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
message | string | 固定为 域名绑定成功 |
proxy | object | 更新后的完整隧道模型(字段见「完整隧道字段」总表;不预载 node) |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"message": "域名绑定成功",
"proxy": {
"id": 43,
"name": "web-blog",
"type": "http",
"domain": "blog.example.hyperfrp.com,www.example.hyperfrp.com",
"enabledUser": true,
"statusAdmin": true,
"configurationComplete": true
}
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 请求体无法解析 | 400 | 无效的请求数据 |
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 隧道类型不是 http / https | 400 | 只有 HTTP 和 HTTPS 类型的隧道才能绑定域名,当前隧道类型为 <TYPE> |
| 域名已被同节点其他隧道占用 | 409 | 域名 <域名> 已被节点 [节点名] 上的隧道 [隧道名] 占用 |
| 域名格式无效 | 409 | 域名格式无效: <域名>(冲突检查入口以 Conflict=true 回传格式错误) |
| 持久化失败(内部错误) | 500 | 绑定域名失败 / 检查域名冲突失败 |
配置生成与客户端辅助
GET /api/proxies/:id/config-preview
生成本人隧道的 FRPC 客户端配置预览,同时返回 INI(legacy 格式)与 TOML(新格式)两份文本。生成前会做传输协议 fail-closed 校验;隧道名称含配置文件不安全字符时拒绝生成。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求示例
curl https://api.hyperfrp.com/api/proxies/42/config-preview \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42/config-preview', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/42/config-preview',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/42/config-preview", 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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
ini | string | INI 格式配置全文 |
toml | string | TOML 格式配置全文 |
json | string | JSON 格式配置全文(与 frpc v1 配置结构一致,可直接作为 frpc -c xxx.json 使用) |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"ini": "[common]\nserver_addr = gd01.hyperfrp.com\nserver_port = 7000\nuser = \"AKxxxxxxxx\"\ntoken = \"<节点token>\"\n\n[web-ssh]\ntype = tcp\nmeta_tunnel_id = 42\nmeta_user_id = 1001\nlocal_ip = 127.0.0.1\nlocal_port = 22\nremote_port = 30001\nuse_encryption = true\n",
"toml": "serverAddr = \"gd01.hyperfrp.com\"\nserverPort = 7000\nuser = \"AKxxxxxxxx\"\n\n[auth]\nmethod = \"token\"\ntoken = \"<节点token>\"\n\n[[proxies]]\nname = \"web-ssh\"\ntype = \"tcp\"\nmetadatas.tunnel_id = \"42\"\nmetadatas.user_id = \"1001\"\nlocalIP = \"127.0.0.1\"\nlocalPort = 22\nremotePort = 30001\n\n[proxies.transport]\nuseEncryption = true\n",
"json": "{\n \"serverAddr\": \"gd01.hyperfrp.com\",\n \"serverPort\": 7000,\n \"user\": \"AKxxxxxxxx\",\n \"auth\": {\n \"method\": \"token\",\n \"token\": \"<节点token>\"\n },\n \"proxies\": [\n {\n \"name\": \"web-ssh\",\n \"type\": \"tcp\",\n \"metadatas\": {\n \"tunnel_id\": \"42\",\n \"user_id\": \"1001\"\n },\n \"localIP\": \"127.0.0.1\",\n \"localPort\": 22,\n \"remotePort\": 30001,\n \"transport\": {\n \"useEncryption\": true\n }\n }\n ]\n}\n"
}
}生成内容结构说明
- INI:
[common]段(server_addr/server_port/user=用户访问密钥 /token=节点 FRPS token;QUIC 时附加transport.protocol = "quic"),随后每个隧道一段[<隧道名>]:type、meta_tunnel_id、meta_user_id,非 https 类型输出local_ip/local_port;tcp/udp 追加remote_port,http/https 追加custom_domains;https 类型改为插件形式(plugin = https2http+plugin_local_addr/plugin_crt_path/plugin_key_path,证书路径留空时输出占位提示文本);按需追加use_encryption/use_compression/proxy_protocol_version。 - TOML:顶层
serverAddr/serverPort/user,[auth](method = "token"+ 节点 token),QUIC 时追加[transport];每个隧道一个[[proxies]]块:name/type/metadatas.tunnel_id/metadatas.user_id/localIP/localPort/remotePort/customDomains(数组);https 类型追加[proxies.plugin];加密 / 压缩 / Proxy Protocol 任一存在时追加[proxies.transport]。 - JSON:与 TOML 字段逐项一致(同一份数据在 frpc 里加载出的结构相同):顶层
serverAddr/serverPort/user/auth,QUIC 时追加transport.protocol;proxies为数组,每项含name/type/metadatas等,https 类型带plugin对象、不输出localIP/localPort;加密 / 压缩 / Proxy Protocol 任一存在时带transport对象。字符串按标准 JSON 转义,不做 HTML 转义。 - 合并下载(见下)复用同一套生成器,
[common]/ 顶层只出现一次,其后串联该节点全部已启用隧道。
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 传输协议非法或节点未开启 QUIC | 400 | 当前节点未开启 QUIC,无法使用 QUIC 传输协议 / 传输协议 "<值>" 不受支持,仅支持 tcp 或 quic |
| 隧道名称含配置文件不安全字符 | 500 | 隧道名称不符合配置格式要求 |
注意事项
- 配置中内嵌用户访问密钥(user)与节点 FRPS token(token),均为敏感凭据:预览文本请勿截图 / 转发到公开场合。
- 隧道名称允许中文与点号(
^[\p{L}\p{N}_.-]+$),但名称超长或含控制字符时生成器拒绝输出,需先改名。
POST /api/proxies/:id/quick-start-command
生成三平台的一键启动命令(使用下载站分发的官方 frpc 客户端拉起指定隧道)。命令内嵌用户访问密钥与面板 API 基址(取自节点配置并规范化,无尾斜杠);参数统一经单引号包裹,防 shell / PowerShell 注入。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求示例
curl -X POST https://api.hyperfrp.com/api/proxies/42/quick-start-command \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42/quick-start-command', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.post(
'https://api.hyperfrp.com/api/proxies/42/quick-start-command',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/proxies/42/quick-start-command", 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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 固定 true |
commands.windows | string | Windows(PowerShell)启动命令 |
commands.linux | string | Linux 启动命令 |
commands.macos | string | macOS 启动命令 |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"success": true,
"commands": {
"windows": "frpc.exe quick-start -u 'AKxxxxxxxx' -p 42 --api-url 'https://api.hyperfrp.com/api'",
"linux": "./frpc quick-start -u 'AKxxxxxxxx' -p 42 --api-url 'https://api.hyperfrp.com/api'",
"macos": "./frpc quick-start -u 'AKxxxxxxxx' -p 42 --api-url 'https://api.hyperfrp.com/api'"
}
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 用户访问密钥为空 | 500 | 无法获取用户的访问密钥 (Access Key) |
| 隧道关联节点信息丢失 | 500 | 隧道关联的节点信息丢失 |
| 节点面板 API 地址无效 | 400 | 节点面板 API 地址无效 |
注意事项
- 命令内嵌 accessKey(账号级凭据)明文:拿到命令即可用你的身份创建 / 修改隧道,请勿公开分享、截图或提交到代码仓库;泄露后应立即在控制台重置访问密钥(重置会使全部隧道强制下线)。
- 每次调用都会写入审计日志(动作
tunnel-quick-start)。
POST /api/proxies/:id/force-unregister
对本人单条隧道执行强制下线:事务内原子递增持久强制下线代次(forceOfflineGeneration + 1)并把 status 置为 stopped,同时尝试发送 Redis 即时下线信号。代次是下线意图的事实来源——即使即时通知失败,FRPS 也会在下次状态检查时关闭该隧道。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求示例
curl -X POST https://api.hyperfrp.com/api/proxies/42/force-unregister \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42/force-unregister', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.post(
'https://api.hyperfrp.com/api/proxies/42/force-unregister',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/proxies/42/force-unregister", 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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 固定 true |
message | string | 强制下线指令已发送成功;即时通知失败时追加 ;即时通知失败,已由持久下线记录兜底,将在节点下次状态检查时生效 |
forceOfflineFailed | boolean | true 表示 Redis 即时通知失败(持久代次已生效,仅延迟生效) |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"success": true,
"message": "强制下线指令已发送成功",
"forceOfflineFailed": false
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 代次递增 / 状态更新失败 | 500 | 强制下线失败 |
运行观测
GET /api/proxies/:id/events
查询本人隧道的启停日志(上线/离线历史),按时间倒序返回。事件由转发核心在隧道注册成功(proxy_created)/ 注销(proxy_closed)时上报落库,自功能上线起开始记录,无历史回填;保留 30 天(每日定时清理)。同一运行实例的同类型事件按唯一索引去重,转发核心重试重投不会产生重复记录。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Query)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | integer | 否 | 返回条数上限,缺省 50、上限 200。 |
请求示例
curl "https://api.hyperfrp.com/api/proxies/42/events?limit=50" \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42/events?limit=50', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/42/events?limit=50',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/42/events?limit=50", 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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 事件记录 ID |
eventType | string | running = 隧道上线,stopped = 隧道离线(取值口径与隧道 status 的运行态一致) |
remotePort | integer | 事件发生时的远程端口(离线事件取隧道当前值,可能为 0) |
runId | string | 转发核心运行实例标识前 8 位,用于关联同一次运行的上线/离线对 |
createdAt | string | 事件时间 |
响应示例
{
"code": 0,
"message": "成功",
"data": [
{
"id": 128,
"eventType": "stopped",
"remotePort": 30001,
"runId": "run-abc1",
"createdAt": "2026-10-04T09:12:35.120+08:00"
},
{
"id": 127,
"eventType": "running",
"remotePort": 30001,
"runId": "run-abc1",
"createdAt": "2026-10-04T08:02:11.480+08:00"
}
]
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 查询失败 | 500 | 查询启停日志失败 |
注意事项
- 记录自功能上线起才开始积累,旧隧道也不会有历史回填;隧道从未运行过时
data为空数组。 - frpc 每次重连都会产生一对新的上线/离线记录(运行实例标识不同),频繁重连会快速消耗 30 天保留窗口内的记录数。
GET /api/proxies/:id/traffic-history
查询本人隧道最近 N 分钟的流量历史,按 10 秒桶聚合升序返回,供实时带宽走势图使用。数据源是转发核心每 10 秒批量上报写入的流量历史(data_type='proxy');零流量时段不落行,响应中自然没有对应桶,调用方需自行补零。带宽即时性受核心上报周期限制(约 10~20 秒延迟)。
鉴权:JWT Bearer · 限流:无专用限流(建议客户端轮询间隔不低于 10 秒) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Query)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
minutes | integer | 否 | 查询窗口分钟数,缺省 30、上限 1440(一天)。 |
请求示例
curl "https://api.hyperfrp.com/api/proxies/42/traffic-history?minutes=30" \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42/traffic-history?minutes=30', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/42/traffic-history?minutes=30',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/42/traffic-history?minutes=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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
buckets | array | 10 秒桶序列,升序。每项含 time(桶起点秒级 Unix 时间戳)、inBytes、outBytes(该桶内的字节数) |
current | integer | 当前带宽(字节/秒):最近一桶 (inBytes + outBytes) / 10;超过 30 秒没有新桶时为 0 |
totals.trafficInBytes | integer | 隧道累计入站字节数 |
totals.trafficOutBytes | integer | 隧道累计出站字节数 |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"buckets": [
{ "time": 1797081120, "inBytes": 10240, "outBytes": 20480 },
{ "time": 1797081130, "inBytes": 5120, "outBytes": 0 }
],
"current": 512,
"totals": {
"trafficInBytes": 1073741824,
"trafficOutBytes": 2147483648
}
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
| 查询失败 | 500 | 查询流量历史失败 |
注意事项
- 空闲隧道的
buckets可能为空数组、current为 0,这是正常形态而非异常。 current只反映最近一个 10 秒桶的均速;需要按方向拆分的速率时,用最近一桶的inBytes / 10与outBytes / 10自行换算。
HTTPS 隧道证书
HTTPS 隧道默认由用户本地的 frpc 持有证书并处理 HTTPS。平台也支持把证书与私钥统一保存到平台(本节八个接口,含「我的证书」列表 / 详情、未绑定证书的上传 / 详情 / 删除,以及每隧道的上传 / 查询 / 删除),配合创建 / 更新隧道接口的 tls_terminate_enabled 开关使用:开关开启且证书已上传时,由节点(服务端)解开访客的 HTTPS 连接再进入防护与转发流程,CC 限流与 SQL / XSS 请求防护对该隧道生效。私钥 AES-GCM 加密落库,私钥明文与密文在任何接口都不回显;托管状态类接口只返回指纹 / 有效期 / 版本,证书详情接口额外返回公钥证书本身(公钥证书是公开件,访客本可从 TLS 握手中获取,不代表私钥泄露)。证书每次上传版本 +1,节点在轮询周期内自动换用新证书,无需重启隧道;证书被删除或尚未上传时,节点自动恢复为不解密的原样转发(隧道照常工作,但 SQL / XSS 请求防护不可用)。
隐私与安全提示:开启后节点将持有该证书并可解密该域名的全部流量。证书上传接口对证书做严格校验(公私钥配对、有效期、证书域名列表覆盖隧道全部域名),任何一项不通过整体拒绝。
列表接口只返回当前用户自己上传过的证书;隧道粒度的三个接口均要求本人隧道(按 user_id 归属校验,非本人隧道一律按不存在处理)。证书可以先上传为未绑定证书(POST /api/proxies/tls-certs,只校验配对与有效期,不校验域名覆盖),创建 HTTPS 隧道时通过创建请求的 tls_cert_id 选择绑定(届时校验域名覆盖,绑定失败则整次创建回滚);删除隧道后其证书自动回到未绑定状态,可被新隧道再次选择。
GET /api/proxies/tls-certs
查询当前用户全部已上传的托管证书,供「证书管理」页展示与「创建隧道」页选择已有证书。列表以证书为行(每条已上传的证书一行,未上传证书的隧道不出现),所属隧道与节点作为归属列。一次返回不分页,按最近上传时间倒序。响应不含证书 PEM,更不含私钥。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求示例
curl https://api.hyperfrp.com/api/proxies/tls-certs \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/tls-certs', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/tls-certs',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/tls-certs", 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.certs 为证书数组,每项字段:
| 字段 | 类型 | 说明 |
|---|---|---|
id | number | 证书记录 ID(全表唯一;创建隧道传 tls_cert_id、未绑定证书详情 / 删除都使用该值) |
proxyId | number | 所属隧道 ID;未绑定证书恒为 0 |
proxyName | string | 所属隧道名(未绑定证书为空串) |
domain | string | 绑定证书为隧道绑定域名(逗号分隔原样);未绑定证书为证书叶子 SAN(逗号分隔) |
nodeId | number | 所属节点 ID(未绑定证书为 0) |
nodeName | string | 所属节点名(未绑定证书为空串) |
tlsTerminateEnabled | boolean | 该隧道的服务端解密开关(未绑定证书为 false) |
proxyStatus | string | 隧道运行状态(口径同隧道模型 status;未绑定证书为空串) |
fingerprint | string | 叶子证书 SHA256 指纹(hex 小写) |
notBefore | number | 证书生效时间(Unix 秒) |
notAfter | number | 证书过期时间(Unix 秒) |
version | number | 托管版本号,每次上传 / 替换 +1 |
updatedAt | string | 最近上传 / 替换时间(RFC3339) |
dnsNames | string[] | 证书叶子 SAN 列表,仅未绑定证书返回(绑定证书的 SAN 走详情接口) |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"certs": [
{
"proxyId": 42,
"proxyName": "web",
"domain": "shop.example.com",
"nodeId": 2,
"nodeName": "华南-广东-01",
"tlsTerminateEnabled": true,
"proxyStatus": "running",
"fingerprint": "3f2a9c…(64 位 hex)",
"notBefore": 1758038400,
"notAfter": 1766140800,
"version": 3,
"updatedAt": "2026-09-26T15:04:05+08:00"
}
]
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 数据库查询失败 | 500 | 查询证书列表失败 |
注意事项
- 列表里的
notAfter用于前端到期提醒:已过期(红)/ 距今 30 天内即将到期(橙)/ 正常(绿),判定边界与服务端到期筛选口径完全一致。 - 过期或即将过期的证书不会被平台自动删除;由节点在握手时自行拒绝过期证书,请及时续期并重新上传。
POST /api/proxies/tls-certs
上传一张未绑定证书:只保存证书与私钥,不关联任何隧道。适合「先上传证书、创建 HTTPS 隧道时再选择」的流程——创建 HTTPS 隧道时在创建请求里携带本接口返回的证书 id(请求字段 tls_cert_id)即可完成绑定。校验与每隧道上传接口一致(公私钥配对、有效期、64KiB 上限),但因为尚无隧道,不校验域名覆盖。私钥 AES-GCM 加密落库,响应不含任何 PEM 或密文。
鉴权:JWT Bearer · 限流:无专用限流 · 缓存:NoCache
请求示例
curl -X POST https://api.hyperfrp.com/api/proxies/tls-certs \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"cert_pem":"-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----","key_pem":"-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----"}'const res = await fetch('https://api.hyperfrp.com/api/proxies/tls-certs', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <token>',
},
body: JSON.stringify({"cert_pem":"-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----","key_pem":"-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----"})
});
const data = await res.json();
console.log(data);import requests
res = requests.post(
'https://api.hyperfrp.com/api/proxies/tls-certs',
headers={'Authorization': 'Bearer <token>'},
json={
'cert_pem': '-----BEGIN CERTIFICATE-----
…
-----END CERTIFICATE-----',
'key_pem': '-----BEGIN PRIVATE KEY-----
…
-----END PRIVATE KEY-----'
},
)
data = res.json()
print(data)package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
var payload bytes.Buffer
json.NewEncoder(&payload).Encode(map[string]any{
"cert_pem": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----",
"key_pem": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----",
})
req, _ := http.NewRequest("POST", "https://api.hyperfrp.com/api/proxies/tls-certs", &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)
}请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cert_pem | string | 是 | 公钥证书 PEM 全文(含 BEGIN CERTIFICATE 行),上限 64KiB |
key_pem | string | 是 | 私钥 PEM 全文,仅用于配对校验与加密存储,永不回显,上限 64KiB |
响应字段
data 为证书托管摘要:
| 字段 | 类型 | 说明 |
|---|---|---|
id | number | 证书记录 ID(创建隧道时 tls_cert_id 使用该值) |
proxyId | number | 恒为 0(未绑定) |
fingerprint | string | 叶子证书 SHA256 指纹(hex 小写) |
notBefore | number | 证书生效时间(Unix 秒) |
notAfter | number | 证书过期时间(Unix 秒) |
version | number | 托管版本号,新证书为 1 |
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 请求体缺失字段 | 400 | 证书与私钥都不能为空 |
| 证书与私钥不配对 / 解析失败 | 400 | 证书与私钥解析失败或不配对… |
| 证书未生效或已过期 | 400 | 错误信息含 notBefore / notAfter 具体时间 |
| 单文件超过 64KiB | 400 | 证书文件超过 64KB 上限 / 私钥文件超过 64KB 上限 |
| 服务端加密器未配置 | 500 | 上传证书失败(fail-closed,拒绝明文落库) |
注意事项
- 未绑定证书不会出现在任何节点的下发链路里(节点按隧道拉取证书),上传后不产生任何线上效果。
- 同一张证书可以重复上传为多条记录,由用户自行管理;删除走未绑定证书删除接口。
GET /api/proxies/tls-certs/unbound/:certId
查询单张未绑定证书的详情,结构与绑定证书详情接口一致(叶子解析 + 证书链 + 公钥 PEM),但隧道 / 节点归属字段为空值,domain 取证书叶子 SAN。仅能查看本人上传且仍未绑定的证书。
鉴权:JWT Bearer · 限权:本人证书(非本人或已绑定时按业务错误返回 400) · 限流:无专用限流 · 缓存:NoCache
请求示例
curl https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11 \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11", 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)
}路径参数
| 参数 | 类型 | 说明 |
|---|---|---|
certId | number | 证书记录 ID(证书列表 data.certs[].id,未绑定行 proxyId 为 0) |
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 证书不存在 / 已绑定隧道 / 非本人证书 | 400 | 查询证书详情失败(未绑定行按 ID 与属主精确匹配) |
注意事项
- 已绑定到隧道的证书请走
GET /api/proxies/tls-certs/:proxyId(按隧道取详情)。
DELETE /api/proxies/tls-certs/unbound/:certId
删除当前用户的一张未绑定证书(配对的私钥密文一并删除,不可恢复)。已绑定到隧道的证书不在此删除——请走 DELETE /api/proxies/:id/tls-cert(删除后隧道回落为不解密的原样转发)。
鉴权:JWT Bearer · 限权:本人证书 · 限流:无专用限流 · 缓存:NoCache
请求示例
curl -X DELETE https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11 \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.delete(
'https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("DELETE", "https://api.hyperfrp.com/api/proxies/tls-certs/unbound/11", 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)
}响应示例
{
"code": 0,
"message": "成功",
"data": {
"message": "证书已删除"
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 证书不存在 / 已绑定隧道 / 非本人证书 | 400 | 证书未找到、已绑定隧道或您无权访问 |
注意事项
- 删除隧道不会删除证书:隧道删除(含批量删除、管理端删除)时其证书自动回到未绑定状态,仍可被新隧道选择。
GET /api/proxies/tls-certs/:proxyId
查询单张托管证书的详情:托管元数据 + 叶子证书解析(主题 / 颁发者 / 序列号 / 证书域名列表 / 签名与公钥算法)+ 证书链逐段 + 公钥证书 PEM 原文。所属隧道未上传证书时 data 为 null(不报错)。
鉴权:JWT Bearer · 限权:本人隧道(非本人一律 404) · 限流:无专用限流 · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
proxyId | number | 是 | 隧道 ID |
请求示例
curl https://api.hyperfrp.com/api/proxies/tls-certs/42 \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/tls-certs/42', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/tls-certs/42',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/tls-certs/42", 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 在列表行字段(proxyId~version、updatedAt)基础上追加:
| 字段 | 类型 | 说明 |
|---|---|---|
subject | string | 叶子证书主题(RFC2253 风格字符串) |
issuer | string | 叶子证书颁发者 |
serialNumber | string | 序列号(十进制字符串,防大数精度丢失) |
dnsNames | string[] | 证书域名列表(SAN) |
signatureAlgorithm | string | 签名算法(如 SHA256-RSA) |
publicKeyAlgorithm | string | 公钥算法(如 RSA / ECDSA) |
chain | object[] | 证书链(上传 PEM 内的全部证书块顺序,第一项为叶子;每项含 subject / issuer / notBefore / notAfter / fingerprint) |
certPem | string | 公钥证书 PEM 原文(公开件;私钥永不返回) |
响应不出现 userId / username(归属用户信息对用户端隐藏)。
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或非本人隧道 | 400 | 隧道未找到或您无权访问 |
proxyId 非法 | 400 | 无效的隧道ID |
| 数据库查询失败 | 500 | 查询证书详情失败 |
注意事项
- 单个 PEM 块解析失败不影响整体返回:详情尽力展示可解析的链段,个别损坏块被跳过。
- 详情用于自查「上传的证书对不对」;如需换证书,走「HTTPS 隧道证书」章的上传接口(
PUT /api/proxies/:id/tls-cert)。
PUT /api/proxies/:id/tls-cert
上传 / 替换本人 HTTPS 隧道保存在平台的证书与私钥。服务端完成校验后私钥加密落库、版本 +1;节点在轮询周期内感知新版本并自动换用。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | number | 是 | 隧道 ID,必须是本人的 https 类型隧道 |
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cert_pem | string | 是 | 证书 PEM 文本(UTF-8,可含证书链),单字段 ≤ 64KiB |
key_pem | string | 是 | 私钥 PEM 文本(UTF-8),须与证书公钥配对,单字段 ≤ 64KiB |
服务端校验项(任一失败整体拒绝、返回 400):
cert_pem/key_pem能否解析为一对配对的证书与私钥;- 服务端当前时间必须落在证书有效期内(未生效 / 已过期均拒绝);
- 证书的域名列表(SAN)必须覆盖该隧道的全部域名:绑定域名(
domains逗号分隔列)+protocolConfig.customDomains+subdomain(补全节点域名后缀)。绑定域名以*.开头(通配符绑定)时按证书域名列表精确包含该通配符名判定——通配符证书不匹配裸域名,需同时覆盖。
请求示例
curl -X PUT https://api.hyperfrp.com/api/proxies/42/tls-cert \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"cert_pem": "-----BEGIN CERTIFICATE-----\nMIIF...\n-----END CERTIFICATE-----",
"key_pem": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----"
}
JSON// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
const res = await fetch('https://api.hyperfrp.com/api/proxies/42/tls-cert', {
method: 'PUT',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
# 另一种用法:GET
res = requests.put(
'https://api.hyperfrp.com/api/proxies/42/tls-cert',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
// 另一种用法:GET
package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("PUT", "https://api.hyperfrp.com/api/proxies/42/tls-cert", 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)
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
proxyId | number | 隧道 ID |
fingerprint | string | 证书 SHA-256 指纹(64 位小写十六进制) |
notBefore | number | 证书生效时间(Unix 秒) |
notAfter | number | 证书过期时间(Unix 秒) |
version | number | 版本号,从 1 起每次上传 +1;节点凭版本变化自动换用证书 |
响应示例
{
"code": 0,
"message": "成功",
"data": {
"proxyId": 42,
"fingerprint": "3b1f...c9a0",
"notBefore": 1767225600,
"notAfter": 1798761600,
"version": 1
}
}错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或非本人隧道 | 404 | 隧道未找到或您无权访问 |
隧道类型不是 https | 400 | TLS 终结证书仅支持 HTTPS 类型隧道 |
cert_pem / key_pem 缺失或空白 | 400 | 证书与私钥都不能为空 |
| PEM 无法解析 / 公私钥不配对 | 400 | 证书解析失败 / 证书与私钥不配对 等 |
| 证书已过期 / 尚未生效 | 400 | 证书已过期(notAfter=...)... / 证书尚未生效(notBefore=...)... |
| 证书未覆盖某绑定域名 | 400 | 证书未覆盖域名 <域名> |
| 单字段超过 64KiB | 400 | 证书 PEM 超过 64KiB 上限 等 |
| 敏感配置加密不可用 / 加密或落库失败 | 500 | 隧道敏感配置加密不可用,已拒绝操作 等(fail-closed,绝不明文落库) |
注意事项
- 私钥安全:私钥以 AES-GCM 加密保存,任何接口(含本接口响应)都不返回明文或密文;如怀疑泄露,删除证书并更换证书后重新上传。
- 开启后的 frpc 配置变化:
tls_terminate_enabled开启时生成的 frpc 配置会摘除https2http插件(本地服务直连明文 HTTP),需重新下载 frpc 配置并重启隧道;过渡期旧配置会握手失败,属预期。 - 证书替换(重新 PUT)在节点轮询周期内自动生效,无需重启隧道。
GET /api/proxies/:id/tls-cert
查询本人隧道保存在平台的证书状态(仅指纹 / 有效期 / 版本)。未上传过证书时 data 为 null。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | number | 是 | 隧道 ID |
请求示例
curl https://api.hyperfrp.com/api/proxies/42/tls-cert \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42/tls-cert', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/42/tls-cert',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/42/tls-cert", 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)
}响应字段
同 PUT 接口响应(proxyId / fingerprint / notBefore / notAfter / version);未上传时 data 为 null。
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或非本人隧道 | 404 | 隧道未找到或您无权访问 |
DELETE /api/proxies/:id/tls-cert
删除本人隧道保存在平台的证书(幂等:未上传时同样返回成功)。tls_terminate_enabled 开关保持不变:无证书期间节点自动恢复为不解密的原样转发,重新上传后恢复服务端解密。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | number | 是 | 隧道 ID |
请求示例
curl -X DELETE https://api.hyperfrp.com/api/proxies/42/tls-cert \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/42/tls-cert', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer <token>',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.delete(
'https://api.hyperfrp.com/api/proxies/42/tls-cert',
headers={'Authorization': 'Bearer <token>'},
)
data = res.json()
print(data)package main
import (
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("DELETE", "https://api.hyperfrp.com/api/proxies/42/tls-cert", 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 | string | 证书已删除 |
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或非本人隧道 | 404 | 隧道未找到或您无权访问 |
配置下载
两个下载端点直接返回配置文件附件(ini/toml 为 Content-Type: application/octet-stream,json 为 application/json; charset=utf-8,均带 Content-Disposition: attachment),不走统一 JSON 包络;错误时仍返回 JSON 错误体。配置内容结构与预览接口一致(见上文「生成内容结构说明」),其中同样内嵌访问密钥与节点 token,下载后请妥善保管。
GET /api/proxies/config/download/:id/:format
下载本人单条隧道的 FRPC 配置文件。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | number | 是 | 隧道 ID |
format | string | 是 | 配置格式:ini、toml 或 json,其他值报错 |
请求示例
curl -o frpc_web-ssh.ini https://api.hyperfrp.com/api/proxies/config/download/42/ini \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/config/download/42/ini', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const blob = await res.blob(); // 浏览器可用 URL.createObjectURL(blob) 触发保存import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/config/download/42/ini',
headers={'Authorization': 'Bearer <token>'},
)
with open('frpc_web-ssh.ini', 'wb') as f:
f.write(res.content)package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/config/download/42/ini", 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('frpc_web-ssh.ini')
defer out.Close()
io.Copy(out, res.Body)
fmt.Println("saved frpc_web-ssh.ini")
}响应说明
成功时返回 200 + 配置文件附件:
Content-Type:ini / toml 为application/octet-stream,json 为application/json; charset=utf-8Content-Disposition: attachment; filename=frpc_<隧道名>.ini(或.toml/.json)
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 隧道不存在或不属于当前用户 | 404 | 隧道未找到或您无权访问 |
format 不是 ini / toml / json | 400 | 不支持的配置文件格式 |
| 传输协议非法或节点未开启 QUIC | 400 | 同预览接口 |
| 隧道名称无法安全生成配置 | 500 | 隧道名称不符合配置格式要求 |
GET /api/proxies/config/download/merged/:nodeId/:format
下载本人指定节点下全部已启用隧道(enabledUser=true 且 statusAdmin=true)合并而成的单文件 FRPC 配置,[common] / 顶层段只出现一次,其后串联每条隧道的配置块。
鉴权:JWT Bearer · 限流:无专用限流(全站 WAF 防护照常生效) · 缓存:NoCache(Cache-Control: no-store, no-cache, must-revalidate, private)
请求参数(Path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
nodeId | number | 是 | 节点 ID |
format | string | 是 | 配置格式:ini、toml 或 json,其他值报错 |
请求示例
curl -o frpc_gd01_merged.toml https://api.hyperfrp.com/api/proxies/config/download/merged/2/toml \
-H "Authorization: Bearer <token>"const res = await fetch('https://api.hyperfrp.com/api/proxies/config/download/merged/2/toml', {
headers: {
'Authorization': 'Bearer <token>',
},
});
const blob = await res.blob(); // 浏览器可用 URL.createObjectURL(blob) 触发保存import requests
res = requests.get(
'https://api.hyperfrp.com/api/proxies/config/download/merged/2/toml',
headers={'Authorization': 'Bearer <token>'},
)
with open('frpc_gd01_merged.toml', 'wb') as f:
f.write(res.content)package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.hyperfrp.com/api/proxies/config/download/merged/2/toml", 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('frpc_gd01_merged.toml')
defer out.Close()
io.Copy(out, res.Body)
fmt.Println("saved frpc_gd01_merged.toml")
}响应说明
成功时返回 200 + 配置文件附件:
Content-Type:ini / toml 为application/octet-stream,json 为application/json; charset=utf-8Content-Disposition: attachment; filename=frpc_<节点名>_merged.ini(或.toml/.json)
错误场景
| 场景 | HTTP | 说明 |
|---|---|---|
| 节点不存在 | 404 | 节点未找到 |
该节点下没有已启用的隧道(enabledUser 与 statusAdmin 均为 true 才计入) | 404 | 该节点下没有可用的隧道 |
format 不是 ini / toml / json | 400 | 不支持的配置文件格式 |
| 各隧道传输协议不一致 | 400 | 隧道 "<名称>" 的传输协议与合并配置中其他隧道不一致(<A>/<B>),单个客户端只能使用一种协议 |
| 传输协议非法或节点未开启 QUIC | 400 | 当前节点未开启 QUIC,无法使用 QUIC 传输协议 等 |
| 合并配置生成结果为空 | 400 | 合并配置无效,请检查隧道配置 |
| 查询节点 / 隧道列表失败 | 500 | 查询节点失败 / 获取隧道列表失败 |
注意事项
- 单个 frpc 客户端的
transport.protocol是全局的,因此合并配置要求该节点下所有已启用隧道的传输协议完全一致(全部tcp或全部quic),混合即整体拒绝,不做静默降级。 - 管理员禁用(
statusAdmin=false)的隧道不会出现在合并配置中。