# 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` 实例化。参考 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) │ ├── 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 的成熟业务代码可迁移复用,但底层基础设施(网络、数据库、配置、日志)需要在新项目里重建。