GameFrameX.Core 2.0.0.2-dev11

GameFrameX

高性能、跨平台的游戏服务器框架

🎯 框架简介

GameFrameX 是一个基于 C# .NET 8.0 开发的高性能、跨平台游戏服务器框架，采用 Actor 模型设计，支持热更新机制。专为多人在线游戏开发而设计，完美支持 Unity3D 客户端集成。

设计理念：大道至简，以简化繁

✨ 核心特性

🚀 高性能架构

• Actor 模型：基于 TPL DataFlow 构建的无锁高并发系统
• 零锁设计：通过消息传递机制避免传统锁性能损耗
• 全异步编程：完整的 async/await 异步编程模型
• 内存优化：自动垃圾回收和对象池管理

🔄 热更新系统

• 零停机更新：运行时逻辑更新，无需停止服务
• 状态逻辑分离：持久化状态数据与可热更业务逻辑分离
• 回滚保护：更新失败自动回滚到稳定版本
• 版本管理：支持程序集版本控制和回退功能

🌐 多协议网络通信

• TCP/UDP/WebSocket/HTTP：全面的协议支持
• SuperSocket 集成：高性能异步 I/O 模型
• 消息分帧：内置数据包处理和流量控制
• SSL/TLS 加密：安全通信通道支持
• 连接池：优化的资源利用率

💾 数据库与持久化

• MongoDB 主数据库：完整的 MongoDB 集成和连接池管理
• 透明持久化：自动序列化/反序列化，开发者无感知
• 状态管理：智能缓存和生命周期管理
• 批量操作：高性能批量处理

📊 监控与可观测性

• OpenTelemetry：全面的指标、追踪和日志
• Grafana 集成：内置仪表板和告警支持
• Prometheus 导出：原生指标导出功能
• 健康检查：实时系统健康监控
• 性能指标：数据库、网络和业务逻辑监控

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────┐
│                        客户端层                              │
├─────────────────────────────────────────────────────────────┤
│                        网络层                                │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │     TCP     │ │  WebSocket  │ │    HTTP     │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
├─────────────────────────────────────────────────────────────┤
│                       消息处理层                             │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │                  消息处理器                              │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                       Actor 层                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   玩家      │ │   服务器    │ │   账户      │           │
│  │   Actor     │ │   Actor     │ │   Actor     │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
├─────────────────────────────────────────────────────────────┤
│                      组件层                                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   组件      │ │   组件      │ │   组件      │           │
│  │  + 状态     │ │  + 状态     │ │  + 状态     │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
├─────────────────────────────────────────────────────────────┤
│                      数据库层                                │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │                    MongoDB                              │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

🚀 快速开始

环境要求

• .NET 8.0 SDK
• MongoDB 4.x+
• Visual Studio 2022 或 JetBrains Rider

安装步骤

1. 克隆仓库

   git clone https://github.com/GameFrameX/GameFrameX.git
   cd GameFrameX
   

2. 还原依赖

   dotnet restore
   

3. 配置数据库

   • 启动 MongoDB 服务
   • 更新配置文件中的连接字符串

4. 构建运行

   dotnet build
   dotnet run --project GameFrameX.Launcher --ServerType=Game --ServerId=1000
   

5. 验证部署

   • 检查健康端点：http://localhost:29090/health
   • 查看日志确认启动成功

📁 项目结构

GameFrameX/
├── GameFrameX.Apps/              # 应用层（状态数据）
│   ├── Account/                  # 账户模块状态
│   ├── Player/                   # 玩家模块状态
│   └── Server/                   # 服务器模块状态
├── GameFrameX.Hotfix/            # 热更新层（业务逻辑）
│   ├── Logic/                    # 业务逻辑实现
│   └── StartUp/                  # 热更新启动逻辑
├── GameFrameX.Core/              # 核心框架
│   ├── Actors/                   # Actor 系统实现
│   ├── Components/               # 组件系统
│   └── Events/                   # 事件系统
├── GameFrameX.NetWork/           # 网络通信
├── GameFrameX.DataBase.Mongo/    # MongoDB 集成
├── GameFrameX.Config/            # 配置管理
├── GameFrameX.Monitor/           # 监控和指标
├── GameFrameX.Launcher/          # 应用入口点
└── GameFrameX.StartUp/           # 启动编排

🔧 业务逻辑开发

基础示例：Hello World

快速创建一个 HTTP 接口来体验开发流程。

using GameFrameX.NetWork.HTTP;

[HttpMessageMapping(typeof(TestHttpHandler))]
[HttpMessageResponse(typeof(HttpTestResponse))]
[Description("Hello World 示例接口")]
public sealed class TestHttpHandler : BaseHttpHandler
{
    public override Task<string> Action(string ip, string url, Dictionary<string, object> parameters)
    {
        var response = new HttpTestResponse
        {
            Message = "Hello World From GameFrameX",
            Time = DateTime.Now
        };
        // 返回标准 JSON 格式
        return Task.FromResult(HttpJsonResult.SuccessString(response));
    }
}

public sealed class HttpTestResponse : HttpMessageResponseBase
{
    public string Message { get; set; }
    public DateTime Time { get; set; }
}

组件-代理模式

1. 定义状态（Apps 层 - 不可热更）

public class BagState : CacheState
{
    public List<ItemData> Items { get; set; } = new();
    public int MaxSlots { get; set; } = 50;
}

2. 创建组件（Apps 层）

public class BagComponent : StateComponent<BagState>
{
    // 组件初始化逻辑
    protected override async Task OnInit()
    {
        await base.OnInit();
        // 初始化组件状态
    }
}

3. 实现业务逻辑（Hotfix 层 - 可热更）

public class BagComponentAgent : StateComponentAgent<BagComponent, BagState>
{
    public async Task<bool> AddItem(int itemId, int count)
    {
        if (State.Items.Count >= State.MaxSlots)
            return false;

        var item = new ItemData { Id = itemId, Count = count };
        State.Items.Add(item);

        await Save();
        return true;
    }
}

消息处理器模式

HTTP 处理器示例：

[HttpMessageMapping(typeof(GetPlayerInventoryHttpHandler))]
[Description("获取玩家背包物品")]
public sealed class GetPlayerInventoryHttpHandler : BaseHttpHandler
{
    public override async Task<MessageObject> Action(string ip, string url, Dictionary<string, object> parameters, MessageObject messageObject)
    {
        var request = (GetPlayerInventoryRequest)messageObject;
        var response = new GetPlayerInventoryResponse();

        // 从参数中获取玩家ID
        if (!parameters.TryGetValue("playerId", out var playerIdObj))
        {
            response.ErrorCode = (int)ResultCode.InvalidParameter;
            return response;
        }

        var playerId = Convert.ToInt64(playerIdObj);
        var bagAgent = await ActorManager.GetComponentAgent<BagComponentAgent>(playerId);

        if (bagAgent == null)
        {
            response.ErrorCode = (int)ResultCode.PlayerNotFound;
            return response;
        }

        var items = await bagAgent.GetItems();
        response.Items = items;
        return response;
    }
}

RPC 处理器示例：

[MessageMapping(typeof(ReqAddItem))]
internal sealed class AddItemHandler : PlayerRpcComponentHandler<BagComponentAgent, ReqAddItem, RespAddItem>
{
    protected override async Task ActionAsync(ReqAddItem request, RespAddItem response)
    {
        try
        {
            // ComponentAgent 由基类自动注入,无需手动获取
            await ComponentAgent.AddItem(request, response);
        }
        catch (Exception e)
        {
            LogHelper.Fatal(e);
            response.ErrorCode = (int)OperationStatusCode.InternalServerError;
        }
    }
}

事件处理模式

[Event(EventId.PlayerLogin)]
internal sealed class PlayerLoginEventHandler : EventListener<PlayerComponentAgent>
{
    protected override Task HandleEvent(PlayerComponentAgent agent, GameEventArgs gameEventArgs)
    {
        if (agent == null)
        {
            LogHelper.Error("代理对象为空");
            return Task.CompletedTask;
        }

        // 处理登录事件逻辑
        return agent.OnLogin();
    }
}

🔄 热更新机制

架构概述

热更新系统将状态（持久化数据）与逻辑（业务规则）分离：

1. Apps 层：包含状态定义和组件外壳（不可热更）
2. Hotfix 层：包含业务逻辑实现（可热更）
3. 代理模式：作为状态和逻辑之间的桥梁

热更新流程

1. 编译新逻辑：构建更新的 GameFrameX.Hotfix.dll
2. 部署程序集：复制到 /hotfix 目录
3. 触发重载：通过 HTTP 端点或文件监视器
4. 优雅过渡：新请求使用更新后的逻辑
5. 回滚支持：失败时自动回滚

热更新 API

# 通过 HTTP 触发热更新
curl -X POST http://localhost:29090/api/reload

# 检查重载状态
curl http://localhost:29090/api/reload/status

📊 配置管理

GameFrameX 使用扁平化的配置结构，支持命令行参数 (--Key=Value)、环境变量 (Key=Value) 和 appsettings.json 配置文件。

核心配置 (Server)

网络配置 (Network)

数据库配置 (Database)

监控配置 (Monitoring)

启动命令示例

dotnet GameFrameX.Launcher.dll \
    --ServerType=Game \
    --ServerId=1000 \
    --OuterPort=10000 \
    --DataBaseUrl=mongodb://127.0.0.1:27017 \
    --DataBaseName=game_db

🐳 Docker 部署

# 构建阶段
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet restore && dotnet build -c Release

# 运行阶段
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY --from=build /src/bin/Release/net8.0/ .
EXPOSE 29100 29110 29090
ENTRYPOINT ["dotnet", "GameFrameX.Launcher.dll"]

# docker-compose.yml
version: '3.8'
services:
  gameframex:
    build: .
    ports:
      - "29100:29100"  # TCP
      - "29110:29110"  # WebSocket
      - "29090:29090"  # 指标
    environment:
      - ServerType=Game
      - ServerId=1000
      - DataBaseUrl=mongodb://mongodb:27017
    depends_on:
      - mongodb

  mongodb:
    image: mongo:6.0
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

🔍 监控与可观测性

指标端点

• 健康检查：http://localhost:29090/health
• Prometheus 指标：http://localhost:29090/metrics
• Grafana 仪表板：可通过环境配置

关键指标

• 数据库：查询次数、持续时间、连接池状态
• 网络：连接数、消息吞吐量、字节传输量
• 业务：玩家登录、活跃会话、游戏特定指标
• 系统：CPU、内存、GC 性能、线程池状态

🤝 贡献指南

我们欢迎任何形式的贡献！如果你想为 GameFrameX 做出贡献，请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加某个功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

📄 许可证

本项目采用 Apache License 2.0 许可证 - 详见 LICENSE 文件。

🔗 相关链接

• 在线文档
• Unity 客户端
• 问题反馈
• 社区讨论

<div align="center">

如果这个项目对你有帮助，请给我们一个 ⭐

Made with ❤️ by GameFrameX Team

</div>