OneAPI & NewAPI 完全指南：从零开始搭建你的AI模型聚合网关

在AI大模型百花齐放的今天，我们常常需要同时使用多个模型提供商的服务——OpenAI的GPT-4、Anthropic的Claude、Google的Gemini、国内的文心一言、通义千问等等。每个提供商都有自己的API接口和密钥，管理起来非常繁琐。OneAPI 和 NewAPI 应运而生，它们是开源的API管理和分发系统，让你可以用统一的接口访问所有AI模型。

一、什么是OneAPI和NewAPI？

1.1 OneAPI 简介

OneAPI 是由开发者 songquanpeng 开发的开源项目，它是一个多模型API管理和分发平台。简单来说，它就像一个"AI模型中转站"：

- 你把各种AI模型的API密钥配置到OneAPI中
- OneAPI给你生成一个统一的访问地址和密钥
- 你只需要用这一个地址和密钥，就能访问所有配置好的AI模型

**核心价值：**统一接口、集中管理、灵活分发、成本控制。

1.2 NewAPI 简介

NewAPI（也叫 New API）是由开发者 Calcium-Ion 基于OneAPI二次开发的增强版本。它在保留OneAPI核心功能的基础上，增加了许多实用特性：

- **更美观的UI界面**：重新设计的用户界面，更加现代化
- **更多模型支持**：支持Midjourney绘图、TTS语音合成等
- **完善的计费系统**：支持按次计费、按Token计费等多种方式
- **充值系统**：内置用户充值功能，适合商业化运营
- **更好的兼容性**：兼容更多第三方客户端和平台
- **分组管理**：支持用户分组，不同分组使用不同模型和配额

**简单总结：**如果你是个人使用或小团队，OneAPI足够；如果你需要更好的界面、更完善的功能或商业化运营，推荐使用NewAPI。

二、核心功能详解

2.1 渠道管理（Channel）

"渠道"是OneAPI/NewAPI的核心概念之一。每个渠道代表一个AI模型提供商的接入配置。

- **添加渠道**：配置提供商类型（如OpenAI、Claude等）、API密钥、API地址
- **负载均衡**：同一模型可以配置多个渠道，系统自动轮询或按优先级分配
- **故障转移**：某个渠道出错时，自动切换到备用渠道
- **状态监控**：实时查看每个渠道的可用状态和调用次数

2.2 令牌管理（Token）

令牌是访问OneAPI/NewAPI的凭证。你可以创建多个令牌，分配给不同的用户或应用。

- **额度控制**：设置每个令牌的可用额度（按Token或金额）
- **过期时间**：设置令牌有效期
- **模型限制**：限制令牌只能访问指定模型
- **IP限制**：限制令牌只能从指定IP访问

2.3 用户管理

- **用户注册**：支持开放注册或邀请码注册
- **用户分组**：不同分组配置不同的可用模型和配额
- **余额管理**：管理员可以给用户充值或扣费

2.4 模型支持

支持的模型提供商包括但不限于：

- **OpenAI**：GPT-4、GPT-4o、GPT-3.5-turbo等
- **Anthropic**：Claude 3.5 Sonnet、Claude 3 Opus等
- **Google**：Gemini Pro、Gemini Ultra等
- **国内模型**：文心一言、通义千问、智谱GLM、讯飞星火等
- **其他**：Mistral、Cohere、AWS Bedrock等

三、Docker部署（推荐）

Docker是最简单的部署方式，推荐新手使用。

3.1 环境准备

- 一台Linux服务器（推荐Ubuntu 20.04+或CentOS 7+）
- 已安装Docker和Docker Compose
- 服务器有公网IP或已配置域名

3.2 安装Docker（如未安装）

Ubuntu/Debian系统：

# 更新包索引
sudo apt update

# 安装依赖
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加Docker仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动Docker并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version

CentOS/RHEL系统：

# 安装依赖
sudo yum install -y yum-utils

# 添加Docker仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动Docker并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version

3.3 部署OneAPI

方式一：使用Docker Compose（推荐）

  1. 创建项目目录：
mkdir -p /opt/oneapi
cd /opt/oneapi
  1. 创建 docker-compose.yml 文件：
version: '3.8'

services:
  oneapi:
    image: justsong/one-api:latest
    container_name: oneapi
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      # SQLite数据库（默认，适合个人使用）
      - SQL_DSN=sqlite:///data/one-api.db
      # 如需使用MySQL，取消下面的注释并填写配置
      # - SQL_DSN=root:password@tcp(localhost:3306)/oneapi
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
  1. 启动服务：
# 启动
docker compose up -d

# 查看日志
docker compose logs -f

# 检查状态
docker compose ps
  1. 访问OneAPI：

打开浏览器，访问 http://你的服务器IP:3000

默认管理员账号：root

默认密码：123456（请立即修改！）

3.4 部署NewAPI

  1. 创建项目目录：
mkdir -p /opt/newapi
cd /opt/newapi
  1. 创建 docker-compose.yml 文件：
version: '3.8'

services:
  newapi:
    image: calciumion/new-api:latest
    container_name: newapi
    restart: always
    ports:
      - "3001:3000"
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      # SQLite数据库（默认）
      - SQL_DSN=sqlite:///data/new-api.db
      # 如需使用MySQL，取消下面的注释
      # - SQL_DSN=root:password@tcp(localhost:3306)/newapi
      # 站点名称（可选）
      - SESSION_SECRET=random_secret_string_here
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
  1. 启动服务：
docker compose up -d
  1. 访问NewAPI：

打开浏览器，访问 http://你的服务器IP:3001

默认管理员账号：root

默认密码：123456

3.5 配置Nginx反向代理（可选但推荐）

使用Nginx反向代理可以配置域名访问和HTTPS。

# 安装Nginx
sudo apt install -y nginx  # Ubuntu
# 或
sudo yum install -y nginx  # CentOS

# 创建配置文件
sudo nano /etc/nginx/conf.d/oneapi.conf

配置文件内容：

server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名

    location / {
        proxy_pass http://127.0.0.1:3000;  # OneAPI端口
        # 如果是NewAPI，改为 proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket支持（对话功能需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
        proxy_buffering off;
    }
}

# 测试配置
sudo nginx -t

# 重启Nginx
sudo systemctl restart nginx

# 设置开机自启
sudo systemctl enable nginx

配置HTTPS（使用Let’s Encrypt）：

# 安装Certbot
sudo apt install -y certbot python3-certbot-nginx  # Ubuntu
# 或
sudo yum install -y certbot python3-certbot-nginx  # CentOS

# 申请证书
sudo certbot --nginx -d your-domain.com

# 自动续期测试
sudo certbot renew --dry-run

四、初始配置教程

4.1 首次登录设置

Step 1：修改管理员密码

- 登录后，点击右上角头像 → "个人设置"
- 修改密码为强密码
- 建议开启两步验证（如果支持）

Step 2：配置站点信息

- 进入 "系统设置" → "通用"
- 设置站点名称、描述
- 配置服务器地址（你的域名或IP）

4.2 添加第一个渠道（以OpenAI为例）

Step 1：获取OpenAI API密钥

- 访问 [platform.openai.com](https://platform.openai.com)
- 登录后进入 "API Keys" 页面
- 点击 "Create new secret key"
- 复制并保存密钥（只显示一次）

Step 2：在OneAPI/NewAPI中添加渠道

- 进入 "渠道管理" → 点击 "添加渠道"
填写信息：
    
        - **名称**：自定义，如"OpenAI官方"
        - **类型**：选择 "OpenAI"
        - **密钥**：粘贴你的API Key
        - **代理**：如果需要代理，填写代理地址（如 `https://api.openai.com`）
        - **模型**：选择支持的模型（如 gpt-4o, gpt-4, gpt-3.5-turbo）
    

- 点击 "测试" 按钮验证密钥是否有效
- 测试成功后，点击 "提交" 保存

4.3 添加其他模型渠道

添加Claude（Anthropic）渠道：

- 类型选择 "Anthropic Claude"
- 密钥填写你的Claude API Key
- 代理地址：`https://api.anthropic.com`（或你使用的代理地址）
- 模型选择：claude-3-5-sonnet-20241022, claude-3-opus 等

添加国内模型（以通义千问为例）：

- 类型选择 "阿里通义千问"
- 密钥填写你的DashScope API Key
- 代理地址通常不需要修改
- 模型选择：qwen-turbo, qwen-plus, qwen-max 等

4.4 创建访问令牌

添加渠道后，需要创建令牌才能使用API：

- 进入 "令牌管理" → 点击 "添加令牌"
填写信息：
    
        - **名称**：如"我的应用"
        - **额度**：设置可用额度（-1表示无限制）
        - **过期时间**：设置有效期
        - **可用模型**：选择允许访问的模型
    

- 点击 "提交" 创建令牌
- 复制生成的令牌（以 `sk-` 开头）

五、使用指南

5.1 基本API调用

OneAPI/NewAPI完全兼容OpenAI的API格式，你可以直接使用OpenAI的SDK。

Python示例：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",  # OneAPI/NewAPI生成的令牌
    base_url="http://你的服务器地址:3000/v1"  # OneAPI地址
    # 如果是NewAPI，端口可能是3001
)

# 普通对话
response = client.chat.completions.create(
    model="gpt-4o",  # 或其他模型
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手"},
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    temperature=0.7,
    max_tokens=1000
)

print(response.choices[0].message.content)

# 流式输出
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "写一首关于春天的诗"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Node.js示例：

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'sk-你的令牌',
    baseURL: 'http://你的服务器地址:3000/v1'
});

async function main() {
    const response = await client.chat.completions.create({
        model: 'gpt-4o',
        messages: [
            { role: 'system', content: '你是一个有帮助的助手' },
            { role: 'user', content: '你好，请介绍一下你自己' }
        ],
        temperature: 0.7,
        max_tokens: 1000
    });

    console.log(response.choices[0].message.content);
}

main();

curl示例：

curl http://你的服务器地址:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "你是一个有帮助的助手"},
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'

5.2 指定使用特定渠道

如果你想指定使用某个渠道（比如优先使用某个API Key），可以在请求中添加前缀：

# 模型名格式：渠道ID-模型名
model = "2-gpt-4o"  # 使用渠道ID为2的gpt-4o

5.3 负载均衡配置

当你有多个相同类型的渠道时，OneAPI/NewAPI会自动进行负载均衡：

- 添加多个相同类型的渠道（如多个OpenAI账号）
- 在渠道设置中配置优先级（数字越小优先级越高）
- 系统会自动轮询或按优先级分配请求
- 某个渠道出错时，自动切换到下一个可用渠道

5.4 在第三方客户端中使用

ChatGPT-Next-Web：

- 在设置中填写：OpenAI Base URL: `http://你的地址:3000`
- API Key填写OneAPI/NewAPI生成的令牌

LobeChat：

- 设置 → 语言模型 → OpenAI
- API Proxy Address: `http://你的地址:3000/v1`
- API Key填写令牌

Cursor/Windsurf等编程助手：

- 在AI设置中找到API配置
- 填写Base URL和API Key

六、高级配置

6.1 配置Midjourney（仅NewAPI）

NewAPI支持Midjourney绘图功能：

- 添加渠道时类型选择 "Midjourney"
- 配置Midjourney代理地址（如使用第三方API）
- 在令牌中开启 "绘画" 权限

6.2 配置TTS语音合成

支持OpenAI TTS和其他语音合成服务：

# TTS调用示例
curl http://你的地址:3000/v1/audio/speech \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "你好，这是一段测试语音",
    "voice": "alloy"
  }' \
  --output speech.mp3

6.3 用户分组配置（NewAPI）

NewAPI支持用户分组，不同分组可以有不同的配额和可用模型：

- 进入 "系统设置" → "用户分组"
- 创建分组，如"免费用户"、"付费用户"、"VIP用户"
为每个分组配置：
    
        - 可用模型列表
        - 速率限制（每分钟请求数）
        - 并发限制
        - 默认额度

6.4 配置Webhook通知

可以配置Telegram、邮件等通知方式，在渠道异常时收到提醒：

- 进入 "系统设置" → "通知"
- 配置Telegram Bot Token和Chat ID
- 配置通知规则（如余额不足、渠道异常等）

七、运维与监控

7.1 查看使用日志

OneAPI/NewAPI提供详细的使用日志：

- **日志查看**：进入 "日志" 页面，可以查看所有API调用记录
- **筛选功能**：按时间、用户、模型、渠道等筛选
- **统计分析**：查看Token使用量、费用统计等

7.2 数据库备份

SQLite备份（默认）：

# 备份数据目录
cp -r /opt/oneapi/data /backup/oneapi-$(date +%Y%m%d)

# 或者只备份数据库文件
cp /opt/oneapi/data/one-api.db /backup/one-api-$(date +%Y%m%d).db

MySQL备份：

# 使用mysqldump备份
mysqldump -u root -p oneapi > /backup/oneapi-$(date +%Y%m%d).sql

7.3 Docker命令速查

# 查看容器状态
docker ps | grep oneapi

# 查看实时日志
docker logs -f oneapi

# 重启服务
docker restart oneapi

# 停止服务
docker stop oneapi

# 更新到最新版本
cd /opt/oneapi
docker compose pull
docker compose up -d

# 进入容器（调试用）
docker exec -it oneapi /bin/sh

7.4 性能优化建议

- **使用MySQL**：如果用户量大，建议使用MySQL替代SQLite
- **配置缓存**：使用Redis缓存热点数据
- **CDN加速**：静态资源使用CDN
- **日志清理**：定期清理过期日志，避免数据库过大

八、常见问题解答（FAQ）

Q1：OneAPI和NewAPI选哪个？

选择OneAPI的理由：

- 追求简洁稳定
- 个人使用，不需要复杂功能
- 原版更新及时，社区支持好

选择NewAPI的理由：

- 需要更美观的界面
- 需要Midjourney、TTS等扩展功能
- 需要完善的充值和计费系统
- 商业化运营场景

Q2：如何切换模型？

在API调用时，修改 model 参数即可。例如：

- 使用GPT-4: `"model": "gpt-4"`
- 使用Claude: `"model": "claude-3-5-sonnet-20241022"`
- 使用通义千问: `"model": "qwen-max"`

Q3：报错"insufficient_quota"怎么办？

这个错误表示API额度不足：

- 检查提供商账号余额（如OpenAI账号）
- 检查OneAPI/NewAPI中令牌额度是否用完
- 充值后重试

Q4：如何实现高可用？

可以使用以下方式实现高可用：

- 配置多个渠道实现负载均衡
- 使用Docker Swarm或Kubernetes部署
- 配置数据库主从复制
- 使用Nginx做负载均衡

Q5：访问速度慢怎么优化？

- 使用地理位置更近的服务器
- 配置合适的代理
- 使用连接池
- 开启Gzip压缩

九、安全建议

- **修改默认密码**：首次登录后立即修改管理员密码
- **使用HTTPS**：配置SSL证书，避免API密钥明文传输
- **限制访问IP**：通过防火墙限制管理后台的访问IP
- **定期更换密钥**：定期更换API Key和令牌
- **监控使用情况**：设置异常告警，及时发现异常调用
- **最小权限原则**：给用户分配必要的最小权限
- **定期备份**：配置自动备份，防止数据丢失

十、总结

OneAPI和NewAPI是非常实用的AI模型管理工具，它们解决了多模型API管理的痛点：

- ✅ **统一接口**：一个地址访问所有模型
- ✅ **集中管理**：所有密钥在一个平台管理
- ✅ **灵活分发**：轻松创建和分发访问令牌
- ✅ **成本控制**：精确控制每个用户/应用的使用额度
- ✅ **高可用**：支持负载均衡和故障转移

无论你是个人开发者、小型团队还是企业用户，OneAPI/NewAPI都能帮助你更高效地管理和使用AI模型。现在就动手搭建你自己的AI模型聚合网关吧！

附录：资源链接

- **OneAPI官方仓库**：[github.com/songquanpeng/one-api](https://github.com/songquanpeng/one-api)
- **NewAPI官方仓库**：[github.com/Calcium-Ion/new-api](https://github.com/Calcium-Ion/new-api)
- **OneAPI文档**：[OneAPI Wiki](https://github.com/songquanpeng/one-api/wiki)
- **Docker Hub - OneAPI**：[justsong/one-api](https://hub.docker.com/r/justsong/one-api)
- **Docker Hub - NewAPI**：[calciumion/new-api](https://hub.docker.com/r/calciumion/new-api)
# linux # 运维 # 服务器
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

常驻网关崩溃恢复的代价：为什么你的 Agent 守护进程总在深夜挂掉？

avatar 龙虾开发者社区
cover

Agent 日历权限管理：从会议室预定到社交工程防御

avatar 龙虾开发者社区
cover

Agent 开发中密钥轮换的自动化实践：从泄露风险到安全凭据管理

avatar 龙虾开发者社区