# 联机房间操作

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

## 三种邀请形式

`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` 取自内置游戏列表（见[中继服务器与游戏目录](relay-servers.md)），`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.` 离线串：

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

## 相关页面

- [WebSocket 事件推送](websocket-events.md)
- [守护进程自动联网](daemon-auto-connect.md)
- [中继服务器与游戏目录](relay-servers.md)
- [REST API 参考](rest-api.md)