跳到主要内容

网关系统

网关系统是井云平台的统一入口，负责请求路由、认证、限流、负载均衡等功能，是整个系统对外的统一接口层。

🎯 系统概述​

核心功能​

  • 统一入口: 所有外部请求的统一接入点
  • 路由转发: 根据请求路径转发到对应的后端服务
  • 认证鉴权: JWT Token验证和用户认证
  • 限流熔断: 请求限流和服务熔断保护
  • 负载均衡: 后端服务的负载均衡
  • 错误处理: 统一的错误处理和响应

支持的服务​

  • Auth Service (9001) - 认证服务
  • User Service (9002) - 用户服务
  • Tenant Service (9003) - 租户服务
  • Agent Service (9004) - 智能体服务
  • Payment Service (9006) - 支付服务
  • Integration Service (9007) - 集成服务

服务端口​

  • HTTP服务: 8000
  • gRPC服务: 9000

🏗️ 架构设计​

系统架构​

┌─────────────────────────────────────────┐
│           Gateway Service               │
│         (HTTP: 8000, gRPC: 9000)       │
├─────────────────────────────────────────┤
│  Middleware Layer                       │
│  - Recovery (异常恢复)                  │
│  - Auth (认证鉴权)                      │
│  - CORS (跨域处理)                      │
│  - Tracing (链路追踪)                   │
│  - Logging (日志记录)                   │
├─────────────────────────────────────────┤
│  Service Layer                          │
│  - AuthService                          │
│  - UserService                          │
│  - TenantService                        │
│  - AgentService                         │
│  - PaymentService                       │
│  - IntegrationService                   │
├─────────────────────────────────────────┤
│  Data Layer                             │
│  - gRPC Client                          │
│  - Redis Cache                          │
└─────────────────────────────────────────┘

请求流程​

网关请求处理流程：

  1. 客户端发送请求到网关服务
  2. 网关服务通过认证中间件验证 Token
  3. Token 验证结果：
    • Token 有效 → 路由转发到对应服务
    • Token 无效 → 返回 401 错误
  4. 路由转发到后端服务：
    • 认证服务 (Auth)
    • 用户服务 (User)
    • 租户服务 (Tenant)
    • 智能体服务 (Agent)
    • 支付服务 (Payment)
    • 集成服务 (Integration)
  5. 后端服务处理请求并返回响应
  6. 响应返回到网关服务
  7. 网关服务返回响应给客户端

🔐 认证机制​

JWT Token 验证​

  • Token提取: 从HTTP Header中提取Token
  • 签名验证: 验证Token签名有效性
  • 有效期检查: 检查Token是否过期
  • 用户信息注入: 将用户信息注入到请求上下文

错误码区分​

  • 401 Unauthorized: Token过期，需要重新登录
  • 402 Payment Required: Token无效，需要重新认证
  • 403 Forbidden: 权限不足
  • 404 Not Found: 资源不存在

租户信息传递​

  • TenantID: 从Token或Header中提取租户ID
  • 上下文注入: 将租户ID注入到请求上下文
  • 数据隔离: 确保数据按租户隔离

🚦 中间件​

Recovery (异常恢复)​

  • 功能: 捕获panic并返回500错误
  • 作用: 防止服务崩溃
  • 日志: 记录异常堆栈信息

Auth (认证鉴权)​

  • 功能: 验证JWT Token
  • 作用: 保护需要认证的接口
  • 用户信息: 注入用户和租户信息

CORS (跨域处理)​

  • 功能: 处理跨域请求
  • 配置: 允许的来源、方法和头部
  • 安全: 防止CSRF攻击

Tracing (链路追踪)​

  • 功能: 分布式链路追踪
  • 标准: 遵循OpenTelemetry规范
  • 作用: 便于问题排查和性能分析

Logging (日志记录)​

  • 功能: 记录请求和响应日志
  • 格式: 结构化JSON日志
  • 信息: 包含trace_id、span_id等

📊 监控指标​

关键指标​

  • 请求总数: HTTP/gRPC请求总数
  • 响应时间: 请求响应时间
  • 错误率: 请求错误率
  • QPS: 每秒请求数
  • 并发数: 当前并发连接数

健康检查​

  • HTTP健康检查: /health
  • gRPC健康检查: grpc.health.v1.Health
  • 服务状态: 服务运行状态

🔌 API 服务​

认证服务 (Auth)​

  • SendSMSVerificationCode: 发送短信验证码
  • UserRegister: 用户注册
  • UserLogin: 用户登录
  • ValidateToken: 验证Token
  • SMSLogin: 短信登录
  • WechatLogin: 微信登录

用户服务 (User)​

  • CreateUser: 创建用户
  • UpdateUser: 更新用户信息
  • GetUserInfo: 获取当前用户信息
  • ListUsers: 获取用户列表

租户服务 (Tenant)​

  • CreateTenant: 创建租户
  • GetTenant: 获取租户信息
  • UpdateTenant: 更新租户信息
  • ListTenants: 获取租户列表

智能体服务 (Agent)​

  • CreateAgent: 创建智能体
  • GetAgent: 获取智能体详情
  • ListAgents: 获取智能体列表
  • UpdateAgent: 更新智能体

支付服务 (Payment)​

  • CreateTenantOrder: 创建租户订单
  • WechatPay: 微信支付
  • GetOrder: 获取订单详情

集成服务 (Integration)​

  • GetOSSSignature: 获取OSS签名
  • HandleOSSCallback: 处理OSS回调
  • SendSMS: 发送短信

🔒 安全特性​

认证安全​

  • JWT Token: 无状态Token认证
  • Token刷新: 支持Token刷新机制
  • Token撤销: 登出时撤销Token

防护措施​

  • 限流: 防止API滥用
  • 熔断: 保护后端服务
  • 超时: 请求超时控制

数据安全​

  • HTTPS: 支持HTTPS加密传输
  • 敏感信息: 敏感信息过滤
  • 日志脱敏: 日志信息脱敏

🚀 性能优化​

连接池​

  • gRPC连接池: 复用gRPC连接
  • HTTP连接池: 复用HTTP连接
  • 连接超时: 合理的连接超时设置

缓存​

  • Token缓存: Token验证结果缓存
  • 用户信息缓存: 用户信息缓存
  • Redis: 使用Redis作为缓存

负载均衡​

  • 服务发现: 基于Consul的服务发现
  • 负载均衡: 支持多种负载均衡策略
  • 健康检查: 定期健康检查

🔗 相关文档​