# API-Relay

**Repository Path**: BlueRocket/api-relay

## Basic Information

- **Project Name**: API-Relay
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# api-relay

多上游 LLM API 网关。单端口接收 OpenAI 格式请求，按 model 名路由到对应上游供应商，客户端无需感知上游差异。

## 架构

```
客户端（OpenAI 格式）
    │  Authorization: Bearer <relay_token>
    ▼
┌─────────────── api-relay :8000 ───────────────┐
│  鉴权 → 解析 model → 路由 → 改写密钥 → 转发      │
│                                                │
│  GET /v1/models   合并返回所有上游模型列表        │
│  GET /healthz     健康检查（免鉴权）             │
└───────┬──────────┬──────────┬──────────┬───────┘
        ▼          ▼          ▼          ▼
    DeepSeek    OpenAI      GLM/Kimi   Ollama/vLLM
   （OpenAI 格式，直连透传）
```

- **统一入口**：客户端统一发 OpenAI 格式（`/v1/chat/completions`），网关根据请求体里的 `model` 字段转发到对应上游
- **密钥隔离**：客户端只持有 relay token，各上游的真实 API Key 只存在网关侧
- **错误透传**：上游返回的任何错误原样转发给客户端，不吞不改

## 快速开始

### 1. 配置

```bash
# 复制环境变量模板（填上游 API Key，也可以用 config/keys/*.txt 文件方式）
cp config/.env.example config/.env

# 编辑 config/relay_config.json，按需增删 upstreams 条目
```

上游配置示例：

```json
{
  "name": "custom-gw",
  "base_url": "https://your-gateway.example.com/v1",
  "api_key": "sk-xxx",
  "models": ["model-a", "model-b"]
}
```

API Key 三种给法（优先级从高到低）：`api_key_env`（环境变量名）→ `api_key`（内联）→ `api_key_file`（文件路径，相对 config/ 目录）。

### 2. 启动

| 平台 | 方式 |
|---|---|
| Windows（图形面板） | 双击 `run_panel.bat` |
| Windows（命令行） | 双击 `run_relay.bat` |
| Linux / WSL | `./start_relay.sh`（后台运行） |
| 通用 | `python run.py` 或 `python -m relay` |

启动成功输出：

```
relay v2 pid=1234 listening on 0.0.0.0:8000 upstreams=[deepseek(2 models), custom-gw(4 models), ...]
```

### 3. 客户端接入

```bash
# 查看可用模型
curl http://<relay-ip>:8000/v1/models \
  -H "Authorization: Bearer $(cat relay_token.txt)"

# 调用
curl http://<relay-ip>:8000/v1/chat/completions \
  -H "Authorization: Bearer $(cat relay_token.txt)" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}'
```

relay token 首次启动时自动生成在项目根目录 `relay_token.txt`，可用环境变量 `RELAY_TOKEN` 覆盖。

## 配置优先级

```
shell 环境变量  >  config/.env  >  config/relay_config.json  >  代码默认值
```

常用环境变量：

| 变量 | 说明 |
|---|---|
| `RELAY_HOST` / `RELAY_PORT` | 监听地址/端口（默认 0.0.0.0:8000） |
| `RELAY_TOKEN` | 中继鉴权 token |
| `RELAY_ALLOW_IPS` | 客户端 IP 白名单（CIDR，逗号分隔；不设则允许所有） |
| `RELAY_LOG_LEVEL` / `RELAY_LOG_JSON` | 日志级别 / JSON 格式 |

## 管理 API

中继提供管理端点，用于动态重载配置和重启（无需远程登录）：

```bash
# 重载配置（不用重启进程）
curl -X POST http://localhost:8000/admin/reload \
  -H "Authorization: Bearer $(cat relay_token.txt)"

# 重启中继（旧进程退出，新进程自动拉起）
curl -X POST http://localhost:8000/admin/restart \
  -H "Authorization: Bearer $(cat relay_token.txt)"
```

管理 API 与普通 API 共用同一端口和鉴权，`/healthz` 免鉴权。

## 日志与用量

- `logs/relay.log` — 访问日志，按天轮转保留 7 天，每条请求带 trace_id
- `logs/usage_YYYYMMDD.jsonl` — 每请求一行：IP、trace_id、session_id、上游名、状态码、上下行字节、connect/ttfb/总耗时、input/output/total tokens
- Windows 面板实时显示日志尾部和今日用量汇总（按上游、按会话聚合）

定位一次请求：在日志里搜 trace_id，access log 和 usage 记录可以互相印证。

## 目录结构

```
relay/                  核心包（python -m relay）
├── core/               server（HTTP 处理）、router（模型路由）、upstream（上游连接）
├── middleware/          auth（鉴权/白名单）、usage（token 用量追踪）
└── config/              loader（配置加载）
config/                 配置文件
├── relay_config.json    中继配置（上游列表在这里）
├── client_config.json   客户端侧配置示例
├── .env.example         环境变量模板
└── keys/                上游 API Key 文件（已 gitignore）
scripts/                panel.py（面板）、launcher.py、verify.py 等工具
docs/                   部署文档
run.py / run_panel.py   快捷启动入口
```

## 已知限制

- 仅支持 OpenAI 格式上游；Anthropic 原生上游需经 cc-switch 等转换层接入
- model 路由基于 `relay_config.json` 中静态声明的模型列表，不向上游动态发现
- 请求体按 `Content-Length` 完整读入后再路由，不支持 chunked 请求体