17 KiB
17 KiB
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
- SQLite →
- 迁移目录按 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 Claimperm数组;PermissionAttribute("code")服务端校验 - 首次启动种子:系统角色(Admin/Moderator/User)、全部权限点、初始管理员(用户名/密码由 appsettings
Bootstrap:Admin提供,仅首次生效)
4. WebSocket 与负载模型(决策 3/7)
4.1 接入
- 端点:
GET /ws?access_token={jwt} - ASP.NET Core 原生
UseWebSockets;连接对象ClientSession(会话模型,替代 v2ServerModel<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 |
同上(物品) |
实体模组也可只提供
EntityModuleConfigJSON 文件(平行通道,见 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())→ 等待该角色决策(WSgaming.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 的迁移与部署验证