How is gt_ai_gateway's architecture designed?

详细分析这个 repo 的架构设计

完美！现在我有了足够的信息来提供一份全面的架构分析。让我生成详细的分析文档：

##📐 GT AI Gateway 架构设计详细分析

这是一个高度模块化、多运行模式支持的 AI 网关系统。让我为你详细分析其架构设计。

###1. 整体架构概览

┌─────────────────────────────────────────────────────────────┐
│                     运行模式 (4种)                           │
├─────────────────────────────────────────────────────────────┤
│ ① Serverless (Cloudflare Workers) | ② Docker 部署           │
│ ③ 桌面应用 (Tauri)              | ④ Node 源码运行          │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    分层架构 (3层)                             │
├──────────────────────┬──────────────────┬──────────────────┤
│   前端层 (Vue 3)     │   API层 (Hono)   │  核心服务层      │
├──────────────────────┼──────────────────┼──────────────────┤
│ • 管理界面           │ • 路由管理       │ • 请求转发       │
│ • 流量可视化         │ • 中间件系统     │ • 协议转换       │
│ • 数据分析           │ • 错误处理       │ • 用户管理       │
│                      │ • 认证授权       │ • 计费统计       │
└──────────────────────┴──────────────────┴──────────────────┘

###2. 后端核心架构

####2.1 分层设计

请求流 ↓
┌─────────────────────────────────────┐
│      路由层 (routes.ts)              │
│  • /llm/v1/chat/completions        │
│  • /llm/v1/messages                │
│  • /llm/v1/responses               │
└──────────┬──────────────────────────┘
           ▼
┌─────────────────────────────────────┐
│      中间件层 (middleware/)           │
│  • 认证中间件 (authMiddleware)      │
│  • CORS中间件 (corsMiddleware)      │
│  • 数据库中间件 (dbMiddleware)      │
│  • 全局错误处理                      │
└──────────┬──────────────────────────┘
           ▼
┌─────────────────────────────────────┐
│     控制器层 (controller/)            │
│  • gatewayController (核心逻辑)     │
│  • userController                   │
│  • vendorController                 │
│  • modelController                  │
│  • recordController                 │
└──────────┬──────────────────────────┘
           ▼
┌─────────────────────────────────────┐
│      服务层 (service/)               │
│  • senderService (请求发送)         │
│  • pluginService (插件系统)         │
│  • userService                      │
│  • vendorService                    │
│  • recordService (日志记录)         │
│  • ormService (数据库操作)          │
└──────────┬──────────────────────────┘
           ▼
┌─────────────────────────────────────┐
│      模型层 (model/)                 │
│  • SgRecord (请求记录)              │
│  • SgUser (用户)                    │
│  • SgVendor (供应商)                │
│  • SgModel (模型配置)               │
│  • SgVendorModel                    │
└──────────┬──────────────────────────┘
           ▼
┌─────────────────────────────────────┐
│       数据层 (Database)              │
│  • SQLite (Node/Docker)            │
│  • Cloudflare D1 (Serverless)      │
└─────────────────────────────────────┘

####2.2 关键组件详解

① 协议转换系统 (Protocol Converter)

客户端请求 (Protocol A)
        ▼
┌─────────────────────────────────────┐
│   ConverterFactory                  │
│   根据 clientFormat 和 upstream     │
│   Format 创建转换器                 │
└──────────┬──────────────────────────┘
           ▼
┌──────────────────────────┬──────────────────────┐
│   请求转换 (Request)     │   响应转换 (Response)│
├──────────────────────────┼──────────────────────┤
│ • OpenAI → Anthropic    │ • Anthropic → OpenAI│
│ • OpenAI → Responses    │ • Responses → OpenAI│
│ • Anthropic → Responses │ • Responses → Anthro│
└──────────┬───────────────┴──────────┬───────────┘
           ▼                          ▼
     转换后请求                   转换后响应
        ▼
   上游API调用
        ▼
    原始响应

核心转换器实现：

• OpenAIToAnthropicConverter: OpenAI → Anthropic
• AnthropicToOpenAIConverter: Anthropic → OpenAI
• ResponsesToAnthropicConverter: Responses → Anthropic
• AnthropicToResponsesConverter: Anthropic → Responses

② 请求改写插件系统

原始请求体
    ▼
┌────────────────────────┐
│  Plugin 1: CCH Rewriter │  (清理 claude-code 缓存标记)
│  enable: configurable   │
└────────┬───────────────┘
         ▼
┌────────────────────────────────────────┐
│ Plugin 2: Claude Code Tracking Rewriter│  (清除追踪标记)
│ enable: configurable                   │
└────────┬───────────────────────────────┘
         ▼
┌────────────────────────────────┐
│ Plugin 3: Responses PromptCache │  (注入缓存key)
│ enable: configurable            │
└────────┬───────────────────────┘
         ▼
    最终请求体 → 上游

③ 请求日志系统 (Record Service)

请求发送 ─→ 初始化记录 (status: init)
             ▼
          转换请求
             ▼
          发送上游 (status: processing)
             ▼
          接收响应
             ▼
          解析Usage ─┐
             ▼      │
          计费      ◄─┘
             ▼
          更新用户余额
             ▼
       返回给客户端 (status: success/failed)
             ▼
       异步保存完整日志 (background task)

④ 请求发送流程 (senderService)

gatewayController 收到请求
             ▼
       1. 认证用户
             ▼
       2. 获取模型配置
             ▼
       3. 获取供应商配置
             ▼
       4. 解析上游格式
             ▼
       5. 创建协议转换器
             ▼
       6. 转换请求体
             ▼
       7. 应用改写插件
             ▼
       8. 发送上游请求
             ▼
       9. 处理SSE流式响应
             ▼
      10. 转换响应数据
             ▼
      11. 计算成本 & 更新余额
             ▼
      12. 记录请求日志
             ▼
      13. 返回客户端

###3. 前端架构

Vue 3 应用 (frontend/src)
├── api/
│   ├── vendorApi.ts       (供应商API)
│   ├── modelApi.ts        (模型API)
│   ├── userApi.ts         (用户API)
│   ├── recordApi.ts       (记录API)
│   └── ...
├── views/
│   ├── VendorView         (供应商管理)
│   ├── ModelView          (模型管理)
│   ├── UserView           (用户管理)
│   ├── RecordView         (请求记录)
│   └── DashboardView      (数据分析)
├── stores/
│   └── (Pinia状态管理)
├── composables/
│   └── (逻辑复用)
└── components/
    └── (UI组件)

技术栈：

• 框架: Vue 3 + TypeScript
• 路由: Vue Router 5
• 状态管理: Pinia
• UI组件库: Ant Design Vue
• HTTP客户端: Axios
• 构建工具: Vite
• 桌面支持: Tauri v2

###4. 数据库设计

核心数据表：

-- 用户表
table: users
├── id (PK)
├── name
├── token (认证令牌)
├── type (normal/admin)
├── status (active/disabled)
├── balance (余额)
└── timestamps (created_at, updated_at)

-- 供应商表
table: vendors
├── id (PK)
├── name (供应商名称)
├── type (openai/anthropic/etc)
├── api_key
├── base_url
└── supported_formats (json)

-- 供应商模型表
table: vendor_models
├── id (PK)
├── vendor_id (FK)
├── name (模型名称)
├── supported_formats (json)
└── config (json)

-- 模型表 (用户模型映射)
table: models
├── id (PK)
├── name (对外暴露的模型名)
├── vendor_id (FK)
├── vendor_model_name (上游模型名)
├── prices (json: {input, output, cache_read})
└── plugins (json: 改写插件配置)

-- 请求记录表
table: records
├── id (PK)
├── user_id (FK)
├── model_id (FK)
├── vendor_id (FK)
├── vendor_model_name
├── client_format (openai/anthropic/responses)
├── upstream_format
├── request_data (json)
├── response_data (json)
├── usage (json: {prompt_tokens, completion_tokens, ...})
├── cost (计算成本)
├── status (init/processing/success/failed)
├── first_token_latency (毫秒)
├── start_at, end_at
└── timestamps

-- 充值记录表
table: recharge_records
├── id (PK)
├── user_id (FK)
├── amount
└── created_at

###5. 运行模式对比

###6. 关键设计亮点

####6.1 多协议兼容性

支持的协议转换矩阵:
                OpenAI    Anthropic   Responses
OpenAI            ✓           ✓           ✓
Anthropic         ✓           ✓           ✓
Responses         ✓           ✓           ✓

关键支持:
✓ 完美支持 SSE 流式响应
✓ 完美支持 Tool calling (函数调用)
✓ 完美支持 多模态视觉 (图片)

####6.2 零维护数据库架构

不同运行模式下的数据库适配:

Worker Mode:
  Env.DB (Cloudflare D1)
      ▼
  D1Adapter
      ▼
  knex-cloudflare-d1
      ▼
  SQL语句 ──→ D1 API

Node Mode:
  better-sqlite3
      ▼
  SQLiteAdapter
      ▼
  sutando (ORM)
      ▼
  本地文件: ./data/local.db
      ▼
  立即执行

跨请求D1连接池修复：

• 每个Worker请求有独立的I/O上下文
• 绕过连接池缓存，每次请求直接返回当前env.DB
• 在dbMiddleware中更新D1 binding

####6.3 灵活的身份验证体系

用户类型:
├── ROOT    (超级管理员，环保通过ROOT_TOKEN)
├── ADMIN   (管理员，可管理其他用户)
└── NORMAL  (普通用户，只能调用API)

Token认证流程:
Authorization: Bearer sk-xxx
        ▼
提取token
        ▼
查询数据库或ROOT_TOKEN
        ▼
验证用户存在 & 未禁用
        ▼
获取用户权限级别

####6.4 成本精细化控制

计费流程:
1. 模型配置中定义价格
   prices: {
     input: 0.01 / 1000,      // 每1000 input tokens 的成本
     output: 0.03 / 1000,     // 每1000 output tokens 的成本
     cache_read: 0.001 / 1000 // 缓存读取成本（claude专用）
   }

2. 从上游响应中解析Usage
   ├── prompt_tokens
   ├── completion_tokens
   └── cache_read_tokens (claude)

3. 计算成本
   cost = 
     (prompt_tokens - cache_read) * input_price +
     cache_read * cache_read_price +
     completion_tokens * output_price

4. 更新用户余额
   user.balance -= cost

5. 异步保存记录
   SgRecord.insert({
     usage, cost, status, ...
   })

###7. 安全性设计

认证层:
├── ROOT_TOKEN (环境变量配置)
├── 用户Token (数据库存储)
└── Bearer验证 (HTTP header)

授权层:
├── Admin检查 (authMiddleware.requireAdmin)
├── User检查 (authMiddleware校验)
└── 配额限制 (用户balance检查)

隐私保护:
├── Claude Code 隐私追踪清理
│   └── 移除时间戳、地区、时区信息
├── CCH 缓存标记重写
│   └── 最大化缓存命中率 (0% → 97%)
└── 敏感数据加密存储 (API Key)

请求验证:
├── Token格式检查
├── 用户状态检查 (active/disabled)
├── 模型存在性检查
├── 供应商存在性检查
└── 余额充足检查

###8. 性能优化

1. 流式响应 (SSE)
   ├── 实时数据推送
   ├── 减少首字符延迟
   └── 节省内存 (不缓存完整响应)

2. 异步日志记录
   ├── runInBackground() 非阻塞保存
   └── 不影响API响应时间

3. 缓存系统
   ├── configService 缓存配置
   ├── 支持cache清除 (/test/cache/clear)
   └── 降低数据库查询频率

4. 数据库连接池
   ├── Worker: 每请求更新D1 binding
   ├── Node: better-sqlite3 单文件
   └── 无额外网络往返

5. 批量查询
   ├── userController.getUsersByIds
   ├── vendorModelController.getVendorModelsByIds
   └── 减少查询次数

###9. 可观测性 & 调试

内置功能:
├── 完整请求/响应日志
│   ├── 原始JSON数据
│   ├── 协议转换过程
│   ├── Token使用统计
│   ├── 成本计算过程
│   └── 首字符延迟测量
├── Web管理界面
│   ├── 请求记录查询 & 过滤
│   ├── 单条请求深度排查
│   ├── 可视化流量分析
│   └── 用户/模型/成本统计
├── 仪表盘
│   ├── 实时统计
│   ├── 成功率
│   ├── 缓存命中率
│   └── 成本分析
└── 日志文件
    ├── Node: ./data/log/
    └── Docker: /app/data/log/

###10. 扩展性设计

易扩展的部分:

1. 新增协议支持
   ├── 创建 XxxToYyyConverter.ts
   ├── 继承 BaseConverter
   ├── 在 ConverterFactory 注册
   └── 无需修改其他代码

2. 新增供应商
   ├── config/vendorDefaultUrls.json (预设)
   ├── Post /vendor/create.json (动态添加)
   └── 前端会自动刷新列表

3. 新增插件
   ├── src/plugin/ 目录
   ├── 实现改写逻辑
   ├── pluginService 集成
   └── 动态启用/禁用

4. 新增控制器 & 路由
   ├── 实现 Controller
   ├── routes.ts 中注册
   ├── 认证中间件配置
   └── 前端API对接

###总结

GT AI Gateway 的架构设计具有以下特点：

✅ 高度模块化: 分离式层次结构，各组件职责明确 ✅ 多运行模式: Serverless/Docker/Desktop/Node，一套代码多种部署 ✅ 强大协议转换: 内置4种主流AI API的完美互转 ✅ 零维护数据库: 使用轻量级SQLite和D1，无需额外依赖 ✅ 灵活的插件系统: 支持请求改写，优化缓存命中率 ✅ 完整的日志系统: 全量记录、可视化分析、深度排查 ✅ 精细化计费: 支持多维度的成本控制 ✅ 安全与隐私: 多层认证、敏感数据处理、隐私清洁

这是一个轻量但功能完整的生产级网关系统。