first commit

This commit is contained in:
2026-08-28 19:44:46 +08:00
commit d99ccbbb0c
114 changed files with 16246 additions and 0 deletions
+376
View File
@@ -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、日志工具等。