rooms

联机房间操作

服务器通过 Web 管理端或 REST API 创建、加入、离开房间，并生成邀请链接供玩家加入。房间会话仅保存在内存，服务重启后清空（由守护进程自动联网策略重建）。

三种邀请形式

auto_join_code 与加入房间接口接受三种邀请形式：

形式	示例	说明
短码	ABC123	由外部短码服务托管，短链接更易传播；服务不可用时建房降级为仅离线串
完整邀请链接	https://next.astral.fan/j?c=ABC123	从 URL 的 c 参数提取令牌
AG1. 离线邀请串	AG1.xxxxx…	AG1. 前缀 + Base64urlNoPad(JSON)，完全自包含、不依赖短码服务

短码输入时会先做规范化：去空白 / 连字符 / 下划线并转大写，I/L → 1、O → 0（对齐 Crockford Base32 去歧义规则，允许看错字形）。

创建房间

创建房间时服务器自动完成：

1. 读取已启用的中继服务器（未启用任何服务器则报错，房间必须至少有一个 peer）；
2. 随机生成网络名 network_name（ag_ + 10 位小写字母数字）与网络密钥 network_secret（16 位、剔除易混淆字符），房间之间天然隔离；
3. 编码 AG1. 离线串，并尝试向短码服务注册短码（失败不阻断）；
4. 用服务端资料（昵称 / TUN / P2P / 静态 IP）+ 房间网络身份拼装 EasyTier TOML 并启动实例；
5. 写入当前房间会话并生成分享链接。

加入房间

加入流程与建房共用同一套核心逻辑：解析邀请（自动识别三种格式）→ 构建房间 → 启动节点 → 写入当前房间。加入时也会重新编码一份离线串，保证离开前分享链接始终可生成。

离开房间

停止实例、清空当前房间，并广播 room.left 事件（不发邮件）。

REST 接口

接口	方法	说明
/api/room/create	POST	创建房间，请求体：game_id、game_name、display_name（可选）
/api/room/join	POST	加入房间，请求体：input（短码 / 完整链接 / AG1. 离线串，三选一）
/api/room/leave	POST	离开房间
/api/room/current	GET	当前房间与分享链接（无房间时 room 为 null）

game_id 取自内置游戏列表（见中继服务器与游戏目录），custom 表示自定义网络（由客户端自行处理）。

房间数据模型

房间对象字段：

字段	说明
is_host	本机是否为房主（创建为 true，加入为 false）
game_id / game_name	游戏标识 / 名称
network_name / network_secret	EasyTier 网络名 / 密钥（同房间成员必须一致）
display_name	房间展示名（display_name 缺省时取游戏名）
short_code	短码服务返回的短码；服务不可用时为 null
offline_invite	AG1. 离线邀请串（始终可用）
peers	本房间使用的中继 / 对等节点端点列表

邀请载荷（RoomInvitePayload）包含 v（格式版本，当前固定 1）、game_id、game_name、network_name、network_secret、peers、display_name（可选），既编码为离线串，也提交给短码服务。

分享链接

优先使用短码生成短链接；无短码时回退为 AG1. 离线串：

https://next.astral.fan/j?c=ABC123        # 短码形式
https://next.astral.fan/j?c=AG1.xxxxx…    # 离线串形式

相关页面

• WebSocket 事件推送
• 守护进程自动联网
• 中继服务器与游戏目录
• REST API 参考