s_cherry_e/sr

F1游戏服务端

基于Go语言和Cherry框架构建的SLG（策略类）游戏服务器，采用分布式架构和Actor模型。

目录

• 项目概述
  • 开始
  • 环境要求
• 技术特性
• 项目结构
• 核心功能
• 快速开始
• 服务器架构
  • 术语定义
  • 配置文件说明
  • 节点类型
  • 调试&启动
• 构建和发布
  • 常用命令
  • 测试命令
• 仓库管理
  • Proto仓库
  • 版本发布
  • 部署
• 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/game）

游戏服务节点是核心游戏逻辑处理中心，承载玩家会话和游戏主流程：

• 玩家管理: 玩家Actor分片处理，支持高并发玩家同时在线
• 登录系统: 处理玩家登录流程，创建和管理玩家会话
• 邮件系统: 游戏内邮件的发送、接收和管理
• 排行榜: 各类游戏排行榜的计算和展示
• 通用对象池: GUID生成和对象池管理

网关节点（nodes/gate）

网关节点是客户端统一接入层，负责连接管理和请求路由：

• 连接管理: 维护长连接，处理心跳检测和连接状态
• 登录鉴权: Token验证、SDK配置校验、获取UID
• 请求路由: 根据Session中的节点信息路由到Game/Map等后端节点
• 限速控制: 基于UID和IP的请求频率限制
• 推送服务: 支持按玩家、节点维度批量推送消息
• 踢人机制: 支持重复登录踢出、强制下线等功能

详细文档请参考 README。

中心节点（nodes/center）

中心节点提供跨游戏服的中心数据与控制平面：

• 账号绑定: 统一UID与第三方平台OpenID的绑定管理
• 开发者账号: 开发者账号注册、认证和权限管理
• 登录记录: 聚合并缓存玩家最后登录记录（Redis+MongoDB）
• 运维接口: 健康探测、优雅关停、DB队列监控
• 数据分片: Actor分片设计提升并发处理能力

详细文档请参考 README。

主节点（nodes/master）

主节点是节点发现服务，仅在NATS模式下使用：

• 服务发现: 管理集群中各节点的注册与发现
• 节点同步: 维护节点状态，支持新节点加入时的信息同步
• 轻量级设计: 单节点部署，作为集群协调中心

Web节点（nodes/web）

Web节点处理对外HTTP业务，提供RESTful API：

• HTTP服务: 基于Gin框架的HTTP API服务
• 跨域支持: 内置CORS中间件
• 接口控制器: 首页、开发者、登录、支付、玩家、服务器等接口
• 限速保护: IP级别的请求频率限制

聊天节点（nodes/chat）

聊天节点处理游戏内聊天功能：

• 私聊: 玩家一对一私聊消息
• 群聊: 多人群组聊天功能
• 联盟聊天: 联盟频道内的成员聊天
• 地图聊天: 地图范围内的区域聊天

记录节点（nodes/record）

记录节点处理游戏数据记录和日志存储：

• 数据记录: 游戏行为数据的异步记录
• 多模式存储: 支持本地文件模式和云存储模式
• Actor分片: 根据数据类型分片处理，提升写入性能

运维节点（nodes/ops）

运维节点提供运维相关接口和管理功能：

• 运维接口: 服务器状态查询、配置管理
• 静态资源: 运维后台静态文件服务
• 管理后台: 游戏运营管理界面

---

快速开始

1. 克隆仓库并初始化：

   git clone <repository-url>
   cd f1-server
   make init
   

2. 设置脚本权限：

   make chmod
   

3. 更新外部仓库：

   make pull-excel
   make pull-proto
   

4. 构建项目：

   make build
   

5. 启动节点：

   run -path=./etc/profile/dev.json -node=1
   

---

服务器架构

术语定义

• node 节点，每个服务进程都称为一个节点，通过节点类型进行归类
• pid 平台id
• uid 游戏内用户唯一id
• playerID 玩家id
• openID 第三方的用户唯一id

服务器架构图

(项目使用基于nats集群的架构)

基于nats集群的架构 架构图PNG

配置文件说明

profile 目录

etc/profile/ 目录下存放各环境的配置文件：

详细配置说明请参考 Profile配置文件说明。

节点类型

• game: 游戏服节点，核心游戏逻辑和玩家会话，滚服部署
• gate: 游戏网关节点，WebSocket/HTTP网关，处理客户端连接，可多节点部署
• center: 游戏中心节点，账户管理和支付服务，单节点部署
• master: 节点发现服务，仅在NATS模式下使用，实现简易的发现服务功能
• web: web节点，主要处理对外的http业务
• chat: 聊天节点，处理游戏内聊天功能
• map: 地图节点，处理地图沙盘玩法（核心功能）
• record: 记录节点，处理游戏记录数据
• ops: 运维节点，提供运维相关接口

调试&启动

• 每个节点的启动都通过nodes/main.go的run命令进行
• 启动前先确认etc/profile/目录是否有您需要的profile配置
• 内部已部署整套dev环境，开发人员仅需启动game节点即可进行本地调试
• 详细的文档请查阅开发调试指南。

---

构建和发布

常用命令

# 查看所有可用命令
make help

测试命令

# 运行所有测试
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

仓库管理

# 更新外部仓库
make pull-excel   # 更新Excel配置
make pull-proto   # 更新protobuf协议
make pull-cherry  # 更新Cherry框架(go work方式开发则有必要拉取cherry框架)
make chmod        # 设置脚本权限

Excel数据管理

# 更新Excel仓库并转换为JSON
make pull-e       # 拉取Excel仓库
make e            # 转换xlsx文件到etc/data/并生成go文件到internal/data/

版本发布

• 执行 make build，根据提示选择对应的版本发布。
• 详细的发布流程请参考 docs/git-flow/ 目录下的git flow文档。

部署

• 生产环境部署手册详见 生产环境部署说明。

---

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