
---

# Token运营平台技术方案（基于New API改造）

## 1. 方案定位与设计原则

本次建设基于开源New API项目进行深度改造，目标是在最短周期内构建一个具备生产级能力的Token运营平台。整体设计遵循以下原则：

- **复用优先，适度改造**：充分利用New API已有的通道管理、API Key生成、调用路由等核心能力，避免重复造轮子，仅对不足部分进行增强替换。
- **多租户隔离内置**：从设计之初将企业租户、部门、角色的多级隔离体系融入权限与数据链路，而非后期外挂。
- **运营与数据并重**：平台不仅满足调用、管控、计费等运营闭环，同时将数据埋点、合规标识、回流接口作为一等公民设计，为后续数据集治理奠定基础。
- **可观测与可审计**：全链路调用日志、操作审计日志、费用明细三者联动，确保每一笔Token消耗和每一次配置变更均可追溯。
- **平滑演进**：预留私有化模型接入、数据集系统对接、更多计费策略等扩展点，支撑后续从V1.0到V2.0的迭代。

---

## 2. 整体技术架构

### 2.1 架构分层

平台采用分层架构，各层职责清晰、依赖单向，便于独立迭代与横向扩展：

| 层级 | 说明 |
|---|---|
| **接入层** | 对外提供统一HTTP API（兼容OpenAI格式），对内负责鉴权、限流、路由转发至对应模型通道 |
| **业务服务层** | 承载核心业务逻辑，包括模型管理、定价计算、配额校验、费用核算、日志记录、埋点采集等 |
| **权限控制层** | 基于RBAC+租户隔离的权限模型，贯穿所有业务操作，控制数据可见性与操作边界 |
| **数据访问层** | 对数据库、缓存、消息队列的统一抽象，提供分库分表、读写分离的能力基础 |
| **基础设施层** | 底层存储（关系型数据库、时序数据库、对象存储）、缓存（Redis）、消息中间件、容器运行环境 |

### 2.2 逻辑架构视图

- **管理端**：面向平台超级管理员、运营管理员，提供渠道、模型、租户、全局看板等管理功能。
- **企业端/用户端**：面向企业租户管理员及普通员工，提供本企业/个人维度的用户管理、API Key管理、用量查看、看板等功能。
- **核心调度引擎**：基于New API改造的模型路由与负载均衡模块，负责多通道Key轮询、优先级调度、故障自动剔除与恢复。
- **数据埋点与回流模块**：与主业务流程解耦，采用异步方式记录全场景字段，并通过预留接口供数据集系统拉取。

### 2.3 部署架构

- 采用容器化部署（Kubernetes），支持水平弹性扩缩容。
- 微服务拆分：将权限、计费、日志等相对独立的能力沉淀为独立服务，便于复用。
- 多环境隔离：开发、测试、预发布、生产环境独立部署，配置分离。
- 数据存储：业务库使用MySQL（分库分表），日志与调用明细使用ClickHouse或ElasticSearch以支撑高效检索与聚合。

---

## 3. 核心模块划分与职责

| 模块 | 职责 | 与New API的关系 |
|---|---|---|
| **渠道接入与调度模块** | 管理模型厂商通道配置、API Key池、轮询策略、优先级、熔断降级；兼容DeepSeek、通义、智谱、文心等主流厂商，预留私有化接入点 | **重度改造**：New API已有基础，但需增加健康检查、自动禁用恢复、权重调度等能力 |
| **模型定价与计费模块** | 维护模型元数据（版本、上下文窗口）、全局基准单价；根据实际调用Token量实时计算费用，支持多维度费用汇总 | **新增**：New API无此能力 |
| **多租户与权限管控模块** | 实现平台级、企业级、个人级三层权限隔离；控制菜单可见性、数据行级过滤、操作能力边界 | **新增**：需从零构建完整的RBAC+租户体系 |
| **企业管理模块** | 管理企业资质、部门结构、员工账号；支持批量导入、状态冻结/启用、密码重置等操作 | **新增** |
| **API Key全生命周期管理** | 支持用户创建、配额限制、模型白名单、过期时间、密钥脱敏展示、禁用/启用等管理能力 | **增强**：New API支持基础Key生成，需新增配额、模型限制、脱敏等能力 |
| **调用日志与审计模块** | 记录每次调用的完整上下文（时间、用户、模型、Token、费用、状态、响应时长等），同时记录后台所有配置变更操作日志 | **新增**：New API仅有简单日志 |
| **统计分析看板** | 提供全局、企业、个人多层级看板，聚合展示调用量、Token消耗、费用趋势、热门模型、异常分布等关键指标 | **新增** |
| **数据集埋点与回流接口模块** | 在调用链路中采集完整上下文信息（业务来源、知识引用、文件、问数、用户反馈等），落库并预留数据集拉取接口 | **新增** |
| **数据合规标记模块** | 对每条调用记录标注敏感级别、是否脱敏、是否可入库、是否可训练、是否可导出等合规标签 | **新增** |

---

## 4. 权限体系设计

权限体系采用 **“平台 — 企业 — 个人”** 三层模型，结合角色赋予操作权限，通过数据行级权限控制实现严格的租户隔离。

### 4.1 角色定义

| 角色 | 权限范围 | 数据范围 |
|---|---|---|
| 平台超级管理员 | 全功能操作（渠道、模型、租户、用户、全部看板、全部日志） | 全平台数据 |
| 平台运营管理员 | 仅全局查看（看板、日志、数据集回流配置），无增删改操作 | 全平台数据（只读） |
| 企业租户管理员 | 本企业内用户管理、API Key管理、本企业用量查看、企业内部日志 | 仅限所属企业数据 |
| 普通员工 | 个人API Key管理、个人用量查看、个人调用日志 | 仅限本人数据 |

### 4.2 权限控制方式

- **功能权限**：基于角色+菜单/按钮资源配置，前端控制展示，后端强制校验。
- **数据权限**：所有查询接口自动追加租户过滤条件（企业ID/部门ID/用户ID），确保跨租户数据不可见。
- **接口鉴权**：后台管理接口采用JWT+RBAC，API调用采用API Key+配额/模型策略校验。

---

## 5. 数据模型与数据链路设计

### 5.1 核心实体关系

- **租户维度**：企业（租户） → 部门 → 员工（用户）
- **权限维度**：用户 → 角色 → 权限（功能+数据范围）
- **调用维度**：API Key → 调用记录 → Token消耗明细 → 费用明细
- **模型维度**：渠道 → 模型 → 定价策略
- **埋点维度**：调用记录（1） → 扩展埋点信息（业务场景、知识引用、文件、问数、用户反馈等）

### 5.2 数据流转链路

```mermaid
flowchart LR
    A[用户发起调用] --> B[API Key鉴权&配额校验]
    B --> C[模型路由与负载均衡]
    C --> D[调用上游模型通道]
    D --> E[返回结果&Token计费]
    E --> F[同步写入调用日志]
    F --> G[异步写入埋点明细]
    G --> H[实时统计聚合]
    F --> I[审计日志记录]
    H --> J[看板展示]
    G --> K[预留数据集回流接口]
    K --> L[数据集系统采集]
```

### 5.3 数据分层存储策略

| 数据类型 | 存储方案 | 说明 |
|---|---|---|
| 核心业务数据（企业、用户、模型、定价、API Key） | MySQL（分库分表） | 强一致性要求，事务性操作 |
| 调用日志与埋点明细 | ClickHouse / ElasticSearch | 海量写入，高效时序查询与全文检索 |
| 运营看板聚合数据 | Redis缓存 + 定时物化视图 | 提升大屏展示与高频查询性能 |
| 操作审计日志 | MySQL + 归档 | 合规保留，支持长期审计 |

---

## 6. 关键流程设计

### 6.1 模型调用流程（含埋点）

1. 用户通过API Key发起请求，网关层拦截并解析请求。
2. 校验API Key有效性、配额剩余、模型白名单、过期时间。
3. 根据请求模型匹配对应渠道，按照轮询/优先级策略选取可用通道Key。
4. 转发请求至上游模型厂商，记录开始时间。
5. 接收响应后计算输入/输出Token数量，依据定价策略核算费用。
6. 同步记录调用日志（基础字段），异步写入埋点明细（业务上下文、引用、文件、反馈等）。
7. 更新用户配额与费用汇总数据。
8. 若调用失败，触发重试或故障剔除策略，并记录错误码。

### 6.2 配额与费用核算流程

- **实时扣减**：每次调用成功后实时扣减用户配额（按企业/个人配置），并记录流水。
- **定时汇总**：每日定时任务按企业、部门、用户、模型维度汇总Token消耗与费用，生成对账报表。
- **预警机制**：当配额剩余低于阈值时，支持配置告警通知。

### 6.3 数据集埋点采集流程

- **异步解耦**：调用结束后，将埋点数据发送至消息队列（Kafka/RocketMQ），由独立消费者处理写入，不阻塞主调用链路。
- **合规标记**：在写入埋点数据时，根据配置规则自动添加合规标识（敏感级别、是否可入库、是否可用于训练等）。
- **接口预留**：提供标准HTTP接口供数据集系统按时间范围拉取增量埋点数据，支持分页与断点续传。

---

## 7. 技术选型建议

| 组件 | 选型建议 | 理由 |
|---|---|---|
| 后端框架 | Go（推荐）或Java Spring Boot | New API原为Go实现，若团队对Go熟练可保持技术栈一致；若Java生态更成熟可迁移至Spring Boot |
| 数据库 | MySQL（业务主库）+ TiDB（可选） | 支持分库分表，满足租户数据隔离与扩展 |
| 日志/时序存储 | ClickHouse / ElasticSearch | 支持海量日志写入与快速聚合查询 |
| 缓存 | Redis | 缓存定价配置、配额、渠道Key池，提升调用性能 |
| 消息队列 | Kafka / RocketMQ | 解耦埋点写入，保证削峰填谷 |
| 部署编排 | Kubernetes + Istio（可选） | 支持弹性伸缩、灰度发布与服务治理 |
| 监控告警 | Prometheus + Grafana | 监控平台运行状态与调用SLA |

---

## 8. 扩展性设计

- **模型接入扩展**：渠道管理采用可插拔适配器模式，新增厂商仅需实现标准接口，无需改动核心调度逻辑。
- **计费策略扩展**：预留多套定价模型接口（如按模型、按时段、按企业协议价），支持后续灵活切换。
- **数据集回流扩展**：接口设计遵循分页+增量时间戳模式，支持后续切换为消息推送或Binlog同步方式。
- **国际化扩展**：预留多语言资源配置，支持后续国际化部署。

---

## 9. 非功能性设计考量

| 维度 | 设计措施 |
|---|---|
| **性能** | 调用链路关键环节使用缓存；日志/埋点异步写入；数据库读写分离；支持水平扩容 |
| **可用性** | 核心服务多实例部署；下游模型通道故障自动剔除与恢复；关键数据定期备份 |
| **安全性** | API Key脱敏展示；传输层TLS加密；敏感日志脱敏存储；操作审计全记录 |
| **可维护性** | 统一日志规范；全链路Trace ID贯穿；模块化设计便于独立升级 |
| **数据合规** | 内置合规标识体系；支持数据导出审批流程；满足数据分级分类管理要求 |

---

## 10. 分阶段演进策略

| 阶段 | 重点目标 |
|---|---|
| V1.0（当前） | 基于New API改造完成平台核心运营能力、权限体系、埋点规范与回流接口预留，满足内部试用与对外演示 |
| V1.1（后续） | 增强数据集采集能力，对接数据集系统的清洗、脱敏、标注、入库流水线，实现自动化数据沉淀 |
| V2.0（远期） | 引入更多模型计费策略、智能路由（基于成本/延迟/质量）、企业级SLA保障、开放API网关能力 |

---
