# LLM API限流自动重试网关

**Repository Path**: az13js/token-gateway

## Basic Information

- **Project Name**: LLM API限流自动重试网关
- **Description**: 🚀 专为 LLM API 设计的轻量级流量网关 | 并发控制、自动重试，有效避免不规范HTTP状态码的 Rate Limit 限流导致的客户端中断问题。Go 语言实现。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Token Gateway

**Token Gateway** 是一个轻量级的 API 网关代理，专为对接大语言模型（LLM）服务商设计。

它的核心目标是解决单一账号在面临高并发请求时后端服务的不规范**限流问题**（Rate Limit）。通过排队机制、并发控制和重试机制，Token Gateway 能够“削峰填谷”，确保所有请求都能有序地发送给后端服务，屏蔽后端服务商不规范的HTTP错误码对客户端的影响，最大化业务成功率。

## 🌟 核心特性

*   **并发控制**：限制同时发往后端的请求数量（`-concurrency`），防止触发服务商的并发限制。
*   **排队机制**：当请求量超过阈值时，新请求会自动进入队列等待，而不是直接返回错误。支持配置最大等待时间（`-max-wait`）。
*   **连接保护**：全局限制最大客户端连接数（`-max-conn`），防止服务器资源耗尽。
*   **自动重试**：支持配置后端请求失败后的自动重试次数（`-max-retries`），应对网络波动或瞬时故障。
*   **超时熔断**：具备后端处理超时（`-backend-timeout`）和排队超时机制，防止死锁和资源占用。
*   **分级日志系统**：提供 DEBUG, INFO, WARN, ERROR 四级日志，便于运维监控和故障排查。
*   **透明代理**：完全兼容标准 HTTP 协议，对客户端无需修改代码，只需更改请求地址。

## 🚀 快速开始

### 1. 编译构建

确保已安装 Go 环境 (推荐 1.20+)。

```bash
cd token-gateway

# 编译（Windows）
go build -o token-gateway.exe

# 编译（Linux/macOS）
go build -o token-gateway

# 或者禁用CGO和静态编译
#go build -o token-gateway -ldflags="-s -w"
```

### 2. 运行示例

启动网关并指向你的后端服务（例如 OpenAI，实际使用时只要是HTTP协议均可，程序不支持非HTTP协议）：

```bash
# 基本用法：监听 8080 端口，转发至 OpenAI，限制并发数为 5
./token-gateway -target https://api.openai.com -port 8080 -concurrency 5

# 高级用法：开启调试日志，允许最大等待 30 秒，失败自动重试 2 次
./token-gateway -target https://api.openai.com \
  -port 8080 \
  -concurrency 5 \
  -max-wait 30s \
  -backend-timeout 300s \
  -max-retries 2 \
  -log-level DEBUG
```

**客户端调用方式：**

只需将客户端请求的目标地址改为网关地址即可。

*   原地址：`https://api.openai.com/v1/chat/completions`
*   新地址：`http://localhost:8080/v1/chat/completions`

> **注意** ：如果后端需要认证（如 API Key），请在客户端请求头中照常携带 `Authorization`，网关会透明转发。

### 3. 配置参数详解

| 参数 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `-target` | String | **(必填)** | 后端真实服务地址。例如：`https://api.openai.com`。 |
| `-port` | Int | `8080` | 网关本地监听端口。 |
| `-concurrency` | Int | `5` | **核心参数**。允许同时发往后端的最大请求数。建议设置为服务商对单账号的并发限制值。 |
| `-max-wait` | Duration | `60s` | 请求在队列中的最大等待时间。超时后返回 `503 Service Unavailable`。 |
| `-backend-timeout` | Duration | `300s` | 单个请求在后端处理的最大耗时。防止长尾请求占用槽位过久。 |
| `-max-conn` | Int | `1000` | 网关允许的最大总连接数（包含排队中的连接）。用于保护服务器资源。 |
| `-max-retries` | Int | `0` | 后端请求失败后的自动重试次数。适用于网络波动或瞬时报错场景。 |
| `-log-level` | String | `WARN` | 日志级别。可选：`DEBUG`, `INFO`, `WARN`, `ERROR`。生产环境建议设为 `WARN` 或 `ERROR`。 |
| `-strip-user-agent` | Bool | `false` | 移除客户端请求中的 `User-Agent` 头部，不转发给后端。 |
| `-user-agent` | String | 空 | 为转发给后端的请求设置指定的 `User-Agent` 头部。若同时设置 `-strip-user-agent` 和 `-user-agent`，以后者为准。 |
| `-header` | String | 空 | 添加自定义请求头（格式：`"Key: Value"`）。可重复使用，类似 curl 的 `-H` 参数。优先级最高，会覆盖同名头部。 |

### 4. 日志系统说明

网关内置分级日志系统，帮助运维人员快速定位问题：

*   **DEBUG**: 记录详细的请求头、客户端主动断开连接、重试过程等调试信息。仅在排查问题时开启。
*   **INFO**: 记录后端服务异常（如超时、连接重置）等非致命错误。
*   **WARN**: 记录排队超时、接近连接上限等警告信息。
*   **ERROR**: 记录无法处理的严重错误（如配置错误、资源耗尽拒绝服务）。

**示例日志输出：**

```text
[WARN] Request waited too long in queue: POST /v1/chat/completions
[INFO] Backend request timed out: POST /v1/chat/completions
[DEBUG] Client disconnected while waiting in queue
```

### 5. 工作原理流程

1.  **连接接入**：客户端发起请求，网关检查当前总连接数是否超过 `-max-conn`。若超过，直接拒绝。
2.  **并发排队**：
    *   若当前后端处理请求数 `< -concurrency`，请求立即获得槽位并转发。
    *   若槽位已满，请求进入 FIFO 队列等待。
    *   若等待时间超过 `-max-wait`，请求被丢弃并返回错误。
    *   若客户端在排队期间断开，网关自动清理该请求。
3.  **请求转发与重试**：
    *   获取槽位后，网关读取请求体，向后端发起请求。
    *   若配置了 `-max-retries` 且遇到网络错误或特定状态码，自动重试。
    *   若超过 `-backend-timeout`，强制终止请求并释放槽位。
4.  **响应回传**：后端响应以流式方式（Streaming）实时回传给客户端，传输完成后释放槽位。

### 6. 示例应用场景

#### 场景 1：LLM 服务商

```bash
./token-gateway \
  -target https://api.llm-provider.cn \
  -concurrency 10 \
  -max-wait 60s \
  -backend-timeout 300s \
  -max-retries 2
```

#### 场景 2：开发调试
```bash
./token-gateway \
  -target https://api.openai.com \
  -concurrency 5 \
  -log-level DEBUG \
  -max-retries 0
```

### 7. 注意事项

*   **资源限制**：在高并发场景下，请根据服务器内存和带宽合理设置 `-max-conn` 和 `-concurrency`。
*   **超时设置**：对于生成时间较长的 LLM 任务，请务必调大 `-backend-timeout`，避免正常请求被误杀。
*   **安全性**：当前无鉴权模块，建议部署在内网。
*   **重试策略**：目前重试逻辑主要针对网络错误和非 2xx 状态码。