Files
2026-08-28 19:44:46 +08:00

377 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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、日志工具等。