【源码分析】pomelo源码分析

源码： https://github.com/NetEase/pomelo

定位

维度	说明
名称	Pomelo — fast, scalable game server framework for Node.js
作者	网易（NetEase）
版本	2.2.7（2019）
协议	MIT
核心思想	多进程 + 单线程 分布式架构，约定优于配置

架构

核心技术栈

类别	技术/依赖	用途
运行时	Node.js	单线程事件驱动
网络协议	pomelo-protocol	自定义二进制协议
序列化	pomelo-protobuf	Protobuf 编解码
压缩	Dictionary 组件	路由/消息字典压缩
RPC	pomelo-rpc（MQTT 协议）	跨进程服务调用
连接层	HybridConnector / SIO / UDP / MQTT	多协议接入
WebSocket	ws	原生 WebSocket
Socket.IO	socket.io 1.7.2	浏览器长连接
日志	pomelo-logger（log4js）	分级日志
调度	pomelo-scheduler	Cron 定时任务
管理	pomelo-admin	运维控制台
模块加载	pomelo-loader	Handler/Remote 自动加载
异步	async	串行/并行流程控制
队列	seq-queue	串行化请求（serial filter）
CLI	commander + cliff	命令行工具

创建并运行项目

# 1. 全局安装 CLI
npm install pomelo -g

# 2. 初始化项目（生成 game-server + web-server 模板）
pomelo init mygame

# 3. 安装依赖
cd mygame && sh npm-install.sh   # Linux/Mac
# 或 npm-install.bat             # Windows

# 4. 启动游戏服务器
cd game-server
pomelo start

# 5. 启动 Web 静态资源服务器（可选）
cd ../web-server
node app.js

## 常用 CLI 命令

命令	作用
pomelo init [path]	创建新项目
pomelo start	启动全部/指定服务器
pomelo start -e production	指定环境
pomelo start -D	后台守护进程
pomelo start -t connector -i connector-server-1	启动指定类型/ID
pomelo list	查看在线服务器
pomelo add	动态添加服务器
pomelo stop	停止服务器
pomelo restart	重启服务器
pomelo kill	强制杀进程

## 关键配置文件

game-server/
├── app.js                    # 入口：createApp() + configure() + start()
├── config/
│   ├── master.json           # Master 地址（默认 3005）
│   ├── servers.json          # 各类型服务器列表
│   ├── log4js.json           # 日志配置
│   ├── serverProtos.json     # 服务端 Protobuf 定义
│   ├── clientProtos.json     # 客户端 Protobuf 定义
│   └── dictionary.json         # 路由压缩字典
└── app/servers/
    └── connector/
        └── handler/
            └── entryHandler.js  # 路由处理：connector.entryHandler.entry

源码分析大纲

第一层：入口与CLI

序号	文件	分析要点
1.1	lib/index.js	导出入口
1.2	lib/pomelo.js	createApp()、组件/Filter/Connector 懒加载
1.3	bin/pomelo	CLI：init/start/stop/list/add/restart/kill/masterha
1.4	lib/modules/console.js	项目初始化脚手架逻辑

第二层：Application核心

序号	文件	分析要点
2.1	lib/application.js	应用单例、状态机、configure/load/filter/start/stop
2.2	lib/util/appUtil.js	配置加载、默认组件装配、生命周期
2.3	lib/util/constants.js	路径、关键字、生命周期常量
2.4	lib/util/pathUtil.js	Handler/Remote/Cron 路径解析
2.5	lib/util/moduleUtil.js	Admin 模块注册与加载
2.6	lib/util/events.js	框架事件定义

第三层：Master与进程管理

序号	文件	分析要点
3.1	lib/master/master.js	Master 启动、服务器注册、断线重连、自动重启
3.2	lib/master/starter.js	fork/spawn 子进程、CPU 绑定
3.3	lib/master/watchdog.js	进程守护
3.4	lib/components/master.js	Master 组件封装
3.5	lib/monitor/monitor.js	监控上报
3.6	lib/components/monitor.js	Monitor 组件

第四层：网络连接层（Connector）

序号	文件	分析要点
4.1	lib/components/connector.js	连接组件：握手、Session 绑定、加解密
4.2	lib/connectors/hybridconnector.js	TCP + WebSocket 混合连接器（默认）
4.3	lib/connectors/hybrid/switcher.js	协议切换
4.4	lib/connectors/hybrid/tcpprocessor.js	TCP 处理
4.5	lib/connectors/hybrid/wsprocessor.js	WebSocket 处理
4.6	lib/connectors/sioconnector.js	Socket.IO 连接器
4.7	lib/connectors/udpconnector.js	UDP 连接器
4.8	lib/connectors/mqttconnector.js	MQTT 连接器
4.9	lib/connectors/commands/handshake.js	握手协议
4.10	lib/connectors/commands/heartbeat.js	心跳保活
4.11	lib/connectors/commands/kick.js	踢人逻辑
4.12	lib/connectors/common/coder.js	编解码

第五层：请求处理链路

序号	文件	分析要点
5.1	lib/components/server.js	Server 组件入口
5.2	lib/server/server.js	消息路由、Filter 链、Handler 分发、Cron
5.3	lib/common/service/handlerService.js	按 serverType.handler.method 路由
5.4	lib/common/service/filterService.js	before/after 过滤器链
5.5	lib/filters/handler/timeout.js	请求超时
5.6	lib/filters/handler/serial.js	同 Session 串行
5.7	lib/filters/handler/toobusy.js	过载保护
5.8	lib/filters/handler/time.js	耗时统计

第六层：Session与连接管理

序号	文件	分析要点
6.1	lib/components/session.js	前端 Session
6.2	lib/components/backendSession.js	后端 Session（跨服共享）
6.3	lib/components/connection.js	连接管理
6.4	lib/common/service/sessionService.js	Session CRUD、绑定 uid
6.5	lib/common/service/connectionService.js	连接池管理
6.6	lib/common/service/backendSessionService.js	后端 Session 服务