# Gate 节点说明

## 节点定位
- 作为外部客户端的统一接入网关，维护长连接与心跳
- 负责登录鉴权、限速控制、协议白名单校验
- 根据会话中记录的节点信息，将请求路由到 Game / Map 等后端节点
- 维护玩家与网关连接的缓存，支持跨节点推送与踢人

## 启动流程
- 入口：[gate.go](./gate.go)
- 基于 Cherry 框架配置并启动节点：
  - ConfigureNode：以 Cluster 模式启动，开启网关特性（第二个参数为 true）
  - cherryApp.Init：初始化全局应用对象、加载配置
  - 注册组件：
    - GOPS：运维诊断
    - 配置中心：SDK、ProtoRoute、RateLimiter、Lua
    - Redis 客户端：GUID、Center
    - Rate 限速组件
  - 注册 Actor：sessions.NewActor(false)
  - initApp：设置网关专用的网络解析器（UserActorParser）
  - Startup：启动网络监听与消息循环

## 用户解析 Actor（UserActorParser）
- 文件：[user/actor.go](./user/actor.go)
- 角色：作为网关上的核心解析器，负责客户端数据流转、心跳、路由与节点同步。
- 初始化逻辑：
  - 在 OnInit 中注册远程接口：
    - User_PlayerPush：由后端节点向玩家推送消息
    - User_PlayerKick：由后端节点控制玩家下线
  - 初始化状态码：预先序列化“重复登录”“未登录”等错误码字节，便于快速踢线
  - 初始化心跳：从配置读取网关心跳超时时间，注册 Heartbeat 包处理
  - 初始化新连接回调：每个新连接创建一个子 Actor（actorAgent）负责该连接的会话与登录
  - 注册数据包路由函数：OnDataRoute，用于处理客户端所有业务消息
  - 初始化节点路由函数：为 Game / Map 等节点注册路由策略
  - 初始化节点同步函数：在 Session 变更或连接关闭时同步到目标 Game / Map 节点
  - 注册网络连接器：当前使用 TCP 监听 cherryApp.App().Address()

## 会话子 Actor（actorAgent）
- 文件：[user/actor_agent.go](./user/actor_agent.go)
- 角色：与单个 pomelo.Agent 一一对应，负责该连接上的登录流程、Session 设置、同步与关闭处理。
- 核心逻辑：
  - Login 流程：
    - 校验基础参数与 debug 模式下的 GameNodeID
    - validateToken：解析并校验登录 token（PID、OpenID、签名等）
    - 从 SDK 配置表中获取渠道信息，校验 PID 合法性
    - 调用 Center 节点（CenterPlayer）根据 PID / OpenID 获取 UID
    - 调用 checkNodeState 确认目标 Game 节点可用（在线人数、维护状态、白名单等）
    - 通过 pomelo.Bind 将 UID 与当前会话绑定，如存在旧会话则踢出
    - 在 Session 中记录 GameNodeID、PID、OpenID 等字段
    - 返回 UserLoginResponse，包含 UID、PID、OpenID、GameNodeID 及扩展参数
  - SetSession：
    - 根据传入的 StrStrList 动态设置 / 删除 Session 键值
    - 调用 cache.UpdateAgent 刷新玩家在缓存中的映射
    - 遍历需要同步的键，按 key 查找对应 SyncFunc（例如 game / map），推送 Session 到对应节点
  - OnSessionClose：
    - 从缓存中移除 Agent
    - 调用所有 SyncFunc 执行解绑逻辑（包括 Redis 中的 session 数据）
    - 清理自身引用并退出 Actor

## 数据路由与限速
- OnDataRoute（user/actor.go）
  - 构建 Session 并打印调试日志（可选）
  - 协议路由白名单校验：使用 data.ProtoRoute 限制可访问的路由
  - 限速控制：优先基于 UID，其次基于 IP 调用 rate.Check
  - 登录状态检查：未绑定 UID 且不是 GateUser_Login，则立即踢下线
  - 本地路由：当当前节点类型与目标 route.NodeType 相同时，构造 ChildPath，通过 LocalDataRoute 将请求转发给本节点内部 Actor
  - 远端路由前的检查：
    - 再次确认 Session 已绑定 UID
    - 对除 GameLogin_Enter 外的路由，要求 Session 中已经存在 PlayerID
  - 节点路由：根据 NodeType（Game / Map）获取 routeFunc，完成真正的集群路由

## 节点路由函数
- 文件：[user/route.go](./user/route.go)
- Game 节点路由（gameNodeRoute）：
  - 从 Session 中获取绑定的 GameNodeID，不存在则踢下线
  - 通过 ClusterLocalDataRoute 将消息发送到对应 Game 节点
- Map 节点路由（mapNodeRoute）：
  - 仅在角色已进入游戏（GameLogin_Enter）后才能访问
  - 从 Session 中获取 MapNodeID，若为空则返回 NodeMapNodeIDIsEmpty
  - 使用服务发现（Discovery）检查目标 Map 节点是否存在，不存在则返回 NodeMapIsClosed
  - 否则通过 ClusterLocalDataRoute 转发消息
- 节点状态检查（checkNodeState）：
  - 调用目标节点上的 Ops_CheckNodeState，用 UID 与 IP 进行校验
  - 根据返回值或错误决定节点是否可进入，统一映射为 NodeIsClosed / NodeMapIsClosed 等错误码

## 会话同步（Sessions Sync）
- 文件：[user/sync.go](./user/sync.go)
- sync2Game：
  - 从 Session 中取 GameNodeID 与 PlayerID
  - 当 isBind 为 true：
    - 将 Session 写入 Redis（SendRedisBind）
    - 向 Game 节点的 GateSessions Actor 发送 Sessions_Bind
  - 当 isBind 为 false：
    - 删除 Redis 中的 Session 映射（SendRedisUnbind）
    - 向 Game 节点发送 Sessions_Unbind（携带 PlayerID）
- sync2Map：
  - 与 Game 类似，只是目标节点为 Map 节点，并不涉及 Redis 写入

## 网关缓存（Agent Cache）
- 文件：[cache/cache.go](./cache/cache.go)
- 数据结构：
  - playerAgentsMap：playerID → Agent
  - gameAgentsMap：gameNodeID → {playerID → Agent}
  - mapAgentsMap：mapNodeID → {playerID → Agent}
- UpdateAgent：
  - 根据 Session 中的 PlayerID / GameNodeID / MapNodeID 更新三张映射表
  - 方便后续按玩家、按 Game 节点、按 Map 节点批量推送消息或踢人
- RemoveAgent：
  - 在连接关闭时，从上述三张映射表中删除对应记录

## 推送与踢人
- playerPush（user/actor.go）
  - 支持按玩家、按 Game 节点、按 Map 节点三种模式推送：
    - Player：根据 I64List 中的 playerID 从 playerAgentsMap 中找到 Agent 逐个 Push
    - GameNode：根据 GameNodeID 找到对应 gameAgentsMap 后遍历 Push
    - MapNode：根据 MapNodeID 找到对应 mapAgentsMap 后遍历 Push
- playerKick（user/actor.go）
  - 可按 FilterNodeIDS 过滤当前 Gate 节点
  - 支持按玩家、按 Game 节点、按 UID、按 Map 节点踢人：
    - Player：从 playerAgentsMap 中查找并 Kick
    - GameNode/MapNode：按节点维度批量 Kick
    - UID：通过 pomelo.GetAgentWithUID 获取 Agent 后 Kick

## 典型调用流程
- 登录流程
  - 客户端连接 Gate，网关创建 pomelo.Agent 与 actorAgent
  - 客户端发起登录请求（User_Login，本地路由到 actorAgent.login）
  - 网关校验 token、SDK 配置、获取 UID，检查 Game 节点状态
  - 绑定 UID 与 Session，记录 GameNodeID / PID / OpenID
  - 向客户端返回 UserLoginResponse，同时通过 SetSession / Sync 将会话同步到 Game 节点
- 业务路由
  - 客户端发送业务协议
  - OnDataRoute 完成路由白名单、限速、登录状态检查
  - 根据 Session 中记录的 GameNodeID / MapNodeID，将请求路由到对应节点

## 设计目标
- 高吞吐：通过轻量级网关、会话分片 Actor 与缓存结构提升并发能力
- 安全性：统一的 token 验证、协议白名单、限速策略
- 一致性：通过 Redis + Sessions_Bind/Unbind 保证 Game 节点的会话感知与状态同步
- 可扩展性：节点路由、同步函数、缓存结构均可扩展新的节点类型或业务需求