# Gobige

**Repository Path**: night-tc/gobige

## Basic Information

- **Project Name**: Gobige
- **Description**: Gobige 是一个高性能、模块化的分布式游戏服务器框架，旨在简化游戏服务器的开发和部署。它支持多种服务器类型的协同工作，提供了灵活的消息路由和高效的 RPC 调用机制。
- **Primary Language**: Go
- **License**: BSD-4-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 20
- **Forks**: 10
- **Created**: 2023-05-08
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: game-dev

**Tags**: Go语言, 服务器框架, 游戏服务器, MMO

## README

# Gobige Framework

[![License](https://img.shields.io/badge/License-BSD%204--Clause-blue.svg)](LICENSE)
[![Go Version](https://img.shields.io/badge/Go-1.24.0-00ADD8?logo=go)](https://go.dev)
[![star](https://gitee.com/night-tc/gobige/badge/star.svg?theme=dark)](https://gitee.com/night-tc/gobige/stargazers)

Gobige 是一个高性能、模块化的分布式游戏服务器框架，基于 Go 开发，面向多服务协作、实体系统、消息路由与高并发场景。

> 这个仓库主要介绍和提供框架能力。
> 如果你想直接运行完整应用或查看业务级示例，请前往 Gobige Demo：<https://gitee.com/night-tc/gobige-demo>

## 仓库对照

| 维度 | gobige（本仓库） | gobige-demo（应用仓库） |
|------|------------------|--------------------------|
| 目标 | 提供框架内核与通用能力 | 提供可运行示例与业务应用 |
| 主要内容 | Service、Entity、MsgHandler、Sess、Etcd、Timer 等基础模块 | 服务器实例、配置样例、构建脚本、联调流程 |
| 适合人群 | 框架开发者、需要扩展底层能力的开发者 | 想快速跑通项目、验证业务流程的开发者 |
| 推荐动作 | 阅读架构和模块设计，按约定扩展能力 | 按启动步骤运行服务并做端到端联调 |
| 仓库地址 | https://gitee.com/night-tc/gobige | https://gitee.com/night-tc/gobige-demo |

## 先看这里

- 想了解本仓库定位：看 [仓库定位与使用方式](#仓库定位与使用方式)
- 想理解系统：看 [架构总览](#架构总览)
- 想知道目录职责：看 [目录速览](#目录速览)
- 想扩展业务：看 [开发约定](#开发约定)
- 想运行完整应用：看 [Demo 指引](#demo-指引)
- 启动报错：看 [常见问题与排查](#常见问题与排查)

## 仓库定位与使用方式

- 本仓库（gobige）：框架内核、基础组件、接口规范、性能与扩展能力。
- Demo 仓库（gobige-demo）：可运行的业务应用、配置样例、启动脚本、实战联调流程。

建议阅读顺序：

1. 先阅读本仓库的架构与模块能力（本 README）
2. 再去 demo 仓库按步骤运行服务与联调
3. 最后回到本仓库按约定扩展业务模块

## 框架快速校验（开发者）

### 1. 环境要求

- Go 1.24.0+
- ETCD 3.6+
- Redis 5.0+
- MySQL 5.7+ 或 PostgreSQL 12+

建议先确认版本：

```bash
go version
etcd --version
redis-server --version
```

### 2. 获取代码与依赖

```bash
git clone https://gitee.com/night-tc/gobige.git
cd gobige
go mod tidy
```

### 3. 编译与测试（框架层）

```bash
go build ./...
go test ./entity ./service -run=^$
```

如果你在本地有自定义入口程序，再执行：

```bash
go run ./cmd/your-server
```

> 说明：本仓库偏框架层，不提供固定业务主程序。完整应用启动流程在 demo 仓库。

### 4. 最小验证

满足以下条件即视为框架层验证通过：

- `go build ./...` 通过
- `go test ./entity ./service -run=^$` 通过
- 关键包可通过无副作用测试

## Demo 指引

如果你的目标是“启动可用服务并验证业务流程”，建议直接使用 demo 仓库：

- Demo 仓库：https://gitee.com/night-tc/gobige-demo
- 配置生成工具：https://gitee.com/night-tc/gen-gobige-json

在 gobige-demo 中，通常执行顺序是：

1. 准备依赖环境（ETCD/Redis/DB）
2. 生成协议相关工具（协议有变更时）
3. 生成 server.json
4. 编译并启动各类服务
5. 通过客户端或测试脚本做联调验证

## 架构总览

```text
Client (WebSocket/TCP/KCP)
          |
       Gateway
          |
   +------+-------+
   |      |       |
 Login  Game   Entity/Space
          |
         ETCD
          |
   +------+------+
   |      |      |
  DB    Redis   Kafka
```

### 核心能力

- 模块化服务基座：Service + MsgHandler + Entity
- 分布式服务发现：ETCD 注册、监听、重连
- 消息体系完整：普通消息、RPC、服务器间消息
- 多协议网络：TCP/KCP/WebSocket
- 定时器与对象池：面向高并发和低 GC 压力
- 多存储支持：MySQL、PostgreSQL、Redis

## 目录速览

```text
gobige/
├── common/        通用工具和基础结构
├── dbaccess/      数据库访问路由
├── dbmanager/     数据模型与脏数据管理
├── dblink/        数据库连接层
├── dbpgx/         PostgreSQL 支持
├── entity/        实体系统
├── etcd/          服务发现与配置中心访问
├── msgdef/        协议与消息定义
├── msghandler/    消息注册与分发
├── redislib/      Redis 封装
├── serverMgr/     服务映射与负载
├── service/       服务生命周期与主循环
├── sess/          网络会话与编解码
├── space/         场景系统与寻路
├── timerwheel/    时间轮定时器
└── gobige_test.go 基础测试
```

## 开发约定

### 消息处理函数命名

- `MsgProc_XXX`：普通消息
- `RPC_XXX`：RPC 请求
- `Srv_XXX`：服务器间消息

### 推荐开发流程

1. 在 proto 中新增或修改协议
2. 生成代码与协议映射
3. 在业务对象上实现 `MsgProc_`/`RPC_`/`Srv_`
4. 在 Service/Entity 挂载处理器并联调

### 示例（示意代码）

```go
type EntitiesMsgProc struct {
    es IEntities
}

func (p *EntitiesMsgProc) MsgProc_CreateEntityReqSrv(msg *protomsg.CreateEntityReqSrv) {
    // 处理普通消息
}

func (p *EntitiesMsgProc) Srv_CreateEntityReqSrv(req *protomsg.RouteMsgSrvReq, msg *protomsg.CreateEntityReqSrv) error {
    // 处理服务器间消息并返回 error（可选）
    return common.Err_Success
}
```

`RPC_XXX` 处理函数由框架前缀机制支持；具体业务实现通常在 demo 或业务仓库中提供。

## 源码对照（关键能力）

- Service 生命周期与主循环: `service/Service.go`, `service/IserviceReal.go`
- 消息注册与前缀分发: `msghandler/MsgHandlers.go`, `msghandler/KeyHandlers.go`
- Service 内置消息处理示例: `service/Service_Proc.go`
- Entity 层消息处理示例: `entity/Entities_MsgProc.go`
- 服务发现与负载入口: `serverMgr/Discovery.go`
- 配置解析与字段映射: `global/GlobalConfig.go`

如果文档描述与代码行为不一致，请以源码为准，欢迎直接提 Issue 或 PR 修正文档。

## 配置要点

常见配置键：

- `Config.Recover`：是否启用 panic recover
- `Config.Debug`：是否启用调试模式
- `Etcd`：ETCD 地址、超时、租约（顶层键）
- `[ServerName].Inner/Outer/Http`：监听配置（如 `Game.Inner`）
- `DBMap`：数据库连接池参数（顶层键）
- `[ServerName].RedisList`：Redis 配置引用列表
- `[ServerName].LocalTypes/WatchLocalTypes`：本组连接与关注的服务类型

建议把不同环境（开发/测试/生产）拆分为独立配置文件，避免手工切换。

## 性能建议

- 使用对象池减少短生命周期对象分配
- 使用并发安全容器（如 xsync）降低锁竞争
- 通过批处理消费消息队列降低调度开销
- 根据业务粒度调整时间轮精度

## 常见问题与排查

### Q1: 服务发现失败

检查：

```bash
etcdctl endpoint health
```

确认配置中的 ETCD 地址、租约 TTL、网络可达性。

### Q2: 启动后无连接或端口不可用

检查监听地址、端口冲突、防火墙策略。确保 `[ServerName].Inner/Outer/Http` 与部署环境匹配。

### Q3: 消息处理函数未触发

检查：

- 函数前缀是否符合约定（`MsgProc_`/`RPC_`/`Srv_`）
- 协议号映射是否已更新
- 处理器是否正确注册

### Q4: 数据库连接异常

检查 `DBMap` 的地址、账号、连接池大小与最大生命周期配置是否合理。

### Q5: 全量测试失败

框架内某些包可能依赖外部资源，建议先执行最小验证：

```bash
go test ./entity ./service -run=^$
```

## 兼容性

建议在以下组合上验证后再进入生产：

- Go：1.24.x
- ETCD：3.6.x
- PostgreSQL：12+
- Redis：5+

## 贡献

欢迎提交 Issue 和 Pull Request。

1. Fork 仓库
2. 创建分支：`git checkout -b feature/AmazingFeature`
3. 提交代码：`git commit -m 'Add some AmazingFeature'`
4. 推送分支：`git push origin feature/AmazingFeature`
5. 提交 PR

## 许可证

Gobige 使用 [BSD 4-Clause License](LICENSE)。

## 相关链接

- 项目地址：https://gitee.com/night-tc/gobige
- Demo 项目：https://gitee.com/night-tc/gobige-demo
- 配置生成工具：https://gitee.com/night-tc/gen-gobige-json

---

最后更新时间：2026 年 3 月 10 日