联机大厅 API
接口地址:
/oh.php请求方式:
POSTContent-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":"服务器异常,请稍后重试."} | 服务端异常 |
注意事项
- 房间 ID ≠ 隧道 ID:
add传的tunnel是隧道 ID,其余接口传的id是房间 ID - 隧道唯一性:一条隧道只能开一个房间,重复开房返回「隧道已存在」
- 权限边界:
add/remove仅限房主;run/check/ 聊天接口需要房主或已加入的参与者 - 密钥轮换:房主每次
run都会覆盖旧密钥 - 聊天上限:每房间最多 20 条
- 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保持房间状态与聊天同步。