Skip to content

联机大厅 API ​

接口地址: /oh.php

请求方式: POST Content-Type: application/json(也支持 application/x-www-form-urlencoded)

页面入口: /lobby(Lobby.vue)

概念

联机大厅基于 P2P(XTCP / STCP)隧道。房主先创建一条 P2P 隧道,再用该隧道「开房」;参与者加入房间后获取临时连接密钥,即可与房主点对点联机。

API 列表 ​

type说明需要 CSRF权限
list列出所有房间否(可选)任何人
add创建(开房)是隧道归属人
join加入房间是任何人
run获取连接密钥是房主 / 参与者
remove删除房间是房主
check查询房间实时在线状态是房主 / 参与者
getchat获取房间聊天记录是房主 / 参与者
clearchat清空聊天记录是房主 / 参与者
sendchat发送聊天消息是房主 / 参与者

1. 列出房间 type=list ​

参数必填说明
csrf否传入自己的 CSRF 后,自己创建或已加入房间的密码会以明文返回;不传则密码显示为掩码
json
{ "type": "list", "csrf": "Token值" }
json
{
  "status": 200,
  "message": "获取成功",
  "data": [
    {
      "id": "12",
      "name": "我的世界联机房",
      "introduce": "一起玩生存模式",
      "tunnel": "10086",
      "passwd": "********************",
      "time": "1730000000",
      "user": "uuid-of-host",
      "visitor": "uuid-of-visitor1,uuid-of-visitor2",
      "status": "offline",
      "local_port": "25565",
      "remote_port": "25565",
      "node": "3",
      "username": "host_name",
      "userqid": "10001",
      "userdesc": "NULL",
      "visitorname": "visitor1,visitor2",
      "visitorqid": "20001,20002",
      "visitordesc": "NULL,NULL"
    }
  ]
}
字段说明
id房间 ID(后续 join / run / remove / check / 聊天都用它)
tunnel房间绑定的隧道 ID(与房间 ID 不同)
status房间状态:online / offline
passwd无权限时返回 ********************
user / visitor房主 / 访客的 UUID 列表(逗号分隔)

2. 创建房间 type=add ​

参数必填说明
csrf是CSRF Token
name是房间名称
introduce是房间介绍
tunnel是隧道 ID(必须是当前账号拥有的 P2P 隧道)
passwd否房间密码,留空表示公开房间
json
{
  "type": "add",
  "csrf": "Token值",
  "name": "我的世界联机房",
  "introduce": "一起玩生存模式",
  "tunnel": "10086",
  "passwd": "1234"
}
返回含义
{ "status": 200, "message": "添加成功." }成功
{ "status": 403, "message": "隧道不属于您." }隧道不属于当前账号
{ "status": 403, "message": "隧道已存在." }该隧道已开过房间

WARNING

add 不返回房间 ID,需要通过 type=list 找到自己刚创建的房间。

3. 加入房间 type=join ​

参数必填说明
csrf是CSRF Token
id是房间 ID
passwd否房间有密码时必填
json
{ "type": "join", "csrf": "Token值", "id": "12", "passwd": "1234" }

房主本人:

json
{ "status": 200, "message": "欢迎回来,房主.", "key": "1234", "role": "host" }

已加入的参与者再次进入:

json
{ "status": 200, "message": "欢迎回来,参与者.", "key": "1234", "role": "visitor" }

首次加入:

json
{ "status": 200, "message": "加入成功,欢迎来到房间 我的世界联机房 .", "key": "1234" }

常见失败:

返回含义
{ "status": 404, "message": "房间不存在,请检查后重试." }房间 ID 无效
{ "status": 404, "message": "该房间需要密码,请填写." }缺少密码
{ "status": 403, "message": "房间密码有误,请检查后重试." }密码错误

4. 获取连接密钥 type=run ​

参数必填说明
csrf是CSRF Token
id是房间 ID
json
{ "type": "run", "csrf": "Token值", "id": "12" }
json
{
  "status": 200,
  "message": "获取成功,该密钥在下一次房主您的获取前保持有效.",
  "token": "NewTempKey1234567890"
}
  • 房主每次调用都会重新生成密钥并覆盖旧值,旧密钥立即失效
  • 参与者获得的密钥在「下一位参与者获取」或「房主下一次获取」前有效
  • 未加入房间:{ "status": 403, "message": "您未加入房间,无权获取命令." }

5. 删除房间 type=remove ​

json
{ "type": "remove", "csrf": "Token值", "id": "12" }
json
{ "status": 200, "message": "删除房间成功" }
json
{ "status": 403, "message": "只有房主才允许删除房间." }

删除房间会同时清理房间聊天记录与绑定隧道。

6. 查询房间实时状态 type=check ​

json
{ "type": "check", "csrf": "Token值", "id": "12" }
json
{ "status": 200, "message": "隧道在线.", "ostatus": "online" }
json
{ "status": 500, "message": "隧道离线.", "ostatus": "offline" }
json
{ "status": 403, "message": "您没有权限查看此房间的实时状态." }

7. 获取聊天记录 type=getchat ​

json
{ "type": "getchat", "csrf": "Token值", "id": "12" }
json
{
  "status": 200,
  "message": "获取成功!",
  "chats": [
    {
      "id": "1",
      "msg": "大家准备好了吗",
      "room": "12",
      "uuid": "uuid-of-sender",
      "time": "1730000100",
      "qid": "10001",
      "username": "host_name"
    }
  ]
}
返回含义
{ "status": 204, "message": "暂无信息." }暂无消息
{ "status": 403, "message": "未加入目标房间,您无法浏览目标房间的内容." }未加入房间

每个房间最多保留 20 条聊天记录,超出自动清理最旧的。

8. 清空聊天记录 type=clearchat ​

json
{ "type": "clearchat", "csrf": "Token值", "id": "12" }
json
{ "status": 200, "message": "清屏成功!" }

9. 发送聊天消息 type=sendchat ​

json
{ "type": "sendchat", "csrf": "Token值", "id": "12", "msg": "晚上八点开打" }
json
{ "status": 200, "message": "消息发送成功!" }
json
{ "status": 403, "message": "未加入目标房间,您无法向目标房间发送内容." }

完整流程 ​

bash
BASE_URL="https://api.hayfrp.1zyq1.com"

# 1. 登录拿 CSRF
CSRF=$(curl -s -X POST "$BASE_URL/user" -H "Content-Type: application/json" \
  -H "waf: off" \
  -d '{"type":"login","user":"demo@example.com","passwd":"123456","keepcsrf":1}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

# 2. 创建一条 P2P 隧道(stcp),记住隧道 ID
curl -s -X POST "$BASE_URL/proxy" -H "Content-Type: application/json" -H "waf: off" \
  -d "{\"type\":\"add\",\"csrf\":\"$CSRF\",\"proxy_name\":\"mc-p2p\",\"proxy_type\":\"stcp\",
       \"local_ip\":\"127.0.0.1\",\"local_port\":\"25565\",\"node\":\"3\"}"

# 3. 用该隧道开房
curl -s -X POST "$BASE_URL/oh.php" -H "Content-Type: application/json" -H "waf: off" \
  -d "{\"type\":\"add\",\"csrf\":\"$CSRF\",\"name\":\"我的世界联机房\",
       \"introduce\":\"一起玩生存模式\",\"tunnel\":\"10086\",\"passwd\":\"1234\"}"

# 4. 列出房间,拿到房间 ID
curl -s -X POST "$BASE_URL/oh.php" -H "Content-Type: application/json" -H "waf: off" \
  -d "{\"type\":\"list\",\"csrf\":\"$CSRF\"}"

# 5. 房主获取连接密钥
curl -s -X POST "$BASE_URL/oh.php" -H "Content-Type: application/json" -H "waf: off" \
  -d "{\"type\":\"run\",\"csrf\":\"$CSRF\",\"id\":\"12\"}"

# 6. 查询在线状态 / 发聊天消息
curl -s -X POST "$BASE_URL/oh.php" -H "Content-Type: application/json" -H "waf: off" \
  -d "{\"type\":\"check\",\"csrf\":\"$CSRF\",\"id\":\"12\"}"

参与者流程:

bash
# 加入房间(有密码时带 passwd)
curl -s -X POST "$BASE_URL/oh.php" -H "Content-Type: application/json" -H "waf: off" \
  -d "{\"type\":\"join\",\"csrf\":\"$CSRF\",\"id\":\"12\",\"passwd\":\"1234\"}"

# 获取连接密钥
curl -s -X POST "$BASE_URL/oh.php" -H "Content-Type: application/json" -H "waf: off" \
  -d "{\"type\":\"run\",\"csrf\":\"$CSRF\",\"id\":\"12\"}"

通用错误 ​

返回含义
{"status":404,"message":"无联机大厅请求类型."}未传 type
{"status":404,"message":"无联机大厅CSRF请求类型."}缺少 csrf
{"status":404,"message":"无联机大厅ID请求类型."}缺少 id
{"status":404,"message":"无联机大厅msg请求类型."}发送聊天时缺少 msg
{"status":403,"message":"登录无效或已过期."}CSRF 无效或已过期
{"status":500,"message":"服务器异常,请稍后重试."}服务端异常

注意事项 ​

  1. 房间 ID ≠ 隧道 ID:add 传的 tunnel 是隧道 ID,其余接口传的 id 是房间 ID
  2. 隧道唯一性:一条隧道只能开一个房间,重复开房返回「隧道已存在」
  3. 权限边界:add / remove 仅限房主;run / check / 聊天接口需要房主或已加入的参与者
  4. 密钥轮换:房主每次 run 都会覆盖旧密钥
  5. 聊天上限:每房间最多 20 条
  6. CSRF 有效期:7 天,过期需重新登录

前端封装 ​

typescript
const rooms = await api.listRooms(csrf)                       // type=list
await api.addRoom(csrf, name, introduce, tunnel, passwd)      // type=add
await api.joinRoom(csrf, id, passwd)                          // type=join
const key = await api.getRoomKey(csrf, id)                    // type=run
await api.removeRoom(csrf, id)                                // type=remove
const status = await api.checkRoom(csrf, id)                  // type=check
const chats = await api.getRoomChat(csrf, id)                 // type=getchat
await api.sendRoomChat(csrf, id, msg)                         // type=sendchat
await api.clearRoomChat(csrf, id)                             // type=clearchat

getRoomKey 在 api.ts 中以 type: 'run' 实现。前端 Lobby.vue 会定时轮询 check 与 getchat 保持房间状态与聊天同步。

相关页面 ​

基于 MIT 许可证发布