详解One API安装、配置、部署全流程，嫌麻烦自己搭建？

---

什么是 One API

One API 是一个开源的 OpenAI 接口管理和分发系统，项目地址在 GitHub（songquanpeng/one-api）。它的核心价值在于：

• 多渠道聚合：把 OpenAI、Azure、Claude、Gemini、国内各家大模型统一接入，对外暴露标准的 OpenAI 接口格式

• Token 配额管理：给下游用户分配不同额度的 Key，做多租户管理

• 负载均衡与优先级：多个渠道之间按权重或优先级自动调度

• 计费统计：实时记录各渠道、各 Token 的用量与费用

对于个人开发者来说，最常见的用法是：自己有多个平台的 API Key，希望统一用一个地址调用，顺便做一层鉴权和额度控制。对于团队来说，可以用 One 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 后，下游即可通过以下方式调用：

暂时无法在飞书文档外展示此内容

环境变量说明

One API 支持通过环境变量控制行为，常用配置：

• PORT：监听端口，默认 3000

• SQL_DSN：数据库连接串，不填则用 SQLite

• SESSION_SECRET：Session 加密密钥，生产环境必须设置

• INITIAL_ROOT_TOKEN：初始 root 令牌（方便自动化部署时直接配置）

• MEMORY_CACHE_ENABLED：开启内存缓存，提升性能

---

常见问题

1. 渠道测试失败，提示连接超时

通常是服务器无法访问目标 API 端点。OpenAI 的接口在国内服务器上需要代理。可以在 Docker 启动参数里加上 HTTP 代理环境变量：

暂时无法在飞书文档外展示此内容

或者换用国内可直连的中转节点，省去自建代理的麻烦。

2. 数据库迁移失败

从 SQLite 迁移到 MySQL 时，建议先备份 /data/one-api.db，再修改 SQL_DSN 重启。One API 会自动建表，但历史数据需要手动迁移。

3. 令牌额度消耗异常

检查「日志」页面，按令牌筛选，查看每次请求的 Token 消耗。注意 One API 的额度单位是"$0.000001"，即 1 美元 = 1,000,000 配额单位，设置时不要弄错数量级。

4. 多实例部署时 Session 不一致

多台机器部署时，必须设置相同的 SESSION_SECRET 和 REDIS_CONN_STRING，否则负载均衡后用户会频繁掉登录。

5. 前端页面打开空白

检查 web/dist 目录是否正确构建，或者检查 Nginx 的静态资源路径配置。Docker 版本无此问题。

---

托管替代方案

自建 One API 需要：准备服务器、配置出海网络、维护更新、处理各种运维问题。如果你的需求是「快速接入 API、稳定调用」而不是「深度定制中转网关」，可以考虑直接使用现成的托管服务。

jiekou.ai 是一个开箱即用的 API 中转平台，支持 GPT-4o、Claude 3.5/3.7、Gemini 等主流模型，国内直连免翻墙，按量计费不需要预先订阅海外服务。

用法和标准 OpenAI SDK 完全兼容，只需要换一个 base_url：

暂时无法在飞书文档外展示此内容

对于大多数个人项目和小团队来说，托管方案的稳定性和维护成本优势比较明显——省下来的时间可以用来写业务代码。当然，如果你有多租户管理、私有化部署、深度定制的需求，自建 One API 依然是最灵活的选择。

---

结语

One API 是目前社区最活跃的开源 API 网关项目之一，功能完善、部署灵活，适合有一定运维能力的开发者自建使用。本文覆盖了从环境准备、Docker 部署、配置管理到常见问题排查的完整流程，按步骤操作基本可以在半小时内搭起一套可用的 API 中转服务。

如果你在搭建过程中遇到问题，优先查阅官方 GitHub 的 Issues 和 Wiki，社区积累的解决方案非常丰富。对于不想花时间在运维上的开发者，jiekou.ai 这类托管方案可以作为快速启动的替代选项。

希望这篇教程对你有帮助，如有问题欢迎在评论区交流。

---