详解One API安装、配置、部署全流程嫌麻烦自己搭建什么是 One APIOne API 是一个开源的 OpenAI 接口管理和分发系统项目地址在 GitHubsongquanpeng/one-api。它的核心价值在于多渠道聚合把 OpenAI、Azure、Claude、Gemini、国内各家大模型统一接入对外暴露标准的 OpenAI 接口格式Token 配额管理给下游用户分配不同额度的 Key做多租户管理负载均衡与优先级多个渠道之间按权重或优先级自动调度计费统计实时记录各渠道、各 Token 的用量与费用对于个人开发者来说最常见的用法是自己有多个平台的 API Key希望统一用一个地址调用顺便做一层鉴权和额度控制。对于团队来说可以用 One API 做内部的 AI 网关避免把真实 Key 暴露给每个成员。环境准备在开始 One API 搭建之前确认以下环境已就绪服务器要求操作系统LinuxUbuntu 20.04 / Debian 11 均可内存最低 512MB推荐 1GB 以上磁盘至少 5GB 可用空间网络服务器需要能访问目标 AI 服务商的 API 端点如 OpenAI 需要出海线路依赖软件Docker 20.10推荐方式或 Go 1.21手动编译方式MySQL 5.7 或 SQLite默认使用 SQLite生产环境建议 MySQL安装 DockerUbuntu 示例暂时无法在飞书文档外展示此内容安装部署步骤方式一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监听端口默认 3000SQL_DSN数据库连接串不填则用 SQLiteSESSION_SECRETSession 加密密钥生产环境必须设置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 这类托管方案可以作为快速启动的替代选项。希望这篇教程对你有帮助如有问题欢迎在评论区交流。