# 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
### 构建项目
```bash
# 构建整个解决方案
dotnet build Server.sln
# 构建特定项目
dotnet build Main/Main.csproj
dotnet build Entity/Entity.csproj
dotnet build Hotfix/Hotfix.csproj
```
### 运行项目
```bash
# 运行主程序
dotnet run --project Main/Main.csproj
# 或直接编译运行
cd Main/bin/Debug/net9.0
Main.exe
```
### 配置说明
#### 1. MongoDB 配置
在 `Entity/Fantasy.config` 中配置数据库连接：
```xml
```
#### 2. 服务器配置
在 `Entity/Fantasy.config` 中配置服务器地址：
```xml
```
#### 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`：
```csharp
public class C2Game_GetItemsRequestHandler : MessageRPC
{
protected override async FTask Run(Session session, C2Game_GetItemsRequest request, G2C_GetItemsResponse response, Action reply)
{
// 业务逻辑
response.ErrorCode = ErrorCode.Successful;
}
}
```
### 实体系统
所有实体继承自 `Entity` 基类：
```csharp
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**: 致命错误
### 日志使用
```csharp
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`
### 2. 如何添加新的实体？
1. 在 `Entity/{Module}/Entity/` 创建实体类
2. 继承 `Entity` 基类
3. 在 `Hotfix/{Module}/` 创建对应的 System
### 3. 如何配置数据库？
修改 `Entity/Fantasy.config` 中的数据库连接字符串：
```xml
```
### 4. 如何修改服务器端口？
修改 `Entity/Fantasy.config` 中对应场景的端口配置：
```xml
```
## 开发工具
### 协议导出工具
位置: `Tools/ProtocolExportTool/`
用于从配置文件导出网络协议代码。
### 配置表工具
配置表定义在 `Main/configs.json`，代码自动生成到 `Entity/Generate/ConfigTable/`。
## 贡献指南
1. 遵循现有的命名约定和代码风格
2. 添加必要的注释和文档
3. 确保代码编译通过
4. 测试新功能
5. 更新相关文档
## 许可证
本项目为内部项目，版权所有。
---
**文档版本**: 1.0
**最后更新**: 2026-03-05
**维护者**: Fishing2Server Team