# 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`) - 人数上限检查(`ConnectingPlayerCount + OnlinePlayerCount > MaxPlayers` 拒绝) - IP 黑名单检查(`BannedList`,按 `ip:port` 拆分比较) - 客户端参数验证(`OnValidateClientParameters`): - Desktop 参数 1:客户端模组列表,与服务器 `GameModuleSupported` 对比,缺失则拒绝 - Desktop 参数 2:客户端是否开启开发者模式(`isDebugMode`,开发者模式部分功能禁用) - 可挂载 `ValidateClientParameters` 事件由插件扩展校验 - 握手回复 `Connect` 消息(成功/失败原因),携带服务器名与公告 - 连接成功回调插件事件:`OnBeforeConnectEvent` / `OnAfterConnectEvent` ### 3.2 客户端会话(`ServerModel` : IServerModel) 每个连接对应一个 `ServerModel` 或 `ServerModel`: - **消息分发** `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` 是业务核心,按 `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 ` | `-a` / `-r` | 添加/移除 IP 黑名单 | | `reload ` | `-a/-m/-p/-sp/-wp` | 热重载加载项 | - 命令解析支持引号与转义(`ParseCommandLine`) - 未知指令广播给插件处理 --- ## 12. WebAPI(RESTful)接口清单 统一返回 `PayloadModel`(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` 形式直接调用数据请求(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、日志工具等。