Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
354 lines (279 loc) · 14.1 KB

ARCHITECTURE.md

File metadata and controls

354 lines (279 loc) · 14.1 KB

Customer-Service 系统架构文档

1. 系统概述

Customer-Service 是途游游戏客服系统的后端服务，基于 Go 语言开发，使用 Gin 框架提供 HTTP REST API 服务。系统负责处理游戏相关的客服工单、用户管理、订单管理、内容审核、通知推送等核心业务。

2. 技术栈

2.1 核心框架

  • 语言: Go 1.x
  • Web框架: Gin (github.com/gin-gonic/gin)
  • ORM: GORM (用于数据库操作)
  • 配置管理: YAML 配置文件
  • 日志: tygit.tuyoo.com/gocomponents/glog

2.2 数据存储

  • 关系型数据库: MySQL
    • 主数据库
    • 分片数据库 (content-lib 子模块)
  • 缓存: Redis
  • 搜索: Elasticsearch (pkg/es)
  • 消息队列: Kafka (content-lib/tykafka)
  • 文档数据库: MongoDB (部分业务)

2.3 协议与通信

  • API 协议: HTTP/HTTPS RESTful API
  • RPC: Protobuf (使用 protoc 生成代码)
  • 消息推送: WebSocket
  • 外部服务集成: HTTP REST

2.4 开发工具

  • API文档: Swagger (swaggo/gin-swagger)
  • 代码生成: protobuf (protoc), swagger 注解
  • 构建工具: Makefile
  • 容器化: Docker

3. 系统架构

3.1 整体架构图

┌─────────────────────────────────────────────────────────────┐
│                         客户端层                             │
│  (Web管理后台, 游戏客户端, 微信公众号, 第三方调用)                │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       中间件层                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │   JWT    │ │   CORS   │ │  权限验证 │ │ 限流控制   │       │
│  │  认证     │ │  跨域    │ │          │ │          │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ 签名验证 │ │行为记录  │ │恢复处理  │ │请求体限制 │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       API 路由层                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Admin    │ │  Game    │ │  Work    │ │  VIP     │       │
│  │  用户管理 │ │  游戏管理 │ │  工单    │ │ 会员管理 │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Order    │ │  Pay     │ │  Email   │ │ Content  │       │
│  │ 订单管理  │ │  支付    │ │ 邮件服务 │ │ 内容审核 │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       业务服务层                             │
│  (internal/service/*)                                        │
│  - 业务逻辑处理                                               │
│  - 数据转换与验证                                             │
│  - 调用DAO层进行数据操作                                       │
│  - 调用外部服务集成                                           │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       数据访问层                             │
│  (internal/dao/*)                                            │
│  - 数据库CRUD操作                                             │
│  - 复杂查询封装                                               │
│  - 事务管理                                                   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       数据模型层                             │
│  (internal/model/*)                                           │
│  - 数据库表结构映射                                           │
│  - 业务实体定义                                               │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       存储层                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │  MySQL   │ │  Redis   │ │    ES    │ │ MongoDB  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                       外部服务集成                           │
│  (pkg/*)                                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ 游戏服务器 │ │ 邮件服务 │ │ 短信服务 │ │ 呼叫中心 │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ 钉钉集成 │ │ 微信集成 │ │ AI帮助   │ │ 计费系统 │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────┘

3.2 服务启动流程

main.go
  └─> cmd.Execute() [cmd/root.go]
      └─> internal.StartHttpServer() [internal/run.go]
          └─> api.StartServer() [internal/api/server.go]
              ├─> 初始化 Gin 引擎
              ├─> 注册中间件 (Recovery, CORS, JWT, 权限验证等)
              ├─> 注册路由分组
              ├─> 注册各业务服务的 HTTP Handler
              └─> 启动 HTTP 服务器 (端口 8010)

3.3 数据流向

3.3.1 典型请求处理流程

1. 客户端发起 HTTP 请求
   ↓
2. 中间件处理
   - Recovery (异常恢复)
   - CORS (跨域处理)
   - JWT (身份认证)
   - 权限验证 (URL权限 + 项目权限)
   - 行为记录 (LogParams)
   ↓
3. 路由匹配 (Gin Router)
   ↓
4. Service 层处理业务逻辑
   - 参数验证
   - 业务逻辑处理
   - 调用 DAO 层
   - 调用外部服务
   ↓
5. DAO 层数据库操作
   - GORM 查询/更新
   - 事务管理
   ↓
6. 返回响应
   - 数据格式化
   - 错误处理
   - 返回 JSON 响应

3.3.2 Worker 任务处理流程

1. 启动时初始化 Worker Manager (content_audit)
   ↓
2. 从消息队列 (Kafka) 拉取任务
   ↓
3. Worker 处理任务
   - 内容审核
   - 消息推送
   - 邮件发送
   ↓
4. 更新任务状态
   ↓
5. 回调或通知

3.4 核心组件说明

3.4.1 API Server (internal/api)

  • server.go: 主 API 服务器，端口 8010，处理管理后台和游戏客户端请求
  • api.go: 专用 API 服务器，处理特定业务场景的 API 调用

3.4.2 Service 层 (internal/service)

每个业务域都有独立的 service 包，负责：

  • 接收 HTTP 请求参数
  • 执行业务逻辑
  • 调用 DAO 层进行数据操作
  • 调用 pkg 中的外部服务
  • 返回响应结果

3.4.3 DAO 层 (internal/dao)

  • 封装数据库操作
  • 提供 CRUD 方法
  • 处理复杂查询
  • 管理数据库事务

3.4.4 Model 层 (internal/model)

  • 定义数据库表结构
  • 定义业务实体
  • 数据验证规则
  • 关联关系

3.4.5 外部服务集成 (pkg/*)

  • game_server: 游戏服务器 SDK 封装
  • email_server: 邮件发送服务
  • sms: 短信发送服务
  • es: Elasticsearch 操作
  • cticloud: 呼叫中心集成
  • dingtalk: 钉钉通知
  • wechat: 微信公众号集成
  • ai_help_server: AI 客服集成

4. 部署架构

4.1 服务端口

  • 主 API 服务: 8010
  • 健康检查: /health
  • Swagger 文档: /swagger/* (仅开发环境)

4.2 环境配置

  • 开发环境: 本地启动，使用 internal/conf/cfg.yaml
  • 测试环境: Kubernetes 集群部署
  • 生产环境: Kubernetes 集群部署，多副本

4.3 日志管理

  • 日志文件: run/logs/
  • 日志级别: Debug, Info, Warn, Error
  • 日志组件: glog (tygit.tuyoo.com/gocomponents/glog)

4.4 监控与健康检查

  • 健康检查端点: /health
  • 性能分析: 支持 SIGUSR2 信号开启/关闭 pprof

5. 关键业务流程

5.1 工单处理流程

  1. 用户提交工单
  2. 客服人员接单
  3. 处理工单
  4. 关闭工单
  5. 评价工单

5.2 内容审核流程

  1. 内容生成 (游戏内、用户上传)
  2. 提交到审核队列
  3. Worker 拉取任务
  4. 人工审核或机器审核
  5. 审核结果处理 (通过/驳回)
  6. 处罚执行 (如需要)

5.3 通知推送流程

  1. 业务系统触发通知事件
  2. 写入通知表
  3. Worker 轮询或消息队列
  4. 根据配置选择通知方式
  5. 发送通知 (邮件/短信/站内信)

6. 安全机制

6.1 身份认证

  • JWT Token 验证
  • Token 刷新机制
  • 多端登录支持

6.2 权限控制

  • URL 级别权限验证
  • 项目级别权限验证
  • 角色权限管理 (RBAC)

6.3 数据安全

  • 密码加密存储
  • 敏感数据脱敏
  • SQL 注入防护 (GORM 参数化查询)

6.4 接口安全

  • 签名验证 (针对第三方调用)
  • 限流控制 (IP限制、请求频率限制)
  • 请求体大小限制 (最大 100MB)

7. 性能优化

7.1 缓存策略

  • Redis 缓存热点数据
  • 配置数据缓存
  • 会话缓存

7.2 数据库优化

  • 索引优化
  • 查询优化
  • 读写分离 (content-lib 支持分片)

7.3 异步处理

  • Kafka 消息队列
  • Worker 异步任务处理
  • 邮件/短信异步发送

8. 扩展性设计

8.1 模块化设计

  • 各业务模块独立
  • 清晰的层次划分
  • 低耦合高内聚

8.2 插件化

  • 中间件可插拔
  • 外部服务可配置
  • 功能模块可开关

8.3 水平扩展

  • 无状态设计
  • 支持多副本部署
  • 负载均衡友好

9. 相关文档