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(控制台)
- 设置控制台标题、打印版本信息
- 检查
FunGame.ini 配置文件,不存在则自动生成并退出
- 读取配置(
ServerHelper.GetServerSettings() → Config)
- 解析启动参数:
--debug/-d、--allowanyorigin/-aao
- 初始化 SQLHelper(
FunGameSystem.InitSQLHelper:MySQL/SQLite 二选一,首次运行自动建库)
- 初始化 MailSender(SMTP)
- 加载 Server 插件(
plugins/ 目录)
- 加载游戏模组(
modules/ 目录,地图/角色/技能/物品/GameModuleServer 五项)
- 初始化本地配置(
PluginConfig:user_keys / local / sqlconfig)
- 启动监听(Socket 或 WebSocket 二选一,
Config.UseWebSocket)
- 进入控制台命令循环
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 能力全景)
v2 中属于"服务器自研"(迁移到 v3 需要保留/重写):连接握手、会话模型、DataRequest 分发、房间/匹配/账号/经济全部业务逻辑、控制台指令、数据库访问封装。
v2 中由 Core v2 提供(v3 已删除,见 02 文档):网络监听与协议、SQLHelper 抽象、MailSender、插件/模组加载器、INI 读写、任务调度、Factory、日志工具等。