188 lines
12 KiB
Markdown
188 lines
12 KiB
Markdown
# 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 的成熟业务代码可迁移复用,但底层基础设施(网络、数据库、配置、日志)需要在新项目里重建。
|