# llm-gateway

**Repository Path**: gu-beichen-starlight/llm-gateway

## Basic Information

- **Project Name**: llm-gateway
- **Description**: 本项目是一个**企业级 LLM 统一网关**，为多厂商大模型服务提供统一的接入入口。网关层统一处理**认证鉴权、流量控制、计费统计、请求转发**等通用能力，上层业务无需关心底层 LLM 厂商的差异，实现模型的无缝切换与统一管理。

- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



<div align="center">

# LLM Gateway · StarGate

**企业级 LLM 统一接入网关**

一个基于 Go 语言开发的生产级大语言模型 API 网关，为多厂商 LLM 提供统一的接入入口，统一处理认证鉴权、流量控制、精准计费与全链路可观测性。

[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat-square&logo=go)](https://golang.org/)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16+-336791?style=flat-square&logo=postgresql)](https://www.postgresql.org/)
[![Redis](https://img.shields.io/badge/Redis-7.0+-DC382D?style=flat-square&logo=redis)](https://redis.io/)

</div>

---

## 功能特性

- **多厂商统一接入**：OpenAI、硅基流动、豆包、Ollama、vLLM，一套 API 无缝切换
- **完整身份体系**：管理员后台 Token + 用户 API Key 双鉴权，SHA-256 哈希存储，明文不落库
- **精准 Token 计费**：tiktoken 本地预估 + 厂商实际用量结算，Redis Lua 原子操作保证一致性
- **灵活流量控制**：API Key 级别 RPM（每分钟请求数）+ TPD（每日 Token 配额）双维度限速
- **多种响应模式**：同步 HTTP、SSE 流式、WebSocket 全双工，满足不同场景需求
- **故障自动转移**：多厂商按优先级 Failover，上游 5xx/超时自动切换，全部失败返回 503
- **异步高性能写入**：BillingWorker + Channel 批量落库，不阻塞响应链路
- **全链路可观测性**：Prometheus 指标埋点 + 结构化日志，内置 `/metrics` 端点

## 界面预览

### 数据总览

![数据总览](/pic/数据总览.png)

### 用量流水

![用量流水](/pic/用量流水.png)

### 聊天测试

![聊天测试](/pic/聊天测试.png)

## 系统架构

```
客户端请求
    ↓
[Gin HTTP 层] — 路由分发、协议解析
    ↓
[中间件层] — 认证 / 限速 / 日志 / 追踪 / Metrics / Panic 恢复
    ↓
[Service 层] — 业务逻辑编排、核心转发流程
    ↓
[Mapper 层] — 数据库 CRUD 抽象（GORM）
    ↓
[数据存储层] — PostgreSQL（持久化）+ Redis（缓存 / 限速 / 计费）
    ↓（转发请求）
[LLM Provider 层] — 各厂商 API 适配、格式转换
    ↓
OpenAI / 硅基流动 / 豆包 / Ollama / vLLM
```

## 技术栈

| 技术 | 版本 | 用途 |
| :--- | :--- | :--- |
| **Go** | 1.24+ | 核心开发语言，高并发网关流量处理 |
| **Gin** | 最新 | Web 框架，HTTP 路由与中间件 |
| **GORM** | 最新 | ORM，操作 PostgreSQL |
| **PostgreSQL** | 16+ | 关系型数据库，存储用户、厂商、模型、账单等核心数据 |
| **Redis** | 7.0+ | 会话存储、余额缓存、限速计数、分布式原子操作 |
| **tiktoken-go** | 最新 | 本地 Token 估算，用于请求前余额预检 |
| **Prometheus** | 最新 | Metrics 指标监控，支持 Grafana 可视化 |
| **MinIO** | 最新 | 对象存储（预留接口，当前版本不使用） |

## 快速开始

### 环境要求

- Go 1.24+
- PostgreSQL 16+
- Redis 7.0+

### 配置说明

编辑 `config.yaml`：

```yaml
server:
  port: 4300
  mode: debug   # debug | release

database:
  host: localhost
  port: 5432
  user: postgres
  password: "your_password"
  db_name: llm_gateway
  schema: public
  max_idle_conns: 10
  max_open_conns: 100
  conn_max_lifetime: 3600

redis:
  host: localhost
  port: 6379
  password: ""
  db: 0

billing:
  flush_interval: 5s     # 后台 Worker 批量写 DB 间隔
  channel_buffer: 10000  # Worker Channel 缓冲大小

websocket:
  idle_timeout: 5m          # 空闲连接超时
  max_message_size: 1048576 # 单帧最大消息体（1 MiB）
```

### 编译运行

```bash
# 克隆项目
git clone https://gitee.com/gu-beichen-starlight/llm-gateway.git
cd llm-gateway

# 整理依赖
go mod tidy

# 编译
go build -o llm-gateway

# 运行
./llm-gateway -config config.yaml
```

服务启动后默认监听 `http://0.0.0.0:4300`

## API 接口

### 认证接口

| 方法 | 路径 | 说明 |
| :--- | :--- | :--- |
| POST | /api/auth/login | 用户 / 管理员登录 |
| POST | /api/auth/logout | 登出 |

### 网关接口（OpenAI 兼容格式）

| 方法 | 路径 | 说明 |
| :--- | :--- | :--- |
| POST | /v1/chat/completions | 聊天完成（HTTP 同步 / SSE 流式，由 `stream` 字段决定） |
| GET  | /v1/chat/ws | WebSocket 全双工流式聊天 |
| POST | /v1/embeddings | 文本嵌入向量 |
| GET  | /v1/models | 查询可用模型列表 |

### 用户自服务接口

| 方法 | 路径 | 说明 |
| :--- | :--- | :--- |
| GET  | /api/user/balance | 查询账户余额 |
| GET  | /api/user/usage/stats | 查询个人用量统计 |
| POST/GET | /api/user/apikeys | 创建 / 查看 API Key |
| POST | /api/user/apikeys/delete | 删除 API Key |

### 管理接口（需 Admin 权限）

| 方法 | 路径 | 说明 |
| :--- | :--- | :--- |
| POST/GET | /api/admin/users | 用户管理 |
| POST/GET | /api/admin/vendors | LLM 厂商管理 |
| POST/GET | /api/admin/models | 模型配置管理 |
| POST/GET | /api/admin/apikeys | API Key 管理 |
| POST | /api/admin/billing/recharge | 用户充值 |
| GET  | /api/admin/billing/records | 充值记录 |
| GET  | /api/admin/billing/usage | 全量用量流水 |
| GET  | /api/admin/billing/usage/stats | 用量聚合统计 |
| GET  | /api/admin/users/stats | 用户统计报表 |

### 监控

| 方法 | 路径 | 说明 |
| :--- | :--- | :--- |
| GET | /metrics | Prometheus 指标端点（无需鉴权） |

## 使用示例

### cURL 调用聊天接口

```bash
# 非流式
curl -X POST http://localhost:4300/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好，请介绍一下自己"}],
    "stream": false
  }'

# SSE 流式
curl -X POST http://localhost:4300/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

### Python 调用示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="http://localhost:4300/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好，请介绍一下自己"}]
)
print(response.choices[0].message.content)
```

## 限流说明

限流基于 API Key 级别，支持两种策略：

- **RPM**：每分钟请求数限制（Redis ZSet 滑动窗口）
- **TPD**：每日 Token 消耗限制（Redis 原子累加，次日零点重置）

`rate_limit_rpm = 0` 或 `rate_limit_tpd = 0` 表示不限制。超出限制返回 HTTP 429。

## 计费说明

- 余额单位为**微分**（1 元 = 100 分 = 100,000 微分）
- 请求前：tiktoken 本地估算 Prompt Token 数，Lua 脚本原子检查余额并预扣
- 请求后：以厂商返回的 `usage` 字段为准多退少补；厂商不返回时以本地计算值兜底
- 异步写入：BillingWorker 批量 INSERT 使用流水，BalanceSyncWorker 定时同步 Redis 余额到 DB

## Metrics 监控

内置 Prometheus 指标，通过 `/metrics` 端点暴露：

| 指标名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `llmgw_requests_total` | Counter | HTTP 请求总数 |
| `llmgw_request_duration_seconds` | Histogram | 请求耗时分布 |
| `llmgw_tokens_total` | Counter | Token 消耗总量（区分 input/output） |
| `llmgw_billing_total_ufen` | Counter | 累计扣费金额（微分） |
| `llmgw_active_streams` | Gauge | 当前活跃流式连接数 |
| `llmgw_rate_limit_hits_total` | Counter | 限流命中次数 |

## 项目结构

```
llm-gateway/
├── main.go                     # 程序入口，启动 Gin + 后台 Worker
├── config.yaml                 # 配置文件
├── pkg/                        # 可复用基础包（无业务依赖）
│   ├── config/                 # 配置加载、DB/Redis/MinIO 初始化
│   ├── result/result.go        # 统一响应结构 Result[T]
│   ├── page/page.go            # 统一分页结构 Page[T]
│   ├── util/id_util.go         # 带前缀的 ULID 生成（u_ / m_ / ak_ ...）
│   ├── middleware/             # Gin 中间件（认证 / 限速 / 日志 / Metrics）
│   ├── llm/                    # LLM Provider 接口 + 各厂商适配
│   ├── billing/                # 计费引擎（Lua 脚本 / Worker / 余额同步）
│   ├── ratelimit/              # Redis 滑动窗口限速实现
│   └── metrics/                # Prometheus 指标定义
├── src/
│   ├── admin/                  # 管理后台业务模块
│   │   ├── domain/             # DO / DTO / VO 数据对象
│   │   ├── mapper/             # 数据库 CRUD（GORM）
│   │   └── service/            # 业务逻辑层
│   ├── gateway/service/        # 网关核心：路由服务 + 转发服务
│   └── router/                 # 路由注册
│       ├── api/                # 管理后台接口（/api/admin/* 和 /api/user/*）
│       └── v1/                 # 网关标准接口（/v1/*，OpenAI 兼容格式）
└── web/                        # 前端管理面板
```

## 许可证

[MIT License](LICENSE)

## 贡献指南

欢迎提交 Issue 和 Pull Request！