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

19 KiB
Raw Permalink Blame History

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、日志工具等。