# 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`: ```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`: ``` 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`;权限用 `[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`(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`) ### 4.2 负载信封(替代 SocketObject) ```jsonc // 客户端 → 服务器(请求) { "t": "room.create", // 消息类型(点分字符串,替代 SocketMessageType 枚举) "i": 1, // 请求序号(客户端生成,用于响应关联) "d": { ... } // 负载(Dictionary,实体用 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 对齐) ```jsonc { "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` 生成/读取 JSON 配置;`Factory.GetGameModuleInstances(module, file)` 实例化实体 - WebUI 提供"实体模组管理"页:查看/编辑/重新加载 JSON 配置(不重启进程改游戏内容) ### 5.4 服务器插件接口(Contracts) ```csharp public interface IServerPlugin : IPluginBase { // 注册 HTTP 端点(挂载 /plugin/{name}/{path},注册表 + 单一路由分发,可热移除) // 与 WebSocket 消息处理器(随插件热卸载自动注销) void ConfigureEndpoints(IPluginHttpHandlerRegistry http, IMessageHandlerRegistry messages); // 对局模式逻辑(可选):局内消息转发到模式插件 Task?> HandleGamingMessage(IGameSession session, string type, Dictionary 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 的迁移与部署验证