# API-Router

**Repository Path**: Leorizon/api-router

## Basic Information

- **Project Name**: API-Router
- **Description**: API-Router - 私有 API 聚合网关，用一个 Key 在 Claude Code、Codex、OpenCode 等工具中使用所有上游大模型。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# API-Router

API-Router - 私有 API 聚合网关，用一个 Key 在 Claude Code、Codex、OpenCode 等工具中使用所有上游大模型。

## 功能

- **统一认证** — 生成多个客户端 API Key，所有工具共用，支持 API Key 内存缓存验证
- **双端点** — `/v1/messages`（Anthropic）和 `/v1/chat/completions`（OpenAI）
- **双向格式转换** — Anthropic Messages ↔ OpenAI ChatCompletion，含 SSE 流式转换
- **上游一对多模型** — 一个上游 API 接口可关联多个大模型
- **优先级调度** — 同一模型名可配置多个上游，按优先级自动调度，高优先级失败自动 fallback
- **自动健康检查** — 后台定期探测上游状态（60 秒间隔），离线上游自动跳过并触发路由缓存失效
- **模型级别开关** — 每个模型可独立启用/禁用
- **SSE 流式支持** — 逐事件转换透传，不缓冲完整响应，优化内存使用
- **Web 管理界面** — 可视化管理上游、模型、API Key 和查看用量统计
- **用量统计** — SQLite 持久化，异步批量写入，按模型/上游/每日维度统计，支持预计算汇总

## 快速开始

### 编译

```bash
go build -o api-router .
```

### 生成默认配置

```bash
./api-router -gen-config
```

生成 `config.yaml`：

```yaml
server:
  port: 9090
  jwt_secret: your_jwt_secret
database:
  path: ./data/api-router.db
```

> **注意**：`jwt_secret` 用于签名管理员会话的 JWT Token。生产环境建议使用随机生成的安全字符串。如果不配置，系统会在启动时自动生成随机密钥（但重启后会失效）。

### 启动

```bash
./api-router
```

首次启动时，浏览器访问 `http://localhost:9090/admin/` 会提示设置管理员账号和密码。设置完成后即可登录管理界面。

> **提示**：管理员信息存储在 SQLite 数据库中，密码使用 bcrypt 加密存储。

## 配置

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `server.port` | 监听端口 | `9090` |
| `server.jwt_secret` | JWT 签名密钥（用于管理员认证） | 自动生成随机值（重启后失效，生产环境建议手动配置） |
| `database.path` | SQLite 数据库路径 | `./data/api-router.db` |

## 性能优化特性

- **连接池优化** — HTTP 连接池复用（MaxIdleConns: 200, MaxIdleConnsPerHost: 20, IdleConnTimeout: 120s）
- **API Key 缓存** — 内存缓存已验证的 API Key，减少数据库查询
- **异步批量统计** — 请求记录异步批量写入（batch size: 50, flush interval: 3s），消除响应延迟
- **路由缓存** — 模型路由结果缓存，健康检查状态变化时自动失效
- **预计算统计** — 每日统计汇总预计算，加速用量查询
- **SSE 流优化** — 逐事件转换，减少内存占用和 JSON 解析开销

## Web 管理界面

浏览器打开 `http://localhost:9090/admin/`，首次访问需要设置管理员账号密码。

### 首次启动

首次启动时，访问管理界面会自动提示设置管理员账号和密码：
- **用户名** — 自定义管理员用户名
- **密码** — 自定义管理员密码（建议使用强密码）

### 登录认证

设置完成后，使用设置的用户名和密码登录，系统使用 JWT Token 进行认证。

### 上游管理

添加上游 API 提供商时，一并配置该接口支持的模型列表：

- **上游信息** — 名称、Base URL、API 类型（OpenAI / Anthropic）、API Key、启用状态
- **模型配置** — 每个模型设置名称、上游模型名映射、优先级（数值越大越优先）、启用状态
- **健康状态** — 自动检测上游在线/离线/异常状态，状态灯实时展示（60 秒间隔）
- **模型开关** — 每个模型可独立启用/禁用
- **API Key 脱敏** — 列表中显示脱敏后的 API Key（前后各 4 位）

### 优先级调度

同一个模型名也可以在多个上游配置不同的优先级：

1. 请求按优先级从高到低依次尝试各上游
2. 高优先级上游离线（健康检查标记）自动跳过
3. 高优先级上游返回 5xx 错误，自动 fallback 到次优先级上游
4. 所有上游均失败时，返回最后一个上游的错误
5. 非流式和流式请求均支持 Fallback 机制

### API Key 管理

生成和管理客户端使用的 API Key：

- 一键生成随机 Key（`sk-` 前缀）
- 自定义 Key 名称（用于标识用途）
- 启用/禁用 Key
- 一键复制

### 用量统计

实时查看 API 调用数据和趋势分析：

- **数据概览** — 总请求数、总输入/输出 Token、平均延迟（基于预计算汇总，查询性能优化）
- **模型用量** — 按模型统计请求次数和 Token 消耗
- **上游用量** — 按上游统计请求次数和 Token 消耗
- **每日趋势** — 近 7 天请求量柱状图
- **最近请求** — 详细请求记录（时间、客户端类型、模型、上游、Token 数、状态码、延迟、错误信息）

## API 端点

### 认证端点（公开）

```bash
# 检查系统初始化状态
curl http://localhost:9090/admin/api/auth/status

# 首次设置管理员（仅首次启动时可用）
curl -X POST http://localhost:9090/admin/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your_password"}'

# 登录获取 JWT Token
curl -X POST http://localhost:9090/admin/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your_password"}'
```

### 认证端点（需要管理员认证）

```bash
# 登出
curl -X POST http://localhost:9090/admin/api/auth/logout \
  -H "Authorization: Bearer <jwt_token>"

# 修改密码
curl -X POST http://localhost:9090/admin/api/auth/change-password \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"old_password": "old_pass", "new_password": "new_pass"}'
```

### Anthropic 格式（Claude Code）

```bash
curl -X POST http://localhost:9090/v1/messages \
  -H "x-api-key: sk-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "hello"}]
  }'
```

### OpenAI 格式（Codex / OpenCode）

```bash
curl -X POST http://localhost:9090/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "stream": true,
    "messages": [{"role": "user", "content": "hello"}]
  }'
```

### 模型列表

```bash
curl http://localhost:9090/v1/models -H "Authorization: Bearer sk-your-key"
```

### 管理 API 端点（需要管理员 JWT Token）

```bash
# 上游管理
GET    /admin/api/upstreams          # 获取所有上游（含健康状态和模型列表）
POST   /admin/api/upstreams          # 创建上游（同时创建关联的模型）
GET    /admin/api/upstreams/{id}     # 获取单个上游（含模型列表）
PUT    /admin/api/upstreams/{id}     # 更新上游（可同时更新模型）
DELETE /admin/api/upstreams/{id}     # 删除上游

# 模型管理
GET    /admin/api/models             # 获取所有模型
PUT    /admin/api/models/{id}        # 更新模型（名称、优先级、启用状态）
DELETE /admin/api/models/{id}        # 删除模型

# API Key 管理
GET    /admin/api/keys               # 获取所有 Key（脱敏显示）
POST   /admin/api/keys               # 创建 Key（返回完整 Key）
GET    /admin/api/keys/{id}          # 获取单个 Key
PUT    /admin/api/keys/{id}          # 启用/禁用 Key
DELETE /admin/api/keys/{id}          # 删除 Key

# 用量统计
GET    /admin/api/stats/overview     # 数据概览（总请求数、Token、平均延迟）
GET    /admin/api/stats/models       # 模型用量统计
GET    /admin/api/stats/upstreams    # 上游用量统计
GET    /admin/api/stats/requests     # 最近请求列表（支持分页）
GET    /admin/api/stats/daily        # 每日统计数据（近 N 天）
```

## 客户端接入

### Claude Code

```bash
export ANTHROPIC_BASE_URL=http://localhost:9090
export ANTHROPIC_API_KEY=sk-your-key
```

### Codex / OpenCode

```bash
export OPENAI_BASE_URL=http://localhost:9090/v1
export OPENAI_API_KEY=sk-your-key
```

## 格式转换

当客户端格式与上游格式不一致时，API-Router 自动进行双向转换：

| 场景 | 客户端 | 上游 | 处理 |
|------|--------|------|------|
| 直连转发 | Anthropic | Anthropic | 直接转发 |
| 直连转发 | OpenAI | OpenAI | 直接转发 |
| 格式转换 | Anthropic | OpenAI | 请求 + 响应自动转换 |
| 格式转换 | OpenAI | Anthropic | 请求 + 响应自动转换 |

转换范围包括：
- **消息结构** — user/assistant/system 消息格式转换
- **Tool Calls** — Anthropic tool_use/tool_result ↔ OpenAI tool_calls
- **Stop Sequences** — 停止序列格式转换
- **Token 统计** — usage 信息转换
- **SSE 流式事件** — 逐帧转换，不缓冲完整响应

## 优先级调度与 Fallback

同一个模型名可以在多个上游配置不同的优先级：

1. 请求按优先级从高到低依次尝试各上游
2. 高优先级上游离线（健康检查标记为 offline）自动跳过
3. 高优先级上游返回 5xx 错误，自动 fallback 到次优先级上游
4. 所有上游均失败时，返回最后一个上游的错误
5. 非流式和流式请求均支持 Fallback 机制

## 健康检查

系统后台定期检测上游可用性：

- **检查间隔** — 60 秒
- **并发检测** — 最多同时检测 10 个上游
- **状态标记** — online / offline / error
- **错误记录** — 记录最后一次错误信息
- **自动缓存失效** — 状态变化时自动清除路由缓存
- **健康端点** — OpenAI 上游检测 `/models`，Anthropic 上游检测 `/v1/models`

## 项目结构

```
├── main.go                     # 入口
├── config.yaml                 # 配置文件
├── web/                        # Web 管理界面（Vue 3 + Vite）
│   ├── index.html              # HTML 模板
│   ├── package.json            # 依赖配置
│   ├── vite.config.js          # Vite 配置
│   ├── public/                 # 静态资源
│   └── src/
│       ├── main.js             # 入口文件
│       ├── App.vue             # 根组件
│       ├── api/
│       │   └── client.js       # API 客户端
│       ├── assets/             # 资源文件
│       ├── components/
│       │   └── Sidebar.vue     # 侧边栏组件
│       ├── router/
│       │   └── index.js        # 路由配置
│       ├── stores/
│       │   └── auth.js         # 认证状态管理
│       └── views/
│           ├── Keys.vue        # API Key 管理
│           ├── Layout.vue      # 布局组件
│           ├── Login.vue       # 登录页面
│           ├── Setup.vue       # 首次设置
│           ├── Stats.vue       # 用量统计
│           └── Upstreams.vue   # 上游管理
├── internal/
│   ├── admin/
│   │   ├── handler.go          # Admin CRUD API（上游/模型/Key/统计）
│   │   ├── auth.go             # JWT 认证处理（登录/登出/修改密码）
│   │   ├── validate.go         # 输入验证（URL 格式/API 类型）
│   │   └── ui.go               # Web UI embed（SPA 处理）
│   ├── config/
│   │   └── config.go           # 配置加载（YAML）
│   ├── convert/
│   │   ├── types.go            # Anthropic/OpenAI 类型定义
│   │   ├── anthropic2openai.go # Anthropic → OpenAI 转换
│   │   └── openai2anthropic.go # OpenAI → Anthropic 转换
│   ├── db/
│   │   └── sqlite.go           # SQLite 初始化 + 迁移（WAL 模式）
│   ├── health/
│   │   └── checker.go          # 自动健康检查（60 秒间隔，并发检测）
│   ├── proxy/
│   │   ├── model_router.go     # 模型路由（优先级调度 + 路由缓存）
│   │   ├── proxy.go            # 非流式代理（连接池优化 + fallback）
│   │   └── stream.go           # SSE 流式代理（逐事件转换 + fallback）
│   ├── server/
│   │   ├── server.go           # HTTP 服务 + 路由设置
│   │   ├── middleware.go       # API Key 认证中间件（缓存验证）
│   │   ├── anthropic.go        # Anthropic 端点（/v1/messages）
│   │   ├── openai.go           # OpenAI 端点（/v1/chat/completions）
│   │   └── helpers.go          # 响应工具函数
│   └── store/
│       ├── store.go            # Store 初始化（DB + 缓存 + 异步 recorder）
│       ├── upstreams.go        # 上游 CRUD + 状态更新
│       ├── models.go           # 模型 CRUD + 路由查询
│       ├── apikeys.go          # API Key CRUD + 内存缓存
│       ├── stats.go            # 用量统计（预计算汇总）
│       ├── recorder.go         # 异步批量统计写入（batch: 50, interval: 3s）
│       └── admin.go            # 管理员用户管理
```

## 技术栈

- **后端**
  - Go 1.25
  - SQLite (WAL 模式，go-sqlite3)
  - gorilla/mux（路由）
  - golang-jwt/jwt v5（JWT 认证）
  - bcrypt（密码加密）
  - gopkg.in/yaml.v3（YAML 解析）
  - github.com/google/uuid（请求 ID 生成）

- **前端**
  - Vue 3（Composition API）
  - Vite（构建工具）
  - Vue Router（路由管理）
  - Pinia（状态管理）
  - Tailwind CSS v4（样式）

- **数据库表**
  - `requests` — 请求记录（用量统计）
  - `upstreams` — 上游配置（含健康检查状态：status/last_check_at/last_error）
  - `models` — 模型路由配置（含优先级 priority）
  - `api_keys` — 客户端 API Key
  - `admin_users` — 管理员用户
  - `system_state` — 系统状态（初始化标记）
  - `daily_stats_summary` — 每日统计汇总（预计算加速查询）

## Web 前端开发

如果需要修改 Web 管理界面，进入 `web` 目录进行开发：

```bash
cd web

# 安装依赖
npm install

# 启动开发服务器（热重载）
npm run dev

# 构建生产版本
npm run build
```

构建后的静态文件会嵌入到 Go 二进制文件中（通过 `embed.FS`）。