游戏服务器框架pomelo基础详解

一 . pomelo 介绍

pomelo是一个游戏服务器框架，与以往单进程的游戏框架不同, 它是高性能、高可伸缩、分布式多进程的游戏服务器框架，并且使用很简单。它包括基础开发框架和一系列相关工具和库，可以帮助开发者省去游戏开发中枯燥的重复劳动和底层逻辑工作，免除开发者的重造轮子，让开发者可以更多地去关注游戏的具体逻辑，大大提高开发效率。pomelo强大的可伸缩性和灵活性使得pomelo也可以作为通用的分布式实时应用开发框架，用于一些高实时应用的开发，而且pomelo在很多方面的表现甚至超越了现有的开源实时应用框架。pomelo支持所有主流平台的客户端，并提供了客户端的开发库，使得客户端的开发变得很友好。

二 . pomelo 的组成

1.框架：是pomelo最核心的部分
2.库：pomelo提供了很多库，有些是跟游戏逻辑完全相关的，如AI，AOI，寻路等；也有与游戏逻辑无关但比较通用的，如定时任务执行， 数据同步等等；
3.工具：pomelo提供了服务器管理控制工具、命令行工具、压力测试工具等一系列工具；
4.客户端库：pomelo提供了各类平台的客户端开发库，包括js, C, C#，Android, iOS, Unity3D等等，几乎支持涵盖了目前所有的主流平台，由于pomelo的协议是开放的，架构耦合松散，对于没有支持的客户端平台，用户也可以很容易地开发出自己需要的库，定制自己的通信协议；
5.一个框架需要强大的demo来展示功能并为开发者提供示例，pomelo提供了全平台的聊天demo和基于HTML5的捡宝demo，系统还提供了一个强大的基于HTML5开发的MMO游戏demoLordofpomelo（源码）。

三 . pomelo 的优点

高并发、高实时的游戏服务器的开发是很复杂的工作。跟web应用一样， 一个好的开源容器或开发框架可以大大减少游戏服务器开发的复杂性，让开发变得更加容易。pomelo的优势有以下几点：

1.可伸缩性好
采用多进程单线程的运行架构，扩展服务器非常方便， node.js的网络io优势提供了高可伸缩性，写好的应用只需要简单地修改一下配置就能轻松地伸缩扩充；

2. 易用
pomelo基于轻量级的nodejs，其开发模型与web应用的开发类似，基于convention over configuration的理念， 几乎零配置， api的设计也很精简，很容易上手，开发快速；

3.框架的松耦合和可扩展性好
遵循node.js微模块的原则， 框架本身只有很少的代码，所有component、库、工具都可以用npm module的形式扩展进来，任何第三方都可以根据自己的需要开发自定义module，并把它整合到pomelo的框架中。

4.完整的中英文文档
pomelo提供了完整的中英文文档，pomelo还提供一个完整的开源MMO游戏，个超过1万行代码的游戏demo，使开发者可以随时借鉴demo的设计与开发思路。

四 . pomelo 的使用范围

pomelo是一个轻量级的服务器框架，它最适合的应用领域是网页游戏、社交游戏、移动游戏的服务端，开发者会发现pomelo可以用如此少的代码达到强大的扩展性和伸缩性。当然还不仅仅是游戏，用pomelo开发高实时web应用也如此合适， 而且伸缩性比其它框架好。

五 . pomelo 安装

pomelo是基于Node.js的，目前pomelo已经完全支持Windows、Linux、Mac等多种平台;

1 . 安装前准备工作
1.确保你的机器可以上网,因为安装pomelo的过程需要从网上下载其依赖的包。
2.确保你的系统上已经要安装了Node。
3.确保你的系统中安装有python(2.5 < version < 3.0)以及C++的编译器。

2 . 安装pomelo

安装node.js可以使用npm命令进行安装pomelo,我这里使用的是windos系统；

npm install pomelo -g
其中-g表示全局安装，安装时将命令行工具安装到bin目录下
pomelo --version
查询安装的版本

六 . pomelo的命令工具

命令行工具pomelo是Pomelo框架提供的一个小工具，该工具能够帮助开发者更便捷、更有效率地进行应用开发。该工具包括的命令支持绝大多数的应用开发操作，包括创建初始项目、启动应用、停止应用、关闭应用等。

1 . pomelo命令：init
init: 创建一个新项目，该项目中包含创建pomelo应用的基本文件及pomelo应用的简单示例。支持相对路径和绝对路径。默认情况下为当前路径，项目名称为当前文件夹名称。

pomelo init [dirname] 命令格式

在创建新项目时，需要选择新项目使用的与客户端通信时使用的connector，1代表Websocket(native socket)，2代表 socket.io。

2.pomelo命令：start
start: 启动应用及服务器。

pomelo start [-e,–env ] [-d,–directory ] [-D,–daemon] 命令格式

其中，-e 用来选择启动时使用的env，如production，development，stress-test等; -d 用来指定项目目录； -D 用来开启daemon模式启动，如果开启了daemon，那么进程将转入后台运行, 所有的日志将不再打印到console上，只能通过对应的日志文件查看日志。

3 . pomelo 命令：list

list: 列出当前应用开启的所有服务器的信息，包括服务器Id、服务器类型、pid、堆使用情况、启动时长。

pomelo list [-u,–username ] [-p,–password ] [-h,–host ] [-P,–port ] 命令格式

当应用启动后，该命令列出所有服务器信息。由于当执行此操作时，pomelo是作为监控管理框架的一个客户端的，在连接注册到master上的时候，需要进行身份验证。默认生成的项目中，有一个默认的用户名admin，口令也为admin，因此在不指定用户名和口令的时候，默认使用的用户名和口令均为admin，下面的stop命令和kill命令均需要使用用户名和口令验证，默认值与此处相同。应用的管理用户可以通过修改config/adminUser.json文件进行配置；
执行本命令时，还需要指定master服务器的ip和port, 这样可以是的pomelo list可以在任意地方执行。pomelo stop/kill/add等也同样需要指定master服务器的ip和port，默认使用127.0.0.1:3005作为master服务器的地址。

4 . pomelo命令：stop

stop: 关闭应用及服务器或者停止指定的服务器。

pomelo stop [-u,–username ] [-p,–password ] [-h,–host ] [-P,–port ] […] 命令格式

stop用来停止当前应用，优雅地关闭应用。和kill命令不同，这种关闭首先会切断客户端与服务器的连接，然后逐一关闭所有服务器。如果指定了服务器serverId的话，则会关闭特定的服务器，而不是关闭所有的服务器。与list命令一样，需要权限验证，默认的用户名和密码均为admin,也需要指定master服务器的位置, 跟pomelo list一样，默认使用127.0.0.1:3005。

5 . pomelo命令：kill
该命令需在项目的根目录或game-server下使用;
kill: 强制关闭应用及服务器。

pomelo kill [-u,–username ] [-p,–password ] [-h,–host ] [-P,–port ] [-f,–force]

该命令强制关闭应用。在本地进行应用开发过程中，如果遇到kill之后还有服务器进程没有关闭的情况，可以增加–force选项，强制关闭所有服务器进程。该操作相当地暴力，可能产生数据丢失等不好的影响，可以在开发调试时使用，不推荐在线上使用该命令。该命令同样也需要进行身份验证以及指定master服务器的位置，具体方式同list和stop。

6 . pomelo命令：add

add: 运行时动态添加服务器。pomelo add也需要身份验证以及指定master服务器的地址。

pomelo add [-u,–username ] [-p,–password ] [-h,–host ] [-P,–port ] […]

args参数是用来指定新增服务器的参数的，包括服务器类型，服务器id等， 支持一次增加一台或多台同类型的服务器；示例如下：

pomelo add host=127.0.0.1 port=8000++ clientPort=9000++ frontend=true clusterCount=3 serverType=connector
pomelo add host=127.0.0.1 port=8000 clientPort=9000 frontend=true serverType=connector id=added-connector-server

7 . pomelo命令：masterha

masterha: 当启用masterha高可用的时候，用来启动master服务器的slave节点。需要在game-server/config目录下配置masterha.json。其他的命令行参数类似于pomelo start；

pomelo masterha [-d,–direcotry ]

8 . pomelo其他命令
–version：列出当前使用pomelo的版本信息。
–help：列出所有pomelo支持的命令及使用说明。

七 . pomelo的术语解释

1 . gate服务器
一个应用的gate服务器，一般不参与rpc调用，也就是说其配置项里可以没有port字段，仅仅有clientPort字段，它的作用是做前端的负载均衡。客户端往往首先向gate服务器发出请求，gate会给客户端分配具体的connector服务器。具体的分配策略一般是根据客户端的某一个key做hash得到connector的id，这样就可以实现各个connector服务器的负载均衡。

2 . connector服务器
connector服务器接收客户端的连接请求，创建与客户端的连接，维护客户端的session信息。同时，接收客户端对后端服务器的请求，按照用户配置的路由策略，将请求路由给具体的后端服务器。当后端服务器处理完请求或者需要给客户端推送消息的时候，connector服务器同样会扮演一个中间角色，完成对客户端的消息发送。connector服务器会同时拥有clientPort和port，其中clientPort用来监听客户端的连接，port端口用来给后端提供服务。

3 . 应用逻辑服务器
gate服务器和connector服务器又都被称作前端服务器，应用逻辑服务器是后端服务器，它完成实际的应用逻辑，提供服务给客户端，当然客户端的请求是通过前端服务器路由过来的。后端服务器之间也会通过rpc调用而有相互之间的交互。由于后端服务器不会跟客户端直接有连接，因此后端服务器只需监听它提供服务的端口即可。

4 . master服务器
master服务器加载配置文件，通过读取配置文件，启动所配置的服务器集群，并对所有服务器进行管理。

5 . rpc调用
pomelo中使用rpc调用进行进程间通信，在pomelo中rpc调用分为两大类，使用namespace进行区分，namespace为sys的为系统rpc调用，它对用户来说是透明的，目前pomelo中系统rpc调用有：
1.后端服务器向前端服务器请求session信息
2.后端服务器通过channel推送消息时对前端服务器发起的rpc调用
3.前端服务器将用户请求路由给后端服务器时也是sys rpc调用
除了系统rpc调用外，其余的由用户自定义的rpc调用属于user namespace的rpc调用，需要用户自己完成rpc服务端remote的handle代码，并由rpc客户端显式地发起调用

6 . route,touter
route用来标识一个具体服务或者客户端接受服务端推送消息的位置，对服务端来说，其形式一般是…,例如"chat.chatHandler.send", chat就是服务器类型，chatHandler是chat服务器中定义的一个Handler，send则为这个Handler中的一个handle方法。对客户端来说，其路由一般形式为onXXX，当服务端推送消息时，客户端会有相应的回调。 一般来说具体的同类型应用服务器都会有多个，当客户端请求到达后，前端服务器会将用户客户端请求派发到后端服务器，这种派发需要一个路由函数router，可以粗略地认为router就是根据用户的session以及其请求内容，做一些运算后，将其映射到一个具体的应用服务器id。可以通过application的route调用给某一类型的服务器配置其router。如果不配置的话，pomelo框架会使用一个默认的router。pomelo默认的路由函数是使用session里面的uid字段，计算uid字段的crc32校验码，然后用这个校验码作为key，跟同类应用服务器数目取余，得到要路由到的服务器编号。注意这里有一个陷阱，就是如果session没有绑定uid的话，此时uid字段为undefined，可能会造成所有的请求都路由到同一台服务器。所以在实际开发中还是需要自己来配置router。

7 . Channel
channel可以看作是一个玩家id的容器，主要用于需要广播推送消息的场景。可以把某个玩家加入到一个Channel中，当对这个Channel推送消息的时候，所有加入到这个Channel的玩家都会收到推送过来的消息。一个玩家的id可能会被加入到多个Channel中，这样玩家就会收到其加入的Channel推送过来的消息。需要注意的是Channel都是服务器本地的，应用服务器A和B并不会共享Channel，也就是说在服务器A上创建的Channel，只能由服务器A才能给它推送消息。

8 . request, response, notify, push
pomelo中有四种消息类型的消息，分别是request，response，notify和push，客户端发起request到服务器端，服务器端处理后会给其返回响应response;notify是客户端发给服务端的通知，也就是不需要服务端给予回复的请求;push是服务端主动给客户端推送消息的类型。

9 . filter
filter分为before和after两类，每类filter都可以注册多个，形成一个filter链，所有的客户端请求都会经过filter链进行一些处理。before filter会对请求做一些前置处理，如：检查当前玩家是否已登录，打印统计日志等。after filter是进行请求后置处理的地方，如：释放请求上下文的资源，记录请求总耗时等。after filter中不应该再出现修改响应内容的代码，因为在进入after filter前响应就已经被发送给客户端。

10 . handler
handler是实现具体业务逻辑的地方，在请求处理流程中，它位于before filter和after filter之间，handler的接口声明如下：

handler.methodName = function(msg, session, next) {
// …
}

参数含义与before filter类似。handler处理完毕后，如有需要返回给客户端的响应，可以将返回结果封装成js对象，通过next传递给后面流程。

11 . error handler
error handler是一个处理全局异常的地方，可以在error handler中对处理流程中发生的异常进行集中处理，如：统计错误信息，组织异常响应结果等。error handler函数是可选的，格式如下：

app.set(‘errorHandler’, handleFunc);
来向pomelo框架进行注册，函数声明如下：
errorHandler = function(err, msg, resp, session, next) {
// …
}
err是前面流程中发生的异常；resp是前面流程传递过来，需要返回给客户端的响应信息。

12 . component
pomelo 框架是由一些松散耦合的component组成的，每个component完成一些功能。每个component往往有start，afterStart，stop等调用，用来完成生命周期管理。

13 . admin client, monitor, master
monitor运行在各个应用服务器中，它会向master注册自己，向master上报其服务器的信息，当服务器群有变化时，接收master推送来的变化消息，更新其服务器上下文。
master运行在应用服务器中，它会收集整个服务器群的信息，有变化时会将变化推送到各个monitor；同时，master还接受admin client的请求，按照client发出的命令，执行对应的操作。
client独立运行自己的进程，它会发起到master的连接，然后通过对master发出请求或者命令，来管理整个服务器群。

14 . admin module
在pomelo中，module特指服务器监控管理模块，实现的是监控逻辑，比如收集进程状态等。用户在使用时，可以通过application的registerAdmin注册管理模块，实现自己定制的监控管理功能。每一个module中都会定义可选的四种回调函数：

1. masterHandler(agent, msg, cb) 当有应用服务器给master发监控数据时，这个回调函数会由master进程进行回调，完成应用服务器的消息处理;
2. monitorHandler(agent, msg, cb) 当有master请求应用服务器的一些监控信息时，由应用服务器进行回调，完成对master请求的处理;
3. clientHandler(agent, msg, cb）当由管理客户端向master请求服务器群信息时，由master进程进行回调处理客户端的请求。
4. start(cb) 当admin module，注册加载完成后，这个回调会被执行，在这里可以做一些初始化工作。

八 . helloworld项目示例

命令行工具新建一个项目
1.底层通信协议选择websocket，依工作环境而定

2.进入新建文件夹安装依赖包
windos用户使用npm-install.bat
linux用户使用 sh npm-install.sh

2 . 项目目录结构
新建项目目录结构如下：

game-server

game-server是用pomelo框架搭建的游戏服务器，以文件app.js作为入口，运行游戏的所有逻辑和功能。所有游戏逻辑、功能、配置等都在该目录下进行。

app子目录

这个目录下放置所有的游戏服务器代码的地方，用户在这里实现不同类型的服务器，添加对应的Handler，Remote等等

config子目录

game-server下config包括了游戏服务器的所有配置信息。配置信息以JSON文件的格式进行定义，包含有日志、master、server等服务器的配置信息。该目录还可以进行扩展，对数据库配置信息、地图信息和数值表等信息进行定义。

logs子目录

日志是项目中不可或缺的，可以对项目的运行情况进行很好的备份，也是系统运维的参考数据之一，logs存放了游戏服务器所有的日志信息。

shared

shared存放一些前后端、game-server与web-server共用代码，由于都是javascript代码，那么对于一些工具或者算法代码，就可以前后端共用，极大地提高了代码重用性。

web-server

web-server是用express 3.x框架搭建的web服务器，以文件app.js作为入口，当然开发者可以选择Nginx等其他web服务器。如果游戏的客户端不是web的话，如Android平台的话，这个目录就不是必须的了。

3 . 启动项目
由于客户端是web，所以必须启动game-server(游戏服务器)和web-server(web服务器)

启动game-server服务器：

启动web-server服务器：

4 . 浏览器测试
在启动过程中可能会有端口号冲突导致启动不成功，只需在config里面修改使用的端口号即可。访问：http://localhost:3001或者 http://127.0.0.1:3001

5 . 查看服务

服务器信息详解：
serverId：服务器的serverId，同config配置表中的id。
serverType：服务器的serverType，同config配置表中的type。
pid：服务器对应的进程pid。
heapUsed：该服务器已经使用的堆大小（单位：兆）。
uptime：该服务器启动时长（单位：分钟）。

6 . 关闭项目
在game-server目录下执行pomelo stop命令

pomelo官方中文参考文档