什么是 One API
One API是一个OpenAI的开源接口管理和分发系统，项目地址在GitHub（songquanpeng/one-api）。其核心价值在于：
-
多渠道聚合：将OpenAI、Azure、Claude、Gemini、国内各家大模型统一接入，对外暴露标准的OpenAI接口格式
-
代币损耗管理：给下游用户分配不同额度的Key，做多机场管理
-
负载均衡与优先级：多个渠道之间按权重或优先级自动调度
-
设备统计：实时记录各渠道、各Token的用量与费用
对于个人开发者来说，最常见的方式是：自己有多个平台的API Key，希望统一用一个地址调用，顺便做层级鉴权和额度控制。对于团队来说，可以用一个API做内部的AI网关，避免把真实的Key暴露给每个成员。
环境准备
在开始One API搭建之前，确认以下环境已就绪：
服务器要求：
-
操作系统：Linux（Ubuntu 20.04+ / Debian 11+ 劳动力）
-
内存：最低512MB，推荐1GB以上
-
磁盘： 至少 5GB 可用空间
-
网络：服务器需要能够访问目标AI服务商的API端点（如OpenAI需要出海线路）
依赖软件：
-
Docker 20.10+（推荐方式）
-
或 Go 1.21+（手动编译方式）
-
MySQL 5.7+ 或 SQLite（默认使用SQLite，生产环境建议MySQL）
安装 Docker（Ubuntu 示例）：
暂时无法在飞书文档外展示此内容
安装步骤部署
方式一：Docker部署（推荐）
这是最快的方式，5分钟内就可以跑起来。
1.使用SQLite（适合个人使用）：
暂时无法在飞书文档外展示此内容
2.使用MySQL（适合生产环境）：
首先启动MySQL容器：
暂时无法在飞书文档外展示此内容
重新启动One API，指定数据库连接：
暂时无法在飞书文档外展示此内容
3.使用Docker Compose（推荐生产部署）：
创建docker-compose.yml：
暂时无法在飞书文档外展示此内容
启动：
暂时无法在飞书文档外展示此内容
方式二：手动编译安装
如果你想自定义代码，或者不方便使用 Docker，可以手动编译。
1.克隆仓库并基础前端：
暂时无法在飞书文档外展示此内容
2. 编译：
暂时无法在飞书文档外展示此内容
3.运行：
暂时无法在飞书文档外展示此内容
建议配合systemd或supervisor做进程守护。
配置说明
配置完成后，访问http://your-server-ip:3000，管理员默认账号密码为root / 123456，首次登录后立即修改密码。
添加渠道（上游API）
进入「渠道」页面，点击「添加渠道」：
-
类型：选择对应的服务商，如 OpenAI、Azure OpenAI、Anthropic Claude 等
-
名称：定制，方便识别
-
密钥：填入对应服务商的API Key
-
模型：选择该渠道支持的模型列表
-
优先级：数字增大优先级增益
配置完成后点「测试」，确保通道联通正常。
创建Token（终端分发Key）
进入「令牌」页面，点击「添加令牌」：
-
名称：标识用途，如“开发测试”、“产品服务”
-
上限：设置最大使用量（以Token计数），-1表示无限制
-
过渡时间：任选，设置Key的最近
-
IP白名单：可选，限制只有特定IP才能使用
生成Token后，下游可以通过以下方式调用：
暂时无法在飞书文档外展示此内容
环境指标说明
一个API支持通过环境变量控制行为，常用配置：
-
PORT：监听端口，默认3000 -
SQL_DSN：数据库连接串，不填则用SQLite -
SESSION_SECRET：会话加密密钥，生产环境必须设置 -
INITIAL_ROOT_TOKEN：初始root token（方便自动化部署时直接配置） -
MEMORY_CACHE_ENABLED：开启内存缓存，提升性能
常见问题
1.渠道测试失败，提示连接超时
通常是服务器无法访问目标 API 端点。OpenAI 的接口在内部服务器上需要代理。可以在 Docker 启动参数里加上 HTTP 代理环境变量：
暂时无法在飞书文档外展示此内容
或者换用国内可直连的中转节点，省去自建代理的麻烦。
2. 数据库迁移失败
从SQLite迁移到MySQL时，先备份/data/one-api.db，再修改SQL_DSN重启。建议一个API会自动建表，但历史数据需要手动迁移。
3. 代币挖矿消耗异常
检查「日志」页面，按令牌筛选，查看每次请求的代币消耗。注意一个 API 的额度单位为“$0.000001”，即 1 美元 = 1,000,000 消耗单位，设置时不要弄错数量级别。
4. 多实例部署时会话不一致
多台机器配置时，必须设置相同的SESSION_SECRET和REDIS_CONN_STRING，否则负载均衡后用户会关闭掉登录。
5.前端页面打开空白
检查web/dist目录是否正确构建，或者检查 Nginx 的静态资源路径配置。Docker 版本无此问题。
托管替代方案
自建一个API需要：准备服务器、配置出海网络、维护更新、处理各种运维问题。如果您的需求是「快速接入API、稳定调用」而不是「深度定制中转网关」，可以考虑直接使用现成的托管服务。
jiekou.ai 是一个开箱即用的 API 中转平台，支持 GPT-4o、Claude 3.5/3.7、Gemini 等主流模型，国内直连免翻墙，按量无需预先订阅海外服务。
最和标准的OpenAI SDK完全兼容，只需要换一个base_url：
暂时无法在飞书文档外展示此内容
对于大多数个人项目和小团队来说，托管方案的稳定性和维护成本优势比较明显——省下来的时间可以用来写业务代码。当然，如果你有机场管理、内部化部署、深度定制的需求，自建一个API仍然是最灵活的选择。
结语
One API 是目前社区最活跃的开源 API 网关项目，功能完善、部署灵活，适合有一定运维能力的开发者自建使用。本文涵盖了从环境准备、Docker 部署、配置管理到常见问题排查的完整流程，按步骤操作基本可以在半小时内搭起一套可用的 API 中转服务。
如果你在搭建过程中遇到问题，优先查阅官方 GitHub 的 Issues 和 Wiki，社区积累的解决方案非常丰富。对于不想花时间在运维上的开发者，jiekou.ai 这类托管方案可以作为快速启动的替代选项。
希望这篇教程对你有帮助，如有问题欢迎在评论区交流。
