# one-api

**Repository Path**: foreignwool/one-api

## Basic Information

- **Project Name**: one-api
- **Description**: 开源api，用来api中转和配置
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-03
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="right">
   <strong>中文</strong> | <a href="./README.en.md">English</a>
</p>

<p align="center">
   <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://github.com/MartialBE/one-hub/assets/42402987/c4125d1a-5577-446d-ba15-2a71c52140c1">
   <img height="90" src="https://raw.githubusercontent.com/MartialBE/one-api/main/web/src/assets/images/logo.svg">
   </picture>
</p>

<div align="center">

# One Hub

</div>

> [!WARNING]
> 本项目为个人学习使用，不保证稳定性，且不提供任何技术支持，使用者必须在遵循各 AI 供应商的使用条款以及法律法规的情况下使用，不得用于非法用途。
> 根据[《生成式人工智能服务管理暂行办法》](http://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm)的要求，请勿对中国地区公众提供一切未经备案的生成式人工智能服务。

---

## 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [Docker 部署](#docker-部署)
- [环境变量说明](#环境变量说明)
- [支持的模型列表](#支持的模型列表)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

---

## 项目简介

One Hub 是一个基于 [one-api](https://github.com/songquanpeng/one-api) 二次开发的 **大模型 API 网关与管理平台**。它提供了一个统一的 OpenAI 兼容接口，能够将请求智能路由到 40+ 个不同的 AI 供应商，包括 OpenAI、Anthropic、Google Gemini、百度文心、通义千问等国内外主流大模型服务。

通过 One Hub，你可以：

- **统一接口** — 用一套 API Key 调用所有供应商的大模型
- **负载均衡** — 多渠道智能调度，支持故障自动转移
- **精细管控** — 用户分组、令牌管理、模型权限、用量计费一站式管理
- **灵活扩展** — 支持虚拟模型映射、自定义价格、模型通配符

[演示网站](https://one-hub.xiao5.info/) | [在线文档](https://one-hub-doc.vercel.app/)

---

## 功能特性

### 核心功能

- **全新 UI 界面** — 基于 React + Material UI 的现代化管理后台
- **用户仪表盘** — 用户可查看用量、消费、模型统计等数据
- **管理员数据统计** — 多维度数据分析与可视化统计界面
- **供应商管理** — 重构的供应商模块，支持 40+ AI 供应商的统一接入
- **渠道管理** — 支持批量管理、健康检查、余额查询、自动测试
- **用户管理** — 多级用户分组，支持分组自动升级
- **令牌管理** — 灵活的 API Token 配置，支持模型权限控制与用量限制

### 模型与计费

- **模型通配符** — 支持通配符匹配模型名称
- **模型按次收费** — 支持按 Token 和按次两种计费模式
- **自定义价格** — 支持自定义模型价格与完成倍率
- **模型价格更新** — 支持自动从价格服务更新模型定价（覆盖更新、只更新现有价格、只新增价格等多种策略）
- **虚拟模型** — 支持虚拟模型配置，可映射到实际模型并控制路由
- **用户月度账单** — 支持生成用户月度账单数据

### 认证与安全

- **多种登录方式** — 密码登录、GitHub OAuth、飞书 OAuth、微信登录、OIDC、WebAuthn/Passkey
- **Telegram Bot** — 集成 Telegram 机器人，支持用户绑定与通知
- **内容安全** — 可配置的关键词内容审查
- **速率限制** — 全局 API 与 Web 接口速率限制

### API 兼容性

- **OpenAI 兼容接口** — 完全兼容 OpenAI API 格式（`/v1/`）
- **Claude 原生接口** — 支持 Claude 格式 API 请求（`/claude/v1/`）
- **Gemini 原生接口** — 支持 Gemini 格式 API 请求（`/gemini/`）
- **函数调用** — 支持和优化非 OpenAI 模型的 Function Call
- **流式响应** — 完整的 SSE 流式传输支持

### 部署与运维

- **多数据库支持** — SQLite（默认）、MySQL、PostgreSQL
- **Redis 缓存** — 可选 Redis 缓存，提升并发性能
- **多节点部署** — 支持主从节点分布式部署
- **Prometheus 监控** — 内置 Prometheus 指标端点
- **Uptime Kuma** — 支持集成 Uptime Kuma 状态页展示
- **日志管理** — 基于 zap 的结构化日志，支持日志轮转与压缩
- **配置文件** — 支持 YAML 配置文件启动程序

### 其他特性

- **MCP 服务** — 支持 Model Context Protocol 服务器
- **支付功能** — 支持支付宝、微信支付、Stripe、ePay 等支付方式
- **通知系统** — 支持邮件、企业微信、钉钉、飞书、PushDeer、Telegram 等通知渠道
- **对象存储** — 支持 SMMS、Imgur、阿里云 OSS、S3 兼容存储
- **搜索引擎集成** — 支持 SearxNG、Tavily 搜索
- **国际化** — 支持中文、英文、日文、繁体中文

---

## 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                      前端 (React/Vite)                   │
│            MUI · Redux · React Router · i18next          │
├─────────────────────────────────────────────────────────┤
│                   HTTP 路由层 (Gin)                       │
│     Web SPA · REST API · OpenAI Relay · Claude/Gemini    │
├────────────┬────────────┬────────────┬──────────────────┤
│  中间件层    │  认证层     │  限流层     │   安全检查        │
│  日志/会话   │  JWT/OAuth  │  Rate Limit│   内容审查        │
├────────────┴────────────┴────────────┴──────────────────┤
│                   Relay 中继层                            │
│       请求解析 · 虚拟模型映射 · 供应商路由 · 重试策略       │
├─────────────────────────────────────────────────────────┤
│                  供应商适配层 (40+)                        │
│  OpenAI · Claude · Gemini · 文心 · 千问 · Deepseek ...   │
├─────────────────────────────────────────────────────────┤
│                    数据层                                 │
│         GORM (MySQL / PostgreSQL / SQLite)               │
│              Redis (可选缓存/限流)                         │
└─────────────────────────────────────────────────────────┘
```

### 技术栈

| 层级 | 技术选型 |
|------|---------|
| 前端 | React 18 + Vite + Material UI 5 + Redux + i18next |
| 后端 | Go 1.25 + Gin + GORM + Viper |
| 数据库 | SQLite / MySQL 8 / PostgreSQL |
| 缓存 | Redis (可选) + FreeCache (内存缓存) |
| 日志 | Zap + Lumberjack (日志轮转) |
| 认证 | JWT + OAuth2 + OIDC + WebAuthn |
| 监控 | Prometheus + Uptime Kuma |
| 部署 | Docker + Docker Compose + Systemd |

---

## 项目结构

```
one-api/
├── main.go                       # 程序入口
├── go.mod / go.sum               # Go 依赖管理
├── config.example.yaml           # 配置文件示例
├── docker-compose.yml            # Docker Compose 编排文件
├── Dockerfile                    # Docker 构建文件
├── makefile                      # 构建脚本
├── deploy.sh                     # 一键部署脚本
├── one-api.service               # Systemd 服务模板
│
├── cli/                          # CLI 参数与数据导出
├── common/                       # 公共工具包
│   ├── config/                   #   配置变量与常量
│   ├── cache/                    #   内存缓存
│   ├── redis/                    #   Redis 客户端
│   ├── logger/                   #   日志
│   ├── notify/                   #   通知分发
│   ├── oidc/                     #   OIDC 认证
│   ├── webauthn/                 #   WebAuthn 认证
│   ├── telegram/                 #   Telegram Bot
│   ├── storage/                  #   对象存储
│   ├── search/                   #   搜索引擎
│   └── requester/                #   HTTP 客户端
├── controller/                   # HTTP 控制器（约 38 个文件）
├── middleware/                    # Gin 中间件
├── model/                        # 数据库模型与迁移
├── router/                       # 路由注册
├── relay/                        # 请求中继与路由
│   ├── midjourney/               #   Midjourney 中继
│   ├── relay_util/               #   配额计算工具
│   └── task/                     #   异步任务（Kling、Suno）
├── providers/                    # 供应商适配器（40+ 个供应商）
│   └── base/                     #   供应商基础接口
├── payment/                      # 支付网关
│   ├── gateway/                  #   支付宝/微信/Stripe/ePay
│   └── types/                    #   支付类型定义
├── mcp/                          # Model Context Protocol
│   └── tools/                    #   MCP 工具
├── safty/                        # 内容安全/审查
├── metrics/                      # Prometheus 指标
├── cron/                         # 定时任务
├── i18n/                         # 国际化资源
├── docs/                         # VitePress 文档站点
└── web/                          # React 前端
    └── src/                      #   前端源码
```

---

## 快速开始

### 环境要求

- Go 1.25+
- Node.js 22+ (仅开发前端时需要)
- Yarn (仅开发前端时需要)

### 方式一：直接运行（开发模式）

```bash
# 克隆项目
git clone https://github.com/MartialBE/one-api.git
cd one-api

# 构建前端
cd web
yarn install
yarn build
cd ..

# 构建并运行后端
go build -o one-api .
./one-api
```

程序默认监听 `3000` 端口，访问 `http://localhost:3000` 即可进入管理界面。

### 方式二：使用 Makefile

```bash
make web       # 构建前端
make one-api   # 构建前端 + 后端
```

### 方式三：使用配置文件启动

将 `config.example.yaml` 复制为 `config.yaml`，根据需要修改配置后启动：

```bash
cp config.example.yaml config.yaml
# 编辑 config.yaml 修改配置
./one-api
```

### 默认管理员账号

首次启动后，使用以下默认账号登录：

- 用户名：`root`
- 密码：`123456`

> 请在首次登录后立即修改默认密码！

---

## Docker 部署

### 使用 Docker Compose（推荐）

```bash
# 克隆项目
git clone https://github.com/MartialBE/one-api.git
cd one-api

# 复制并修改配置
cp config.example.yaml config.yaml
# 编辑 config.yaml 和 docker-compose.yml 中的数据库密码等配置

# 启动服务
docker-compose up -d
```

`docker-compose.yml` 包含三个服务：

| 服务 | 镜像 | 说明 |
|------|------|------|
| one-hub | 本地构建 | 主应用，端口 3000 |
| redis | redis:latest | Redis 缓存 |
| db | mysql:8.2.0 | MySQL 数据库 |

查看日志：

```bash
docker-compose logs -f one-hub
```

### 使用 Docker 单独运行

如果已有数据库和 Redis，可以直接运行应用容器：

```bash
docker run -d \
  --name one-hub \
  -p 3000:3000 \
  -v $(pwd)/data:/data \
  -v $(pwd)/config.yaml:/data/config.yaml \
  -e SQL_DSN="user:password@tcp(host:3306)/one-api" \
  -e REDIS_CONN_STRING="redis://default:password@host:6379" \
  -e SESSION_SECRET="your-random-session-secret" \
  -e USER_TOKEN_SECRET="your-random-token-secret-at-least-32-chars" \
  -e TZ=Asia/Shanghai \
  --restart always \
  ghcr.io/martialbe/one-api:latest
```

### Docker 镜像

Docker 镜像在以下平台可用：

- **GitHub Container Registry**: `ghcr.io/martialbe/one-api`
- **Docker Hub**: `martialbe/one-api`

### 使用 SQLite（无需外部数据库）

如果不想部署 MySQL/PostgreSQL，可以使用默认的 SQLite：

```bash
docker run -d \
  --name one-hub \
  -p 3000:3000 \
  -v $(pwd)/data:/data \
  -e SESSION_SECRET="your-random-session-secret" \
  -e USER_TOKEN_SECRET="your-random-token-secret-at-least-32-chars" \
  -e TZ=Asia/Shanghai \
  --restart always \
  ghcr.io/martialbe/one-api:latest
```

---

## 环境变量说明

配置支持通过环境变量或 `config.yaml` 配置文件设置。配置文件中的键名中的 `.` 在环境变量中替换为 `_`（例如 `global.api_rate_limit` 对应环境变量 `GLOBAL_API_RATE_LIMIT`）。

### 服务器设置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `PORT` | `3000` | 服务监听端口 |
| `GIN_MODE` | `release` | Gin 运行模式，可选 `release` / `debug` |
| `LOG_LEVEL` | `info` | 日志级别：`debug` / `info` / `warn` / `error` / `fatal` / `panic` |
| `LOG_DIR` | `./logs` | 日志输出目录 |
| `SESSION_SECRET` | 随机值 | 会话加密密钥 |
| `LANGUAGE` | `zh_CN` | 默认 UI 语言，支持 `zh_CN` / `en_US` / `ja_JP` / `zh_HK` |
| `TRUSTED_HEADER` | 空 | 可信代理头，如 `CF-Connecting-IP`（Cloudflare） |
| `FICON` | 空 | 自定义 Favicon，支持 URL 或文件路径 |
| `FRONTEND_BASE_URL` | 空 | 前端重定向地址，仅从节点使用 |

### 数据库设置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `SQL_DSN` | 空 | 数据库连接串；为空时使用 SQLite |
| `SQLITE_PATH` | `one-api.db` | SQLite 数据库文件路径 |
| `SQLITE_BUSY_TIMEOUT` | `3000` | SQLite 忙等待超时（毫秒） |
| `REDIS_CONN_STRING` | 空 | Redis 连接串，格式：`redis://default:password@host:port` |
| `REDIS_DB` | `0` | Redis 数据库编号 |

### 缓存与同步

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `MEMORY_CACHE_ENABLED` | `false` | 启用内存缓存 |
| `SYNC_FREQUENCY` | `600` | 缓存模式下数据库同步间隔（秒） |
| `NODE_TYPE` | `master` | 节点类型：`master`（主节点）/ `slave`（从节点） |
| `BATCH_UPDATE_ENABLED` | `false` | 启用数据库批量更新 |
| `BATCH_UPDATE_INTERVAL` | `5` | 批量更新间隔（秒） |

### 安全设置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `USER_TOKEN_SECRET` | 空 | 用户令牌签名密钥（至少 32 位随机字符串） |
| `HASHIDS_SALT` | 空 | Sqids 编码字母表参数 |
| `DISABLE_TOKEN_ENCODERS` | `false` | 禁用 tiktoken 编码器（可节省约 40MB 内存，但 Token 计数不精确） |

### 速率限制

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `GLOBAL_API_RATE_LIMIT` | `180` | API 速率限制（单 IP / 3 分钟） |
| `GLOBAL_WEB_RATE_LIMIT` | `100` | Web 速率限制（单 IP / 3 分钟） |

### 连接设置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `RELAY_TIMEOUT` | `0` | 中继请求超时时间（秒），0 表示不限制 |
| `CONNECT_TIMEOUT` | `5` | 连接超时时间（秒） |
| `POLLING_INTERVAL` | `0` | 渠道检查的请求间隔（秒） |

### 自动更新价格

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `AUTO_PRICE_UPDATES` | `false` | 启用模型价格自动更新 |
| `AUTO_PRICE_UPDATES_MODE` | `system` | 更新模式：`add`（仅新增）/ `overwrite`（全部覆盖）/ `update`（只更新现有）/ `system`（使用程序内置） |
| `AUTO_PRICE_UPDATES_INTERVAL` | `1440` | 更新间隔（分钟） |

### Telegram 设置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `TG_BOT_API_KEY` | 空 | Telegram Bot API 密钥 |
| `TG_WEBHOOK_SECRET` | 空 | Webhook 密钥（为空时使用轮询模式） |
| `TG_HTTP_PROXY` | 空 | Telegram 代理地址 |

### 通知设置

在 `config.yaml` 的 `notify` 节点下配置通知渠道：

- **email** — 邮件通知（需配置 SMTP）
- **wecom** — 企业微信机器人
- **dingTalk** — 钉钉机器人
- **lark** — 飞书机器人
- **pushdeer** — PushDeer
- **telegram** — Telegram 通知

### 存储设置

在 `config.yaml` 的 `storage` 节点下配置对象存储（用于图片生成场景）：

- **smms** — SM.MS 图床
- **imgur** — Imgur
- **alioss** — 阿里云 OSS
- **s3** — S3 兼容存储（支持 Cloudflare R2 等）

### MCP 设置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `MCP_ENABLE` | `false` | 启用 Model Context Protocol 服务 |

### 监控设置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `METRICS_USER` | 空 | Prometheus 指标端点用户名 |
| `METRICS_PASSWORD` | 空 | Prometheus 指标端点密码 |

### Uptime Kuma

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `UPTIME_KUMA_ENABLE` | `false` | 启用 Uptime Kuma 状态页 |
| `UPTIME_KUMA_DOMAIN` | 空 | Uptime Kuma 地址 |
| `UPTIME_KUMA_STATUS_PAGE_NAME` | 空 | 状态页面 slug |

---

## 支持的模型列表

One Hub 支持 40+ 个 AI 供应商，通过 OpenAI 兼容接口统一调用。

### 供应商能力总览

| 供应商 | Chat | Embeddings | Audio | Images | 其他 |
|--------|------|------------|-------|--------|------|
| [OpenAI](https://platform.openai.com/) | ✅ | ✅ | ✅ | ✅ | — |
| [Azure OpenAI](https://oai.azure.com/) | ✅ | ✅ | ✅ | ✅ | — |
| [Azure Speech](https://portal.azure.com/) | — | — | ⚠️ TTS | — | — |
| [Azure Databricks](https://azure.microsoft.com/) | ✅ | — | — | — | — |
| [Anthropic / Claude](https://www.anthropic.com/) | ✅ | — | — | — | — |
| [Google Gemini](https://aistudio.google.com/) | ✅ | — | — | — | — |
| [Google Vertex AI](https://cloud.google.com/vertex-ai) | ✅ | — | — | — | — |
| [百度文心](https://console.bce.baidu.com/qianfan/overview) | ✅ | ✅ | — | — | — |
| [通义千问](https://dashscope.console.aliyun.com/overview) | ✅ | ✅ | — | — | — |
| [讯飞星火](https://console.xfyun.cn/) | ✅ | — | — | — | — |
| [智谱 AI](https://open.bigmodel.cn/overview) | ✅ | ✅ | — | ⚠️ 图片生成 | — |
| [腾讯混元](https://cloud.tencent.com/product/hunyuan) | ✅ | — | — | — | — |
| [百川](https://platform.baichuan-ai.com/) | ✅ | ✅ | — | — | — |
| [MiniMax](https://www.minimaxi.com/) | ✅ | ✅ | — | — | — |
| [Deepseek](https://platform.deepseek.com/) | ✅ | — | — | — | — |
| [Moonshot](https://moonshot.ai/) | ✅ | — | — | — | — |
| [Mistral](https://mistral.ai/) | ✅ | ✅ | — | — | — |
| [Groq](https://console.groq.com/) | ✅ | — | — | — | — |
| [Amazon Bedrock](https://console.aws.amazon.com/bedrock/) | ⚠️ 仅 Anthropic 模型 | — | — | — | — |
| [零一万物](https://platform.lingyiwanwu.com/) | ✅ | — | — | — | — |
| [Cloudflare AI](https://ai.cloudflare.com/) | ✅ | — | ⚠️ STT | ⚠️ 图片生成 | — |
| [Cohere](https://cohere.com/) | ✅ | — | — | — | — |
| [Stability AI](https://platform.stability.ai/) | — | — | — | ⚠️ 图片生成 | — |
| [Coze](https://www.coze.com/) | ✅ | — | — | — | — |
| [Ollama](https://github.com/ollama/ollama) | ✅ | ✅ | — | — | — |
| [OpenRouter](https://openrouter.ai/) | ✅ | — | — | — | — |
| [Midjourney](https://www.midjourney.com/) | — | — | — | — | midjourney-proxy |
| [Suno](https://suno.com/) | — | — | — | — | Suno-API |
| [xAI](https://x.ai/) | ✅ | — | — | — | — |
| [GitHub Models](https://github.com/marketplace/models) | ✅ | — | — | — | — |
| [Siliconflow](https://siliconflow.cn/) | ✅ | — | — | — | — |
| [Jina](https://jina.ai/) | — | ✅ | — | — | Rerank |
| [Recraft AI](https://www.recraft.ai/) | — | — | — | ✅ | 向量化 |
| [Replicate](https://replicate.com/) | ✅ | — | — | — | — |
| [可灵 Kling](https://klingai.kuaishou.com/) | — | — | — | — | 视频生成 |

### 原生 API 兼容

除 OpenAI 兼容接口外，One Hub 还支持以下原生 API 格式：

- **Claude 格式** — `/claude/v1/messages`
- **Gemini 格式** — `/gemini/v1beta/models/{model}`
- **OpenAI Billing 兼容** — `/dashboard/billing/subscription`

### 模型价格管理

如果发现缺少新模型，请在管理后台的 **模型价格 → 更新价格** 中进行更新。支持以下策略：

- **system** — 使用程序内置价格，启动时自动从价格服务器更新
- **overwrite** — 全部覆盖现有价格
- **update** — 只更新已有模型的价格
- **add** — 只新增不存在的模型价格

---

## 贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进项目！

### 开发环境搭建

```bash
# 1. Fork 并克隆仓库
git clone https://github.com/your-username/one-api.git
cd one-api

# 2. 启动前端开发服务器
cd web
yarn install
yarn dev    # 默认运行在 localhost:5173，代理到 localhost:3000

# 3. 启动后端
cd ..
go run main.go
```

### 提交规范

- 使用清晰的提交信息，描述修改的目的和内容
- 一个 PR 只做一件事，保持变更范围小且聚焦
- 确保代码通过现有测试
- 新功能请补充必要的测试用码

### 代码规范

- Go 代码遵循标准 Go 规范
- 前端代码遵循项目 ESLint + Prettier 配置

---

## 许可证

本项目基于 [MIT License](./LICENSE) 开源。

---

## 致谢

本项目基于以下开源项目：

- [one-api](https://github.com/songquanpeng/one-api) — 本项目的基础
- [Berry Free React Admin Template](https://github.com/codedthemes/berry-free-react-admin-template) — 前端界面
- [minimal-ui-kit](https://github.com/minimal-ui-kit/material-kit-react) — 部分样式
- [new-api](https://github.com/Calcium-Ion/new-api) — Midjourney / Suno 模块
- [go-zero](https://github.com/zeromicro/go-zero) — Token 限流器实现

感谢以上项目的作者和所有贡献者！