# Token网关

**Repository Path**: micro-plat/token

## Basic Information

- **Project Name**: Token网关
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TOKEN聚合平台

> **TOKEN聚合平台** 是一个大模型 API 聚合网关与运营平台：对下统一接入 OpenAI、Anthropic、DeepSeek、智谱 GLM 等多家上游厂商，对上以统一的域名、密钥与配额体系向客户提供大模型服务，自带 Web 管理控制台，基于 Go 多进程架构部署。

**主要特点**：

- ✅ **四协议统一入口，任意互转**：OpenAI Chat / Responses / Anthropic / Gemini 四种客户端协议原生支持，内置 5 组双向转换器，任意入口 → 任意上游；
- ✅ **上游账号池智能调度**：成本优先选号 + 三轮故障转移 + 429 成本探测，上游账号切换对客户端完全透明；
- ✅ **双层配额体系**：5 小时滚动窗口 + 周配额，以套餐方式管理客户额度、可用模型与有效期；
- ✅ **响应全面脱敏**：上游真实模型名与账号信息绝不外泄，状态码混淆改写；
- ✅ **RTK 上下文压缩**：网关侧透明压缩超长上下文，平均节省 20%~40% token；
- ✅ **多租户隔离**：行级 / Schema 级两种隔离模式，按接入域名自动解析租户；
- ✅ **全维度运营分析**：60+ 字段用量流水 + 6 个内置分析视图，新增报表零代码；
- ✅ **对二次开发友好**：Go 单一二进制、仅依赖 MySQL，全链路数据驱动 + 模块化源码，克隆即建即跑（见第 9 章）。

---

## 目录

- [1. 管理控制台](#1-管理控制台)
  - [1.1 登录与首页](#11-登录与首页)
  - [1.2 左侧导航与底部设置按钮](#12-左侧导航与底部设置按钮)
  - [1.3 一级菜单：客户套餐](#13-一级菜单客户套餐)
  - [1.4 一级菜单：上游配额](#14-一级菜单上游配额)
  - [1.5 一级菜单：数据分析](#15-一级菜单数据分析)
  - [1.6 一级菜单：厂商模型](#16-一级菜单厂商模型)
  - [1.7 一级菜单：资料档案](#17-一级菜单资料档案)
- [2. 平台概述](#2-平台概述)
- [3. 为什么基于本平台做二次开发（同类项目对比）](#3-为什么基于本平台做二次开发同类项目对比)
- [4. 总体架构](#4-总体架构)
- [5. 支持的协议与接口](#5-支持的协议与接口)
  - [5.1 客户端（下游）可用接口](#51-客户端下游可用接口)
  - [5.2 流式与长连接](#52-流式与长连接)
  - [5.3 协议转换矩阵](#53-协议转换矩阵)
  - [5.4 上游厂商接入](#54-上游厂商接入)
- [6. 核心功能详解](#6-核心功能详解)
  - [6.1 客户与密钥管理](#61-客户与密钥管理)
  - [6.2 套餐与配额体系](#62-套餐与配额体系)
  - [6.3 上游账号池与智能调度](#63-上游账号池与智能调度)
  - [6.4 模型映射与响应脱敏](#64-模型映射与响应脱敏)
  - [6.5 RTK 上下文压缩](#65-rtk-上下文压缩)
  - [6.6 多租户体系](#66-多租户体系)
  - [6.7 会话粘性](#67-会话粘性)
  - [6.8 用量统计与审计](#68-用量统计与审计)
- [7. 数据模型（核心表）](#7-数据模型核心表)
- [8. 开发平台与技术生态](#8-开发平台与技术生态)
- [9. 支持二次开发](#9-支持二次开发)
  - [9.1 天生适合二次开发的架构基因](#91-天生适合二次开发的架构基因)
  - [9.2 零代码扩展点（配置与数据级）](#92-零代码扩展点配置与数据级)
  - [9.3 源码级扩展点（模块级）](#93-源码级扩展点模块级)
  - [9.4 二次开发工作流](#94-二次开发工作流)
  - [9.5 典型二次开发场景](#95-典型二次开发场景)
- [10. 构建与部署](#10-构建与部署)
- [11. 二次开发](#11-二次开发)
---

## 1. 管理控制台

管理控制台地址：`http://ai.ismart.xhydra.cn`（登录页见下图）。整体为**动态多页签工作台**：左侧是可收藏的菜单导航，右侧内容区以页签（Tab）组织，所有打开过的页面均以页签保留，可同时切换；一级菜单之间也可通过内容区顶部页签直接互切。对二次开发者而言，控制台同样是一等扩展面——页面按菜单配置动态装配，新增页面只需开发对应组件并挂到菜单配置（见第 9 章）。

### 1.1 登录与首页

**登录页**（账号密码登录：用户名/手机号 + 密码）：

![登录页](docs/screenshots/00-login.png)

**首页**（登录后工作台）：

![首页](docs/screenshots/01-home.png)

### 1.2 左侧导航与底部设置按钮

左侧菜单栏分为"快速访问"与一级功能菜单两组；**菜单栏底部有一个设置按钮，点击后弹出设置菜单**——这是本控制台的导航中枢：

**底部按钮弹出的设置菜单**——快速访问、展开所有、外观（3 种模式）、主题色（6 色）、当前用户与退出登录：

![底部按钮-设置菜单展开](docs/screenshots/10-底部按钮-设置菜单展开.png)

### 1.3 一级菜单：客户套餐

面向运营：管理客户、密钥与客户套餐。

**默认页**（客户列表与套餐视图）：

![客户套餐-默认页](docs/screenshots/14-客户套餐-默认页.png)

**页签：客户套餐**：

![页签-客户套餐](docs/screenshots/15-客户套餐-页签-客户套餐.png)

**页签：客户账户**（`ik-` 密钥、状态机管理）：

![页签-客户账户](docs/screenshots/16-客户套餐-页签-客户账户.png)

**页签：自用-glm-gpt2**（内部自用套餐）：

![页签-自用-glm-gpt2](docs/screenshots/17-客户套餐-页签-自用-glm-gpt2.png)

**页签：智普GLM-1天卡**（500万token/5小时窗口）：

![页签-智普GLM-1天卡](docs/screenshots/18-客户套餐-页签-智普GLM-1-天卡-500-5小时.png)

**页签：智普GLM-3天卡**（500万token/5小时窗口）：

![页签-智普GLM-3天卡](docs/screenshots/19-客户套餐-页签-智普GLM-3-天卡-500-5小时.png)

> 每个客户套餐在侧栏/页签中是独立分组，截图 17~19 展示了具体套餐实例的明细页。

### 1.4 一级菜单：上游配额

面向成本管理：上游账号池、上游套餐与额度探测。

**默认页**：

![上游配额-默认页](docs/screenshots/20-上游配额-默认页.png)

**页签：客户套餐**（跨菜单互切）：

![页签-客户套餐](docs/screenshots/21-上游配额-页签-客户套餐.png)

**页签：上游配额**（各账号剩余额度总览）：

![页签-上游配额](docs/screenshots/22-上游配额-页签-上游配额.png)

**页签：服务账号**（上游账号池维护）：

![页签-服务账号](docs/screenshots/23-上游配额-页签-服务账号.png)

**页签：上游套餐**：

![页签-上游套餐](docs/screenshots/24-上游配额-页签-上游套餐.png)

**页签：额度探测**（429 探测与成本推断记录）：

![页签-额度探测](docs/screenshots/25-上游配额-页签-额度探测.png)

**上游套餐默认视图**（厂商套餐分组）：

![上游套餐-默认](docs/screenshots/48-上游配额-上游套餐-默认.png)

### 1.5 一级菜单：数据分析

面向运营分析：基于用量日志的 6 个分析视图（图表由元数据查询服务渲染）。

**默认页**：

![数据分析-默认页](docs/screenshots/26-数据分析-默认页.png)

**页签：日志分析**（60+ 字段用量流水检索）：

![页签-日志分析](docs/screenshots/30-数据分析-页签-日志分析.png)

**页签：请求会话**（会话维度追踪、粘性路由验证）：

![页签-请求会话](docs/screenshots/31-数据分析-页签-请求会话.png)

**页签：成本分析**（上游成本 vs 客户计费）：

![页签-成本分析](docs/screenshots/32-数据分析-页签-成本分析.png)

**页签：请求分析**（QPS、延迟、首字延迟、错误率）：

![页签-请求分析](docs/screenshots/33-数据分析-页签-请求分析.png)

**页签：账号分析**（账号池健康度与命中率）：

![页签-账号分析](docs/screenshots/34-数据分析-页签-账号分析.png)

**页签：数据分析总览**：

![页签-数据分析](docs/screenshots/29-数据分析-页签-数据分析.png)

**页签：客户套餐**（跨菜单互切）：

![页签-客户套餐](docs/screenshots/27-数据分析-页签-客户套餐.png)

**页签：上游配额**（跨菜单互切）：

![页签-上游配额](docs/screenshots/28-数据分析-页签-上游配额.png)

### 1.6 一级菜单：厂商模型

面向接入管理：厂商与模型台账。

**默认页**：

![厂商模型-默认页](docs/screenshots/35-厂商模型-默认页.png)

**页签：模型厂商**（厂商登记，数据驱动接入）：

![页签-模型厂商](docs/screenshots/40-厂商模型-页签-模型厂商.png)

**页签：模型版本**（模型台账与映射配置）：

![页签-模型版本](docs/screenshots/41-厂商模型-页签-模型版本.png)

**页签：厂商模型总览**：

![页签-厂商模型](docs/screenshots/39-厂商模型-页签-厂商模型.png)

**页签：客户套餐**（跨菜单互切）：

![页签-客户套餐](docs/screenshots/36-厂商模型-页签-客户套餐.png)

**页签：上游配额**（跨菜单互切）：

![页签-上游配额](docs/screenshots/37-厂商模型-页签-上游配额.png)

**页签：数据分析**（跨菜单互切）：

![页签-数据分析](docs/screenshots/38-厂商模型-页签-数据分析.png)

### 1.7 一级菜单：资料档案

面向配置归档：字典、文档类资料的集中管理。

**默认页**：

![资料档案-默认页](docs/screenshots/42-资料档案-默认页.png)

**页签：资料档案**：

![页签-资料档案](docs/screenshots/47-资料档案-页签-资料档案.png)

**页签：客户套餐**（跨菜单互切）：

![页签-客户套餐](docs/screenshots/43-资料档案-页签-客户套餐.png)

**页签：上游配额**（跨菜单互切）：

![页签-上游配额](docs/screenshots/44-资料档案-页签-上游配额.png)

**页签：数据分析**（跨菜单互切）：

![页签-数据分析](docs/screenshots/45-资料档案-页签-数据分析.png)

**页签：厂商模型**（跨菜单互切）：

![页签-厂商模型](docs/screenshots/46-资料档案-页签-厂商模型.png)

---

## 2. 平台概述

TOKEN聚合平台 是一个**大模型 API 聚合网关与运营平台**：对下统一收敛多家上游大模型厂商（OpenAI、Anthropic、DeepSeek、智谱 GLM 等）的服务能力，对上以统一的域名、密钥、协议和配额体系向客户（内部系统与外部租户）提供大模型服务。

平台解决的核心问题：

| 问题 | 平台的解法 |
| --- | --- |
| 多厂商接口协议不一致 | 多协议接入 + 协议自动互转（OpenAI / Anthropic / Gemini 之间任意组合） |
| 上游账号额度有限、单价不一 | 上游账号池管理，按成本优先调度，多轮故障转移自动切换 |
| 客户用量需要精细化控制 | 客户套餐体系，5 小时滚动窗口 + 周配额双重限额 |
| 上游账号、真实模型名不能泄露 | 响应脱敏：隐藏上游模型名、混淆上游状态码 |
| 上下文过长导致 token 浪费 | RTK 上下文压缩，节省 20%~40% token |
| 多客户共用一套部署 | 多租户体系（行级 / Schema 级隔离），按域名自动解析租户 |
| 运营需要量化 | 60+ 字段的用量日志与多维分析报表（日志、请求、会话、成本、账号） |
| 业务持续演进，平台需要定制 | 全链路数据驱动 + 模块化源码，常规变更零代码、深度改造按模块替换（见第 9 章） |

---

## 3. 为什么基于本平台做二次开发（同类项目对比）

选型即选择"二次开发的起点"。社区常见的大模型网关方案有三类：**one-api / new-api**（Go 编写、以 OpenAI 格式统一多厂商的网关）、**LiteLLM**（Python 编写、聚合 100+ 提供商的代理）、**通用 API 网关 + AI 插件**（Kong / APISIX / Higress 等）。下表将本平台与三类方案放在同一维度对比：

| 能力维度 | TOKEN聚合平台 | one-api / new-api | LiteLLM | 通用网关 + AI 插件 |
| --- | --- | --- | --- | --- |
| 技术形态 | Go 单体多进程，单一二进制 | Go 单体 | Python Proxy + SDK | 数据面 + 控制面 + 插件 |
| 外部依赖 | 仅 MySQL | MySQL（Redis 可选） | 完整能力需 Redis + Postgres | etcd / Postgres 等组件 |
| 客户端协议 | OpenAI / Responses / Anthropic / Gemini 四种原生入口 | 以 OpenAI 格式为主 | 统一为 OpenAI 格式 | 以 OpenAI 为主 |
| 协议互转 | 5 组双向转换器，任意入口 → 任意上游 | 基本归一到 OpenAI 出站 | 归一到 OpenAI 出站 | 无 / 有限 |
| 客户配额体系 | 套餐 + 5 小时滚动 + 周配额双层、账户状态机 | 令牌单一额度 | budget / RPM / TPM | 无，需自建 |
| 上游调度 | 成本优先 + 三轮故障转移 + 429 成本探测 | 渠道权重 / 优先级 | fallback + 冷却 | 无 / 插件 |
| 多租户 | 行级 / Schema 级隔离 + 域名解析租户 | 用户 / 令牌级 | 虚拟 key / 团队级 | 网关路由级 |
| 响应脱敏 | 模型名改写 + 状态码混淆 + 字段清洗 | 部分 | 无 | 无 |
| 上下文压缩 | RTK 内置，节省 20%~40% token | 无 | 无 | 无 |
| 运营分析 | 60+ 字段流水 + 6 个内置视图 + 元数据报表（新增报表零代码） | 基础调用日志 | 需自建看板 | 需外接观测栈 |
| 二次开发路径 | 数据驱动 + 模块化源码替换，多数变更零代码 | 以改源码为主 | 配置 + 回调钩子 | 插件体系 |

> 对比基于各项目公开文档与社区版常见形态整理，随版本演进可能变化，选型请以实际验证为准。

**对二次开发者的三点结论**：

1. **相比 fork one-api / new-api**：本平台把运营所需的套餐、双层配额、多租户、脱敏、用量报表做成了内置的数据模型与页面，而不是留给二次开发者补的业务缺口；且厂商、模型映射、套餐、报表、菜单全部落库驱动，多数"新需求"改数据即可上线。
2. **相比基于 LiteLLM 二次开发**：Go 单一二进制仅依赖 MySQL，四个进程独立启停，克隆代码即可 `go build` 本地跑通全链路；没有 Redis / Postgres 等多组件运维负担，私有化交付成本显著更低。
3. **相比通用网关 + AI 插件**：套餐、配额窗口、成本调度、脱敏是"业务语义"而非"流量插件"——本平台把它们沉淀为核心数据表与报表引擎；插件体系补不出这些能力，最终仍需实现一个本平台这样的系统。

---

## 4. 总体架构

平台后端为 **Go 语言单体多进程架构**：一份代码编译出多个服务进程，各自独立启动、互不依赖运行。

| 服务进程 | 端口 / 路径 | 职责 |
| --- | --- | --- |
| **API 网关服务** | `:8099` | 对外大模型 API 统一入口：鉴权、路由、协议转换、流式转发、用量统计、响应脱敏 |
| **Web 管理服务** | `:8098`（路由前缀 `/ak3qw`） | 管理控制台后端：登录认证、菜单、各管理页面的数据查询与维护接口 |
| **CRON 定时任务服务** | — | 8 个周期作业：配额窗口滚动重置、额度探测、统计汇总、过期清理等 |
| **WSS 长连接服务** | `:18080`（路径 `/hydra/wss`） | 承载 WebSocket 长连接通道，服务需要双向长连接的上游与客户端场景 |

技术栈总览：

- **语言与框架**：Go 1.23 + `micro-plat/hydra` v1.3.16 微服务框架（提供路由、配置中心、RPC、cron、集群注册等基础能力）
- **数据库**：MySQL（阿里云 RDS）
- **前端**：Vue 3 + Element Plus 单页应用（动态多页签工作台，见第 1 章）
- **交付形态**：单一二进制文件部署；通过 `dev` / `prod` 构建标签区分开发与生产配置
- **协议层**：HTTP/HTTPS + SSE 流式 + WebSocket（ws/wss）

---

## 5. 支持的协议与接口

### 5.1 客户端（下游）可用接口

客户端只需对接平台域名（如 `http://ai.ismart.xhydra.cn`），即可使用以下任意一种协议风格，**四种协议之间可自由互转**——例如用 OpenAI SDK 调用，实际命中 Anthropic 上游模型。

| 协议风格 | 接口路径 | 说明 |
| --- | --- | --- |
| OpenAI Chat Completions | `/v1/chat/completions` | 兼容 OpenAI SDK / 各类 ChatGPT 客户端，支持流式与非流式 |
| OpenAI Responses | `/v1/responses`、`/v1/responses/compact` | 兼容 OpenAI 新版 Responses API，`compact` 为平台扩展的紧凑响应格式 |
| Anthropic Messages | `/v1/messages`、`/anthropic/v1/messages`、`/v1/messages/count_tokens` | 兼容 Claude SDK 与 Claude Code 等工具；支持 token 预估接口 |
| Google Gemini | `/v1beta/models/:model`（generateContent 等）、`/gemini/v1beta/...` | 兼容 Gemini 原生协议 |
| 模型列表 | `/v1/models` | 返回当前密钥可用的（已映射后的）模型清单 |

### 5.2 流式与长连接

- **SSE 流式响应**：所有对话类接口均支持 `stream: true`，流式会话最长保持 **30 分钟**，超时自动收尾；
- **WebSocket 上游通道**：当上游厂商仅提供 WebSocket 接入时，通过 WSS 服务（`:18080/hydra/wss`）以 ws/wss 方式桥接，对客户端仍呈现标准 HTTP/SSE 接口。

### 5.3 协议转换矩阵

平台内置 5 组双向协议转换器：

```
anthropic ↔ openai          chat ↔ anthropic
responses ↔ anthropic       gemini ↔ openai
gemini ↔ anthropic
```

即：任意"客户端协议 → 任意上游协议"的组合均可转换，请求与响应（含流式分片、工具调用、多模态内容块）逐段翻译。

### 5.4 上游厂商接入

上游厂商完全由数据库驱动（`aigw_model_provider` 表），**无硬编码白名单**——新增厂商只需在管理控制台"模型厂商"页面登记，无需改代码。当前已接入示例：OpenAI、Anthropic、DeepSeek、智谱（GLM）。

> 说明：平台当前不支持 MCP 协议的代理。

---

## 6. 核心功能详解

### 6.1 客户与密钥管理

- 平台向客户签发 **`ik-` 前缀的 API Key**，所有 `/v1/*` 请求凭该密钥鉴权；
- 客户账户具有生命周期状态机：`0-禁用`、`1-启用`、`2-待激活`、`3-已过期`，由 CRON 作业按套餐有效期自动流转；
- 密钥与客户套餐绑定，决定可用模型集合与配额。

### 6.2 套餐与配额体系

- **客户套餐**（`aigw_cust_package`）：面向客户的销售单元，定义可用模型、额度与有效期（如"智普GLM-1天卡-500万token/5小时"、"3天卡"等，见控制台截图 §1.3）；
- **双重限额窗口**：**5 小时滚动窗口** + **周配额**，任一超限即拦截并返回明确错误码；
- **上游套餐**（`aigw_provider_plan`）：描述从上游厂商购买的套餐（折扣、额度、有效期），是成本核算的依据；
- **额度探测**（`aigw_plan_quota_probe`）：平台主动以小请求探测上游套餐剩余额度，并利用上游 **429 限流响应**反推套餐的真实成本档位，为成本优先调度提供数据。

### 6.3 上游账号池与智能调度

- 同一厂商可配置多个**服务账号**（`aigw_provider_account`）组成账号池；
- 调度策略：**成本优先**——单价更低的套餐/账号优先承接请求；
- **三轮故障转移**：请求失败（超时、5xx、限流）自动换号重试，最多三轮，对客户端完全透明；
- 速率限制器按账号维度平滑限速，避免无谓撞限。

### 6.4 模型映射与响应脱敏

- **模型映射**：客户端请求的"逻辑模型名"（如 `gpt-4o`）由平台映射到真实上游模型；返回给客户端的模型名统一改写为逻辑名，**上游真实模型名、账号信息绝不外泄**；
- **状态码混淆**：上游的 `401/403/404` 统一改写为 `530`，`429/5xx` 改写为 `503`，避免客户端从错误码推断上游厂商与账号状态；
- 响应体中的敏感字段（上游组织名、请求 ID 等）在回传前统一清洗。

### 6.5 RTK 上下文压缩

平台内置面向编码/智能体场景的上下文压缩引擎（RTK，16 个模块文件）：

- 对超长对话上下文做结构化压缩，平均节省 **20%~40% token**；
- 内置针对开发工具输出的专项过滤器：`git diff`、`grep`、`find`、`git log` 等命令输出的冗余行、重复路径、无关上下文会被裁剪；
- 压缩在网关侧透明完成，客户端与上游均无感知。

### 6.6 多租户体系

- 支持**行级（ROW）**与 **Schema 级**两种数据隔离模式，可按租户规模灵活选择；
- **域名 → 租户自动解析**：不同租户使用不同接入域名，网关据请求 Host 自动定位租户上下文；
- 租户间的套餐、账号、日志完全隔离。

### 6.7 会话粘性

同一会话（`aigw_cust_session`）的连续请求尽量路由到同一上游账号，保证：上下文缓存命中率高、模型风格一致、上游按会话计费时成本最优。

### 6.8 用量统计与审计

- 每一次请求写入用量日志 `aigw_log_usage`（**60+ 字段**）：覆盖请求/响应 token、模型、账号、套餐、耗时、首字延迟、流式分片数、错误码、租户等维度；
- 流式请求由独立的流式统计器在收流过程中增量累计；
- 管理端"数据分析"菜单提供 6 个分析视图（见 §1.5）；字典表 `aigw_sys_dict` 驱动下拉枚举与维度配置。

---

## 7. 数据模型（核心表）

| 表 | 用途 |
| --- | --- |
| `aigw_model_provider` | 上游厂商注册（协议类型、接入地址、认证方式），数据驱动、无硬编码 |
| `aigw_model_version` | 模型版本台账（上下文长度、计价、能力标签） |
| `aigw_provider_plan` | 上游套餐（购入价、额度、有效期） |
| `aigw_provider_account` | 上游服务账号池（凭据、限速参数、健康状态） |
| `aigw_cust_package` | 客户套餐（可用模型、配额、有效期） |
| `aigw_cust_user` | 客户账户与 `ik-` 密钥（状态机 0/1/2/3） |
| `aigw_cust_session` | 客户会话（粘性路由依据） |
| `aigw_log_usage` | 用量流水（60+ 字段，分析报表数据源） |
| `aigw_plan_quota_probe` | 上游套餐额度探测与成本推断记录 |
| `aigw_sys_dict` | 系统字典（枚举、维度配置） |

---

## 8. 开发平台与技术生态

| 层 | 技术 | 说明 |
| --- | --- | --- |
| 后端语言 | **Go 1.23** | 单体多进程，编译为单一二进制 |
| 微服务框架 | **micro-plat/hydra v1.3.16** | 自研生态：路由、配置（支持配置中心/本地双层）、RPC、cron、集群注册、WSS 支持 |
| 数据库 | **MySQL**（阿里云 RDS） | 业务库 + 用量日志库 |
| 前端框架 | **Vue 3 + Element Plus** | 单页应用；动态多页签工作台布局；页面按菜单配置动态装配 |
| 图表/报表 | 元数据查询服务（`ismart_metadata_query`，`metadata_id=1092`） | 数据分析页的图表由元数据驱动，报表维度可配置而无需改前端 |
| 构建标签 | `dev` / `prod` | 同一份代码区分开发/生产配置（数据库、端口、日志级别） |
| 交付 | Linux amd64 二进制 + 发布脚本 | 交叉编译后 scp 至生产服务器（121.196.168.242），滚动重启进程 |

**关键源码模块**（位于源码仓库，相对路径如下）：

```
main.go / app.go / app.cron.go      # 进程入口（网关、Web、CRON）
config.dev.go / config.prod.go       # 环境配置
services/aigw/                       # 网关核心服务
  ├─ proxy.go        # 转发主流程
  ├─ auth.go         # ik- 密钥鉴权
  ├─ account.go      # 账号池
  ├─ routing.go      # 路由与模型映射
  ├─ failover.go     # 三轮故障转移
  ├─ quota.go        # 5h/周配额窗口
  ├─ session.go      # 会话粘性
  ├─ usage.go / stream_usage.go   # 用量统计（含流式）
  ├─ sanitize.go / response.go    # 响应脱敏
  ├─ tenant_resolve.go # 域名→租户
  ├─ audit.go / probe.go # 审计与额度探测
modules/provider/                    # 上游适配层
  ├─ client.go / rate_limit.go / wss_transport.go
  └─ 5 组协议转换器（openai/anthropic/gemini/responses/chat 互转）
modules/rtk/                         # RTK 上下文压缩引擎（16 个文件）
modules/web/query.go                 # 控制台查询接口
schemas/v2/                          # 数据库结构与变更脚本
```

---

## 9. 支持二次开发

平台并非封闭黑盒，而是按"**可运营、可裁剪、可扩展**"的目标设计，为二次开发提供了从**零代码配置**到**源码模块替换**的完整扩展路径。

### 9.1 天生适合二次开发的架构基因

- **单体多进程 + 单一二进制**：一份 Go 代码库编译出网关、Web、CRON、WSS 四个进程，除 MySQL 外无消息队列、注册中心等重型外部依赖——克隆代码、初始化数据库、`go build` 即可本地跑通全链路；
- **分层清晰、边界稳定**：进程入口（`app*.go`）→ 核心服务（`services/aigw`）→ 可复用模块（`modules`）→ 数据结构（`schemas/v2`），替换或增强某一层不影响其余部分；
- **全链路数据驱动**：厂商、模型、映射、套餐、菜单枚举、报表维度全部落库，行为由数据决定，常规变更不需要重新编译发版；
- **环境编译期隔离**：`dev` / `prod` 构建标签切换两套配置，二次开发的本地环境与生产环境天然隔离、互不干扰。

### 9.2 零代码扩展点（配置与数据级）

| 扩展场景 | 操作方式 | 是否改代码 |
| --- | --- | --- |
| 新增上游厂商 / 模型服务 | 管理控制台「模型厂商」页登记协议类型、接入地址、认证方式，再配账号与套餐 | 否 |
| 调整模型映射与计价 | 「模型版本」页配置逻辑模型名 ↔ 真实上游模型、单价 | 否 |
| 上下线客户套餐与配额 | 「客户套餐」页操作，5 小时 / 周窗口即时生效 | 否 |
| 新增分析报表 | 在元数据查询服务（`ismart_metadata_query`）登记新的 `metadata_id` 报表定义，数据分析页直接出现新视图 | 否（前端零发版） |
| 菜单、枚举、维度调整 | 维护 `aigw_sys_dict` 字典表 | 否 |
| 新增控制台页面 | 页面按菜单配置动态装配，开发新 Vue 3 + Element Plus 组件挂到菜单配置即可 | 仅新增组件 |

### 9.3 源码级扩展点（模块级）

| 二次开发需求 | 扩展位置 | 说明 |
| --- | --- | --- |
| 接入新协议的上游 | `modules/provider` | 参照既有 openai / anthropic / gemini 适配器新增实现，注册进协议转换矩阵后自动获得与其它协议的互转能力 |
| 自定义调度策略 | `services/aigw/account.go` | 账号池默认"成本优先"选号，可在此实现按质量、按地域、按权重等自有策略 |
| 新增上下文压缩过滤器 | `modules/rtk` | 模块化压缩引擎（16 个文件），新增过滤器即可裁剪新工具的输出 |
| 加固 / 调整脱敏规则 | `services/aigw/sanitize.go` | 状态码改写与敏感字段清洗规则集中在一处维护 |
| 扩展用量字段 | `aigw_log_usage` + `usage.go` / `stream_usage.go` | 日志加字段即加分析维度，报表侧由元数据服务承接 |
| 新增定时作业 | `app.cron.go` | 基于 hydra cron 注册新作业（自定义对账、告警、清理等） |
| 新增租户隔离模式 | `services/aigw/tenant_resolve.go` | 在行级 / Schema 级之外扩展自有隔离与域名解析策略 |

### 9.4 二次开发工作流

```bash
# 1. 本地起服务（dev 构建标签加载本地配置，改完即编译即验证）
go build -tags dev -o gateway-dev.exe .

# 2. 数据库结构初始化 / 升级：重放 schemas/v2 脚本

# 3. 发布：交叉编译 + scp（见第 10 章「构建与部署」）
#    四进程独立启停——只改了哪个进程，就只重启哪个进程
```

### 9.5 典型二次开发场景

- **私有化 / 白标部署**：更换品牌、域名与默认套餐体系，面向自有客户独立运营；
- **对接内部系统**：把 60+ 字段的用量流水（`aigw_log_usage`）对接内部计费、工单或告警体系；
- **接入自建模型服务**：把内部训练 / 私有化部署的模型作为"厂商"登记进账号池，与公有云厂商统一调度、统一配额；
- **行业化报表定制**：通过元数据服务配置行业专属分析维度，前端零改动；
- **裁剪部署**：只对外部署网关进程，管理端与 CRON 按需启用，适配从小型试点到大规模运营的不同规模。

---

## 10. 构建与部署

```bash
# 生产构建（Linux amd64）
set GOOS=linux
set GOARCH=amd64
go build -tags prod -o <服务二进制> .

# 发布：scp 至生产服务器后重启进程
# 服务器：121.196.168.242（ismart 生产机）
```

- 发布脚本封装了"构建 → scp → 重启"完整流程；
- 四个进程（网关 8099 / Web 8098 / CRON / WSS 18080）独立启停，互不影响；
- 配置通过构建标签 + hydra 配置体系注入，二进制内不含敏感明文。

---

## 11. 二次开发

> **⚠️ 有偿服务提示：本章所述源码授权与定制开发均为付费有偿服务，非免费开源**，具体价格与合作方式请添加文末微信沟通。

本平台的完整源码（网关服务、Web 管理服务、CRON 作业、控制台前端、数据库脚本与构建发布脚本）不随本仓库开源。付费授权与服务内容包括：

- **完整源码交付**：全部 Go 源码、控制台前端源码、`schemas/v2` 数据库结构脚本与发布脚本；
- **部署落地支持**：协助在自有 Linux 服务器 + MySQL 环境完成部署、多进程配置与域名接入；
- **定制开发服务**：按需扩展上游协议适配、调度策略、脱敏规则、分析报表与控制台页面（扩展点见第 9 章）。

**添加微信沟通获取完整源码**：

<img src="docs/imgs/wx.jpg" alt="微信二维码" width="260">

---

*本文档基于平台源码分析与生产环境全站页面截图整理，面向需要进行二次开发的技术人员。*