概述

本文档描述了基于 WebSocket 的游戏客户端架构，包括网络连接、账号认证和游戏服登录的完整流程。

网络架构

架构概览

整个系统采用三层架构设计：

┌─────────────────┐    WebSocket     ┌─────────────────┐      TCP        ┌─────────────────┐
│   sconn-client  │ ───────────────► │     goscon      │ ──────────────► │     skyext      │
│  (Game Client)  │                  │   (Gateway)     │                 │  (Game Server)  │
└─────────────────┘                  └─────────────────┘                 └─────────────────┘

组件说明

• sconn-client: TypeScript 游戏客户端，负责与用户交互和网络通信
• goscon: 游戏服务器网关，负责协议转换（WebSocket ↔ TCP）
• skyext: 游戏服务器，处理游戏逻辑和数据存储

通信协议

所有组件间的通信均使用 sproto RPC 协议进行数据交换。

登录流程

流程概览

登录过程分为两个主要阶段：

1. 账号登录 - 通过第三方平台或本地账号获取认证令牌
2. 游戏服登录 - 使用令牌连接游戏服务器

完整登录架构图

┌─────────────┐                    ┌─────────────┐
│   Client    │                    │  GamePass   │
│(phaser-game)│                    │(Auth Center)│
└──────┬──────┘                    └──────┬──────┘
       │                                  │
       │ 1. HTTP Account Login            │
       │ ──────────────────────────────►  │
       │                                  │
       │ 2. Return jwt-token              │
       │ ◄──────────────────────────────  │
       │                                  │
       │                                  │
┌──────▼──────┐    WebSocket/sproto      ┌─────────────┐      TCP/sproto     ┌─────────────┐
│   Client    │ ─────────────────────►   │   goscon    │ ──────────────────► │   skyext    │
│             │ 3. Game Login(jwt-token) │             │ 4. Forward Request  │             │
│             │ ◄─────────────────────   │             │ ◄────────────────── │             │
└─────────────┘    5. Login Response     └─────────────┘    Login Response   └─────────────┘

账号登录详细流程

第三方登录（GitHub 示例）

┌─────────────┐                 ┌─────────────┐                 ┌─────────────┐
│   Client    │                 │  GamePass   │                 │   GitHub    │
└──────┬──────┘                 └──────┬──────┘                 └──────┬──────┘
       │                               │                               │
       │ 1. Click Login Link           │                               │
       │ GET /auth/github              │                               │
       │ ────────────────────────────► │                               │
       │                               │                               │
       │ 2. Redirect to GitHub OAuth   │                               │
       │ ◄──────────────────────────── │ 3. OAuth Authorization        │
       │                               │ ────────────────────────────► │
       │                               │                               │
       │ 4. User Authorization         │                               │
       │ ───────────────────────────────────────────────────────────── │
       │                               │                               │
       │                               │ 5. Authorization Code         │
       │                               │ ◄──────────────────────────── │
       │                               │                               │
       │ 6. Redirect to Client         │                               │
       │    with jwt-token             │                               │
       │ ◄──────────────────────────── │                               │
       │                               │                               │

登录 URL 格式：

http://localhost:3180/auth/github?callback_url=http://localhost:8080

成功回调 URL 格式：

http://localhost:8080?access_token=jwt-token

游戏服登录详细流程

时序图

Client          goscon          skyext
  │                │               │
  │ 1. WebSocket   │               │
  │   Connection   │               │
  │ ─────────────► │               │
  │                │               │
  │ 2. Send Login  │ 3. Convert to │
  │   Request      │   TCP Forward │
  │ ─────────────► │ ────────────► │
  │                │               │
  │                │ 4. Verify     │
  │                │   Token &     │
  │                │   Process     │
  │                │               │
  │                │ 5. Return     │
  │ 6. Convert to  │   Login       │
  │   WebSocket    │   Result      │
  │ ◄───────────── │ ◄──────────── │
  │                │               │

登录协议定义

.context {
    rid 0 : integer         # role id 用于跳过选角色步骤直接登录角色
    proto_checksum 1 : string # 协议文件 checksum
}

# 登录协议
login 101 {
    request {
        token 0 : string    # JWT token，包含账号信息
        ctx 1 : context     # 上下文信息
    }
    response {
        code 0 : integer    # 响应码 (0: 成功, 其他: 错误码)
        account 1 : string  # 账号标识
        gamenode 2 : string # 需要连接的游戏节点标识
    }
}

响应码说明

响应码	说明
0	登录成功
1001	Token 无效
1002	Token 过期
1003	服务器维护中
1004	角色不存在

后续通信

成功登录游戏服后，客户端与服务器之间的所有通信都遵循 sproto RPC 协议规范：

• 请求格式: 使用 sproto 定义的消息结构
• 响应格式: 对应的 sproto 响应消息
• 传输层: WebSocket (Client ↔ goscon) + TCP (goscon ↔ skyext)

相关项目链接

组件	描述	仓库地址
skyext	游戏服务器	https://github.com/hanxi/skyext
sconn-client	TypeScript 客户端	https://github.com/hanxi/sconn-client
goscon	网关服务	https://github.com/hanxi/goscon
gamepass	账号中心	https://github.com/hanxi/gamepass
client	Phaser 游戏客户端	https://github.com/hanxi/phaser-game

技术栈

• 前端: TypeScript + Phaser.js
• 通信协议: sproto RPC
• 网络传输: WebSocket + TCP
• 认证: JWT Token
• 第三方登录: OAuth 2.0 (GitHub 等平台)