Fishing2Server/CODELY.md

Fishing2Server 项目文档

项目概述

Fishing2Server 是一个基于 Fantasy.Net 框架开发的分布式钓鱼游戏服务器。采用 .NET 9.0 构建，使用 MongoDB 作为数据库存储，支持热更新机制。

技术栈

• .NET 版本: .NET 9.0
• 框架: Fantasy.Net (v2025.2.1423) - 分布式游戏服务器框架
• 数据库: MongoDB
• 日志系统: NLog
• 网络协议: TCP (内部通信), KCP (外部通信)
• 身份认证: JWT (System.IdentityModel.Tokens.Jwt v8.14.0)
• 序列化: LightProto, MemoryPack
• 第三方库: Unity.Mathematics

项目架构

项目采用分层架构，包含四个主要项目：

项目	命名空间	说明
Main	NBF	应用程序入口，负责初始化和启动框架
Entity	NB	实体层，定义所有数据结构和实体
Hotfix	NB	热更新层，包含所有业务逻辑、Handler 和 System
ThirdParty	-	第三方依赖库（Unity.Mathematics）

项目结构

Fishing2Server/
├── Main/                    # 主程序入口
│   ├── Program.cs          # 应用程序入口点
│   ├── NLog.config         # 日志配置
│   ├── configs.json        # 游戏配置（物品、鱼竿等）
│   └── Fantasy.config      # Fantasy 框架配置
├── Entity/                 # 实体层（数据定义）
│   ├── Authentication/     # 认证相关实体
│   ├── Game/               # 游戏实体
│   │   ├── Player/         # 玩家实体
│   │   ├── Item/           # 物品系统
│   │   ├── Map/            # 地图和房间系统
│   │   ├── Fish/           # 钓鱼系统
│   │   ├── Skill/          # 技能系统
│   │   ├── Mission/        # 任务系统
│   │   ├── Achievement/    # 成就系统
│   │   ├── Cache/          # 玩家缓存
│   │   ├── Statistics/     # 统计数据
│   │   └── Activity/       # 活动系统
│   ├── Gate/               # 网关实体
│   ├── Social/             # 社交实体
│   │   ├── Chat/           # 聊天系统
│   │   ├── Club/           # 俱乐部系统
│   │   └── Mail/           # 邮件系统
│   ├── Def/                # 配置定义
│   ├── Generate/           # 自动生成的代码
│   │   ├── NetworkProtocol/ # 网络协议定义
│   │   └── ConfigTable/     # 配置表代码
│   └── Modules/            # 配置表模块
├── Hotfix/                 # 热更新层（业务逻辑）
│   ├── Authentication/     # 认证逻辑
│   │   ├── Handler/        # 认证消息处理器
│   │   └── System/         # 认证系统
│   ├── Game/               # 游戏业务逻辑
│   │   ├── Handler/        # 游戏消息处理器
│   │   ├── Item/           # 物品逻辑
│   │   ├── Map/            # 地图逻辑
│   │   ├── Player/         # 玩家逻辑
│   │   ├── Wallet/         # 钱包逻辑
│   │   └── Cache/          # 缓存逻辑
│   ├── Gate/               # 网关业务逻辑
│   │   ├── Handler/        # 网关消息处理器
│   │   │   ├── Inner/      # 内部消息
│   │   │   └── Outer/      # 外部消息
│   │   └── System/         # 网关系统
│   ├── Social/             # 社交业务逻辑
│   │   ├── Chat/           # 聊天逻辑
│   │   ├── Mail/           # 邮件逻辑
│   │   └── Club/           # 俱乐部逻辑
│   ├── Common/             # 通用逻辑
│   └── HTTPHandler/        # HTTP 接口
├── ThirdParty/             # 第三方库
└── Tools/                  # 工具集
    ├── NetworkProtocol/    # 协议配置
    └── ProtocolExportTool/ # 协议导出工具

服务器架构

场景类型（Scene Types）

服务器采用分布式场景架构，包含以下场景类型：

Scene ID	场景类型	外网端口	内网端口	说明
1001	Authentication	20001	11001	登录认证服务器（KCP）
1002	Addressable	-	11011	地址服务器
1003	Gate	20000	11021	网关服务器（KCP）
1004	Game	-	11031	游戏逻辑服务器
1006	Social	-	11051	社交服务器
1007	Map	-	11061	地图服务器（已注释）

登录流程

1. 客户端连接到 Authentication 服务器（端口 20001）
2. 用户名密码验证，支持自动注册
3. 验证成功后颁发 JWT Token
4. 客户端使用 Token 连接到 Gate 服务器（端口 20000）
5. Gate 验证 Token 并建立会话
6. 客户端通过 Gate 与其他服务器通信

通信架构

• 内部通信: 使用 TCP 协议，各服务器之间通过 Scene ID 路由
• 外部通信: 使用 KCP 协议，客户端通过 Gate 服务器连接
• 消息路由: 支持自定义路由（ICustomRouteRequest 接口）

构建和运行

前置要求

• .NET 9.0 SDK
• MongoDB 服务器
• Visual Studio 2022 或 Rider

构建项目

# 构建整个解决方案
dotnet build Server.sln

# 构建特定项目
dotnet build Main/Main.csproj
dotnet build Entity/Entity.csproj
dotnet build Hotfix/Hotfix.csproj

运行项目

# 运行主程序
dotnet run --project Main/Main.csproj

# 或直接编译运行
cd Main/bin/Debug/net9.0
Main.exe

配置说明

1. MongoDB 配置

在 Entity/Fantasy.config 中配置数据库连接：

<database dbType="MongoDB" dbName="fantasy_main" dbConnection="mongodb://127.0.0.1" />

2. 服务器配置

在 Entity/Fantasy.config 中配置服务器地址：

<machines>
    <machine id="1" outerIP="127.0.0.1" outerBindIP="127.0.0.1" innerBindIP="127.0.0.1" />
</machines>

3. 日志配置

在 Main/NLog.config 中配置日志输出位置和格式。日志文件保存在：

Main/bin/Debug/Logs/Server/Server{yyyyMMdd}/{logger}.{appId}.{yyyyMMddHH}.{level}.log

开发规范

命名约定

• 命名空间:
  • Entity 层使用 NB 前缀（如 NB.Game, NB.Authentication）
  • Hotfix 层使用 NB 前缀（如 NB.Game, NB.Gate）
• Handler: 使用 {RequestType}Handler 格式（如 C2A_LoginRequestHandler）
• System: 使用 {Entity}System 格式（如 PlayerSystem, MapSystem）
• Helper: 使用 {Module}Helper 格式（如 AuthenticationHelper, PlayerHelper）

消息处理

所有消息处理器继承自 MessageRPC<Request, Response>：

public class C2Game_GetItemsRequestHandler : MessageRPC<C2Game_GetItemsRequest, G2C_GetItemsResponse>
{
    protected override async FTask Run(Session session, C2Game_GetItemsRequest request, G2C_GetItemsResponse response, Action reply)
    {
        // 业务逻辑
        response.ErrorCode = ErrorCode.Successful;
    }
}

实体系统

所有实体继承自 Entity 基类：

public sealed class Player : Entity
{
    [BsonElement("name")] public string NickName = "";
    [BsonElement("lv")] public int Level;
    [BsonIgnore] public long SessionRunTimeId;
}

System 系统

• DestroySystem: 处理实体销毁逻辑（如 PlayerDestroySystem）
• 静态 System: 扩展方法，提供实体操作（如 PlayerSystem.AddItems()）

配置表

配置表使用 JSON 格式定义在 Main/configs.json，自动生成代码到 Entity/Generate/ConfigTable/。

常用配置类型：

• ItemConfig - 物品配置
• LureConfig - 诱饵配置
• RodRingConfig - 鱼竿环配置

核心功能模块

1. 认证系统（Authentication）

• 账号登录/注册
• JWT Token 颁发和验证
• 账号缓存管理
• 区域选择支持

关键文件:

• Entity/Authentication/Entity/Account.cs
• Hotfix/Authentication/Handler/C2A_LoginRequestHandler.cs
• Hotfix/Authentication/System/AuthenticationHelper.cs

2. 网关系统（Gate）

• 客户端连接管理
• Session 管理
• 消息路由转发
• JWT Token 验证

关键文件:

• Entity/Gate/GateUnit.cs
• Hotfix/Gate/Handler/Outer/C2G_LoginRequestHandler.cs
• Hotfix/Gate/System/GateUnitManageComponentSystem.cs

3. 玩家系统（Player）

• 玩家基本数据管理
• 等级和经验系统
• VIP 系统
• 玩家缓存

关键文件:

• Entity/Game/Player/Player.cs
• Hotfix/Game/Player/Helper/PlayerFactory.cs
• Hotfix/Game/Player/Entity/PlayerSystem.cs

4. 物品系统（Item）

• 物品容器管理
• 物品添加/使用
• 物品类型分类
• 奖励物品处理

关键文件:

• Entity/Game/Item/Item.cs
• Entity/Game/Item/PlayerItemContainerComponent.cs
• Hotfix/Game/Item/ItemSystem.cs

5. 地图和房间系统（Map）

• 地图管理
• 房间创建和销毁
• 玩家移动和同步
• 地图单元管理

关键文件:

• Entity/Game/Map/Entity/Map.cs
• Entity/Game/Map/Entity/MapRoom.cs
• Hotfix/Game/Map/Handler/C2Map_CreateRoomRequestHandler.cs

6. 社交系统（Social）

聊天系统（Chat）

• 多频道聊天
• 聊天消息路由
• 聊天单元管理

关键文件:

• Entity/Social/Chat/Model/ChatUnit.cs
• Hotfix/Social/Chat/Handler/Outer/C2Chat_SendMessageRequestHandler.cs

邮件系统（Mail）

• 邮件发送
• 邮件箱管理
• 会话管理

关键文件:

• Entity/Social/Mail/Entity/Mail.cs
• Entity/Social/Mail/Entity/MailBox.cs
• Hotfix/Social/Mail/Handler/C2S_SendMailRequestHandler.cs

7. 钓鱼系统（Fish）

• 鱼类数据管理
• 钓鱼容器
• 鱼竿和诱饵配置

关键文件:

• Entity/Game/Fish/Fish.cs
• Entity/Game/Fish/FishContainer.cs

网络协议

协议生成

网络协议定义在 Tools/NetworkProtocol/ 目录，使用 Tools/ProtocolExportTool/ 工具导出。

自动生成的代码位于：

• Entity/Generate/NetworkProtocol/OuterMessage.cs - 外部消息（客户端-服务器）
• Entity/Generate/NetworkProtocol/InnerMessage.cs - 内部消息（服务器-服务器）

消息命名约定

• C2X_Request - 客户端到服务器请求
• X2C_Response - 服务器到客户端响应
• X2Y_Request - 服务器间请求

例如：

• C2A_LoginRequest - 客户端到认证服务器登录请求
• A2C_LoginResponse - 认证服务器到客户端登录响应
• G2Map_EnterMapRequest - 网关到地图服务器进入地图请求

日志系统

日志级别

• Trace: 最详细的调试信息
• Debug: 调试信息
• Info: 一般信息
• Warn: 警告信息
• Error: 错误信息
• Fatal: 致命错误

日志使用

using Fantasy;

Log.Debug("调试信息");
Log.Info("一般信息");
Log.Warn("警告信息");
Log.Error("错误信息");

日志输出位置

• 控制台: 开发环境彩色输出
• 文件: 生产环境按日期和级别分类存储

热更新机制

项目支持热更新，Hotfix 层可以动态加载和卸载。热更新逻辑位于 Hotfix/ 目录。

Hotfix 层特点

• 不包含实体定义（Entity 层）
• 包含所有 Handler、System 和 Helper
• 可以独立编译和部署

常见问题

1. 如何添加新的消息处理器？

1. 在 Tools/NetworkProtocol/ 定义消息结构
2. 运行协议导出工具生成代码
3. 在 Hotfix/{Module}/Handler/ 创建 Handler 类
4. 继承 MessageRPC<Request, Response>

2. 如何添加新的实体？

1. 在 Entity/{Module}/Entity/ 创建实体类
2. 继承 Entity 基类
3. 在 Hotfix/{Module}/ 创建对应的 System

3. 如何配置数据库？

修改 Entity/Fantasy.config 中的数据库连接字符串：

<database dbType="MongoDB" dbName="fantasy_main" dbConnection="mongodb://127.0.0.1" />

4. 如何修改服务器端口？

修改 Entity/Fantasy.config 中对应场景的端口配置：

<scene id="1003" sceneTypeString="Gate" outerPort="20000" innerPort="11021" />

开发工具

协议导出工具

位置: Tools/ProtocolExportTool/

用于从配置文件导出网络协议代码。

配置表工具

配置表定义在 Main/configs.json，代码自动生成到 Entity/Generate/ConfigTable/。

贡献指南

1. 遵循现有的命名约定和代码风格
2. 添加必要的注释和文档
3. 确保代码编译通过
4. 测试新功能
5. 更新相关文档

许可证

本项目为内部项目，版权所有。

---

文档版本: 1.0
最后更新: 2026-03-05
维护者: Fishing2Server Team