Skip to content

简单启动 API ​

接口地址: /esirun.php

请求方式: POST Content-Type: application/json(也支持表单)

页面入口: /proxies → 隧道行「简单启动」按钮

思路

用一条隧道级临时 CSRF 密钥代替用户完整登录态。客户端拿到密钥即可拉取节点授权信息与隧道全部参数,拼出 frpc 配置并一键拉起 frpc,无需手动写配置,也无需再次携带账号凭据。

两套 CSRF 的区别 ​

名称存放位置用途
登录 CSRFcsrf 表(token, csrf, time)调用 create / get 时证明「我是这个账号」
隧道 CSRFproxies.csrf 列调用 config 时证明「我持有这条隧道的启动密钥」

API 列表 ​

type说明需要的 CSRF权限
create为隧道生成新的启动密钥登录 CSRF隧道归属人
get读取隧道已有的启动密钥(不重新生成)登录 CSRF隧道归属人
config用隧道密钥拉取完整 frpc 配置数据隧道 CSRF持有密钥即可

1. 生成启动密钥 type=create ​

参数必填说明
id是隧道 ID
csrf是登录 CSRF
json
{ "type": "create", "id": "10086", "csrf": "Token值" }
json
{
  "status": 200,
  "message": "简单启动密钥生成成功!",
  "csrf": "WxYzAbCdEf0123456789",
  "port": "7000",
  "hostname": "cn-1.example.com",
  "ip": "1.2.3.4",
  "origin": "true"
}
字段说明
csrf本次生成的隧道启动密钥,用于 config 接口
port隧道所属节点的 frps 端口
hostname节点域名
ip节点 IP
origin是否源站节点(true / false)

错误:

返回触发条件
{"status":403,"message":"CSRF 无效或已过期."}登录 CSRF 无效或超 7 天
{"status":404,"message":"未找到隧道,隧道不存在."}隧道 ID 不存在
{"status":404,"message":"无权访问,隧道不属于您."}隧道不属于当前账号
{"status":403,"message":"本启动密钥生成不支持 X/S TCP(P2P点对点)隧道"}隧道类型为 xtcp / stcp

WARNING

P2P(XTCP / STCP)隧道不支持简单启动,请改为手动配置或使用联机大厅。前端会对这两类隧道直接提示「该隧道类型不支持简单启动」。

2. 读取已有密钥 type=get ​

json
{ "type": "get", "id": "10086", "csrf": "Token值" }

返回字段与 create 相同,csrf 为 proxies.csrf 中已有的值——不会重新生成,原密钥继续有效。

何时用 get

get 用于「已经生成过密钥,只想再拿一次」。若需要作废旧密钥,应调用 create。

3. 拉取 frpc 配置 type=config ​

只需隧道 CSRF,无需登录 CSRF:

json
{ "type": "config", "csrf": "WxYzAbCdEf0123456789" }
json
{
  "status": 200,
  "message": "通过临时CSRF获取数据成功!",
  "data": {
    "id": "10086",
    "uuid": "xxxx-xxxx-xxxx",
    "proxy_name": "my-tunnel",
    "proxy_type": "tcp",
    "local_ip": "127.0.0.1",
    "local_port": "25565",
    "remote_port": "25565",
    "use_encryption": "false",
    "use_compression": "false",
    "domain": "example.com",
    "locations": "",
    "host_header_rewrite": "",
    "sk": "",
    "status": "true",
    "node": "1",
    "token": "登录token",
    "hostname": "cn-1.example.com",
    "port": "7000",
    "ip": "1.2.3.4",
    "key": "节点frps授权密钥"
  }
}

data 由两部分组成:

  1. 隧道行原字段:id / uuid / proxy_name / proxy_type / local_ip / local_port / remote_port / use_encryption / use_compression / domain / locations / host_header_rewrite / sk / status / node
  2. 补充连接字段:
字段来源用途
tokentokens 表(按隧道 uuid)用户登录 token
hostnamenodes 表frpc serverAddr
ipnodes 表serverAddr 备选
portnodes 表serverPort
keynodes.tokenfrps auth.token

错误:

json
{ "status": 500, "message": "隧道CSRF无效或已过期,请重新获取新的隧道CSRF" }

客户端一键启动流程 ​

ini
[common]
server_addr = data.hostname      # 或 data.ip
server_port = data.port
token       = data.key           # frps auth.token

[data.proxy_name]
type        = data.proxy_type
local_ip    = data.local_ip
local_port  = data.local_port
remote_port = data.remote_port
# HTTP/HTTPS 额外使用 data.domain / data.locations / data.host_header_rewrite
1. /user  (type=login)   → 拿到登录 CSRF(token)
2. /esirun.php (type=create) → 凭登录 CSRF 生成隧道启动密钥
3. /esirun.php (type=config) → 凭隧道启动密钥拉取节点授权 + 隧道参数
4. 客户端拼 frpc.ini 并启动 frpc → 隧道上线

前端用法(控制台「简单启动」) ​

typescript
// src/views/Proxies.vue
const createRes = await api.easyRunCreate(userStore.csrf, row.id)
const key = createRes.csrf

easyRunWinCommand.value   = `frpc.exe -esirun ${key} -i https://api.hayfrp.1zyq1.com/`
easyRunLinuxCommand.value = `./frpc -esirun ${key} -i https://api.hayfrp.1zyq1.com/`

用户在 frpc 所在目录直接执行该命令即可一键启动,无需下载配置文件。

安全说明 ​

  • 登录 CSRF 与隧道 CSRF 分离,二者不互通
  • 登录 CSRF 有效期 7 天,超期自动删除
  • create 每次调用都会覆盖 proxies.csrf,旧密钥随即失效
  • config 不校验登录态,持有隧道密钥即等于持有启动权限,勿泄露

相关页面 ​

基于 MIT 许可证发布