s_cherry_e/sr

F1游戏服务端

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

项目概述

F1游戏服务器是一个高性能、分布式的游戏服务端项目，核心玩法为地图沙盘系统。项目使用以下技术栈：

• 语言: Go 1.24
• 框架: Cherry（基于Actor模型的分布式框架）
• 通信: Protocol Buffers + NATS集群
• 存储: MongoDB（持久化） + Redis（缓存）
• 架构: 分布式架构，支持多节点部署

开始

• clone本仓库，通过bash来执行初始化命令
• 安装protoc (v3.17.3) 和 protoc-gen-go (v1.27.1)
• 执行make查询相关指令，执行make init进行项目初始化
• 执行make chmod设置脚本权限

术语定义

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

服务器架构图

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

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

节点类型

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

调试&启动

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

启动参数示例

• run -path=./etc/profile/su.json -node=master-1 启动master类型的节点，环境为dev，节点id为master-1
• run -path=./etc/profile/su.json -node=center-1 启动center类型的节点，环境为dev，节点id为center-1
• run -path=./etc/profile/su.json -node=gate-1 启动gate类型的节点，环境为dev，节点id为gate-1
• run -path=./etc/profile/su.json -node=gate-1 启动gate类型的节点，环境为dev，节点id为gate-1
• run -path=./etc/profile/su.json -node=web-1 启动web类型的节点，环境为dev，节点id为web-1
• run -path=./etc/profile/su.json -node=map-1 启动map类型的节点，环境为dev，节点id为map-1
• run -path=./etc/profile/su.json -node=3 启动game类型的节点，环境为dev，节点id为3

版本查看

• run version 或 run v 或 run ver 查看节点版本信息

调试&启动

• 每个节点的启动都通过nodes/{xxx}/{xxx}.go的Run函数进行
• 启动前先确认etc/profile/目录是否有您需要的profile配置
• 内部已部署整套dev环境，开发人员仅需启动game节点即可进行本地调试

启动参数示例

• run -path=./etc/profile/ryansu.json -node=master-1 启动master类型的节点，环境为ryansu，节点id为master-1
• run -path=./etc/profile/ryansu.json -node=center-1 启动center类型的节点，环境为ryansu，节点id为center-1
• run -path=./etc/profile/ryansu.json -node=gate-1 启动gate类型的节点，环境为ryansu，节点id为gate-1
• run -path=./etc/profile/ryansu.json -node=web-1 启动web类型的节点，环境为ryansu，节点id为web-1
• run -path=./etc/profile/ryansu.json -node=1 启动game类型的节点，环境为ryansu，节点id为1

构建和发布

常用命令

# 查看所有可用命令
make help

# 初始化项目（安装protoc-gen-go）
make init

# 构建完整项目（交互模式）
make build

# 非交互模式构建
make build <env> <update_excel> <publish>
# env: 1=dev, 2=test, 3=dev&test, 4=prod
# update_excel: y/Y/1 表示更新并导出Excel数据
# publish: y/Y/1 表示推送到发布仓库

# 仅构建源代码
make code

# 构建Excel数据文件
make excel

# 构建protobuf文件
make proto

# 清理构建产物
make clean

# 清理数据库
make clean_db

仓库管理

# 更新外部仓库
make pull-excel    # 更新Excel配置
make pull-proto   # 更新protobuf定义
make pull-cherry  # 更新Cherry框架

# 设置脚本权限
make chmod

Excel数据管理

# 更新Excel仓库并转换为JSON
make pull-e        # 从f1/excel.git更新excel仓库
make e            # 转换xlsx文件到etc/data/并生成go文件到internal/data/

测试命令

# 运行所有测试
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 build，根据提示选择对应的版本发布。
• 详细的发布流程请参考 docs/git-flow/ 目录下的git flow文档。

模块简介

excel

• 本目录为策划excel配表仓库
• 通过make e导表
• Excel数据导出到 etc/data/ 目录

protocol

• 本目录为protobuf通信协议仓库，通信协议包头
• 协议文件位于 internal/pb/ 目录，基于 /f1/protocol.git 仓库生成
• 生成逻辑详见etc/script/build_proto.sh脚本
• 使用 make pull-p 更新protocol.git仓库
• 使用 make proto 生成最终的协议文件
• protoc-gen-go v1.27.1
• protoc v3.17.3

nodes/center

• 游戏中心节点，单节点部署，用于处理帐号、支付相关公共业务
• 不做具体游戏内的业务

nodes/map

• 地图节点，处理地图沙盘玩法（核心功能）
• 包含AOI管理、寻路、联盟地图等功能
• 详细文档请参考 nodes/map/README.md

nodes/game

• 游戏服节点，滚服部署

nodes/gate

• 游戏网关节点，可多节点部署，根据负载情况进行多节点部署
• 可以给每个区设置一个网关地址。通过数据库center.area.gate字段进行设置
• 可以自行架设反向代理进行多个gate节点集群
• 可通过阿里/腾讯云的SLB服务进行多网关节负载部署

nodes/master

• 仅在profile->cluster->discovery模式为nats时使用该节点
• 实现简易的发现服务功能，单节点部署，用于同步/广播节点信息

nodes/web

• web节点主要处理对外的http业务

nodes/chat

• 聊天节点，处理游戏内聊天相关业务

nodes/pay

• 支付节点，处理游戏支付相关业务

nodes/record

• 记录节点，处理游戏记录数据相关业务

nodes/ops

• 运维节点，提供运维相关接口

nodes/match

• 匹配节点，处理游戏匹配相关业务

tool

• 工具目录，包含各种开发工具
  • client-cli: 客户端命令行工具，用于测试
  • cleandb: 数据库清理工具
  • proto-route: 协议路由工具
  • test: 各种测试工具

数据库

• 通过gorm的migrator功能管理数据库结构

部署

• TODO (生产环境部署手册)

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 初始化相关组件

项目结构

f1-server/
├── nodes/              # 各个节点目录
│   ├── center/         # 中心节点
│   ├── game/           # 游戏节点
│   ├── gate/           # 网关节点
│   ├── master/         # 主节点
│   ├── web/            # Web节点
│   ├── chat/           # 聊天节点
│   ├── map/            # 地图节点（核心功能）
│   ├── pay/            # 支付节点
│   ├── 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星算法
• 行军系统: 支持多种行军状态（空闲、停留、撤退、占领、采集、驻守、攻城等）
• 碰撞系统: 处理行军对象之间的碰撞和战斗逻辑
• 城战系统: 支持攻城大营、宣战、集结等城战玩法
• 联盟地图: 支持联盟在地图上的业务逻辑

详细文档请参考 nodes/map/README.md。

技术特性

• Actor模型: 基于Cherry框架的Actor模型，实现高并发处理
• 分布式架构: 支持多节点部署，可横向扩展
• NATS集群: 节点间通过NATS进行通信
• Protocol Buffers: 高效的消息序列化
• MongoDB + Redis: 持久化存储和高速缓存

开发文档

• 开发规范和指南：请参考 AGENTS.md
• Git工作流：请参考 docs/git-flow/
• 架构文档：请参考 docs/ 目录

快速开始

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=10002
   

贡献指南

请参考 docs/git-flow/ 目录下的git flow文档了解开发流程。

许可证

[请在此处添加许可证信息]