# GoGameDemo

**Repository Path**: web/go-game-demo

## Basic Information

- **Project Name**: GoGameDemo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于CocosCreator和Go WebSocket的游戏示例

## 项目简介

这是一个基于CocosCreator 3.x和Go语言开发的游戏示例，使用WebSocket实现客户端与服务器之间的实时通信。项目采用了分布式架构设计，支持高并发、低延迟和可扩展性，为50万人同时在线通信打好基础。

## 技术栈

### 服务端
- **编程语言**: Go 1.20+
- **WebSocket库**: gorilla/websocket
- **ORM框架**: gorm
- **JWT库**: github.com/golang-jwt/jwt/v4
- **加密库**: golang.org/x/crypto/bcrypt
- **配置管理**: spf13/viper
- **日志库**: go.uber.org/zap
- **指标监控**: github.com/prometheus/client_golang/prometheus
- **序列化**: Protobuf + FlatBuffers

### 客户端
- **游戏引擎**: CocosCreator 3.x
- **编程语言**: TypeScript
- **WebSocket**: 引擎内置WebSocket

## 项目结构

```
GoGameDemo/
├── cocos-client/          # CocosCreator客户端项目
│   ├── assets/            # 资源目录
│   │   ├── scripts/       # 脚本目录
│   │   │   ├── network/   # 网络通信模块
│   │   │   ├── game/      # 游戏逻辑模块
│   │   │   └── ui/        # UI模块
│   │   ├── resources/     # 资源文件
│   │   └── scenes/        # 场景文件
│   └── ...
├── go-server/             # Go服务端项目
│   ├── api/               # API模块
│   ├── config/            # 配置模块
│   ├── db/                # 数据库模块
│   ├── game/              # 游戏逻辑模块
│   ├── logger/            # 日志模块
│   ├── metrics/           # 指标采集模块
│   ├── network/           # 网络通信模块
│   ├── proto/             # 协议定义（预留）
│   ├── service/           # 业务服务模块
│   ├── test/              # 测试工具模块
│   ├── utils/             # 工具函数
│   ├── main.go            # 主入口
│   └── go.mod             # Go模块文件
└── README.md              # 项目说明文档
```

## 核心功能

### 服务端
1. **WebSocket通信**：基于gorilla/websocket实现高性能WebSocket服务器
2. **连接管理**：支持客户端连接的建立、断开和心跳检测
3. **协议编解码**：支持Protobuf和FlatBuffers序列化
4. **消息路由**：将不同类型的消息分发到对应的处理函数
5. **用户认证**：基于JWT的用户登录验证系统
6. **AOI算法**：实现九宫格AOI算法，支持万人同屏同步
7. **分布式架构**：基于etcd实现服务发现和注册
8. **负载均衡**：支持动态扩容和负载均衡
9. **指标监控**：监控系统运行状态和性能指标
10. **日志系统**：支持不同级别日志输出和日志轮转

### 客户端
1. **WebSocket通信**：实现WebSocket客户端，支持连接管理和心跳检测
2. **登录系统**：支持用户登录和注册
3. **玩家控制**：支持键盘和触摸控制玩家移动
4. **实体同步**：实现玩家和其他实体的实时同步
5. **UI系统**：实现登录界面和游戏主界面

## 快速开始

### 服务端

1. **安装依赖**

```bash
cd go-server
go mod tidy
```

2. **配置文件设置**

```bash
# 复制配置示例文件为正式配置文件
cp config/config.yaml.example config/config.yaml

# 根据实际情况修改配置文件
# 主要配置项包括：服务器端口、数据库连接、日志设置等
```

3. **数据库设置**

```bash
# 确保MySQL服务已启动
# 创建数据库
go run db/init.go

# 或手动导入SQL文件
# mysql -u root -p gogamedemo < db/init.sql
```

4. **运行服务端**

```bash
go run main.go
```

服务端将在`0.0.0.0:8080`启动WebSocket服务，API服务将在`0.0.0.0:8081`启动，指标服务将在`0.0.0.0:9090`启动。

### 客户端

1. **打开项目**

使用CocosCreator 3.x打开`cocos-client`目录。

2. **构建项目**

在CocosCreator编辑器中构建项目，选择合适的平台（如Web、Android、iOS等）。

3. **运行项目**

构建完成后，运行项目即可连接到服务端。

## 配置说明

### 服务端配置

服务端配置文件位于`go-server/config/config.yaml`，主要配置项包括：

```yaml
# 服务器配置
server:
  host: "0.0.0.0"
  port: 8080
  ws_path: "/ws"
  max_conn: 100000
  read_buf_size: 4096
  write_buf_size: 4096
  ping_interval: 30
  pong_wait: 60
  enable_compression: true

# 数据库配置
database:
  host: "localhost"
  port: 3306
  user: "root"
  password: "root"
  dbname: "gogamedemo"
  prefix: "game_"
  max_idle_conns: 10
  max_open_conns: 100
  conn_max_lifetime: 3600

# 缓存配置
cache:
  type: "memory"  # 可选值: memory, redis, bigcache, freecache
  redis:
    addr: "localhost:6379"
    password: ""
    db: 0

# JWT配置
jwt:
  secret: "your_jwt_secret_key"
  expire_hours: 24

# 日志配置
log:
  level: "info"
  file_path: "./logs/server.log"
  max_size: 100
  max_age: 7
  compress: true

# 指标配置
metrics:
  enabled: true
  addr: ":9090"

# API配置
api:
  host: "0.0.0.0"
  port: 8081
  secret: "your_api_secret_key"  # 用于API签名验证
```

### 客户端配置

客户端配置主要在代码中直接修改，如WebSocket服务器地址等。

## 数据库设计

数据库包含以下主要表（默认前缀为`game_`）：

- `game_users`: 用户表，存储用户基本信息
- `game_game_data`: 游戏数据表，存储玩家游戏数据
- `game_online_users`: 在线用户表，存储当前在线用户信息

## 缓存系统

项目实现了多种缓存机制，可在配置文件中选择：

1. **内存缓存**：基于Go内置map实现，适用于单机部署
2. **Redis缓存**：基于Redis实现，适用于分布式部署
3. **BigCache**：高性能内存缓存，适合存储大量小对象
4. **FreeCache**：无锁内存缓存，适合高并发场景

缓存自动管理热点数据，减少数据库访问压力。

## API文档

### 认证机制

API采用MD5签名验证机制，请求参数需要包含以下内容：

- `timestamp`: 当前时间戳（秒）
- `nonce`: 随机字符串
- `sign`: MD5签名，生成规则：`MD5(params + secret + timestamp + nonce)`

### 主要API端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/health` | GET | 健康检查 |
| `/api/login` | POST | 用户登录 |
| `/api/register` | POST | 用户注册 |
| `/api/game/state` | GET | 获取游戏状态 |
| `/api/game/users` | GET | 获取在线用户数 |
| `/api/game/broadcast` | POST | 广播消息 |

### PHP测试客户端

项目包含PHP5.6测试客户端，用于API测试：

```bash
# 运行API测试
php test/api_test.php
```

## 测试

### WebSocket性能测试

项目包含多种WebSocket测试工具：

1. **大规模并发测试 (ws_large_scale.go)**

   用于测试WebSocket服务器在大规模并发连接下的性能表现，支持最多100,000+连接，并生成详细的测试报告。

   **功能特性**：
   - 支持逐步增加并发连接数，从100到100,000+
   - 自动生成CSV数据报告和HTML可视化报告
   - 支持WebSocket压缩测试
   - 详细记录每个连接的延迟、成功率、吞吐量等指标
   - 实时监控连接错误率和消息成功率
   - 自动停止条件（成功率<50%或连接错误率>30%）

   **使用方法**：

   ```bash
   cd go-server/test
   go run ws_large_scale.go [参数]
   ```

   **主要参数**：
   
   | 参数 | 类型 | 默认值 | 描述 |
   |------|------|--------|------|
   | -url | string | ws://localhost:8080/ws | WebSocket服务器URL |
   | -start-conns | int | 100 | 起始并发连接数 |
   | -max-conns | int | 10000 | 最大并发连接数 |
   | -conn-increment | int | 500 | 每次测试增加的连接数 |
   | -reqs | int | 10 | 每连接发送的请求数 |
   | -size | int | 1024 | 消息大小（字节） |
   | -compress | bool | true | 是否启用WebSocket压缩 |
   | -interval | duration | 10s | 测试间隔时间 |
   | -report | string | ws_large_scale_report.csv | 测试报告文件名 |

   **示例**：
   ```bash
   # 测试100-10000连接，步长1000，启用压缩
   go run ws_large_scale.go -max-conns 10000 -conn-increment 1000 -compress true
   
   # 测试500-5000连接，步长500，消息大小2048字节
   go run ws_large_scale.go -start-conns 500 -max-conns 5000 -conn-increment 500 -size 2048
   ```

   **测试报告**：
   - CSV报告：包含详细的测试数据，可用于进一步分析
   - HTML报告：可视化图表展示性能趋势，包括成功率、延迟、吞吐量等

2. **压力测试 (ws_stress.go)**

   ```bash
   cd go-server/test
go run ws_stress.go
   ```

3. **性能测试 (ws_perf.go)**

   ```bash
   cd go-server/test
go run ws_perf.go
   ```

### API测试

使用PHP测试客户端进行API测试：

```bash
php test/api_test.php
```

## 线上Linux部署说明

### 系统环境准备

**推荐配置**：
- Linux系统：CentOS 7+/Ubuntu 18.04+
- CPU：4核以上
- 内存：8GB以上
- 带宽：10Mbps以上
- 硬盘：100GB以上

**系统优化**：

1. **调整文件描述符限制**
   
   ```bash
   # 临时调整
   ulimit -n 65535
   
   # 永久调整（编辑/etc/security/limits.conf）
   echo "* soft nofile 65535" >> /etc/security/limits.conf
   echo "* hard nofile 65535" >> /etc/security/limits.conf
   
   # 调整系统级限制（编辑/etc/sysctl.conf）
   echo "fs.file-max = 65535" >> /etc/sysctl.conf
   sysctl -p
   ```

2. **网络优化**
   
   ```bash
   # 编辑/etc/sysctl.conf，添加以下配置
   echo "net.ipv4.tcp_fin_timeout = 30" >> /etc/sysctl.conf
   echo "net.ipv4.tcp_max_syn_backlog = 8192" >> /etc/sysctl.conf
   echo "net.ipv4.tcp_tw_reuse = 1" >> /etc/sysctl.conf
   echo "net.ipv4.tcp_tw_recycle = 1" >> /etc/sysctl.conf
   echo "net.core.somaxconn = 8192" >> /etc/sysctl.conf
   sysctl -p
   ```

### 编译部署

1. **安装Go环境**
   
   ```bash
   # 下载Go 1.20+
   wget https://golang.org/dl/go1.20.13.linux-amd64.tar.gz
   tar -C /usr/local -xzf go1.20.13.linux-amd64.tar.gz
   
   # 配置环境变量
   echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc
   echo "export GOPATH=$HOME/go" >> ~/.bashrc
   source ~/.bashrc
   
   # 验证安装
   go version
   ```

2. **编译项目**
   
   ```bash
   cd /path/to/GoGameDemo/go-server
   go mod tidy
   go build -o game-server main.go
   ```

3. **配置文件设置**
   
   ```bash
   # 复制配置文件
   cp config/config.yaml.example config/config.yaml
   
   # 编辑配置文件（根据实际环境修改）
   vi config/config.yaml
   ```

   **关键配置项**：
   - `server.port`: WebSocket服务端口
   - `database`: 数据库连接信息
   - `cache.type`: 缓存类型（推荐使用Redis）
   - `log.level`: 日志级别（生产环境建议使用info或warn）
   - `log.file_path`: 日志文件路径

4. **创建数据目录**
   
   ```bash
   mkdir -p logs
   mkdir -p data
   chmod 755 logs data
   ```

### 服务管理（systemd）

1. **创建systemd服务文件**
   
   ```bash
   vi /etc/systemd/system/game-server.service
   ```

   **服务文件内容**：
   
   ```ini
   [Unit]
   Description=Game Server WebSocket Service
   After=network.target mysql.service
   
   [Service]
   Type=simple
   User=root
   WorkingDirectory=/path/to/GoGameDemo/go-server
   ExecStart=/path/to/GoGameDemo/go-server/game-server
   Restart=on-failure
   RestartSec=5s
   LimitNOFILE=65535
   
   [Install]
   WantedBy=multi-user.target
   ```

2. **服务管理**
   
   ```bash
   # 重载systemd配置
   systemctl daemon-reload
   
   # 启动服务
   systemctl start game-server
   
   # 停止服务
   systemctl stop game-server
   
   # 重启服务
   systemctl restart game-server
   
   # 查看服务状态
   systemctl status game-server
   
   # 设置开机自启
   systemctl enable game-server
   
   # 取消开机自启
   systemctl disable game-server
   ```

3. **查看日志**
   
   ```bash
   # 使用journalctl查看日志
   journalctl -u game-server -f
   
   # 或查看应用日志
   tail -f /path/to/GoGameDemo/go-server/logs/server.log
   ```

### 监控与维护

1. **监控服务状态**
   
   ```bash
   # 查看服务状态
   systemctl status game-server
   
   # 检查WebSocket端口是否监听
   netstat -tuln | grep 8080
   
   # 检查API端口是否监听
   netstat -tuln | grep 8081
   ```

2. **性能监控**
   
   - **Prometheus监控**：默认在9090端口提供监控指标
   - **Grafana可视化**：可配置Grafana面板查看详细指标
   - **系统监控**：使用top、htop、iotop等工具监控系统资源

3. **日志管理**
   
   - 日志默认按天轮转，保留7天
   - 可通过配置文件调整日志级别和保留时间
   - 建议定期备份重要日志

### 性能优化建议

1. **数据库优化**
   - 使用连接池管理数据库连接
   - 优化SQL查询，添加合适的索引
   - 考虑使用读写分离
   - 频繁访问的数据使用缓存

2. **缓存优化**
   - 生产环境建议使用Redis缓存
   - 合理设置缓存过期时间
   - 定期清理无效缓存

3. **WebSocket优化**
   - 启用WebSocket压缩（已默认启用）
   - 优化读写缓冲区大小
   - 合理设置心跳检测间隔
   - 实现消息合并发送

4. **系统优化**
   - 调整内核参数优化网络性能
   - 关闭不必要的系统服务
   - 使用SSD存储提高IO性能
   - 考虑使用负载均衡扩展服务

### 常见问题处理

1. **服务启动失败**
   
   ```bash
   # 查看详细错误信息
   systemctl status game-server -l
   
   # 检查配置文件
   go run config/check.go
   
   # 检查端口占用
   netstat -tuln | grep 8080
   ```

2. **数据库连接失败**
   
   ```bash
   # 检查数据库服务状态
   systemctl status mysql
   
   # 测试数据库连接
   mysql -h localhost -u root -p gogamedemo
   
   # 检查数据库权限
   SHOW GRANTS FOR 'root'@'localhost';
   ```

3. **高并发下性能下降**
   
   ```bash
   # 检查系统资源使用
   htop
   
   # 检查网络连接数
   ss -s
   
   # 调整连接池大小
   # 修改config/config.yaml中的database.max_open_conns
   ```

4. **日志文件过大**
   
   ```bash
   # 调整日志级别为warn或error
   # 修改config/config.yaml中的log.level
   
   # 调整日志保留时间
   # 修改config/config.yaml中的log.max_age
   ```

## 并发测试报告

项目支持生成详细的并发测试报告，包括：

- **连接数**：从100到10000+的并发连接测试
- **延迟分析**：平均延迟、最大延迟、95%分位延迟
- **吞吐量**：每秒处理的消息数
- **成功率**：消息发送成功率
- **带宽使用**：压缩前后的带宽对比
- **资源占用**：CPU、内存使用情况

报告示例位于`go-server/test/ws_performance_report.md`

## 故障排除

1. **数据库连接失败**：
   - 检查MySQL服务是否启动
   - 验证数据库配置信息是否正确
   - 确保数据库用户有足够权限

2. **WebSocket连接失败**：
   - 检查服务端是否正在运行
   - 验证防火墙设置
   - 检查客户端WebSocket地址是否正确

3. **API签名验证失败**：
   - 确保客户端和服务端使用相同的secret
   - 检查时间戳是否在有效期内
   - 验证签名生成规则是否正确

4. **高并发下性能下降**：
   - 调整服务器最大文件描述符限制
   - 优化数据库连接池配置
   - 考虑使用Redis缓存替代内存缓存

5. **内存占用过高**：
   - 调整缓存大小限制
   - 优化消息大小
   - 考虑使用更高效的序列化协议

## 近期更新

- 添加WebSocket压缩支持，减少带宽使用
- 实现大规模并发测试工具，支持10000+连接
- 优化内存使用，减少GC压力
- 完善API文档和测试工具
- 增加多种缓存机制支持
- 优化数据库查询性能
- 实现更详细的性能报告生成
- 完善线上Linux部署指南

## 开发说明

### 协议定义

项目使用Protobuf和FlatBuffers进行消息序列化，协议定义文件位于`go-server/proto/`目录下。

### 消息处理

服务端消息处理函数注册在`network/message.go`中，客户端消息处理函数注册在对应的场景脚本中。

### 实体同步

实体同步采用AOI（Area of Interest）算法，只有在玩家视野范围内的实体才会被同步。

## 许可证

MIT