鉴权与权限

项目支持房间级别的 JWT 鉴权：服务端在 Room 的生命周期方法上使用 @RequireAuth() 装饰器（见下文），统一完成「JWT 解析 + Redis 会话校验」，再在业务代码里做 guildId / teamId 等细粒度权限。

服务端 JWT、Redis、校验顺序详解：JWT 与房间鉴权

加入房间时传参（客户端）

token 与 accessToken 语义等效，至少传其一。下列 Tab 为 joinOrCreate / JoinOrCreate / join_or_create 的第二个参数（options） 写法；房间名与泛型以你的业务为准。更全的进房字段见 消息协议。

（客户端代码）

TypeScript

import Colyseus from "colyseus.js";

const client = new Colyseus.Client("ws://127.0.0.1:2567");
// 与 accessToken 二选一即可
const room = await client.joinOrCreate("my_room", {
  token: "JWT_ACCESS_TOKEN"
});

C#

using System.Collections.Generic;
using Colyseus;
using Colyseus.Schema;

// 与 accessToken 二选一即可
var options = new Dictionary<string, object> {
    { "token", "JWT_ACCESS_TOKEN" }
};

var client = new Colyseus.Client("ws://127.0.0.1:2567");
var room = await client.JoinOrCreate<DynamicSchema>("my_room", options);

GDScript

# 与 accessToken 二选一即可；Client 以当前 Colyseus Godot 插件 API 为准
var client := Colyseus.Client.new("ws://127.0.0.1:2567")
var access_token := "JWT_ACCESS_TOKEN"
var room = client.join_or_create("my_room", {
    "token": access_token,
})

joinById 时同样把上述 键值 合并进 第二个参数（与 match:found 的 joinOptions 一起传入即可，见 匹配与开房）。

注解（装饰器）的使用

仓库使用 TypeScript 装饰器（需在编译配置中启用；入口已加载 reflect-metadata，见 src/index.ts）。房间侧鉴权装饰器实现位于 src/utils/decorators/RequireAuth.ts。

标在哪

用法	说明
onJoin	最常见：客户端每次成功连接进房时执行一次；在此处标 @RequireAuth()，可保证「先进鉴权、再写座位 / 广播」。
onCreate	若房间创建阶段就需要已认证上下文（较少见），可对 onCreate 标注；客户端 joinOrCreate 的 options 会参与校验（见 JWT 文档）。

一般写在 onJoin 即可；未标注的方法不会自动走 RequireAuth 逻辑。

服务端写法示例

（服务端代码）

import { Room, Client } from "colyseus";
import { RequireAuth } from "../../utils/decorators/RequireAuth"; // 实际路径以仓库为准

export class ExampleRoom extends Room {
  onCreate(options: any) {
    this.onMessage("ping", (_client, _payload) => {
      /* … */
    });
  }

  @RequireAuth()
  onJoin(client: Client, options: any) {
    // 通过校验后，options 已附带 userId、username、email、tokenPayload 等（见 JWT 文档）
    const userId = options.userId as string;
    // 在此继续做 guildId / teamId 等业务校验
  }

  onLeave(client: Client, consented: boolean) {
    /* … */
  }
}

装饰器帮你做了什么、没做什么

• 会做：从 进房 options 读取 token / accessToken，校验 JWT 与 Redis 会话，失败则拒绝进房；通过后在 options 上合并 用户信息。流程见 JWT 与房间鉴权 §4。
• 不会自动做：业务权限（如「只有本公会可进本房」）仍需在 onJoin 里根据 options.guildId 与 userId 自行判断；消息级鉴权（某条 onMessage 仅房主可发）也需在对应 handler 内检查。

与 HTTP 控制器的区别

• HTTP：常用 authMiddleware + Authorization: Bearer，与房间装饰器 不是同一段代码路径；行为细节以各路由是否叠加校验为准。
• 房间：@RequireAuth() 与 Redis 中 access_token / refresh_token 键 强相关，见 JWT 与房间鉴权 与常见问题。

权限粒度

• 是否允许加入：无 Token / Token 失效 / 与 Redis 不一致 → 由 @RequireAuth() 拒绝。
• 业务权限：在通过鉴权后，根据 userId、guildId、teamId 等自行限制可见范围与操作。