OneAPI NewAPI 完全指南从零开始搭建你的AI模型聚合网关在AI大模型百花齐放的今天我们常常需要同时使用多个模型提供商的服务——OpenAI的GPT-4、Anthropic的Claude、Google的Gemini、国内的文心一言、通义千问等等。每个提供商都有自己的API接口和密钥管理起来非常繁琐。OneAPI和NewAPI应运而生它们是开源的API管理和分发系统让你可以用统一的接口访问所有AI模型。一、什么是OneAPI和NewAPI1.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 --versionCentOS/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 --version3.3 部署OneAPI方式一使用Docker Compose推荐创建项目目录mkdir -p /opt/oneapi cd /opt/oneapi创建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: - TZAsia/Shanghai # SQLite数据库默认适合个人使用 - SQL_DSNsqlite:///data/one-api.db # 如需使用MySQL取消下面的注释并填写配置 # - SQL_DSNroot:passwordtcp(localhost:3306)/oneapi logging: driver: json-file options: max-size: 10m max-file: 3启动服务# 启动 docker compose up -d # 查看日志 docker compose logs -f # 检查状态 docker compose ps访问OneAPI打开浏览器访问http://你的服务器IP:3000默认管理员账号root默认密码123456请立即修改3.4 部署NewAPI创建项目目录mkdir -p /opt/newapi cd /opt/newapi创建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: - TZAsia/Shanghai # SQLite数据库默认 - SQL_DSNsqlite:///data/new-api.db # 如需使用MySQL取消下面的注释 # - SQL_DSNroot:passwordtcp(localhost:3306)/newapi # 站点名称可选 - SESSION_SECRETrandom_secret_string_here logging: driver: json-file options: max-size: 10m max-file: 3启动服务docker compose up -d访问NewAPI打开浏览器访问http://你的服务器IP:3001默认管理员账号root默认密码1234563.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配置站点信息- 进入 系统设置 → 通用 - 设置站点名称、描述 - 配置服务器地址你的域名或IP4.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 添加其他模型渠道添加ClaudeAnthropic渠道- 类型选择 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_keysk-你的令牌, # OneAPI/NewAPI生成的令牌 base_urlhttp://你的服务器地址:3000/v1 # OneAPI地址 # 如果是NewAPI端口可能是3001 ) # 普通对话 response client.chat.completions.create( modelgpt-4o, # 或其他模型 messages[ {role: system, content: 你是一个有帮助的助手}, {role: user, content: 你好请介绍一下你自己} ], temperature0.7, max_tokens1000 ) print(response.choices[0].message.content) # 流式输出 stream client.chat.completions.create( modelgpt-4o, messages[ {role: user, content: 写一首关于春天的诗} ], streamTrue ) 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-4o5.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仅NewAPINewAPI支持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.mp36.3 用户分组配置NewAPINewAPI支持用户分组不同分组可以有不同的配额和可用模型- 进入 系统设置 → 用户分组 - 创建分组如免费用户、付费用户、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).dbMySQL备份# 使用mysqldump备份 mysqldump -u root -p oneapi /backup/oneapi-$(date %Y%m%d).sql7.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/sh7.4 性能优化建议- **使用MySQL**如果用户量大建议使用MySQL替代SQLite - **配置缓存**使用Redis缓存热点数据 - **CDN加速**静态资源使用CDN - **日志清理**定期清理过期日志避免数据库过大八、常见问题解答FAQQ1OneAPI和NewAPI选哪个选择OneAPI的理由- 追求简洁稳定 - 个人使用不需要复杂功能 - 原版更新及时社区支持好选择NewAPI的理由- 需要更美观的界面 - 需要Midjourney、TTS等扩展功能 - 需要完善的充值和计费系统 - 商业化运营场景Q2如何切换模型在API调用时修改model参数即可。例如- 使用GPT-4: model: gpt-4 - 使用Claude: model: claude-3-5-sonnet-20241022 - 使用通义千问: model: qwen-maxQ3报错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)