Files
2026-08-28 19:44:46 +08:00

17 KiB
Raw Permalink Blame History

Server-v3 架构设计(已定稿,基于用户 8 项决策)

状态:定稿。本文为 FunGame.Server-v3 的开发规格说明书,取代 03-Server-v3-开发规划.md 中的备选方案。 所有实现以本文为准;01/02 文档作为功能与 Core v3 能力参考。


0. 总体决策摘要

# 决策 结论
1 数据层 EF Core,Provider 可切换:SQLite(默认/开发)与 MySQL(生产,Pomelo)
2 管理入口 废弃控制台输入,提供 WebUI(React + Tailwind) 服务器管理
3 启动方式 仅 WebSocket + WebAPI(单一 ASP.NET Core 进程,同旧版 FunGameWebAPI 形态),移除 TCP Socket
4 用户中心 重构为细粒度权限角色模型(RBAC + 权限点),多端统一验证(WebUI / WebAPI / WebSocket 共用同一 JWT 认证体系 + 刷新令牌 + 会话表)
5 数据库/API 数据表优化 + 追加新表;每张数据表都有对应 CRUD REST 接口(通用 CRUD 基类派生)
6 加载项 始终热重载(无普通加载模式);WebAPI 插件与服务器模组合并为单一"服务器插件";角色/技能/物品模组仍是独立加载项,工厂注册保持模块化;DLL 热重载与实体 JSON 配置加载为两条平行通道
7 负载模型 弃用 SocketObject,全新设计负载模型(WebSocket 信封 + REST 响应包装)
8 回合记录 支持 Core v3 的 IRoundRecordSink 回合记录外发(本地归档 + 可配置远程 POST)

1. 解决方案结构

FunGame.Server-v3/
├── docs/                                  # 文档(01~04)
├── FunGame.Server-v3.slnx                 # 解决方案
├── src/
│   ├── FunGame.Server.Contracts/          # 共享契约:负载模型、插件接口、常量、事件参数
│   ├── FunGame.Server.Infrastructure/     # EF Core 数据层:实体、DbContext、迁移、种子数据
│   ├── FunGame.Server.PluginHost/         # 始终热重载的插件/模组加载系统
│   └── FunGame.Server.Host/               # 宿主:WebAPI + WebSocket + 认证 + 业务服务 + 对局宿主
├── plugins/                               # 服务器插件示例(编译输出 → Host/plugins/)
├── modules/                               # 角色/技能/物品模组示例(编译输出 → Host/modules/)
└── webui/                                 # React + Vite + Tailwind 管理台

依赖方向(严格单向):

FunGame.Core (v3)  ←  Contracts  ←  Infrastructure  ←  PluginHost  ←  Host
                                       ↑                    ↑
                              (共享程序集:插件 ALC 回退到默认上下文解析)

2. 数据层(决策 1/5)

2.1 Provider 切换

appsettings.json:

"Database": {
  "Provider": "Sqlite",              // Sqlite | MySql
  "ConnectionStrings": {
    "Sqlite": "Data Source=Data/fungame-server.db",
    "MySql": "Server=localhost;Port=3306;Database=fungame;User=root;Password=***;"
  }
}
  • AppDbContextFactory(设计时)与 AddDbContext(运行时)都按 Provider 注册对应 Provider:
    • SQLite → Microsoft.EntityFrameworkCore.Sqlite
    • MySQL → Pomelo.EntityFrameworkCore.MySql
  • 迁移目录按 Provider 拆分:Migrations/Sqlite/ 与 Migrations/MySql/(--output-dir 指定)
  • 首次启动自动 Migrate() + 种子数据(系统角色、权限点、初始管理员)

2.2 数据表规划(v2 表优化 + 新增)

认证与用户中心(新增/重构,决策 4)

表 说明
Users 用户(v2 users 重构:密码散列 PBKDF2、邮箱验证、状态、昵称、头像、最后登录 IP/时间)
UserProfiles 用户资料(v2 user_profiles 保留:个性签名、展示角色、偏好设置等)
Roles 角色(Code/Name/是否系统内置)
Permissions 权限点(Code/Name/分组,如 users.read、plugins.reload、games.forceend)
UserRoles 用户-角色 多对多
RolePermissions 角色-权限 多对多
RefreshTokens 刷新令牌(散列存储、设备标识、过期/吊销;多端统一验证的基础)
UserSessions 在线会话(每端一条:WebUI/WebAPI/WebSocket,登录挤下线/多端管理)
LoginLogs 登录日志(v2 user_logs 细化:成功/失败、IP、UA、设备)
ApiTokens API 访问令牌(v2 api_tokens 保留,供外部服务接入)

游戏业务(v2 表迁移/优化)

表 说明
Rooms 房间(v2 rooms 保留,去掉 SQL 运行时依赖)
UserCharacters 玩家角色库(v2 user_characters;实体数据以 Core JSON 存储 + 关键字段列冗余便于查询)
UserItems 玩家物品(v2 user_items)
Inventories 库存(v2 inventories:货币/材料)
Stores / Goods / GoodsPrices / StoreGoods 商店体系(v2 保留)
MarketItems 市场寄售(v2 保留)
Offers / OfferItems 交易报价(v2 保留)
VerifyCodes 验证码(v2 reg_verify_codes + forget_verify_codes 合并,加 Purpose 字段)
UserSignIns 签到(v2 保留)

对局记录与运维(新增,决策 8/2)

表 说明
GameRecords 对局记录索引(GamingQueue Guid、模式、起止时间、回合数、归档路径、胜者)
RoundRecords 回合记录归档(可 JSON 列或归档文件路径;支持按回合查询回放)
ServerLogs 服务器日志(供 WebUI 查看;结构化:级别/来源/分类/消息)
SystemConfigs 系统配置键值(v2 configs 保留:动态公告、开关等)

所有 *Query 静态 SQL 类(SQLQueryExtension)废弃,改为 EF LINQ。

2.3 CRUD API 约定(每表一套,决策 5)

通用基类 CrudControllerBase<TEntity, TKey>:

GET    /api/{resource}            列表(分页 page/pageSize、排序 sort、过滤 filter=field:op:value)
GET    /api/{resource}/{id}       详情
POST   /api/{resource}            创建([Permission("{resource}.create")])
PUT    /api/{resource}/{id}       整体更新
PATCH  /api/{resource}/{id}       部分更新
DELETE /api/{resource}/{id}       删除
  • 派生控制器:UsersController、RolesController、PermissionsController、ApiTokensController、RoomsController、StoresController、GoodsController、MarketItemsController、OffersController、GameRecordsController、ServerLogsController、SystemConfigsController……
  • 关系表(UserRoles/RolePermissions)随主资源提供子路由:GET/PUT /api/users/{id}/roles、GET/PUT /api/roles/{id}/permissions
  • 统一响应包装 ApiResponse<T>;权限用 [Permission] 授权过滤器校验

3. 认证:多端统一验证(决策 4)

一条认证体系,三端共用:

登录 → POST /api/auth/login (用户名/密码 或 刷新令牌) → { accessToken, refreshToken }
WebUI   : Axios 拦截器 → Authorization: Bearer {accessToken};401 → /api/auth/refresh → 重试;失败 → 登录页
WebAPI  : 同上(外部服务可用 ApiTokens 走 X-API-Token)
WebSocket : /ws?access_token=… 握手时校验 JWT(过期可先 refresh 再连)
  • JWT:AccessToken 短时效(默认 30 分钟),RefreshToken 长时效(默认 14 天,可配置),散列入库,支持撤销/设备维度("踢出该设备")
  • UserSessions:每端登录产生会话;同用户可多端同时在线,重复登录可配置"同端互踢"
  • 密码:PasswordHasher<T>(PBKDF2);v2 的每用户密钥加密方案废弃(简化 + 标准库)
  • 权限模型:Permission 权限点字符串(users.read / plugins.reload …)→ 角色聚合 → JWT Claim perm 数组;PermissionAttribute("code") 服务端校验
  • 首次启动种子:系统角色(Admin/Moderator/User)、全部权限点、初始管理员(用户名/密码由 appsettings Bootstrap:Admin 提供,仅首次生效)

4. WebSocket 与负载模型(决策 3/7)

4.1 接入

  • 端点:GET /ws?access_token={jwt}
  • ASP.NET Core 原生 UseWebSockets;连接对象 ClientSession(会话模型,替代 v2 ServerModel<T>)

4.2 负载信封(替代 SocketObject)

// 客户端 → 服务器(请求)
{
  "t": "room.create",     // 消息类型(点分字符串,替代 SocketMessageType 枚举)
  "i": 1,                 // 请求序号(客户端生成,用于响应关联)
  "d": { ... }            // 负载(Dictionary<string, object>,实体用 Core JsonService 序列化)
}

// 服务器 → 客户端(响应 / 广播)
{
  "t": "room.created",    // 或原样回显请求类型 + ".ok"/".error"
  "i": 1,
  "ok": true,
  "error": null,          // { code, message }
  "d": { ... },
  "ts": 1750000000000
}
  • 消息类型注册表 MessageTypes(Contracts 常量类),覆盖:auth.*、room.*、match.*、chat.*、gaming.*(局内:gaming.ready、gaming.action、gaming.sync…)、system.*(公告/系统消息/踢人)
  • 局内数据全部复用 Core v3 实体 JSON(JsonService.GeneralOptions 的转换器已支持 RoundRecord/ActionRecord/Character 等)
  • MessageDispatcher:类型字符串 → 处理器注册表(业务服务 + 插件处理器合并)
  • 心跳:{ "t": "system.ping" } ↔ system.pong;超时判定断线,断线重连(对局内重连保留 v2 思路,凭 gameId 重挂)

4.3 REST 响应包装(与 WS 对齐)

{ "ok": true, "code": 0, "message": null, "data": { ... }, "timestamp": "..." }

5. 加载项系统(决策 6)—— 始终热重载

5.1 三类加载项(DLL 热重载通道)

类型 目录 接口 说明
服务器插件(合并 v2 WebAPIPlugin + GameModuleServer) plugins/ IServerPlugin 生命周期 + REST 端点注册(MapGroup)+ WS 消息处理器 + 对局模式(GameModule)
角色模组 modules/characters/ ICharacterModule 提供角色实体集合,Load() 时通过工厂注册
技能模组 modules/skills/ ISkillModule 同上(技能)
物品模组 modules/items/ IItemModule 同上(物品)

实体模组也可只提供 EntityModuleConfig JSON 文件(平行通道,见 5.3),DLL 与 JSON 两者可共存。

5.2 DLL 热重载机制(始终开启,无普通加载模式)

  • 每个加载项一个可回收 AssemblyLoadContext(PluginLoadContext,isCollectible: true),按 Name + Guid 命名
  • PluginManager:
    • LoadAll() / Load(string name) / Unload(string name) / Reload(string name) / ReloadAll()
    • Plugins / Modules 清单(名称、版本、状态、加载时间)
    • 文件监视(FileSystemWatcher,去抖合并变更)→ 自动热重载;也可 POST /api/admin/plugins/{name}/reload 手动触发
    • 卸载顺序:OnUnload() → 摘除端点/处理器 → ALC.Unload() → 弱引用等待 GC(必要时 GC.Collect)
  • 共享程序集(FunGame.Core、Contracts、Infrastructure、PluginHost)不随插件加载:PluginLoadContext.Load 优先返回默认上下文已加载程序集;插件自有依赖从插件目录解析
  • 插件端点用 Minimal API MapGroup(plugin.ConfigureEndpoints(app)),可热卸载(v2 的 Controller 程序集注册方式因无法热移除而弃用)
  • 对局中途插件被卸载:PluginManager 拒绝卸载"仍被活跃对局引用"的插件(引用计数)

5.3 实体 JSON 通道(与 5.2 平行)

  • EntityModuleConfig<T> 生成/读取 JSON 配置;Factory.GetGameModuleInstances<T>(module, file) 实例化实体
  • WebUI 提供"实体模组管理"页:查看/编辑/重新加载 JSON 配置(不重启进程改游戏内容)

5.4 服务器插件接口(Contracts)

public interface IServerPlugin : IPluginBase
{
    // 注册 HTTP 端点(挂载 /plugin/{name}/{path},注册表 + 单一路由分发,可热移除)
    // 与 WebSocket 消息处理器(随插件热卸载自动注销)
    void ConfigureEndpoints(IPluginHttpHandlerRegistry http, IMessageHandlerRegistry messages);
    // 对局模式逻辑(可选):局内消息转发到模式插件
    Task<Dictionary<string, object>?> HandleGamingMessage(IGameSession session, string type, Dictionary<string, object> data);
    void OnLoad(IServiceProvider services);   // 继承自 IPluginBase
    void OnUnload();                          // 继承自 IPluginBase
}

注:插件 HTTP 端点采用 注册表 + 单一路由分发(/plugin/{name}/{path})而非动态注册 Controller/MapGroup——保证端点可随 ALC 热添加/热移除。


6. 对局宿主与回合记录外发(决策 8)

6.1 对局宿主 GameHostService

  • 房间/匹配就绪 → 创建 GamingQueue(characters, map) → 绑定 RoundRecordSink
  • 局内循环:行动顺序(NextCharacter())→ 等待该角色决策(WS gaming.action)→ ProcessTurn(character)(或插件模式接管整回合逻辑)
  • 维护 gameId → GameSession(队列、玩家会话映射、状态);断线重连、强制结束、观战
  • 游戏结束:结算 GameResult/CharacterStatistics → 写 GameRecords → 通知各端

6.2 回合记录外发 GameRoundRecordSink : IRoundRecordSink

  • 实现 Core v3 的 9 个外发事件(Action/Round/CheckpointRound/CharacterStatistics/Characters/Teams/QueueData/EliminatedCharacters/EliminatedTeams)
  • 本地归档:每局一个 records/{gameId}.zip(沿用 Testing-v3 的 rounds_data.json 格式)或按配置写入 RoundRecords 表
  • 远程转发(可选):配置 RoundRecordSink:PostUrl + Secret 时,内部包装 DefaultRoundRecordSink 转发(生产者/消费者都可)
  • 回放 REST:GET /api/games/{id}/rounds、GET /api/games/{id}/rounds/{n}、GET /api/games/{id}/statistics(参考 Testing-v3 端点设计),配合 BattleStatePredictor 提供任意回合状态
  • WS 实时推送:订阅 sink 事件 → 广播 gaming.round / gaming.action(观战/直播能力)

7. WebUI 管理台(决策 2)

技术栈:React 18 + Vite + TypeScript + Tailwind CSS v4(与 Testing-v3 webui 同栈,可复用组件风格)。

页面 功能
登录 统一 JWT 登录(与 WebAPI/WS 同一认证)
仪表盘 在线玩家/连接数、进行中对局、服务器状态、近期日志
玩家管理 Users CRUD、资料、角色分配、会话管理(踢下线)、登录日志
权限管理 Roles / Permissions CRUD、角色-权限配置
房间/对局 房间列表、对局监控、强制结束、观战入口
插件/模组管理 插件清单、热重载/卸载、实体模组 JSON 编辑与重载
数据管理 各业务表 CRUD 通用表格页(商店/市场/物品/系统配置…)
回放中心 对局记录、回合回放(复用 Testing-v3 回放面板)
日志 ServerLogs 检索、级别过滤、实时尾巴
  • 开发:vite dev(5173)代理 /api、/ws → 服务器(默认 5000)
  • 生产:npm run build → webui/dist 由 Host 静态托管(同 Testing-v3 模式)

8. 目录与命名约定

  • 根命名空间:FunGame.Server.Contracts / FunGame.Server.Infrastructure / FunGame.Server.PluginHost / FunGame.Server.Host;模组/插件可自定义(如 FunGame.Server.Plugins.OfficialStandard)
  • REST 路由:/api/{resource};管理端 [Permission] 保护
  • WS 消息类型:小写点分(room.create、gaming.action)
  • 配置:appsettings.json(分层:Database/Jwt/Auth/Server/RoundRecordSink/Bootstrap/Cors/Plugins)
  • 日志:ILogger + ServerLogs 数据库通道(Serilog 可选接入)

9. 里程碑(对应实施顺序)

  • M0 骨架:解决方案 + 4 个类库/宿主 + Core 引用 + 编译通过 ✅
  • M1 数据层:实体、DbContext、双 Provider、迁移、种子数据、CRUD 基类 + 首批控制器 ✅
  • M2 认证:JWT + 刷新令牌 + 会话 + 权限过滤 + WS 握手认证 ✅
  • M3 插件系统:PluginHost 热重载 + 示例插件/模组 + 管理端点 ✅(影子加载 + _staging 热替换 + 文件监视)
  • M4 WebSocket:ClientSession、信封、消息分发、心跳/断线 ✅
  • M5 业务:房间/匹配/聊天/对局宿主 + 回合记录归档与外发 + 回放端点 ✅(AI 对局循环为演示实现,玩家局内决策接入待办)
  • M6 WebUI:管理台全页面(登录/仪表盘/用户/插件/对局/回放/日志)✅
  • M7 加固发布:测试、Linux 发布、文档 ⏳(进行中)

M7 剩余事项

  • 玩家局内决策接入(gaming.action 驱动 GamingQueue,当前为 AI 自动循环)
  • 更完整的匹配队列(Elo 扩圈,当前为快速匹配演示)
  • 单元/集成测试项目(参考 Testing-v3 的 Tests)
  • Linux 自包含发布脚本(参考 Testing-v3 publish-linux.sh)
  • WebUI 权限/角色管理页、系统配置页
  • MySQL Provider 的迁移与部署验证