boardgame.io 服务器端配置与扩展指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01042/article/details/148393509

boardgame.io 服务器端配置与扩展指南

boardgame.io State Management and Multiplayer Networking for Turn-Based Games 项目地址: https://gitcode.com/gh_mirrors/bo/boardgame.io

概述

boardgame.io 是一个用于构建回合制游戏的框架，其服务器端组件负责管理多人游戏状态同步和游戏会话。本文将深入解析 boardgame.io 服务器端的配置选项、使用方法和扩展技巧，帮助开发者构建稳定可靠的多人游戏服务。

核心配置选项

基础必填配置

游戏定义数组 (games)
必须提供一个或多个符合 Game API 规范的游戏对象数组，每个对象代表一个可运行的游戏逻辑。
跨域源配置 (origins)
安全关键配置，定义允许连接服务器的前端域名。支持字符串或正则表达式：
- 生产环境应严格指定域名
- 开发环境可使用 Origins.LOCALHOST_IN_DEVELOPMENT 便捷值

可选高级配置

数据库连接 (db)
默认使用内存存储，生产环境应配置持久化存储适配器。
传输协议 (transport)
默认使用 socket.io，可替换为自定义实现。
认证相关函数
- uuid: 生成唯一ID的函数
- generateCredentials: 生成玩家凭证
- authenticateCredentials: 验证玩家凭证

服务器启动与管理

基本启动方式

const { Server, Origins } = require('boardgame.io/server');

const server = Server({
  games: [game1, game2],
  origins: [
    'https://yourdomain.com',
    Origins.LOCALHOST_IN_DEVELOPMENT
  ]
});

// 启动在8000端口
server.run(8000);

高级启动选项

回调函数
服务器启动后执行指定逻辑：

server.run(8000, () => {
  console.log("服务器已启动");
  // 其他初始化代码
});

Lobby API 分离配置
将管理API与游戏服务器分离运行：

server.run({
  port: 8000,
  lobbyConfig: {
    apiPort: 8080,  // 管理API端口
    apiCallback: lobbyReadyHandler
  }
});

HTTPS 支持
安全传输配置示例：

server.run({
  port: 8000,
  https: {
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem')
  }
});

认证系统定制

boardgame.io 提供了灵活的认证机制扩展点：

凭证生成与验证

// 自定义凭证生成
const generateCredentials = async (ctx) => {
  const token = await authService.verify(ctx.headers.authorization);
  return token.userId;
};

// 自定义凭证验证
const authenticateCredentials = async (credentials, playerMetadata) => {
  return credentials === playerMetadata.credentials;
};

const server = Server({
  games: [...],
  generateCredentials,
  authenticateCredentials
});

注意：当前自定义认证与React Lobby组件存在兼容性问题。

服务器扩展技巧

boardgame.io 基于Koa框架，提供了丰富的扩展能力：

自定义路由

server.router.get('/health', (ctx) => {
  ctx.body = { status: 'healthy' };
});

中间件注入

// 为特定路由添加预处理
server.router.use('/games/:name/create', async (ctx, next) => {
  // 预处理逻辑
  ctx.state.customData = await fetchExternalData();
  await next();
});