273 lines
9.3 KiB
Markdown
273 lines
9.3 KiB
Markdown
# game_server
|
||
|
||
Erlang/OTP 游戏服务端 umbrella 工程。项目按职责拆成多个 OTP app，并通过 `rebar3` profiles 组合出游戏服、登录服和压测/客户端模拟服。
|
||
|
||
## 项目概览
|
||
|
||
本仓库主要包含：
|
||
|
||
- `game_server`：核心游戏服，负责 TCP/HTTP 服务、角色与玩法逻辑、缓存、日志、定时任务、跨节点通信等。
|
||
- `login_server`：登录服，负责账号登录信息、区服信息、内部账号/IP 白名单、维护状态、合服相关入口等。
|
||
- `client_server`：压测/客户端模拟服务，用于连接登录服、游戏服并执行测试模块。
|
||
- `game_proto`：协议定义与 protobuf/gpb 生成配置。
|
||
- `game_config`：游戏配置表 Erlang 模块及二次加工生成逻辑。
|
||
- `base`：公共基础库，包含网络、HTTP、日志、计时器、进程、JSON、排行榜、工具函数等通用能力。
|
||
|
||
项目依赖 `ranch`、`cowboy`、`ibrowse`、`mysql_poolboy`、`jsx`、`gpb`、`recon`、`ms_cache`、`ms_tbllog` 等库，并使用多个本地 rebar3 插件生成缓存、协议、日志表、功能模块模板和配置加工代码。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
.
|
||
+-- apps/
|
||
| +-- base/ # 公共基础库
|
||
| +-- game_config/ # 游戏配置与配置生成结果
|
||
| +-- game_proto/ # proto 协议与生成结果
|
||
| +-- game_server/ # 核心游戏服
|
||
| +-- login_server/ # 登录服
|
||
| +-- client_server/ # 压测/客户端模拟服
|
||
+-- config/ # 根 profile 使用的 sys/vm 配置模板
|
||
+-- shell/ # 开发、生成、SQL、发布、热更等脚本
|
||
+-- _checkouts/ # 本地依赖与 rebar3 插件
|
||
+-- rebar.config # 根构建配置、profiles、release 配置
|
||
+-- rebar.config.script # shell/compile 时动态生成私有配置
|
||
```
|
||
|
||
## Rebar Profiles
|
||
|
||
根 `rebar.config` 定义了几个主要 profile：
|
||
|
||
| Profile | 说明 | 编译 app |
|
||
| --- | --- | --- |
|
||
| `game_server` | 游戏服 release/shell | `base`、`game_config`、`game_proto`、`game_server` |
|
||
| `login_server` | 登录服 release/shell | `base`、`login_server` |
|
||
| `client_server` | 压测/客户端模拟服 | `base`、`game_config`、`game_proto`、`client_server` |
|
||
| `config_check` | 配置表加工/校验 | `game_config` |
|
||
|
||
`rebar.config.script` 会在 `compile` 和 `shell` 时按本机 IP 尾段推导默认 `server_id`，并在 `config_priv/` 下生成私有运行配置，例如：
|
||
|
||
- `config_priv/sys_game_<server_id>.config`
|
||
- `config_priv/sys_login_<server_id>.config`
|
||
- `config_priv/sys_client_<server_id>.config`
|
||
|
||
这些私有配置会覆盖开发开关、GM 开关、数据库名、端口等运行参数。若 `config/` 模板更新后已有 `config_priv/` 文件较旧，脚本会提示手动同步或删除后重新生成。
|
||
|
||
## 快速开始
|
||
|
||
前置要求：
|
||
|
||
- Erlang/OTP
|
||
- rebar3
|
||
- MySQL 或项目配置中指定的数据库环境
|
||
- Windows 下建议使用 PowerShell/Cygwin；Linux 下可直接使用 shell 脚本
|
||
|
||
编译：
|
||
|
||
```bash
|
||
rebar3 as game_server compile
|
||
rebar3 as login_server compile
|
||
rebar3 as client_server compile
|
||
```
|
||
|
||
启动开发 shell：
|
||
|
||
```bash
|
||
rebar3 as game_server shell
|
||
rebar3 as login_server shell
|
||
rebar3 as client_server shell
|
||
```
|
||
|
||
指定多游戏服实例时，可在 profile 名后追加 `_<server_id>`：
|
||
|
||
```bash
|
||
rebar3 as game_server_901 shell
|
||
rebar3 as game_server_902 shell
|
||
```
|
||
|
||
动态 profile 会基于 `game_server` profile 复制配置，并把端口调整为：
|
||
|
||
- TCP：`18000 + server_id`
|
||
- HTTP：`19000 + server_id`
|
||
|
||
## 发布构建
|
||
|
||
生成 release：
|
||
|
||
```bash
|
||
rebar3 as game_server release
|
||
rebar3 as login_server release
|
||
rebar3 as client_server release
|
||
```
|
||
|
||
打包 release：
|
||
|
||
```bash
|
||
rebar3 as game_server tar
|
||
rebar3 as login_server tar
|
||
rebar3 as client_server tar
|
||
```
|
||
|
||
发布产物位于：
|
||
|
||
```text
|
||
_build/<profile>/rel/<profile>/
|
||
```
|
||
|
||
`relx` overlay 会把对应的 `sys.config`、`vm.args`、SQL 文件、定时任务配置等复制到 release 目录。
|
||
|
||
## 配置说明
|
||
|
||
根目录 `config/` 放置通用配置模板：
|
||
|
||
- `sys_game.config` / `vm_game.args`：游戏服运行配置
|
||
- `sys_login.config` / `vm_login.args`：登录服运行配置
|
||
- `sys_client.config` / `vm_client.args`：压测/客户端模拟服配置
|
||
- `cron_game.tab`：游戏服定时任务配置
|
||
|
||
常见关注项：
|
||
|
||
- 游戏服：`server_id`、`server_name`、`tcp_port`、`http_port`、`login_node`、`center_node`、开服时间、GM/开发/内网开关。
|
||
- 登录服：`server_env`、`login_node_port`、日志配置、缓存/数据库配置。
|
||
- 客户端模拟服：目标游戏服 `host/tcp_port`、登录服地址、测试模块列表。
|
||
- `ms_cache` / `ms_tbllog`：缓存与日志表落库配置。
|
||
|
||
注意：本地敏感参数不要写进 README。需要变更数据库、节点名、端口时，优先修改私有配置或部署环境配置。
|
||
|
||
## 自动生成内容
|
||
|
||
编译前会自动执行以下 provider hook：
|
||
|
||
```erlang
|
||
protobuf compile
|
||
cache compile
|
||
cfg_modify gen
|
||
user_default compile
|
||
```
|
||
|
||
主要生成物包括：
|
||
|
||
- `apps/game_proto/src/auto_gen/`：由 `apps/game_proto/proto/*.proto` 生成的 Erlang 协议模块。
|
||
- `apps/game_proto/include/`：协议头文件。
|
||
- `apps/game_config/src/auto_gen/`：由 `game_cfg` 与 `modify` 加工后的配置模块。
|
||
- `apps/*/src/auto_gen/cache/` 与 `include/auto_gen/cache/`：由 `cache/*.table` 生成的缓存访问模块和头文件。
|
||
- `apps/game_server/src/auto_gen/user_default/`：shell 辅助函数。
|
||
|
||
常用生成命令也可以通过 `shell/gen.sh` 中的函数执行：
|
||
|
||
```bash
|
||
rebar3 protobuf compile
|
||
rebar3 cache compile
|
||
rebar3 tbllog compile
|
||
rebar3 cfg_modify gen
|
||
rebar3 gen_mod compile -m <module_name>
|
||
```
|
||
|
||
## 核心运行流程
|
||
|
||
### game_server
|
||
|
||
`game_server_app:start/2` 的启动流程大致为：
|
||
|
||
1. 初始化 logger 与应用环境。
|
||
2. 启动 `game_server_sup`。
|
||
3. 初始化动态 ETS、协议 NIF 缓存、T 后台日志服务和 `ms_cache`。
|
||
4. 启动热更新 reloader、事件服务、业务进程树。
|
||
5. 游戏服类型为 `game_server` 时启动 crontab、HTTP、TCP。
|
||
6. 启动监控服务，注册热更新回调，执行开服后的修复/刷新逻辑。
|
||
|
||
HTTP 路由来自 `fnapi_handler`、`tblapi_handler`、`rccapi_handler`、`api_handler`。TCP 监听由 `ms_network:start_tcp/5` 启动，鉴权模块为 `login_mod`。
|
||
|
||
### login_server
|
||
|
||
`login_server_app:start/2` 的启动流程大致为：
|
||
|
||
1. 初始化 logger 与应用环境。
|
||
2. 启动 `login_server_sup`。
|
||
3. 启动 `ms_cache`。
|
||
4. 启动登录服 HTTP 服务。
|
||
5. 启动登录服业务进程。
|
||
6. 启动热更新 reloader。
|
||
|
||
登录服提供 SDK/API 路由、区服信息、账号登录记录、内部白名单、全服维护、推荐服、合服等管理能力。
|
||
|
||
### client_server
|
||
|
||
`client_server` 是轻量测试/压测服务。配置中指定目标游戏服、登录服和测试模块，启动后通过相关测试模块执行连接与业务验证。
|
||
|
||
## 数据库与 SQL
|
||
|
||
SQL 文件按服务放置：
|
||
|
||
- `apps/game_server/sql/`：游戏库、日志库初始化/合服/升级 SQL。
|
||
- `apps/login_server/sql/`：登录库初始化/合服 SQL。
|
||
|
||
缓存表定义位于：
|
||
|
||
- `apps/game_server/cache/*.table`
|
||
- `apps/login_server/cache/*.table`
|
||
|
||
日志表定义位于：
|
||
|
||
- `apps/game_server/tbllog/*.table`
|
||
|
||
修改 `.table` 后需要重新执行对应生成与编译流程。
|
||
|
||
## 开发约定
|
||
|
||
- 新增游戏功能模块时，优先参考 `apps/game_server/templates/mod/`，或使用 `rebar3 gen_mod compile -m <module_name>` 生成模板。
|
||
- 业务模块通常按 `<module>_mod`、`<module>_lib`、`<module>_data`、`<module>_check`、`<module>_network`、`<module>_log` 拆分。
|
||
- 协议变更放在 `apps/game_proto/proto/`，生成后再更新对应 network/mod 处理逻辑。
|
||
- 配置表变更放在 `apps/game_config/src/game_cfg/`，需要二次加工时在 `apps/game_config/src/modify/` 增加对应模块。
|
||
- 缓存结构变更优先修改 `.table`，由插件生成 record、访问模块和 SQL/prepare 列表。
|
||
|
||
## 运维脚本
|
||
|
||
`shell/` 下提供若干辅助脚本：
|
||
|
||
- `dev.sh`：开发工具主入口，会加载 `config.sh` 以及生成、SQL、服务、SVN 相关脚本。
|
||
- `gen.sh`：生成协议、缓存、日志表、功能模板等。
|
||
- `sql.sh`：数据库相关操作。
|
||
- `srv.sh`：本地/内网服务启停相关操作。
|
||
- `server.sh`：发布、重启、热更、全量包/升级包生成。
|
||
|
||
这些脚本包含环境路径、账号、部署目录等强环境绑定参数，使用前应先检查 `shell/config.sh` 和脚本头部配置。
|
||
|
||
## 常见命令
|
||
|
||
```bash
|
||
# 清理
|
||
rebar3 clean
|
||
|
||
# 编译游戏服
|
||
rebar3 as game_server compile
|
||
|
||
# 启动游戏服 shell
|
||
rebar3 as game_server shell
|
||
|
||
# 启动指定 server_id 的游戏服 shell
|
||
rebar3 as game_server_901 shell
|
||
|
||
# 编译登录服
|
||
rebar3 as login_server compile
|
||
|
||
# 启动登录服 shell
|
||
rebar3 as login_server shell
|
||
|
||
# 配置检查
|
||
rebar3 as config_check compile
|
||
|
||
# 生成 release
|
||
rebar3 as game_server release
|
||
|
||
# 打 tar 包
|
||
rebar3 as game_server tar
|
||
```
|
||
|
||
## 排查建议
|
||
|
||
- 启动失败先看 `log/error.log`、`log/info.log`、`log/http_info.log`。
|
||
- 如果私有配置与模板不一致，删除对应 `config_priv/sys_*_<server_id>.config` 后重新执行 compile/shell 生成。
|
||
- 如果协议或配置表模块缺失，先执行 `rebar3 clean` 后重新 `rebar3 as <profile> compile`。
|
||
- 如果数据库连接失败，检查 `ms_cache`、`ms_tbllog` 配置以及目标数据库是否已执行初始化 SQL。
|
||
- 如果端口冲突，检查 `server_id` 推导值和 `tcp_port/http_port` 是否与其他实例重复。
|