跳到主要内容
AI教程

One API 部署与使用教程：用统一 OpenAI API 接入多种大模型

本教程介绍如何部署 One API、添加模型渠道、创建访问令牌，并通过兼容 OpenAI 的接口调用多种大模型，同时讲解数据库、缓存、负载均衡和多机部署要点。

AI我搜编辑部阅读约 14 分钟
One API 部署与使用教程：用统一 OpenAI API 接入多种大模型

One API 是什么

One API 是一个开源的大模型 API 管理与中继系统。它将不同模型供应商的接口统一为标准的 OpenAI API 格式，让客户端可以使用相同的 API Base 和访问令牌调用多个上游渠道。

项目支持 OpenAI 与 Azure OpenAI、Anthropic Claude、Google Gemini、Mistral、豆包、文心一言、通义千问、讯飞星火、ChatGLM、腾讯混元、Moonshot AI、DeepSeek、Ollama、Cohere、Groq、Cloudflare Workers AI、xAI 等多种服务。

合规提醒：使用 One API 时必须遵守 OpenAI 使用条款及适用的法律法规，不得用于非法用途。请勿面向中国地区公众提供未经备案的生成式人工智能服务。

核心功能

  • 统一接口：通过兼容 OpenAI 的 API 格式访问不同大模型。

  • 多渠道与负载均衡：配置多个上游渠道，不指定渠道时自动进行负载均衡。

  • 流式输出：支持 stream 模式，可实现打字机式响应。

  • 令牌管理：可设置过期时间、额度、允许的 IP 范围和允许访问的模型。

  • 渠道管理：支持批量创建渠道、设置模型列表、渠道分组和模型映射。

  • 额度与计费：支持额度明细、用户分组、渠道分组、倍率和美元额度显示。

  • 可靠性：支持失败自动重试、多机部署、Redis 缓存和数据库连接配置。

  • 管理扩展：可通过系统访问令牌调用管理 API，无需修改源代码即可扩展管理能力。

  • 用户系统：支持邮箱、飞书、GitHub 和微信公众号等登录注册方式。

  • 界面定制：可定制系统名称、Logo、页脚、首页、关于页面和主题。

使用 Docker 快速部署

准备数据目录

SQLite 适合快速体验或低并发部署。首先准备一个可写的数据目录，数据库和日志会保存在该目录中。

mkdir -p /home/ubuntu/data/one-api

启动 One API

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

-p 3000:3000 左侧的端口是宿主机端口，可以按需修改。启动后访问 http://localhost:3000/。

初始用户名为 root，初始密码为 123456。

重要：首次使用 root 登录后必须立即修改默认密码。

如果 Docker Hub 镜像无法拉取，可以将 justsong/one-api 替换为 ghcr.io/songquanpeng/one-api。如果容器启动失败，可根据项目问题记录尝试添加 --privileged=true。

使用 MySQL 部署

并发量较大时，README 明确建议设置 SQL_DSN，不要继续使用 SQLite。数据库 oneapi 需要预先创建，但数据表会由程序自动创建。

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

请将用户名、密码、地址和端口替换为实际数据库参数。如果 MySQL 运行在宿主机上，可根据网络环境添加 --network="host"，使容器能够访问宿主机数据库。

使用 Docker Compose

仓库提供 Docker Compose 启动方式，目前说明中使用 MySQL，并将数据存储在 ./data/mysql 目录。

docker-compose up -d
docker-compose ps

从源码手动部署

如需自行构建，请准备 Node.js、npm 和 Go 环境，然后依次构建前端与后端。

git clone https://github.com/songquanpeng/one-api.git
cd one-api/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

--port 用于指定监听端口，默认值为 3000；--log-dir 用于指定日志目录。还可以使用 --version 查看版本，或使用 --help 查看帮助。

完成基础配置

  1. 打开 One API 管理页面，使用 root 账号登录并修改默认密码。

  2. 进入渠道页面，选择对应的供应商类型并添加上游 API Key。

  3. 根据上游能力设置渠道支持的模型列表和分组。

  4. 进入令牌页面，创建供客户端使用的访问令牌。

  5. 根据需要为令牌设置额度、有效期、允许的 IP 范围以及可访问模型。

One API 本身开箱即用。其他配置可以通过管理界面、环境变量、.env 文件或命令行参数完成。使用 .env 时，可参考仓库中的 .env.example 并将其重命名为 .env。

通过 OpenAI 兼容接口使用

客户端需要把 API Base 设置为你的 One API 部署地址，把 API Key 设置为刚才创建的 One API 令牌。具体 Base URL 格式取决于客户端；对于 OpenAI 官方库，README 给出的配置形式如下：

OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1"

请求会先到达 One API，再由 One API 转发至 OpenAI、Azure 或其他模型渠道。对于接口格式不同的上游，One API 会处理中继所需的请求体和返回体转换。

与现有客户端配合

多数支持自定义 OpenAI 接口地址的客户端都可以接入。以 ChatGPT Next Web 为例，先运行客户端容器：

docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-web

然后在客户端页面中填写 One API 接口地址和 One API 令牌。端口应避免与 One API 使用的 3000 冲突。

ChatGPT Web 也可以通过环境变量连接 One API：

docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.example.com -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-web

请将示例域名和令牌替换为自己的配置。

进阶配置技巧

指定渠道或启用负载均衡

默认情况下，不指定渠道的请求会在多个可用渠道之间进行负载均衡。管理员创建的令牌还可以在令牌后追加渠道 ID，强制本次请求由特定渠道处理：

Authorization: Bearer ONE_API_KEY-CHANNEL_ID

普通用户创建的令牌不能通过这种方式指定渠道 ID。

谨慎使用模型映射

模型映射可以把用户请求的模型重定向到另一个模型。但 README 提醒，如无必要不要设置模型映射，因为启用后请求体会被重新构造，而不是直接透传，部分尚未正式支持的字段可能无法成功传递。

使用 Redis 缓存

设置 REDIS_CONN_STRING 后，One API 会使用 Redis 作为缓存：

REDIS_CONN_STRING=redis://default:redispw@localhost:49153

如果数据库访问延迟很低，没有必要启用 Redis，因为缓存可能带来数据同步滞后。哨兵或集群模式可将该变量设为节点列表，并配合 REDIS_PASSWORD 和 REDIS_MASTER_NAME。

优化数据库连接

数据库连接可通过以下环境变量调整：

  • SQL_MAX_IDLE_CONNS：最大空闲连接数，默认 100。

  • SQL_MAX_OPEN_CONNS：最大打开连接数，默认 1000。

  • SQL_CONN_MAX_LIFETIME：连接最大生命周期，默认 60 分钟。

  • BATCH_UPDATE_ENABLED=true：启用数据库批量更新聚合，可能缓解连接数过多，但会造成额度更新延迟。

  • BATCH_UPDATE_INTERVAL=5：设置批量更新聚合间隔，单位为秒。

如果出现 Error 1040: Too many connections，应适当减小 SQL_MAX_OPEN_CONNS，也可以评估是否启用批量更新。

配置会话、超时与代理

  • SESSION_SECRET：设置固定会话密钥，重启后已登录用户的 Cookie 仍然有效。

  • RELAY_TIMEOUT：设置中继请求超时，单位为秒。

  • RELAY_PROXY：让中继请求通过指定代理访问上游 API。

  • USER_CONTENT_REQUEST_TIMEOUT：设置下载用户上传内容的超时时间。

  • USER_CONTENT_REQUEST_PROXY：为图片等用户上传内容配置下载代理。

配置渠道监测

可以定期更新渠道余额并测试渠道可用性：

CHANNEL_UPDATE_FREQUENCY=1440
CHANNEL_TEST_FREQUENCY=1440
POLLING_INTERVAL=5

前两个变量的单位为分钟，POLLING_INTERVAL 的单位为秒，用于控制批量操作时的请求间隔。

配置多机部署

多机部署不能继续依赖本地 SQLite。所有节点必须连接同一个 MySQL 数据库，并保持一致的会话配置。

  1. 所有服务器设置相同的 SESSION_SECRET。

  2. 所有服务器通过 SQL_DSN 连接同一个 MySQL 数据库。

  3. 从服务器设置 NODE_TYPE=slave，未设置时默认为主服务器。

  4. 使用 SYNC_FREQUENCY 定期从数据库同步配置。

  5. 从服务器可设置 FRONTEND_BASE_URL，将页面请求重定向到主服务器。

  6. 可在各从服务器部署 Redis 并设置 REDIS_CONN_STRING，减少缓存有效期内的数据库访问。

  7. 如果主服务器访问数据库的延迟较高，也应考虑启用 Redis 和定期同步。

SESSION_SECRET=random_string
SQL_DSN=root:123456@tcp(database:3306)/oneapi
NODE_TYPE=slave
SYNC_FREQUENCY=60
FRONTEND_BASE_URL=https://openai.example.com
REDIS_CONN_STRING=redis://default:redispw@localhost:49153

配置 Nginx 与 HTTPS

生产环境可使用 Nginx 反向代理 One API。对于响应时间较长的模型，应适当增加读取超时。

server {
    server_name openai.example.com;

    location / {
        client_max_body_size 64m;
        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;
    }
}

在 Ubuntu 上可以使用 Certbot 申请并配置 HTTPS：

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

常见问题排查

  • 提示额度不足：除账户额度外，还要检查令牌自身的额度上限。

  • 提示无可用渠道：检查用户分组、渠道分组以及渠道支持的模型列表。

  • 当前分组负载已饱和：通常表示上游渠道返回了 429。

  • 客户端提示 Failed to fetch：检查接口地址、API Key 和 HTTPS 配置；HTTPS 页面中的 HTTP 请求可能被浏览器拦截。

  • 渠道测试返回 invalid character：上游返回的可能是 HTML 而非合法 JSON，部署服务器 IP 或代理节点也可能被 Cloudflare 封禁。

  • 升级后担心数据丢失：MySQL 数据不会因正常升级丢失；SQLite 必须正确挂载数据卷以持久化 one-api.db。

结语

One API 适合将多个模型供应商统一到兼容 OpenAI 的调用方式中，并集中管理渠道、令牌、额度和用户。个人或低并发场景可以从 Docker 与 SQLite 开始；高并发和多机环境应使用共享数据库，并根据延迟情况谨慎引入 Redis。投入使用前，请修改默认密码、配置 HTTPS、持久化数据，并确保服务符合相关条款和法律法规。

项目采用 MIT 协议开源，但 README 要求在页面底部保留署名及项目链接；如需移除署名，必须先获得授权。更多信息可查看 One API GitHub 仓库。