first commit
This commit is contained in:
@@ -0,0 +1,376 @@
|
||||
# FunGame.Server v2 功能总结
|
||||
|
||||
> 分析对象:`C:\milimoe\FunGame.Server`(基于 FunGame.Core **v2 / 分支 v2 / 2.1.0**)
|
||||
> 说明:本文基于 v2 服务器源码逐文件梳理,用于作为 v3 开发内容决策的基准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目总览
|
||||
|
||||
v2 服务器仓库构建 **两个** 可执行程序 + 一个实现类库:
|
||||
|
||||
| 项目 | 类型 | 职责 |
|
||||
|---|---|---|
|
||||
| `FunGame.Server` (FunGameServer.exe) | .NET 控制台 (net10.0) | **Socket (TCP) 或 WebSocket 二选一** 的游戏服务器,带管理控制台 |
|
||||
| `FunGame.WebAPI` (FunGameWebAPI.exe) | ASP.NET Core Web API (net10.0) | **WebSocket + RESTful API 共存**,共享同一套数据处理逻辑 |
|
||||
| `FunGame.Implement` | 类库 | 实现 Core 的 `IServer` 接口(目前仅提供空 `SecretKey`) |
|
||||
|
||||
### 依赖(NuGet / 项目引用)
|
||||
|
||||
- `FunGame.Core` **2.1.0**(v2 核心库,含网络、SQLHelper、插件/模组加载器等全部服务器运行时)
|
||||
- `FunGame.SQLQueryExtension` 2.0.0(SQLHelper 的查询扩展,全部 SQL 语句都来自这里)
|
||||
- `MySql.Data`、`Microsoft.Data.Sqlite`
|
||||
- `FunGame.Implement`(项目引用)
|
||||
|
||||
### v2 架构特征
|
||||
|
||||
v2 的架构是 **"Core 内置整套服务器运行时"**:网络监听、Socket 协议、数据库访问、SMTP 邮件、插件/模组加载器、任务调度、INI 配置……全部由 Core 提供,Server 项目只负责"接线"与业务逻辑(连接握手、数据请求分发、房间/用户/经济业务)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 启动流程(Main.cs / Program.cs)
|
||||
|
||||
### 2.1 FunGameServer(控制台)
|
||||
|
||||
1. 设置控制台标题、打印版本信息
|
||||
2. 检查 `FunGame.ini` 配置文件,不存在则自动生成并退出
|
||||
3. 读取配置(`ServerHelper.GetServerSettings()` → `Config`)
|
||||
4. 解析启动参数:`--debug/-d`、`--allowanyorigin/-aao`
|
||||
5. 初始化 SQLHelper(`FunGameSystem.InitSQLHelper`:MySQL/SQLite 二选一,首次运行自动建库)
|
||||
6. 初始化 MailSender(SMTP)
|
||||
7. 加载 Server 插件(`plugins/` 目录)
|
||||
8. 加载游戏模组(`modules/` 目录,地图/角色/技能/物品/GameModuleServer 五项)
|
||||
9. 初始化本地配置(`PluginConfig`:user_keys / local / sqlconfig)
|
||||
10. 启动监听(Socket 或 WebSocket 二选一,`Config.UseWebSocket`)
|
||||
11. 进入控制台命令循环
|
||||
|
||||
### 2.2 FunGameWebAPI(ASP.NET Core)
|
||||
|
||||
流程与上面类似,额外:
|
||||
|
||||
- 读取 Web API 插件(`WebAPIPlugin`,可在插件里注册 ASP.NET Controller)
|
||||
- 搭建 ASP.NET Core:JWT 认证、CORS、OpenAPI + Scalar 文档、自定义 JSON 转换器、异常处理
|
||||
- WebSocket 监听挂载在 `/ws` 路径
|
||||
- 认证方案三种并存:`JwtBearer`、`APIBearer`(API Token)、`CustomBearer`
|
||||
- 控制台命令循环在后台任务中运行
|
||||
|
||||
---
|
||||
|
||||
## 3. 连接与会话管理
|
||||
|
||||
### 3.1 连接握手(`ConnectController.Connect<T>`)
|
||||
|
||||
- 人数上限检查(`ConnectingPlayerCount + OnlinePlayerCount > MaxPlayers` 拒绝)
|
||||
- IP 黑名单检查(`BannedList`,按 `ip:port` 拆分比较)
|
||||
- 客户端参数验证(`OnValidateClientParameters`):
|
||||
- Desktop 参数 1:客户端模组列表,与服务器 `GameModuleSupported` 对比,缺失则拒绝
|
||||
- Desktop 参数 2:客户端是否开启开发者模式(`isDebugMode`,开发者模式部分功能禁用)
|
||||
- 可挂载 `ValidateClientParameters` 事件由插件扩展校验
|
||||
- 握手回复 `Connect` 消息(成功/失败原因),携带服务器名与公告
|
||||
- 连接成功回调插件事件:`OnBeforeConnectEvent` / `OnAfterConnectEvent`
|
||||
|
||||
### 3.2 客户端会话(`ServerModel<T>` : IServerModel)
|
||||
|
||||
每个连接对应一个 `ServerModel<ServerSocket>` 或 `ServerModel<ServerWebSocket>`:
|
||||
|
||||
- **消息分发** `SocketMessageHandler`:校验 Token(除 HeartBeat 外必须匹配)、处理 8 种消息类型
|
||||
- **HeartBeat** 心跳(回显 probeId)
|
||||
- **DataRequest** 数据请求(见第 4 节)
|
||||
- **GamingRequest** / **Gaming** 对局请求与广播(转发给 `GameModuleServer`)
|
||||
- **AnonymousGameServer** 匿名模组服务器(建立/断开)
|
||||
- **ReconnectToGame** 断线重连对局(从 `NowGamingServers` 找回对局并重新下发 `StartGame`)
|
||||
- **EndGame** 结束对局(清理 NowGamingServer,房间恢复 Created)
|
||||
- **Disconnect** 断开连接
|
||||
- 会话生命周期:`SetClientName`(加入 ClientList、在线数+1)→ `Start`(循环读取 + SQL 保活轮询)→ `Close`(移除、在线数-1)
|
||||
- **失败计数**:连续读失败超过 `MaxConnectionFaileds`(默认 5)自动踢出
|
||||
- **SQL 保活**:每 2 小时对 SQL 服务器做一次心跳查询
|
||||
- 登录态:`PreLogin`(暂存 DataSet + 登录 key)→ `CheckLogin`(构造 User、重复登录检查、加入 UserList)
|
||||
|
||||
### 3.3 在线玩家管理
|
||||
|
||||
- `Listener.ClientList`(所有连接)/ `Listener.UserList`(已登录玩家)/ 全局 `FunGameSystem.UserList`
|
||||
- `AddUser`:记录登录时间、更新最后登录 IP
|
||||
- `RemoveUser`:记录下线时间、累计游戏时长(分钟)写入数据库
|
||||
- 重复登录:`ForceLogOutDuplicateLogonUser` 强制旧连接下线
|
||||
- 踢人/强制下线:`Kick` / `ForceLogOut`(会先退出房间)
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据请求系统(DataRequest)
|
||||
|
||||
`DataRequestController<T>` 是业务核心,按 `DataRequestType` 分发,**全部请求类型**:
|
||||
|
||||
### RunTime
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `RunTime_Logout` | 退出登录(插件可拦截) |
|
||||
|
||||
### Main(大厅/房间)
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `Main_GetNotice` | 获取服务器公告 |
|
||||
| `Main_CreateRoom` | 创建房间(7 位随机房间号、写库、插件事件) |
|
||||
| `Main_UpdateRoom` | 拉取房间列表 |
|
||||
| `Main_IntoRoom` | 进入房间(校验数据库存在、广播进入消息) |
|
||||
| `Main_QuitRoom` | 退出房间(房主退出则移交/解散) |
|
||||
| `Main_MatchRoom` | 开始/取消匹配 |
|
||||
| `Main_Chat` | 房间聊天(广播同房间客户端) |
|
||||
| `Main_Ready` / `Main_CancelReady` | 准备 / 取消准备 |
|
||||
| `Main_StartGame` | 开始游戏(见 5.3) |
|
||||
|
||||
### Reg / Login(账号)
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `Reg_Reg` | 注册(邮箱验证码流程) |
|
||||
| `Login_Login` | 登录(密码或 autokey;check-login key 二次确认) |
|
||||
| `Login_GetFindPasswordVerifyCode` | 找回密码验证码(10 分钟有效,SMTP 发送) |
|
||||
| `Login_UpdatePassword` | 更新密码(换新用户密钥加密) |
|
||||
|
||||
### Room(房间管理)
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `Room_UpdateRoomSettings` | 房主更新房间设置(类型/密码/人数/模组/地图,仅 Created 状态) |
|
||||
| `Room_GetRoomPlayerCount` | 查询房间人数 |
|
||||
| `Room_UpdateRoomMaster` | 转让房主(写库 + 广播) |
|
||||
|
||||
### UserCenter(个人中心)
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `UserCenter_UpdateUser` | 更新用户资料 |
|
||||
| `UserCenter_UpdatePassword` | 修改密码 |
|
||||
| `UserCenter_DailySignIn` | 每日签到(连续签到天数,跨天重置) |
|
||||
|
||||
### Inventory(库存/经济)
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `Inventory_GetStore` | 获取商店(按 store id + 商品) |
|
||||
| `Inventory_GetMarket` | 获取市场(按用户或全局、状态过滤、按物品过滤) |
|
||||
| `Inventory_StoreBuy` | 商店购买(双货币、库存扣减、事务) |
|
||||
| `Inventory_MarketBuy` | 市场购买(15% 手续费、事务) |
|
||||
| `Inventory_UpdateInventory` | 更新库存(全量/增量) |
|
||||
| `Inventory_Use` | 使用物品(目标角色参数) |
|
||||
| `Inventory_StoreSell` | 商店出售(按物品 Price 回收货币) |
|
||||
| `Inventory_MarketSell` | 市场寄售(价格 + 库存) |
|
||||
| `Inventory_MarketDelist` | 下架市场物品 |
|
||||
| `Inventory_UpdateMarketPrice` | 修改寄售价 |
|
||||
| `Inventory_GetOffer` | 查看交易报价(权限校验) |
|
||||
| `Inventory_MakeOffer` | 发起交易报价 |
|
||||
| `Inventory_ReviseOffer` | 修改报价(9 种状态机动作,见 7.4) |
|
||||
| `Inventory_RespondOffer` | 回应报价(接受/拒绝) |
|
||||
|
||||
### Addon(扩展)
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `Addon_Plugin` | 转发给 ServerPlugin / WebAPIPlugin 的 `HandleDataRequest`(支持指定目标插件) |
|
||||
| `Addon_Module` | 转发给 GameModuleServer 的 `HandleDataRequest` |
|
||||
|
||||
---
|
||||
|
||||
## 5. 房间与对局系统
|
||||
|
||||
### 5.1 房间模型
|
||||
|
||||
- `FunGameSystem.RoomList` 全局房间列表(内存)
|
||||
- 房间属性:房间号(7 位随机大写)、房主、类型(`RoomType`)、密码、最大人数、模组(GameModule)、地图(GameMap)、是否排位、状态(Created/Matching/Gaming)
|
||||
- 房间持久化在 `rooms` 表,服务器重启时清空房间表
|
||||
|
||||
### 5.2 匹配系统(Elo)
|
||||
|
||||
- 按 `RoomType` 过滤目标房间(`All` 匹配全部)
|
||||
- 取房间玩家平均 Elo(`Statistics.EloStats[0]`),与玩家 Elo 差在 `300 * i` 内命中
|
||||
- 每 10 秒扩大匹配范围(`i++` 并刷新房间列表),最长 50 秒后返回第一个房间
|
||||
- 匹配过程在线程中轮询(100ms 间隔),可随时取消
|
||||
|
||||
### 5.3 开始游戏流程
|
||||
|
||||
- 房主触发:检查未准备玩家 → 提醒(15 秒 CD)→ 全部准备后发送"10 秒后开始"
|
||||
- 玩家可请求房主开始(同样 15 秒 CD)
|
||||
- 实际启动:`GameModuleLoader.GetServerMode(room.GameModule)` 获取 `GameModuleServer`,为房间所有玩家绑定该服务器、设置 `OnlineState.Gaming`、写入 `Listener.NowGamingServers[userId]`、构造 `GamingObject(room, users, master, all)`、调用 `StartServer(obj)` 后向玩家发送 `StartGame` 消息
|
||||
|
||||
---
|
||||
|
||||
## 6. 账号系统(DataRequestService / Authenticator)
|
||||
|
||||
- **注册**:邮箱验证码(SMTP 发送 6 位数字码,10 分钟有效)→ 校验用户名/邮箱唯一 → 注册入库;首次注册管理员在数据库初始化时控制台交互完成
|
||||
- **登录**:密码用"用户专属密钥"加密后比对(`FunGameSystem.GetUserKey(username)` 来自本地 `user_keys` 配置,改密时轮换密钥)→ 成功后下发 Guid 形式的 check-login key → 客户端凭 key 二次确认登录;支持 `autokey` 自动登录
|
||||
- **找回密码**:邮箱匹配校验 → 验证码发送(10 分钟、限频)→ 验证通过后允许改密
|
||||
- **2FA**:`Authenticator` / `TFA` 类已搭好骨架(继承 Core 的 `Authenticator` / `TwoFactorAuthenticator`),目前 `AfterAuthenticator` / `BeforeAuthenticator` / `IsAvailable` 均为空实现,预留接入点
|
||||
- **安全细节**:密码加密使用每用户随机密钥(`Encryption.GenerateRandomString`);管理员 `IsAdmin` 标记;`NetworkUtility` 校验用户名长度(3~12,中文按 2 字符)、邮箱格式
|
||||
|
||||
---
|
||||
|
||||
## 7. 经济系统
|
||||
|
||||
### 7.1 货币
|
||||
|
||||
- `Credits`(游戏币,InGameCurrency)与 `Materials`(材料,InGameMaterial)双货币
|
||||
- 商店商品按货币分别定价(`Goods.GetPrice(currency)`)
|
||||
|
||||
### 7.2 商店
|
||||
|
||||
- 商店含商品(Goods)+ 价格表(GoodsPrices)+ 库存(Stock,-1 为无限)
|
||||
- 购买:事务内扣货币、扣库存、生成物品(`IsTradable=false`、设定可交易时间、价格折算 35% / 7 倍)、支持 `ignore` 部分失败仍提交
|
||||
- 出售:按物品 `Price` 回收货币,检查 `IsSellable` 与可出售时间
|
||||
|
||||
### 7.3 市场
|
||||
|
||||
- 寄售(价格 + 库存数量)、改价、下架、按用户/状态/物品查询
|
||||
- 购买:15% 手续费(卖家实收 85%),事务内转移物品(买家获得的新物品有可交易冷却)
|
||||
|
||||
### 7.4 交易报价(Offer 状态机)
|
||||
|
||||
- 发起 → 协商(最多 3 轮)→ 确认 → 发送 → 接受/拒绝/取消/过期
|
||||
- 9 种动作:`OfferorRevise / OfferorConfirm / OfferorSend / OfferorCancel / OfferorAccept / OffereeRevise / OffereeConfirm / OffereeSend / OffereeAccept / OffereeReject`
|
||||
- 物品可交易性检查(`IsTradable` + `NextTradableTime`)、修改前备份(`BackupOfferItem`)、事务回滚
|
||||
|
||||
### 7.5 物品使用
|
||||
|
||||
- `item.UseItem(user, useCount, args)`,参数携带目标角色数组;使用后更新库存
|
||||
|
||||
---
|
||||
|
||||
## 8. 数据库层
|
||||
|
||||
- **双数据库**:MySQL / SQLite,由 `FunGame.ini` 的 `[MySQL]` / `[SQLite]` 开关决定;抽象基类 `SQLHelper`,Server 侧实现 `MySQLHelper` / `SQLiteHelper`(连接、执行、事务、DataSet、参数化)
|
||||
- **首次初始化**:执行 `fungame.sql` / `fungame_sqlite.sql` 建库脚本(Core v2 提供)→ 控制台创建管理员 → 生成 `.apisecret` 文件与默认 API Token(`fungame_web_api`,仅显示一次)→ 写 `Initialization` 配置标记
|
||||
- **表结构(来自 SQLQueryExtension)**:users、user_profiles、user_characters、user_items、inventories、stores、goods、goods_prices、store_goods、market_items、offers、offer_items、rooms、reg_verify_codes、forget_verify_codes、user_sign_ins、api_tokens、configs、server_login_logs、user_logs 等
|
||||
- 版本补丁脚本:`Library/SQLScript/PatchScript/{mysql,sqlite}/2.0.0.250728.sql`
|
||||
- 服务器启动登记 `ServerLoginLogs`;每个会话有 2 小时 SQL 心跳保活
|
||||
|
||||
---
|
||||
|
||||
## 9. 插件系统
|
||||
|
||||
### 9.1 ServerPlugin(`plugins/` 目录 DLL)
|
||||
|
||||
- 继承 Core 的 `ServerPlugin`,通过 `LoadPlugins` / `LoadPluginsByHotLoadMode` 加载(`UseHotLoadAddons` 开启热加载)
|
||||
- 全流程事件钩子(在 DataRequestController / ServerModel / Main 中触发):
|
||||
- 连接:`OnBefore/AfterConnectEvent`、`OnAfterDisconnectEvent`
|
||||
- 登录:`OnBefore/AfterLoginEvent`、`OnBefore/AfterLogoutEvent`、`OnBeforeRegEvent`、`OnAfterRegEvent`
|
||||
- 房间:`OnBefore/AfterCreateRoomEvent`、`IntoRoom`、`QuitRoom`、`ChangeRoomSetting`
|
||||
- 对局:`OnBefore/AfterStartGameEvent`、`OnBefore/AfterEndGameEvent`、`OnBeforeStartMatchEvent`
|
||||
- 行为:`OnBefore/AfterSendTalkEvent`、`OnBeforeChangeProfileEvent`、`OnBeforeChangeAccountSettingEvent`、`OnBefore/AfterSignInEvent`、`OnBefore/AfterBuyItemEvent`、`OnBefore/AfterUseItemEvent`、`OnBeforeOpenStoreEvent`、`OnBefore/AfterStartGameEvent`……
|
||||
- 事件均支持 `Cancel` 拦截(返回 `GetPluginCancelString` 拒绝原因)
|
||||
- 插件可响应控制台指令(`plugin.ProcessInput`)、处理自定义 DataRequest(`HandleDataRequest`)
|
||||
|
||||
### 9.2 WebAPIPlugin
|
||||
|
||||
- 类似 ServerPlugin + 可在插件程序集内注册 ASP.NET Controller(`AssemblyPart` 动态加入)
|
||||
- 额外钩子:`OnWebAPIStarted`(拿到 `WebApplication` 与 listener 后回调)
|
||||
|
||||
### 9.3 热加载
|
||||
|
||||
- `reload addons/modules/plugins/serverplugins/webapiplugins` 控制台指令
|
||||
- `TaskScheduler.StartCleanUnusedAddonContexts` 清理卸载的加载上下文
|
||||
|
||||
---
|
||||
|
||||
## 10. 模组系统
|
||||
|
||||
- `GameModuleLoader` 加载 `modules/` 目录:`GameMap`(地图)、`CharacterModule`(角色)、`SkillModule`(技能)、`ItemModule`(物品)、`GameModuleServer`(模组服务器)
|
||||
- 加载校验:模组服务器必须有对应的 `DefaultMap` 地图,否则加载失败
|
||||
- `GameModuleServer`:对局服务器实现(`StartServer(GamingObject)`、`GamingMessageHandler`、`HandleDataRequest`、`AnonymousGameServerHandler`、`Close`),由模组开发者在 DLL 中实现
|
||||
- 热更新:`HotReloadGameModuleList`
|
||||
|
||||
---
|
||||
|
||||
## 11. 控制台管理指令(FunGameServer / FunGameWebAPI 共用)
|
||||
|
||||
| 指令 | 别名 | 功能 |
|
||||
|---|---|---|
|
||||
| `help` | - | 列出可用指令及别名 |
|
||||
| `quit` / `exit` / `close` | - | 关闭服务器 |
|
||||
| `restart` | - | 重新启动监听(仅未运行时) |
|
||||
| `kick <客户端名>` | - | 踢出客户端 |
|
||||
| `logout <玩家名>` | - | 强制下线玩家 |
|
||||
| `show [clients\|users\|-c\|-u]` | `clients` / `users` | 查看在线客户端/玩家列表 |
|
||||
| `ban add\|remove <ip>` | `-a` / `-r` | 添加/移除 IP 黑名单 |
|
||||
| `reload <addons\|modules\|plugins\|serverplugins\|webapiplugins>` | `-a/-m/-p/-sp/-wp` | 热重载加载项 |
|
||||
|
||||
- 命令解析支持引号与转义(`ParseCommandLine`)
|
||||
- 未知指令广播给插件处理
|
||||
|
||||
---
|
||||
|
||||
## 12. WebAPI(RESTful)接口清单
|
||||
|
||||
统一返回 `PayloadModel<T>`(Event / RequestType / StatusCode / Message / Timestamp / Data)。
|
||||
|
||||
### 认证相关
|
||||
| 端点 | 说明 |
|
||||
|---|---|
|
||||
| `POST /User/register` | 注册(RegDTO) |
|
||||
| `POST /User/login` | 登录(LoginDTO,签发 JWT) |
|
||||
| `POST /User/logout` | 退出登录 |
|
||||
| `POST /User/refresh` | 刷新 JWT |
|
||||
|
||||
### 大厅/房间
|
||||
| 端点 | 说明 |
|
||||
|---|---|
|
||||
| `GET /Main/notice` | 服务器公告 |
|
||||
| `POST /Main/chat` | 聊天 |
|
||||
| `POST /Room/create` / `list` / `join` / `quit` / `match` / `ready` / `cancelready` / `start` / `updateroomsettings` / `playercount` / `updatemaster` | 房间全流程 |
|
||||
|
||||
### 用户中心
|
||||
| 端点 | 说明 |
|
||||
|---|---|
|
||||
| `PUT /UserCenter/updateuser` / `updatepassword` | 资料/密码 |
|
||||
| `POST /UserCenter/dailysignin` | 每日签到 |
|
||||
|
||||
### 库存/经济
|
||||
| 端点 | 说明 |
|
||||
|---|---|
|
||||
| `GET /Inventory/getstore`、`getmarketbyuser`、`getmarketbyitem`、`getoffer` | 查询类 |
|
||||
| `POST /Inventory/storebuy`、`marketbuy`、`updateinventory`、`useitem`、`storesell`、`marketsell`、`marketdelist`、`updatemarketprice`、`makeoffer`、`reviseoffer`、`respondoffer` | 操作类 |
|
||||
|
||||
### 协议转发
|
||||
| 端点 | 说明 |
|
||||
|---|---|
|
||||
| `POST /DataRequest` | 客户端以 `PayloadModel<DataRequestType>` 形式直接调用数据请求(JWT 身份 → RESTfulAPIModel) |
|
||||
| `POST /GamingRequest` | 对局请求转发 |
|
||||
| `POST /Adapter` | 接收原始 `SocketObject`(供客户端协议适配) |
|
||||
| `WS /ws` | WebSocket 接入点(完整游戏协议) |
|
||||
|
||||
### WebAPI 架构要点
|
||||
|
||||
- `RESTfulAPIListener` + `RESTfulAPIModel`:REST 请求通过 `IUserContext`(`HttpUserContext` 从 JWT 取用户名)关联在线玩家模型,与 WebSocket 玩家**共享同一套 ServerModel 逻辑**
|
||||
- `JwtAuthenticationMiddleware`:JWT 与两种 Bearer 处理器(API Token / 自定义 Token)
|
||||
- `JWTService`:签发/刷新 JWT
|
||||
- OpenAPI + Scalar 文档(仅开发环境);CORS 白名单(默认 localhost:12099,`--allowanyorigin` 可全开)
|
||||
- 静态文件托管 + 前端默认页
|
||||
|
||||
---
|
||||
|
||||
## 13. 配置(FunGame.ini)
|
||||
|
||||
| 节 | 键 | 说明 |
|
||||
|---|---|---|
|
||||
| `[Console]` | `LogLevel`、`UseHotLoadAddons` | 日志级别、热加载开关 |
|
||||
| `[Server]` | `Name`、`Password`、`Description`、`Notice`、`Key`、`Status`、`BannedList`、`UseDesktopParameters` | 服务器信息与公告、社区注册 Key、黑名单 |
|
||||
| `[ServerMail]` | `OfficialMail`、`SupportMail` | 官方/支持邮箱 |
|
||||
| `[Socket]` | `Port`、`UseWebSocket`、`WebSocketAddress`、`WebSocketPort`、`WebSocketSubUrl`、`WebSocketSSL`、`MaxPlayer`、`MaxConnectFailed` | 监听与人数上限 |
|
||||
| `[MySQL]` / `[SQLite]` | `UseMySQL` / `UseSQLite`、连接参数 | 数据库开关与连接串 |
|
||||
| `[Mailer]` | `UseMailSender`、`MailAddress`、`Name`、`Password`、`Host`、`Port`、`SSL` | SMTP 邮件服务 |
|
||||
|
||||
---
|
||||
|
||||
## 14. 日志
|
||||
|
||||
- `ServerHelper` 分级彩色控制台输出:`[Core] [Error] [Api] [Warning] [Interface] [DataRequest] [Plugin] [GameModule] [System]`
|
||||
- 时间戳 + 日志级别前缀(TRACE~CRIT,按 `Config.LogLevel` 过滤)
|
||||
- 异常写 `error.log`(`TXTHelper.AppendErrorLog`)
|
||||
- 插件/模组可通过委托 `WriteLine_Addons` 接入同一日志体系
|
||||
|
||||
---
|
||||
|
||||
## 15. 小结(v2 能力全景)
|
||||
|
||||
```
|
||||
FunGameServer v2 = 连接层(Socket/WebSocket) + 会话层 + 业务层(房间/匹配/账号/经济)
|
||||
+ 插件/模组扩展 + 控制台管理 + 双数据库 + SMTP + 日志
|
||||
FunGameWebAPI v2 = WebSocket + REST(JWT) + 与游戏服务器共享的会话/业务模型
|
||||
```
|
||||
|
||||
**v2 中属于"服务器自研"(迁移到 v3 需要保留/重写)**:连接握手、会话模型、DataRequest 分发、房间/匹配/账号/经济全部业务逻辑、控制台指令、数据库访问封装。
|
||||
|
||||
**v2 中由 Core v2 提供(v3 已删除,见 02 文档)**:网络监听与协议、SQLHelper 抽象、MailSender、插件/模组加载器、INI 读写、任务调度、Factory、日志工具等。
|
||||
@@ -0,0 +1,211 @@
|
||||
# FunGame.Core v3 变更分析(v2 → v3)
|
||||
|
||||
> 分析对象:`C:\milimoe\FunGame.Core`(master 分支,3.0.0-dev,net10.0)
|
||||
> 对比基准:v2 分支(2.1.0 Release)
|
||||
> 配套参考:`C:\milimoe\FunGame.Testing-v3`(v3 的测试项目,WebAPI + React 回放台)
|
||||
|
||||
---
|
||||
|
||||
## 1. 总体结论(先看这里)
|
||||
|
||||
**v3 把 Core 从"游戏服务器运行时框架"重构为"纯回合制战斗引擎库"。**
|
||||
|
||||
- v2:Core = 网络 + 数据库 + 插件 + 模组加载 + 邮件 + 任务调度 + 战斗引擎(一整包服务器运行时)
|
||||
- v3:Core = 实体模型 + 战斗引擎(GamingQueue)+ 回合记录/回放基础设施 + 模块(数据驱动)机制。**网络、SQL、SMTP、插件加载器等全部从 Core 中移除**,由使用方(Server / WebAPI 等)自行实现。
|
||||
|
||||
v2→v3 共 10 个提交、280 个文件变更,+4816 / -18642 行——**删除远多于新增**,删除的正是"服务器运行时"那一层。
|
||||
|
||||
---
|
||||
|
||||
## 2. 版本与命名空间
|
||||
|
||||
| 项 | v2 | v3 |
|
||||
|---|---|---|
|
||||
| 版本 | 2.1.0 | 3.0.0-dev(每日版本后缀) |
|
||||
| 目标框架 | net10.0(v2 分支后期已升级) | net10.0 |
|
||||
| 根命名空间 | `Milimoe.FunGame.Core` | `FunGame.Core` |
|
||||
| 打包 | NuGet `FunGame.Core` | 继续 NuGet 发布(新增自动发布工作流)+ slnx |
|
||||
| 文档 | README.md | README.md + README_EN.md |
|
||||
|
||||
> ⚠️ **命名空间整体变更**:所有 v2 代码中的 `using Milimoe.FunGame.Core.*` 在 v3 都要改为 `using FunGame.Core.*`。这是迁移时最机械但覆盖面最广的改动。
|
||||
|
||||
---
|
||||
|
||||
## 3. 从 Core 中移除的内容(v3 不再提供)
|
||||
|
||||
> 这些能力在 v3 Server 项目中**必须自行实现**(或放弃)。
|
||||
|
||||
### 3.1 网络与协议层(全部移除)
|
||||
|
||||
| 移除项(v2 位置) | 功能 |
|
||||
|---|---|
|
||||
| `Service/SocketManager.cs` | Socket 服务管理 |
|
||||
| `Library/Common/Network/Socket.cs`、`SocketObject.cs` | Socket 对象与消息协议(SocketMessageType 等) |
|
||||
| `Library/Common/Network/ServerSocket.cs`、`ServerWebSocket.cs` | 服务端 Socket/WebSocket 实现 |
|
||||
| `Library/Common/Network/SocketListener.cs`、`HTTPListener.cs` | 监听器(TCP / HTTP 前缀) |
|
||||
| `Library/Common/Network/HTTPClient.cs` | HTTP 客户端封装 |
|
||||
| `Interface/Base/ISocketListener`、`ISocketMessageProcessor`、`IBaseSocket`、`ISocketHeartBeat`、`ISocketHandler`、Sockets/* | 网络接口 |
|
||||
| `Controller/SocketHandlerController.cs`、`Service/HTTPManager.cs` | 消息处理与 HTTP 管理 |
|
||||
| `Library/Common/Architecture/HeartBeat.cs`、`AsyncAwaiter.cs`、`TaskAwaiter.cs`、`SyncAwaiter.cs`(部分) | 心跳与异步等待基建 |
|
||||
|
||||
### 3.2 数据访问层(移除)
|
||||
|
||||
| 移除项 | 功能 |
|
||||
|---|---|
|
||||
| `Api/Transmittal/SQLHelper.cs`、`Interface/Base/ISQLHelper.cs`、`Model/SQLServerInfo.cs` | SQLHelper 抽象 |
|
||||
| `Library/SQLScript/**`(全部) | 全部 SQL 语句类(UserQuery、RoomQuery、OffersQuery……)与建库脚本 fungame.sql / fungame_sqlite.sql、补丁脚本 |
|
||||
| `Library/Common/JsonConverter/DataSetConverter.cs`、`DataTableConverter.cs` | DataSet/DataTable 序列化(SQL 时代的遗留) |
|
||||
|
||||
### 3.3 通信协议与事务(移除)
|
||||
|
||||
| 移除项 | 功能 |
|
||||
|---|---|
|
||||
| `Api/Transmittal/DataRequest.cs` | DataRequestType 数据请求传输模型 |
|
||||
| `Api/Transmittal/MailSender.cs`、`IMailSender`、`Model/SmtpClientInfo.cs`、`Library/Common/Network/MailObject.cs` | SMTP 邮件 |
|
||||
| `Library/Common/Addon/AddonDataRequestEventArgs.cs` | 插件数据请求事件 |
|
||||
|
||||
### 3.4 插件 / 模组 / 加载器(移除或重构)
|
||||
|
||||
| 移除项 | 功能 |
|
||||
|---|---|
|
||||
| `Service/AddonManager.cs`、`HotLoadAddonManager.cs` | 插件管理、热加载上下文管理 |
|
||||
| `Api/Utility/PluginLoader.cs`、`ServerPluginLoader.cs`、`WebAPIPluginLoader.cs`、`PluginConfig.cs` | 插件加载器与配置存储 |
|
||||
| `Library/Common/Addon/Plugin.cs`、`ServerPlugin.cs`、`WebAPIPlugin.cs`、`GameModule.cs`、`GameModuleDepend.cs`、`GameModuleServer.cs`、`GamingObject.cs` | 插件/模组基类(**全部删除**) |
|
||||
| `Api/Utility/GameModuleLoader.cs` | 模组 DLL 加载器 |
|
||||
| `Controller/AddonController.cs`、`BaseAddonController.cs`、`ServerAddonController.cs`、`RunTimeController.cs` | 加载项控制器(事件分发中枢) |
|
||||
| `Interface/Base/Addons/*`、`Interface/Base/HTTP/*`、`Interface/Base/IAddon.cs`→`IModule.cs` | 加载项接口(重构为模块接口) |
|
||||
| `Api/Utility/TextReader.cs`(txt 资源读取)、`TwoFactorAuthenticator.cs`、`Singleton.cs`、`TaskScheduler.cs`、`ConcurrentFIFOQueue.cs`、`ConcurrentModelList.cs` | 工具类 |
|
||||
|
||||
### 3.5 服务器模型(移除)
|
||||
|
||||
| 移除项 | 功能 |
|
||||
|---|---|
|
||||
| `Interface/Base/IServerModel.cs` | 服务器客户端模型接口(v2 Server 的 ServerModel 实现它) |
|
||||
| `Model/Gaming.cs`、`Model/RoomList.cs`、`Model/ActionQueue.cs`、`Model/RecurringTask.cs`、`Model/ScheduledTask.cs`、`Model/Session.cs`、`Model/FunGameConfig.cs` | 服务器状态模型 |
|
||||
|
||||
---
|
||||
|
||||
## 4. v3 新增 / 重构的内容
|
||||
|
||||
### 4.1 回合记录框架(Framework 模型,v3 核心新特性)
|
||||
|
||||
`Model/Framework/` 下新增,围绕"**可回放的对局记录**"设计:
|
||||
|
||||
| 类型 | 说明 |
|
||||
|---|---|
|
||||
| `RoundRecord` | 单回合完整记录:行动流(Actions)、操作类型与目标、技能/物品及消耗、伤害/暴击/闪避/免疫/治疗字典、特效触发(Effects)与施加特效(ApplyEffects)、击杀/助攻、连杀、吟唱/硬直、复活、回合奖励、杂项消息、全角色清单、队伍归属映射、检查点快照、最终统计、游戏结果排名(`GameResult`)等;提供 `Snapshot()` 结构快照 |
|
||||
| `ActionRecord` | 单次操作记录(决策点系统允许一回合多次操作,`ActionIndex` 从 1 开始),含伤害记录、特效记录、状态变更等 |
|
||||
| `CharacterStateSnapshot` | 角色状态快照(HP/MP/EP、装备明细、物品、技能、状态栏特效) |
|
||||
| `EquipmentStateSnapshot` | 装备状态快照 |
|
||||
| `DamageRecord` / `DeathRelation` | 伤害记录 / 死亡关系 |
|
||||
| `RankingEntry` | 游戏结束排名条目(角色或团队、胜者标记、KDA、得分、赚钱) |
|
||||
| `RoundRecordPayload` | **外发数据包线协议**:紧凑字段 `g`(队列 Guid)/`t`(时间戳)/`e`(事件 id)/`d`(数据)/`s`(签名) |
|
||||
| `GameMap`、`Grid` | 地图与格子(原 Addon 中移入 Framework 并重构) |
|
||||
|
||||
### 4.2 回合记录外发通道(v3 最重要新增特性)
|
||||
|
||||
- `Interface/Base/IRoundRecordSink`:**回合记录外发接口**,8+1 个事件:
|
||||
- `SendAction`("0",每次角色操作后即时)、`SendRound`("1",每操作后当前回合全量)、`SendCheckpointRound`("2",检查点回合,带全角色状态快照)、`SendCharacterStatistics`("3")、`SendCharacters`("4")、`SendTeams`("5")、`SendQueueData`("6",行动顺序表)、`SendEliminatedCharacters`("7")、`SendEliminatedTeams`("8")
|
||||
- 另有 `Attach(queueId)`、`End()` 生命周期方法
|
||||
- `Api/DefaultRoundRecordSink`:默认实现——**即时主动 POST 外发**:把数据包 POST 到外部专用服务器(Bearer AccessToken 可选),支持 `Secret` 签名握手(事件 "13" 验证签名,失败每 60s 重试,成功前不外发其他事件),HttpClient 5 秒超时防挂起
|
||||
- `Api/BattleStatePredictor`:**状态推算器**——从回合记录序列推算任意回合的全角色状态(基于检查点 + 行动记录),回放端无需完整状态即可展示
|
||||
- `Api/RoundRecordRenderer`:回合记录文本渲染(`RenderRound` / `RenderAll` / `RenderCharacterActions`)
|
||||
|
||||
### 4.3 战斗引擎重构(GamingQueue)
|
||||
|
||||
- `Model/ActionQueue.cs` → `Model/Queue/GamingQueue.cs`(**+615 行重写**)
|
||||
- `MixGamingQueue`(混战队列)、`TeamGamingQueue`(团队队列)重构
|
||||
- 新增属性:`RoundRecordSink`(绑定外发通道)、`CheckpointInterval`(检查点间隔,默认 50 回合)、`Rounds`(全量回合记录)、`LastRound`、`GameOver`、`CustomData`、`EarnedMoney`、`CharacterDecisionPoints`、`MaxScoreToWin`、`MaxRespawnTimes` 等
|
||||
- 战斗能力保留并强化:伤害计算(物理/魔法)、暴击/闪避/免疫、特效钩子(`EffectHookCache`)、决策点系统(DecisionPoints)、复活、回合奖励、商店(AddStoreItems/BuyItems)、物品使用、地图寻路与目标选择、AI 决策
|
||||
- `Api/EffectHookCache.cs`:特效钩子缓存(配合 `Model/Framework/ActionRecord` 的"特效记录"重写,提交 #167"依靠检查方法重写以记录触发的特效")
|
||||
|
||||
### 4.4 实体工厂与模块配置(数据驱动)
|
||||
|
||||
- `Api/Factory.cs`:新实体工厂——`Factory.OpenFactory.RegisterFactory<T>` / `GetInstance<T>(id, name, args)`(按 id/name 动态实例化 Character/Skill/Effect/Item/Inventory/Room/User),`GetGameModuleInstances<T>(module_name, file_name)` 从**模块配置文件**批量实例化,`CreateGameModuleEntityConfig<T>` 生成模块实体配置
|
||||
- `Api/EntityModuleConfig.cs`:实体模块配置文件(`modules/` 目录、可配置目录)
|
||||
- `Library/Module/`:`IModule` + `CharacterModule` / `SkillModule` / `ItemModule`(`Load()` / `UnLoad()`),替代 v2 的 `Library/Common/Addon/GameModule` 体系;`Example/` 示例模块
|
||||
- 意义:**模组内容 = 代码类 + 配置文件**,运行期按配置实例化,替代 v2 的"DLL 扫描加载"模式
|
||||
|
||||
### 4.5 JSON 序列化体系重构
|
||||
|
||||
- `Service/JsonManager.cs` → `Api/JsonService.cs`(全局 `JsonSerializerOptions`、`GeneralOptions`)
|
||||
- `Library/Common/JsonConverter/` 大幅更新:新增 `ActionRecordConverter`、`CharacterStateSnapshotConverter`、`RankingEntryConverter`、`RoundRecordConverter`(重写)、`EntityRefHelper`(实体引用表,解决循环引用/共享引用)
|
||||
- 移除 DataSet/DataTable 转换器(SQL 时代产物)
|
||||
|
||||
### 4.6 工具类整合
|
||||
|
||||
- `Api/General.cs`:合并 `NetworkUtility`(partial + RegexGenerator)、`Encryption`(HMAC/SHA/RSA/MD5/随机串)、`Verification`(验证码)、日期时间工具、数值工具(Round/PercentageCheck 等)、JSON 快捷方法
|
||||
- `Api/Attribute.cs`、`LINQExtension.cs`、`SkillExtension.cs`、`OpenItemAdapter`/`OpenSkillAdapter`(开放实体适配)、`NovelConfig.cs`(剧情配置)
|
||||
|
||||
### 4.7 保留的内容(基本未动)
|
||||
|
||||
- `Entity/**`:Character / Skill / Effect / Item / Inventory / User / Room / Team / Store / Market / Offer / Goods / Club / Season / Explore(Region/Quest/Activity) / Statistics 等全部实体(局部字段调整:Item 构造公开、Skill 关联 Item、Equal 应用 Guid)
|
||||
- `Library/Constant/`:TypeEnum(含战斗相关枚举)、StateEnum、ResultEnum、ConstantSet、FunGameInfo、General(经济平衡常量)
|
||||
- `Library/Common/Event/`:事件参数(Connect/Login/Register/Room/SendTalk/General/Gaming/UserActivity 等,命名空间调整)
|
||||
- `Interface/Event/`:事件处理器接口(IGamingConnectEventHandler、IGamingRoundEventHandler 等局内事件 + EventCenter 活动/商店中心)
|
||||
- `Model/PrefabricatedEntity/`:预制技能/特效(灵魂绑定、魔法卡包等)
|
||||
- `Library/Architecture/BaseEntityConverter.cs`:实体转换基类
|
||||
- `Library/Exception/`:异常体系
|
||||
|
||||
---
|
||||
|
||||
## 5. FunGame.Testing-v3 参考(v3 的"服务器"长什么样)
|
||||
|
||||
Testing-v3 是 v3 Core 目前唯一的宿主参考实现,展示了 v3 时代的运行形态:
|
||||
|
||||
```
|
||||
FunGame.Testing-v3/
|
||||
├── WebAPI/ # ASP.NET Core Web API(net10.0,唯一项目)
|
||||
│ ├── Program.cs # 入口:模块初始化 + 6 个 REST 端点 + 托管前端
|
||||
│ ├── Services/ArchiveStore.cs # 读取 rounds_archive.zip(回合存档)
|
||||
│ ├── Tests/FunGameService.cs # 角色/技能/物品注册表 + Rating 计算
|
||||
│ ├── Tests/FunGameSimulation.cs # 进程内跑一局 AI 对战(GamingQueue)
|
||||
│ ├── Tests/EffectAutoRecordTest.cs # 特效自动记录测试
|
||||
│ ├── Tests/RoundRecordSinkTest.cs # RoundRecordSink 测试
|
||||
│ └── OshimaGameModules/ # 模组代码(角色/技能/特效/物品,全部编译期引用)
|
||||
├── webui/ # React + Vite + Tailwind 回放台(统计/回放/快照三面板)
|
||||
└── rounds_archive.zip # 回合记录归档(rounds_data.json)
|
||||
```
|
||||
|
||||
**关键模式**:
|
||||
|
||||
1. **进程内直接引用模组代码**(`characterModule.Load()` 等),不再有 DLL 插件/模组加载器
|
||||
2. **`GamingQueue` 跑完一局 → `RoundRecord` 列表 → 压缩归档 `rounds_archive.zip`**
|
||||
3. **WebAPI 提供回放端点**:`/api/meta`、`/api/rounds/summary`、`/api/rounds/{n}`、`/api/statistics`、`/api/reload`、`/api/simulate/team`
|
||||
4. **无数据库、无账号、无网络协议**——纯战斗模拟与回放
|
||||
5. 发布 Linux 自包含(publish-linux.sh)
|
||||
|
||||
---
|
||||
|
||||
## 6. v2 → v3 变化对照总表
|
||||
|
||||
| 能力 | v2(Core 提供) | v3(Core 提供) | Server-v3 需要 |
|
||||
|---|---|---|---|
|
||||
| 回合制战斗引擎 | ✅ GamingQueue | ✅ 重构强化 + 回合记录 | 直接用 |
|
||||
| 回合记录/回放 | ❌ | ✅ RoundRecord/ActionRecord/快照/渲染 | 直接用 |
|
||||
| 记录外发(POST) | ❌ | ✅ IRoundRecordSink / DefaultRoundRecordSink | 配置 URL 或自定义实现 |
|
||||
| 实体/模块 | Addon DLL 体系 | IModule + 实体配置 + Factory | 采用新模块方式 |
|
||||
| 网络(Socket/WS) | ✅ | ❌ | **自研或引入第三方** |
|
||||
| 消息协议(SocketObject/DataRequest) | ✅ | ❌ | **自研** |
|
||||
| 数据库(SQLHelper + SQL 脚本) | ✅ | ❌ | **自研**(EF/ADO/Dapper…) |
|
||||
| 邮件 SMTP | ✅ | ❌ | 自研或引入库 |
|
||||
| 插件系统 + 热加载 | ✅ | ❌ | **自研**(或改为服务内模块) |
|
||||
| 账号/注册/登录/2FA | 部分(Authenticator 骨架) | ❌ | 自研 |
|
||||
| 房间/匹配/Elo | ❌(Server 层实现) | ❌ | 迁移 v2 Server 代码 |
|
||||
| 商店/市场/报价经济 | ❌(Server 层实现) | ❌ | 迁移 v2 Server 代码 |
|
||||
| 控制台管理 | 部分(Core 提供订单定义) | ❌ | 自研 |
|
||||
| INI 配置 | ✅ | ❌ | 自研或引入库 |
|
||||
| 日志 | ✅ TXTHelper/ServerHelper | ❌ | 自研或引入库(ILogger 等) |
|
||||
| 事件体系 | 插件事件链 | 局内事件 + EventCenter | 自研服务事件 |
|
||||
| 任务调度 | ✅ TaskScheduler | ❌ | 自研 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 对 Server-v3 开发的关键影响(决策输入)
|
||||
|
||||
1. **Core v3 不再是"开箱即用的服务器"**:v3 Server 需要自己补齐网络、数据库、认证、配置、日志五大基础设施。
|
||||
2. **战斗与回放是 v3 的拳头能力**:`GamingQueue` + `RoundRecord` + `IRoundRecordSink`(即时 POST 外发)+ `BattleStatePredictor` + `RoundRecordRenderer` 构成完整的"对局产生 → 记录 → 外发 → 回放"链路,这是 v3 Server 应当优先围绕设计的核心。
|
||||
3. **默认外发通道是 HTTP POST**(`DefaultRoundRecordSink`):说明 v3 的设计意图之一是"战斗服务器算、外部服务收"——Server-v3 天然适合做成 **WebAPI 形态**,自己既是战斗宿主又是记录接收方(或转发到数据服务)。
|
||||
4. **模组体系变化**:从"DLL 热插拔"变为"代码引用 + 配置数据"。Server-v3 要么跟随(进程内引用模组)、要么自行实现 DLL 隔离加载(回到 v2 思路,Core 不再帮忙)。
|
||||
5. **v2 Server 的业务代码(房间/匹配/账号/经济/控制台)仍然有效**,可以整体迁移,但要换掉所有 `Milimoe.FunGame.Core.*` 命名空间引用,并重写底层依赖(SQLHelper→自选数据层、DataRequest 传输→自定协议)。
|
||||
6. **Testing-v3 不是"服务器"**:它是无账号无网络的对战模拟/回放台。Server-v3 可以在它之上叠加网络/账号/房间层,或者完全另起架构。
|
||||
@@ -0,0 +1,187 @@
|
||||
# Server-v3 开发规划(决策与建议)
|
||||
|
||||
> 目标:以 FunGame.Core **v3**(master)为基础,在 `C:\milimoe\FunGame.Server-v3` 重新构建服务器。
|
||||
> 本文基于 `01-v2-功能总结.md` 与 `02-v3-Core-变更分析.md`,列出**必须做的决策**、**建议架构**与**开发路线**,供确定 v3 开发内容。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先决决策(需要你拍板的 5 个问题)
|
||||
|
||||
### 决策 A:服务器形态
|
||||
| 选项 | 说明 | 建议 |
|
||||
|---|---|---|
|
||||
| **A1. 单一 WebAPI 程序**(推荐) | 一个 ASP.NET Core 进程同时提供:WebSocket 游戏协议 + RESTful API + 回合记录回放端点。与 v3 的 `DefaultRoundRecordSink`(POST) 设计意图吻合,与 Testing-v3 一脉相承 | ✅ 推荐:维护面小、天然支持记录外发与回放、Linux 部署友好 |
|
||||
| A2. 控制台 + WebAPI 双程序 | 沿用 v2:FunGameServer(控制台) + FunGameWebAPI 双进程 | 保留 v2 习惯,但两套入口重复维护 |
|
||||
| A3. 控制台单程序 | 只有 Socket/WS 游戏服务 | 无法直接对接 v3 的 POST 外发/回放生态 |
|
||||
|
||||
### 决策 B:客户端传输协议
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| B1. **WebSocket + JSON**(推荐) | 与 v3 回放/记录 JSON 体系一致;浏览器/Web/桌面端都能连;`/ws` 单端点 |
|
||||
| B2. WebSocket + 二进制协议 | 性能更高,但需要重新设计序列化(v3 已无 SocketObject) |
|
||||
| B3. TCP Socket 二进制 | v2 传统;客户端(FunGame.Desktop 等)需同步改造 |
|
||||
| B4. 纯 REST + 轮询/SSE | 放弃实时长连接,最简但体验差 |
|
||||
|
||||
> 注意:v3 已无 `SocketObject`/`SocketMessageType`,**协议要自己定**。建议最小集:
|
||||
> 连接握手(协议版本/模组清单/版本校验)→ 登录/注册 → 大厅/房间/匹配 → 局内指令(决策点/技能/移动)→ 心跳/断线重连。数据格式直接复用 v3 实体 JSON(JsonService 转换器已就绪)。
|
||||
|
||||
### 决策 C:数据层
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| C1. **EF Core + SQLite/MySQL**(推荐) | 现代、迁移方便;v2 的 users/rooms/inventory 等表结构可迁移为 EF 模型 |
|
||||
| C2. 保留 v2 的 SQLHelper 思路自研 | 可从 v2 Server 移植 `MySQLHelper`/`SQLiteHelper` + SQLQueryExtension(注意该包依赖 v2 Core 命名空间,需改) |
|
||||
| C3. Dapper/ADO 手写 | 轻量但开发量大 |
|
||||
|
||||
> v3 需要的持久化比 v2 简单:**对局记录(RoundRecord)可以用 JSON 归档**(Testing-v3 已有 rounds_archive.zip 模式),数据库只存账号/房间/经济等"服务器业务数据"。
|
||||
|
||||
### 决策 D:模组加载方式
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| D1. **编译期进程内引用**(推荐,跟随 v3 设计) | 模组 = 代码类 + `EntityModuleConfig` 配置;`CharacterModule.Load()` 后 `Factory.GetGameModuleInstances<T>` 实例化。参考 Testing-v3 的 OshimaGameModules |
|
||||
| D2. DLL 插件加载器自研 | 保留 v2 的 plugins/modules 热插拔体验,但 Core v3 不再提供任何加载器,需要完整自研(隔离上下文、依赖解析、热卸载) |
|
||||
| D3. 混合 | 核心模组编译期引用,扩展模组走 DLL |
|
||||
|
||||
### 决策 E:回合记录外发(v3 特色能力,强烈建议纳入)
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| E1. **自收自发**(推荐) | 服务器自身实现 `IRoundRecordSink`,把 `RoundRecord` 写入自己的存储(JSON 归档/数据库),并提供回放 REST 端点(参考 Testing-v3 的 ArchiveStore + /api/rounds 系列) |
|
||||
| E2. 使用 `DefaultRoundRecordSink` | 直接 POST 到外部数据服务(如独立的回放服务器),Server 只当生产者 |
|
||||
| E3. 两者结合 | 本地归档 + 转发远端(最完整,实现也最简单:自定义 sink 内包一个 DefaultRoundRecordSink) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 建议架构(以 A1 + B1 + C1 + D1 + E1 为例)
|
||||
|
||||
```
|
||||
FunGame.Server-v3/ (解决方案:FunGame.Server-v3.slnx)
|
||||
├── docs/ # 本文档目录
|
||||
├── Server/ # ASP.NET Core Web API(宿主)
|
||||
│ ├── Program.cs # 入口:模块加载 + 服务注册 + 管道
|
||||
│ ├── Networking/ # 协议层(自研,替代 v2 的 Core 网络)
|
||||
│ │ ├── WebSocketHandler.cs # /ws 长连接接入
|
||||
│ │ ├── Protocol/ # 消息帧/信封、消息类型枚举(替代 SocketObject)
|
||||
│ │ └── ClientSession.cs # 会话模型(替代 ServerModel<T>)
|
||||
│ ├── Controllers/ # RESTful:账号/房间/商店/回放……
|
||||
│ ├── Services/ # 业务层
|
||||
│ │ ├── UserService.cs # 注册/登录/签到/找回密码(迁移 v2 逻辑)
|
||||
│ │ ├── RoomService.cs # 房间/匹配/Elo(迁移 v2 逻辑)
|
||||
│ │ ├── EconomyService.cs # 商店/市场/报价(迁移 v2 逻辑)
|
||||
│ │ ├── GameHostService.cs # 对局宿主:GamingQueue 生命周期管理
|
||||
│ │ └── MatchService.cs # 匹配队列
|
||||
│ ├── Data/ # EF Core:DbContext + 迁移(users/rooms/inventory…)
|
||||
│ ├── Records/ # 回合记录
|
||||
│ │ ├── RoundRecordSink.cs # 实现 IRoundRecordSink → 归档 + 可选转发
|
||||
│ │ ├── ArchiveStore.cs # 存档读写(参考 Testing-v3,可改数据库存储)
|
||||
│ │ └── ReplayController.cs # /api/replay 系列回放端点
|
||||
│ ├── Modules/ # 模组(编译期引用,如 OshimaGameModules)
|
||||
│ │ ├── CharacterModule.cs / SkillModule.cs / ItemModule.cs
|
||||
│ │ └── GameMapModule.cs # 地图(Framework.GameMap)
|
||||
│ ├── Console/ # 管理控制台(ILogger + 指令解析,迁移 v2 ConsoleModel)
|
||||
│ └── appsettings.json # JWT/CORS/数据库/SMTP/回放存储配置
|
||||
├── FunGame.Core (项目引用) # C:\milimoe\FunGame.Core 或 NuGet
|
||||
└── WebUI/ (可选) # 管理后台/回放台(React,参考 Testing-v3 webui)
|
||||
```
|
||||
|
||||
### 核心运行时流程(一局对局)
|
||||
|
||||
```
|
||||
玩家进房/匹配成功
|
||||
→ GameHostService 创建 GamingQueue(角色列表, map)
|
||||
→ queue.RoundRecordSink = RoundRecordSink(本服务实现)
|
||||
→ 局内:玩家决策点指令 → queue.ProcessTurn / GamingMessageHandler 等价物
|
||||
└── GamingQueue 内部自动:写 RoundRecord → 调 Sink(即时存档/转发)
|
||||
→ 游戏结束 → 结算(RankingEntry/CharacterStatistics)→ 归档 → 通知客户端
|
||||
→ 回放:ReplayController 读取归档;BattleStatePredictor 支撑"任意回合状态还原"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. v3 Server 必须重建的基础设施(对照 v2 清单)
|
||||
|
||||
| # | 模块 | v2 位置 | v3 方案 |
|
||||
|---|---|---|---|
|
||||
| 1 | 网络监听与 WebSocket 会话 | Core 提供 | ASP.NET Core `UseWebSockets` + 自研会话模型 |
|
||||
| 2 | 消息协议(信封/序列化) | SocketObject | 自研(推荐 JSON + 类型标记,复用 v3 JsonService) |
|
||||
| 3 | 数据库访问 | SQLHelper + SQLQueryExtension | EF Core(或移植 v2 SQLHelper) |
|
||||
| 4 | 配置系统 | INIHelper(Core) | `Microsoft.Extensions.Configuration`(JSON/appsettings) |
|
||||
| 5 | 日志 | ServerHelper/TXTHelper(Server + Core) | `ILogger` + Serilog 等 |
|
||||
| 6 | 邮件 | MailSender(Core) | 自研 SMTP 封装或 MailKit |
|
||||
| 7 | 认证 | JWT + APIBearer(v2 WebAPI 已有) | 迁移 v2 WebAPI 认证架构 |
|
||||
| 8 | 任务调度 | TaskScheduler(Core) | `BackgroundService` / `System.Threading.Timer` |
|
||||
| 9 | 插件体系 | ServerPluginLoader/WebAPIPluginLoader(Core) | 按决策 D:模块化替代或自研加载器 |
|
||||
| 10 | 控制台指令 | 迁移 v2 ConsoleModel | 指令字典 + ILogger(保留 ban/kick/logout/show/reload) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 可从 v2 直接迁移的业务代码(高复用)
|
||||
|
||||
以下逻辑与 Core 运行时解耦程度高,**迁移成本低**(主要是改命名空间 + 换数据访问 + 换传输参数):
|
||||
|
||||
- ✅ `ConnectController` 握手逻辑(人数/黑名单/参数校验)→ 适配新协议
|
||||
- ✅ `DataRequestController` 的业务方法:房间创建/进入/退出/房主移交/设置、准备、开始游戏流程、聊天
|
||||
- ✅ 匹配算法 `MatchingRoom`(Elo 扩圈)
|
||||
- ✅ `DataRequestService`:注册流程、登录流程(含 autokey、check-login key 思路)、找回密码
|
||||
- ✅ 每日签到、游戏时长统计、重复登录踢下线
|
||||
- ✅ 商店/市场/报价/物品使用全套经济逻辑(事务化)
|
||||
- ✅ `ConsoleModel` 指令解析与常用指令
|
||||
- ✅ WebAPI 的 JWT/CORS/认证处理器架构、`PayloadModel` 包装
|
||||
|
||||
**需要重写/放弃的 v2 部分**:
|
||||
- 所有 `Milimoe.FunGame.Core.*` 网络/传输引用(协议层)
|
||||
- SQLHelper 调用点(改为 EF/新数据层)
|
||||
- 插件事件链(v3 无 ServerPlugin)——如果保留插件需求,事件点要么自建事件总线,要么砍掉
|
||||
- GameModuleServer 机制(v3 无此基类)——对局宿主改为直接驱动 GamingQueue
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议开发路线(里程碑)
|
||||
|
||||
### M0:地基(0.5~1 周)
|
||||
- [ ] Server-v3 解决方案骨架(slnx + WebAPI 项目 + 项目引用 v3 Core)
|
||||
- [ ] appsettings 配置体系、ILogger、统一响应模型 `PayloadModel`(迁移)
|
||||
- [ ] 模块加载骨架:CharacterModule/SkillModule/ItemModule/地图模块 + `Factory.GetGameModuleInstances`
|
||||
- [ ] 用 Testing-v3 的 OshimaGameModules(或精简示例模组)跑通:**进程内 GamingQueue 一局模拟 → RoundRecord → 归档 → 回放端点**(这是 v3 的核心价值验证)
|
||||
|
||||
### M1:网络与账号(1~2 周)
|
||||
- [ ] WebSocket `/ws` 会话层 + 自研消息协议(握手/心跳/分发)
|
||||
- [ ] EF Core + SQLite:users/profiles/rooms 迁移脚本
|
||||
- [ ] 注册(邮箱验证码可选)、登录(密码加密 + 登录 key/autokey)、JWT
|
||||
- [ ] 管理控制台指令框架(kick/logout/show/ban/reload)
|
||||
|
||||
### M2:房间与匹配(1~2 周)
|
||||
- [ ] 房间 CRUD/进入退出/房主移交/设置/准备/开始流程(迁移 v2)
|
||||
- [ ] 匹配队列 + Elo 扩圈匹配(迁移)
|
||||
- [ ] 对局启动:GameHostService 创建 GamingQueue、绑定 IRoundRecordSink、局内指令转发
|
||||
|
||||
### M3:局内体验与回放(1~2 周)
|
||||
- [ ] 局内指令协议:决策点(攻击/技能/物品/移动)、广播(Actions 实时推送,可基于 sink 事件)
|
||||
- [ ] 断线重连(对局内重连,参考 v2 ReconnectToGame 思路)
|
||||
- [ ] 回放台:`/api/replay/*` + 可选 React webui(可直接复用 Testing-v3 webui 改造)
|
||||
|
||||
### M4:经济与扩展(1~2 周)
|
||||
- [ ] 商店/市场/报价/签到迁移(EF 数据层)
|
||||
- [ ] SMTP 找回密码、每日签到、游戏时长统计
|
||||
- [ ] 排位统计(Rating 计算可参考 Testing-v3 的 `CalculateRating`)
|
||||
|
||||
### M5:加固与发布(持续)
|
||||
- [ ] 并发与事务正确性、压力测试
|
||||
- [ ] Linux 自包含发布脚本(参考 Testing-v3 publish-linux.sh)
|
||||
- [ ] 单元测试:迁移 Testing-v3 的 Tests(EffectAutoRecordTest / RoundRecordSinkTest)
|
||||
|
||||
---
|
||||
|
||||
## 6. 开放问题(建议尽早确认)
|
||||
|
||||
1. **客户端是谁?** FunGame.Desktop(v2 客户端)是否同步升级协议?若保留 v2 客户端,Server-v3 需要兼容 v2 的 SocketObject 协议——那网络层改动会大很多。
|
||||
2. **回放数据存哪?** JSON 归档(简单、Testing-v3 模式)vs 数据库(可查询/统计)vs 远端 POST(DefaultRoundRecordSink)。
|
||||
3. **要不要账号系统?** 如果 v3 服务器定位为"对战/回放服务",可以砍掉注册/邮箱,仅保留昵称 + JWT 匿名身份(大幅缩短开发)。
|
||||
4. **插件生态是否保留?** 如果 Oshima 社区依赖 v2 的 ServerPlugin/WebAPIPlugin 插件,需要自研加载器;否则用"模块 + 服务内扩展点"替代。
|
||||
5. **核心业务与 Testing-v3 的关系**:Testing-v3 的对战模拟/回放功能是直接并入 Server-v3(作为测试与演示能力),还是独立保留?
|
||||
6. **Core v3 还在迭代**(3.0.0-dev):建议以 ProjectReference 或本地 NuGet 引用 master,跟随提交更新,并关注 nuget 自动发布工作流(正式版发布后可切 NuGet)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话总结
|
||||
|
||||
> **v2 是"Core 给的服务器",v3 是"自己搭的服务器 + Core 给的战斗/回放引擎"。**
|
||||
> Server-v3 的核心价值 = v3 战斗引擎(GamingQueue)+ 回合记录/即时外发(IRoundRecordSink)+ 回放(BattleStatePredictor/ArchiveStore),叠加自研的网络/账号/房间/经济层;v2 的成熟业务代码可迁移复用,但底层基础设施(网络、数据库、配置、日志)需要在新项目里重建。
|
||||
+309
@@ -0,0 +1,309 @@
|
||||
# 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<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)
|
||||
|
||||
```jsonc
|
||||
// 客户端 → 服务器(请求)
|
||||
{
|
||||
"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 对齐)
|
||||
|
||||
```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<T>` 生成/读取 JSON 配置;`Factory.GetGameModuleInstances<T>(module, file)` 实例化实体
|
||||
- WebUI 提供"实体模组管理"页:查看/编辑/重新加载 JSON 配置(不重启进程改游戏内容)
|
||||
|
||||
### 5.4 服务器插件接口(Contracts)
|
||||
|
||||
```csharp
|
||||
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 的迁移与部署验证
|
||||
@@ -0,0 +1,12 @@
|
||||
# Server-v3 文档索引
|
||||
|
||||
FunGame.Server-v3 规划与设计文档(基于 FunGame.Core v3 / master 分支)。
|
||||
|
||||
| 文档 | 内容 | 状态 |
|
||||
|---|---|---|
|
||||
| [01-v2-功能总结.md](01-v2-功能总结.md) | v2 FunGame.Server 全部功能梳理 | 参考 |
|
||||
| [02-v3-Core-变更分析.md](02-v3-Core-变更分析.md) | v3 FunGame.Core 相对 v2 的变更与边界 | 参考 |
|
||||
| [03-Server-v3-开发规划.md](03-Server-v3-开发规划.md) | v3 开发决策与备选方案(早期) | 已被 04 取代 |
|
||||
| [04-架构设计.md](04-架构设计.md) | **v3 架构定稿**:数据层/认证/负载模型/插件系统/对局与回放/WebUI 规格 | **开发依据** |
|
||||
|
||||
实施顺序见 04 文档第 9 节里程碑(M0~M7)。
|
||||
Reference in New Issue
Block a user