songquanpeng/one-api · 上手攻略

• 仓库：songquanpeng/one-api
• 链接：https://github.com/songquanpeng/one-api
• 分类：skill（LLM Infra · API 管理 · 多模型统一网关）
• 作者：Jay
• 更新：2026-07-09

这是什么

One API 是一个开源的 LLM API 管理与分发系统，用统一的 OpenAI API 格式暴露所有主流大模型接口，支持 API Key 管理、负载均衡、令牌配额控制、用户权限管理和二次分发。

通俗来说：你在 One API 后台配置好各渠道（OpenAI、Claude、Gemini、DeepSeek 等）的 API Key，对外只暴露一个 API 地址，客户端代码无需改动，即可自由切换模型、分散调用压力、统一管理额度。35.5k Stars，MIT 协议，单可执行文件或 Docker 部署，开箱即用。

能解决什么问题

• API Key 集中管理：不用在每个客户端里分散存储多个模型的 Key，统一从 One API 出。
• 多模型统一入口：客户端只需对接一个 API Base URL，One API 自动路由到对应模型。
• 负载均衡与故障转移：同一个模型可配置多个渠道，One API 自动轮询或按比例分发，某个渠道挂了自动切换。
• 额度控制：可以为不同用户/分组设置调用配额、过期时间、IP 白名单，防止 Key 被滥用。
• 模型映射：可以给模型起别名，比如把用户请求的 gpt-4 映射到实际部署的 gpt-4o-mini，节省成本。
• 国内模型支持：豆包、文心、通义、讯飞星火、ChatGLM 等国内大模型均有官方对接，无需额外开发。

快速安装

方式一：Docker 一键部署（推荐，最快）

SQLite 版本（默认，适合个人/小团队）：

docker run --name one-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/data/one-api:/data \
  justsong/one-api

MySQL 版本（适合并发量较大的生产环境）：

docker run --name one-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/data/one-api:/data \
  justsong/one-api

⚠️ 安全警告：首次部署后必须立即修改 root 默认密码 123456！

启动后访问：http://localhost:3000，账号 root，密码 123456。

GitHub 镜像拉取（若 Docker Hub 镜像拉取失败）：

docker run --name one-api -d --restart always \
  -p 3000:3000 \
  -v /home/ubuntu/data/one-api:/data \
  ghcr.io/songquanpeng/one-api:latest

自动更新（Watchtower）：

docker run --rm -v /var/run/docker.sock:/var.run/docker.sock \
  containrrr/watchtower -cR

方式二：宝塔面板部署（适合国内服务器）

1. 安装宝塔面板 9.2.0+ → Docker 管理器
2. 在应用商店搜索"One-API"，一键安装
3. 配置域名和 SSL

方式三：源码编译（适合深度定制）

# 下载可执行文件（从 GitHub Releases）
# 或从源码编译：
git clone https://github.com/songquanpeng/one-api.git
cd one-api

# 构建前端
cd web/default
npm install
npm run build

# 构建后端
cd ../..
go mod download
go build -ldflags "-s -w" -o one-api

# 运行
chmod u+x one-api
./one-api --port 3000 --log-dir ./logs

方式四：docker-compose（需要 MySQL 时）

git clone https://github.com/songquanpeng/one-api.git
cd one-api
docker-compose up -d
docker-compose ps

核心用法

1. 添加渠道（配置 API Key）

登录后台后： 1. 进入 渠道管理 → 添加渠道 2. 选择模型类型（OpenAI / Claude / Gemini / DeepSeek 等） 3. 填写 API Key 和 base URL（部分模型需要特定端点） 4. 设置权重（负载均衡权重）和模型列表

支持的模型类型（截至 2026-07，项目文档已列）：

2. 创建令牌（供客户端使用）

1. 进入 令牌管理 → 添加令牌
2. 设置名称、额度（使用次数或额度值）、过期时间
3. 可选：限制 IP 范围和可用模型
4. 复制生成的令牌（格式类似 sk-xxxxx）

3. 客户端接入

客户端只需把 base_url 指向你的 One API 地址：

# OpenAI Python SDK 示例
from openai import OpenAI

client = OpenAI(
    api_key="你的令牌",
    base_url="http://localhost:3000/v1"  # 指向 One API
)

response = client.chat.completions.create(
    model="gpt-4o-mini",  # 这里写的是模型别名，实际会路由到配置的渠道
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

# cURL 示例
curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

4. 模型映射

在 渠道管理 中设置模型映射，将用户请求的模型名重定向到实际部署的渠道模型：

gpt-4 → gpt-4o-mini  # 节省成本
claude-3-opus → claude-3-5-sonnet-20240620  # 路由到实际可用版本

⚠️ 注意：模型映射会重新构造请求体，不走透传模式，部分字段可能丢失。

5. 额度与用户管理

• 用户分组：不同分组可以设置不同倍率（计费比例）
• 渠道分组：按成本或优先级分组
• 兑换码：批量生成兑换码，用户输入后可充值额度
• 邀请奖励：设置邀请奖励机制

6. 环境变量参考

7. Nginx 反向代理配置

server {
    server_name your-domain.com;

    client_max_body_size 64m;

    location / {
        proxy_http_version 1.1;
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header Accept-Encoding gzip;
        proxy_read_timeout 300s;  # GPT-4 需要较长超时
    }
}

配置 HTTPS（Let's Encrypt）：

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
sudo service nginx restart

典型适用场景

场景一：个人开发者多模型管理

手上有多个模型的 API Key，不想在每个项目里分散配置。用 One API 统一管理，客户端只需对接一个地址，换模型时改后台配置即可，代码零改动。

场景二：AI 应用二次分发（API 二道贩子）

自己有渠道商或云厂商的折扣 API Key，通过 One API 包装后给客户/团队使用，设置额度限制和计费倍率，赚取差价。

场景三：多渠道负载均衡

同一种模型（如 GPT-4o）配置多个渠道，设置不同权重，实现自动故障转移。某个渠道响应慢或超限时，One API 自动切换到其他渠道。

场景四：内部 AI 平台统一网关

企业内部有多个团队使用不同的 LLM 服务，通过 One API 做统一网关，统一鉴权、审计和额度管控，避免各团队重复造轮子。

坑与注意

1. 默认密码必须改！ root 初始密码 123456，部署后第一件事就是改密码，否则任何人可登录管理后台。

2. SQLite vs MySQL 的选择：个人使用 SQLite 足够；但并发量超过每秒数十次请求时，务必切换 MySQL，否则可能出现锁竞争和响应延迟（SQL_DSN 环境变量设置）。

3. 模型映射的坑：开启模型映射后，请求体会被重新构造，gpt-4o 的某些高级参数（如 response_format）可能无法透传到目标模型，有特殊需求时注意测试。

4. Docker 权限问题：部分环境（如某些 NAS 或最小化 Linux）Docker 容器需要 --privileged=true 才能正常运行，参考 Issue #482。

5. 网络访问限制：部分渠道（如 Azure、AWS Claude）需要特殊网络配置（如代理或专线），One API 服务器必须能访问这些端点。

6. 国内部署合规提醒：项目 README 明确指出，根据《生成式人工智能服务管理暂行办法》，请勿对中国地区公众提供未经备案的生成式 AI 服务。使用前请了解当地法规要求。

7. 新版 Docker 镜像可能包含 alpha 版本：文档提到从 Docker Hub 拉取的 latest 镜像有时是 alpha 版本，如遇不稳定可指定稳定版本 tag。

8. 多机部署：如需水平扩展，从服务器需设置 NODE_TYPE=slave，并确保所有服务器连接到同一个 MySQL + Redis。

与同类对比

One API 的核心优势是零门槛自部署 + 开箱即用：一个 Docker 命令就能跑起来，而 LiteLLM 等方案需要更多配置。对国内用户来说，更重要的是它对国内大模型的原生支持（豆包、通义、文心等），开箱即用无需适配。

一句话推荐结论

One API 是个人开发者和小型团队建立 LLM API 统一网关的最佳选择——一个 Docker 命令完成部署，把手上所有模型的 Key 统一管理起来，对外暴露一个 OpenAI 兼容接口，换模型、控额度、加渠道全在后台搞定，代码零改动。