该技能针对 Bun 与 Elysia 上的实时游戏服务器端架构(以 Elysia 1.4.32 为参考)。资料提示:需确认项目所用 Elysia 主版本,Elysia 2 beta 重写了 WebSocket API,示例中的 .ws() 代码不能原样沿用;同时依赖 betterauth-integration(Better Auth 实例、角色与可信来源)和 redis-game-patterns(在线状态键与按动作限流)。
一、核心设计决策 服务器是权威:客户端只发送想做什么(如“向北移动”),绝不发送结果(如“我在 100,200”);服务器依据自身状态校验、应用并告知客户端结果。游戏逻辑以固定时间步运行,与网络 I/O 分离,每个 tick 的 dt 相同,相同输入得到相同结果。房间持有自己的状态、动作队列、玩家集合与 GameLoop,房间之间不共享数据,一个房间运行在一个服务器实例上,适用于玩家数固定且较少的对局。当单个空间需要的玩家或实体超出一个进程的 tick 预算时,此模型不再适用。持久化的请求-响应工作(建房间、读资料、买物品)走 REST;对局走 WebSocket:动作进、状态增量出。身份只在 WebSocket 升级时用 Better Auth 会话验证一次,player id 在整条 socket 生命周期内取自该会话,绝不从消息中读取。默认每秒 20 tick,即实例上所有房间共享每 tick 50 ms 预算,可按品类调整。
二、服务器接线 先在 templates/message-types.ts 定义协议:每条消息是以 type 为判别字段的联合类型成员;客户端消息由一个 TypeBox schema(clientMessage)定义,ClientMessage 通过 Static 派生,server.ts 用它校验,畸形消息在进入业务代码前被拒绝,类型也不会与校验漂移。用 createGameServer(auth, trustedOrigins) 创建服务器并传入 Better Auth 实例与游戏客户端来源;同一组来源也要写入 Better Auth 的 trustedOrigins。升级检查放在独立 Elysia 实例的 .derive() 中,避免在挂载的 auth 路由上执行:不可信 Origin 返回 403,无会话返回 401,路由不升级。直接调用 auth.api 会跳过 Better Auth 自身的来源检查,因此服务器需自行检查 Origin。每个请求的值(player id)放 .derive(),不要放 store(store 是所有请求共享的一个对象)。游戏逻辑写在 RoomManager.tickRoom 与 processAction 中。单个动作的模式是先 validateAction,无效则向该玩家发送 action_result(success: false,并带上拒绝原因,客户端需要它向玩家展示);有效则 applyAction。
三、tick 循环 GameLoop 把真实流逝时间累加到累加器,执行尽可能多的固定 dt 步,余量留到下一轮。单次处理的时间上限为 250 ms:不设上限时,慢 tick 会让下一轮执行更多步、更慢,形成“死亡螺旋”;设上限后,长时间停顿只会让游戏变慢而不会冻结。setSpeed() 缩放流逝时间,用于快进或慢动作,dt 保持固定。每个 tick 后房间对比上一 tick 的状态,只把变化的顶层键作为 state_update 广播,删除的键以 null 到达;由于 WebSocket 基于 TCP 按序送达,对比上一 tick 是安全的;若在不不可靠传输上,应基于客户端已确认的快照编码。客户端重连时通过 room_joined 重新发送完整状态。房间 tick 或 processAction 抛出异常会停止该房间的循环、记录日志并关闭该房间,其他房间继续运行。
四、多实例 房间存在于某一实例的内存中:需把房间所有玩家路由到持有该房间的实例,可在创建房间时返回该实例地址,或在负载均衡器按房间 id 路由。服务器启动时创建一个 ioredis 客户端(new Redis(redisUrl),使用 redis:// URL),传给 createFanOut 与 redis-game-patterns 的助手。boilerplate/fan-out.ts 只用于跨实例消息:向连接在其他实例的玩家直发、全服公告、或在所有实例关闭被封禁玩家的 socket(封禁会吊销会话,但已打开的 socket 需服务器主动关闭)。LocalDelivery 用 player id 到 socket 的映射实现,open 时填充、close 时清除。Redis Pub/Sub 至多投递一次,实例宕机或重连期间发布的消息会丢失;比赛结果、奖励与购买应走队列(bullmq-game-queues),不要走 fan-out。
五、单空间超出一个进程时 按负载单元分区:区域、分片或实例。区域是一个世界中的一块,由一个进程拥有;分片或实例是同一空间的隔离副本,不同副本的玩家不会相遇。维护可重切的“单元到进程”静态映射。要认识下限:负载单元无法拆分到单个热点区域以下;EVE 中一个节点是一个 CPU 核上的一个进程,CCP 表示单个太阳系若超出其核心容量便无法继续平衡,更多进程对本身过忙的房间无济于事,可选方案包括设计更小的区域、人数上限、空间副本或过载策略。把非空间服务移出模拟进程:聊天、市场、邮件、账号与角色数据;模拟进程只保留 tick,其他服务通过 HTTP 或队列调用,绝不在 tick 内调用。CCP 报告称把部分服务移到独立的角色节点后,原本发往最忙系统节点的调用中多达 80% 转向了别处——这是 EVE 的数字,不是目标值。上线前确定过载策略:一是时间膨胀,压低游戏时钟以减少工作队列,负载缓解后小步恢复;GameLoop.setSpeed() 可实现,每秒执行的固定步数减少而 dt 不变;此时所有基于时间的规则(冷却、回复、移动)都必须读取游戏时间而非墙钟时间,并需决定哪些计时器保持真实时间(CCP 将 reinforcement 计时器豁免于时间膨胀,否则玩家可在其到期时行动)。二是降载:拒绝加入繁忙区域、降低低优先级更新的发送频率。资料未说明 EVE 是按节点还是全集群做时间膨胀,需自行决定范围。
六、数据存放 Redis 存瞬时状态:在线状态、限流计数、房间到实例路由、缓存。Redis 持久化在崩溃时可能丢数据:RDB 快照可能丢失最近几分钟,AOF 默认每秒 fsync 可能丢失约一秒;Redis 官方建议 RDB 加 AOF 以获得接近 PostgreSQL 的安全性。不能承受丢失的数据不应只放在 Redis。Postgres 存账本、余额、库存与交易(postgres-game-schema 提供表与受保护的扣费查询)。两名玩家的一笔交易是一个 Postgres 事务:先按 id 顺序用 SELECT ... FOR UPDATE 锁定两名玩家的行(锁定玩家行可覆盖交易插入的行,如合并堆叠,而库存锁做不到),再改库存与货币;两笔相反交易因此以相同顺序取锁,不会互相等待。若 Postgres 仍以 SQLSTATE 40P01(deadlock_detected)中止事务,需整体重试少量、有限次数。此规则仅在写入任一玩家库存或货币的其他所有路径都先按 id 顺序取相同玩家锁时成立;单行受保护语句(如 spendCurrency)是唯一例外。账本与交易写入立即提交,而房间状态写入不同:在房间关闭、定时器或队列中写入 Postgres,绝不在 tick 内 await。
七、心跳与在线状态 客户端发 ping,服务器回 pong 并附带自身时间。每次 ping 刷新该玩家的在线状态键,TTL 设为数个心跳间隔;键缺失即离线,崩溃的客户端无需清理消息。socket 关闭时从该 socket 所在的所有房间移除玩家。重连后新 socket 在房间中替换旧 socket,因此旧 socket 迟到的关闭不会把玩家移除(房间会比较 socket id)。
八、常见陷阱 信任客户端状态(移动、伤害、库存、分数变化均在服务器计算);游戏公式中使用可变 dt;用单一全局游戏状态代替房间;在 tick 内 await 数据库写入(应在房间关闭或每 N tick 于 tick 回调外持久化);每 tick 广播完整状态(应发增量,状态大时按玩家可见范围过滤);单次处理不设时间上限(死亡螺旋);游戏系统导入 WebSocket 类型并直接发消息(系统只改状态、发事件,由房间转为消息);房间一空就立即销毁(应走关闭流程:停循环、持久化、通知、删除);从客户端消息读 player id,或每条消息都读会话而非升级时读一次;忘记会话检查只运行一次(封禁与登出不会关闭已打开的 socket,需用 kick 的 fan-out 消息)。
九、文件说明 boilerplate/server.ts:接线服务器时复制,挂载 Better Auth 处理器,在升级的 .derive() 中检查 Origin 与会话,并把 WebSocket 消息路由到房间管理器。boilerplate/room-manager.ts:添加房间时复制;接入游戏逻辑时阅读,tickRoom 与 processAction 是钩子。boilerplate/game-loop.ts:房间需要 tick 循环时复制,无需改动。boilerplate/fan-out.ts:运行多个服务器实例时复制。templates/message-types.ts:定义客户端-服务器协议时复制,用本游戏的消息扩展联合类型。references/architecture.md:需要连接流程或房间生命周期的图示时阅读。references/sources.md:需要某条规则对应页面时阅读。
十、相关技能 game-state-sync(客户端侧:预测、协调、插值)、bullmq-game-queues(把繁重或不可丢失的工作移出 tick 循环)、postgres-game-schema(玩家资料、库存与比赛历史)、matchmaking-system(填充房间)。