# F1游戏服务端 基于Go语言和Cherry框架构建的SLG（策略类）游戏服务器，采用分布式架构和Actor模型。 ## 目录 - [项目概述](#项目概述) - [开始](#开始) - [环境要求](#环境要求) - [技术特性](#技术特性) - [项目结构](#项目结构) - [核心功能](#核心功能) - [快速开始](#快速开始) - [服务器架构](#服务器架构) - [术语定义](#术语定义) - [配置文件说明](#配置文件说明) - [节点类型](#节点类型) - [调试&启动](#调试启动) - [构建和发布](#构建和发布) - [常用命令](#常用命令) - [测试命令](#测试命令) - [仓库管理](#仓库管理) - [Proto仓库](#proto仓库) - [版本发布](#版本发布) - [部署](#部署) - [QA](#qa) - [贡献指南](#贡献指南) - [许可证](#许可证) --- ## 项目概述 F1游戏服务器是一个高性能、分布式的游戏服务端项目，核心玩法为地图沙盘系统。项目使用以下技术栈： - **语言**: Go 1.24+ - **框架**: Cherry（基于Actor模型的分布式框架） - **通信**: Protocol Buffers + NATS集群 - **存储**: MongoDB（持久化） + Redis（缓存） - **架构**: 分布式架构，支持多节点部署 ### 开始 - `clone`本仓库，通过`bash`来执行初始化命令 - 安装`protoc` (v3.17.3) 和 `protoc-gen-go` (v1.36.8) - 执行`make`查询相关指令，执行`make init`进行项目初始化 - 执行`make chmod`设置脚本权限 ### 环境要求 | 组件 | 版本要求 | |------|----------| | Go | 1.24+ | | protoc | v3.17.3 | | protoc-gen-go | v1.36.8 | | MongoDB | 7.0+ | | Redis | 8.0+ | | NATS | 2.x | > 注意：确保所有依赖版本满足要求，否则可能导致构建或运行问题。 --- ## 技术特性 - **Actor模型**: 基于Cherry框架的Actor模型，实现高并发处理 - **分布式架构**: 支持多节点部署，可横向扩展 - **NATS集群**: 节点间通过NATS进行通信 - **Protocol Buffers**: 高效的消息序列化 - **MongoDB + Redis**: 持久化存储和高速缓存 ## 项目结构 ``` f1-server/ ├── nodes/ # 各个节点目录 │ ├── center/ # 中心节点 │ ├── game/ # 游戏节点 │ ├── gate/ # 网关节点 │ ├── master/ # 主节点 │ ├── web/ # Web节点 │ ├── chat/ # 聊天节点 │ ├── map/ # 地图节点（核心功能） │ ├── record/ # 记录节点 │ ├── match/ # 匹配节点 │ └── ops/ # 运维节点 ├── internal/ # 内部共享代码 │ ├── actor_remote/ # 远程调用 │ ├── component/ # 组件 │ ├── pb/ # 协议文件（自动生成） │ ├── types/ # 自定义类型 │ └── ... ├── etc/ # 配置文件 │ ├── profile/ # 环境配置 │ ├── data/ # Excel数据（JSON） │ └── script/ # 脚本文件 ├── tool/ # 工具目录 ├── docs/ # 文档目录 └── AGENTS.md # AI代理开发指南 ``` --- ## 核心功能 ### 地图沙盘系统（nodes/map） 地图沙盘是本项目的核心功能模块，包含以下特性： - **AOI（Area of Interest）系统**: 分层管理不同类型的地图对象 - **寻路系统**: 支持大地图分区域、分层寻路的A星算法 - **行军系统**: 支持多种行军状态（空闲、停留、撤退、占领、采集、驻守、攻城等） - **碰撞系统**: 处理行军对象之间的碰撞和战斗逻辑 - **城战系统**: 支持攻城大营、宣战、集结等城战玩法 - **联盟地图**: 支持联盟在地图上的业务逻辑 详细文档请参考 [README](nodes/map/README.md)。 ### 游戏服务节点（nodes/game） 游戏服务节点是核心游戏逻辑处理中心，承载玩家会话和游戏主流程： - **玩家管理**: 玩家Actor分片处理，支持高并发玩家同时在线 - **登录系统**: 处理玩家登录流程，创建和管理玩家会话 - **邮件系统**: 游戏内邮件的发送、接收和管理 - **排行榜**: 各类游戏排行榜的计算和展示 - **通用对象池**: GUID生成和对象池管理 ### 网关节点（nodes/gate） 网关节点是客户端统一接入层，负责连接管理和请求路由： - **连接管理**: 维护长连接，处理心跳检测和连接状态 - **登录鉴权**: Token验证、SDK配置校验、获取UID - **请求路由**: 根据Session中的节点信息路由到Game/Map等后端节点 - **限速控制**: 基于UID和IP的请求频率限制 - **推送服务**: 支持按玩家、节点维度批量推送消息 - **踢人机制**: 支持重复登录踢出、强制下线等功能 详细文档请参考 [README](nodes/gate/README.md)。 ### 中心节点（nodes/center） 中心节点提供跨游戏服的中心数据与控制平面： - **账号绑定**: 统一UID与第三方平台OpenID的绑定管理 - **开发者账号**: 开发者账号注册、认证和权限管理 - **登录记录**: 聚合并缓存玩家最后登录记录（Redis+MongoDB） - **运维接口**: 健康探测、优雅关停、DB队列监控 - **数据分片**: Actor分片设计提升并发处理能力 详细文档请参考 [README](nodes/center/README.md)。 ### 主节点（nodes/master） 主节点是节点发现服务，仅在NATS模式下使用： - **服务发现**: 管理集群中各节点的注册与发现 - **节点同步**: 维护节点状态，支持新节点加入时的信息同步 - **轻量级设计**: 单节点部署，作为集群协调中心 ### Web节点（nodes/web） Web节点处理对外HTTP业务，提供RESTful API： - **HTTP服务**: 基于Gin框架的HTTP API服务 - **跨域支持**: 内置CORS中间件 - **接口控制器**: 首页、开发者、登录、支付、玩家、服务器等接口 - **限速保护**: IP级别的请求频率限制 ### 聊天节点（nodes/chat） 聊天节点处理游戏内聊天功能： - **私聊**: 玩家一对一私聊消息 - **群聊**: 多人群组聊天功能 - **联盟聊天**: 联盟频道内的成员聊天 - **地图聊天**: 地图范围内的区域聊天 ### 记录节点（nodes/record） 记录节点处理游戏数据记录和日志存储： - **数据记录**: 游戏行为数据的异步记录 - **多模式存储**: 支持本地文件模式和云存储模式 - **Actor分片**: 根据数据类型分片处理，提升写入性能 ### 运维节点（nodes/ops） 运维节点提供运维相关接口和管理功能： - **运维接口**: 服务器状态查询、配置管理 - **静态资源**: 运维后台静态文件服务 - **管理后台**: 游戏运营管理界面 --- ## 快速开始 1. 克隆仓库并初始化： ```bash git clone cd f1-server make init ``` 2. 设置脚本权限： ```bash make chmod ``` 3. 更新外部仓库： ```bash make pull-excel make pull-proto ``` 4. 构建项目： ```bash make build ``` 5. 启动节点： ```bash run -path=./etc/profile/dev.json -node=1 ``` --- ## 服务器架构 ### 术语定义 - `node` 节点，每个服务进程都称为一个`节点`，通过`节点类型`进行归类 - `pid` 平台id - `uid` 游戏内用户唯一id - `playerID` 玩家id - `openID` 第三方的用户唯一id ### 服务器架构图 (**项目使用基于nats集群的架构**) [基于nats集群的架构](tool/docs/images/architecture-nats.jpg) [架构图PNG](docs/architecture.png) ### 配置文件说明 #### profile 目录 `etc/profile/` 目录下存放各环境的配置文件： 详细配置说明请参考 [Profile配置文件说明](docs/0003-profile-config.md)。 ### 节点类型 - **game**: 游戏服节点，核心游戏逻辑和玩家会话，滚服部署 - **gate**: 游戏网关节点，WebSocket/HTTP网关，处理客户端连接，可多节点部署 - **center**: 游戏中心节点，账户管理和支付服务，单节点部署 - **master**: 节点发现服务，仅在NATS模式下使用，实现简易的发现服务功能 - **web**: web节点，主要处理对外的http业务 - **chat**: 聊天节点，处理游戏内聊天功能 - **map**: 地图节点，处理地图沙盘玩法（核心功能） - **record**: 记录节点，处理游戏记录数据 - **ops**: 运维节点，提供运维相关接口 ### 调试&启动 - 每个节点的启动都通过`nodes/main.go`的`run`命令进行 - 启动前先确认`etc/profile/`目录是否有您需要的profile配置 - **内部已部署整套`dev环境`，开发人员仅需启动`game节点`即可进行本地调试** - 详细的文档请查阅[开发调试指南](docs/0001-dev-debug.md)。 --- ## 构建和发布 #### 常用命令 ```bash # 查看所有可用命令 make help ``` #### 测试命令 ```bash # 运行所有测试 go test ./... # 运行特定测试文件 go test ./tool/test/slice/slice_test.go # 运行测试并显示详细输出 go test -v ./path/to/test # 运行单个测试函数 go test -run TestSpecificFunction ./path/to/test # 运行基准测试 go test -bench=. ./path/to/test # 运行测试并生成覆盖率报告 go test -cover ./path/to/package ``` #### 仓库管理 ```bash # 更新外部仓库 make pull-excel # 更新Excel配置 make pull-proto # 更新protobuf协议 make pull-cherry # 更新Cherry框架(go work方式开发则有必要拉取cherry框架) make chmod # 设置脚本权限 ``` #### Excel数据管理 ```bash # 更新Excel仓库并转换为JSON make pull-e # 拉取Excel仓库 make e # 转换xlsx文件到etc/data/并生成go文件到internal/data/ ``` #### 版本发布 - 执行 `make build`，根据提示选择对应的版本发布。 - 详细的发布流程请参考 `docs/git-flow/` 目录下的git flow文档。 #### 部署 - 生产环境部署手册详见 [生产环境部署说明](docs/0002-prod-env-deployment.md)。 --- ## QA #### 1. 文本格式设置 - clone代码前修改git的`Auto Crlf convert`参数。AutoCrlf:false, SafeCrlf:false - 修改Goland，找到`Settings -> Editor -> Code Style -> Line Separator`修改为`Unix and Macos` #### 2. 代码编写事项 - XxxID 字段 ID 要大小如`HeroID`不能是小写如`Heroid`或者`HeroId` - 方法的接收体名称统一使用 p ，这样看到 p.xxx 就知道是当前方法的主体 - 所有的 int 类型统一使用 int32 或者 int64 - 使用GORM进行数据库操作和映射管理 - 遵循Actor模型进行并发操作 - 详细代码风格指南请参考 `AGENTS.md` #### 3. linux开发环境配置 - 安装`go` https://go.dev/doc/install - 安装`protoc` https://github.com/protocolbuffers/protobuf/releases - 执行`make`或`make help` 查看相关脚本指令 - 执行`make chmod` 设置相关脚本的权限 - 执行`make init` 初始化相关组件 --- ## 贡献指南 请参考 `docs/git-flow/` 目录下的git flow文档了解开发流程。 --- ## 许可证 - Firerock Copyright