从安装到配置：One API多模型管理平台完整使用指南-开发者社区

从安装到配置：One API多模型管理平台完整使用指南

1. 为什么你需要一个统一的大模型接入层

你是否遇到过这样的情况：

同时在用 OpenAI、通义千问、文心一言和 Claude，但每个平台都要单独申请密钥、写不同格式的请求代码？
想给团队共享模型能力，又担心 API Key 泄露或额度失控？
客户要调用大模型服务，你得手动对接多个厂商接口，改一次参数就要重测所有模型？

One API 就是为解决这些问题而生的——它不是另一个大模型，而是一个智能路由中枢。你可以把它理解成“大模型世界的网关路由器”：所有请求都发给它，它自动分发到后端最合适的模型服务商，并统一返回标准 OpenAI 格式响应。

它的核心价值很实在：

对开发者：写一套代码，就能调用 20+ 主流模型，无需反复适配各家 API
对管理者：集中管控密钥、额度、IP 访问、模型权限，告别密钥满天飞
对运营者：支持兑换码、用户分组、邀请奖励、充值链接，开箱即用商业闭环
对个人用户：单文件/一键 Docker 部署，3 分钟完成本地私有化大模型代理服务

这不是概念产品，而是已在数千个技术团队中稳定运行的生产级工具。接下来，我们就从零开始，带你走完从安装、登录、配置到实际调用的全流程。

2. 两种部署方式：Docker 命令行 vs docker-compose（推荐）

One API 提供极简部署体验，无论你是命令行老手还是刚接触容器的新手，都能快速上手。我们推荐优先使用docker-compose方式——它更清晰、易维护、适合长期使用。

2.1 准备工作：三步搞定环境

在开始前，请确认你已完成以下准备：

已安装 Docker 和 docker-compose（Linux/macOS 可通过包管理器安装；Windows 推荐使用 Docker Desktop）
创建用于持久化数据的目录（避免容器重启后配置丢失）
准备好至少一个大模型平台的 API Key（如 OpenAI、通义千问、文心一言等，后续配置渠道时需要）

以 Linux 系统为例，创建标准目录结构：

mkdir -p /share/Container/oneapi/data

这个/share/Container/oneapi/data目录将作为 One API 的数据根目录，所有配置、日志、数据库都会保存在这里。

重要提醒：首次登录系统后，请务必立即修改默认密码123456。这是系统安全的第一道防线。

2.2 方式一：单命令快速启动（适合尝鲜）

打开终端，执行以下命令即可拉起服务：

docker run --name one-api -d --restart always -p 13000:3000 -e TZ=Asia/Shanghai -v /share/Container/oneapi/data:/data justsong/one-api

各参数含义说明：

参数	说明
`--name one-api`	为容器指定名称，便于识别和管理
`-d`	后台运行（detached 模式）
`--restart always`	容器异常退出或系统重启后自动恢复
`-p 13000:3000`	将宿主机 13000 端口映射到容器内服务端口 3000
`-e TZ=Asia/Shanghai`	设置容器时区为中国标准时间
`-v /share/Container/oneapi/data:/data`	挂载数据目录，确保配置不丢失
`justsong/one-api`	官方镜像名，持续更新，稳定可靠

执行后，可通过docker ps查看容器是否正常运行。稍等 10–20 秒，服务即就绪。

2.3 方式二：docker-compose 部署（推荐用于生产）

相比单命令，docker-compose.yml更清晰、可复用、易扩展。在/share/Container/oneapi目录下创建文件docker-compose.yml，内容如下：

version: '3.8' services: oneapi: container_name: oneapi image: justsong/one-api:latest restart: unless-stopped ports: - "13000:3000" volumes: - "/share/Container/oneapi/data:/data" environment: - TZ=Asia/Shanghai # 可选：添加健康检查（适用于集群编排） # healthcheck: # test: ["CMD", "curl", "-f", "http://localhost:3000/health"] # interval: 30s # timeout: 10s # retries: 3

保存后，在该目录下执行：

cd /share/Container/oneapi docker-compose up -d

服务启动后，可通过以下命令验证状态：

docker-compose logs -f oneapi # 实时查看日志 docker-compose ps # 查看运行状态

成功标志：日志中出现Server is running on http://0.0.0.0:3000，且无报错。

3. 首次登录与基础安全设置

服务启动后，在浏览器中访问：http://你的服务器IP:13000（例如http://192.168.1.100:13000）

你会看到简洁的登录界面：

用户名：root
密码：123456

再次强调：登录成功后的第一件事，就是修改密码！
进入【设置】→【个人设置】→【修改密码】，设置强密码并保存。

3.1 界面概览：7 大核心模块一目了然

登录后，左侧导航栏清晰划分出 7 个功能区域，它们构成了 One API 的管理骨架：

渠道管理：添加和配置各类大模型服务商（OpenAI、通义、文心等）
令牌管理：生成供客户端调用的 API Token（类似 OpenAI 的 sk-xxx）
兑换管理：批量生成充值兑换码（面向商业场景）
充值管理：用户使用兑换码为账户充值额度
用户管理：创建、禁用、分组管理用户（支持普通用户、VIP、SVIP）
日志：查看额度消耗、充值记录、API 调用详情
设置：系统级配置，包括运营规则、邮箱通知、界面定制等

这些模块并非全部需要立刻配置。如果你只是个人使用，只需完成「渠道管理」+「令牌管理」两步，即可开始调用。

4. 核心配置实战：让 One API 真正“连上”大模型

One API 的强大，源于它能统一调度真实的大模型服务。这一步，就是把你的 API Key “告诉”它。

4.1 添加第一个渠道：以 OpenAI 为例

进入【渠道管理】→【添加渠道】，填写以下关键信息：

字段	填写说明	示例
类型	选择服务提供商	`OpenAI`
名称	自定义标识，方便识别	`我的OpenAI主账号`
分组	该渠道对哪些用户分组开放	勾选`default`（所有用户可用）
模型	支持的模型列表（自动填充）	`gpt-3.5-turbo`,`gpt-4-turbo`（可多选）
密钥	你的 OpenAI API Key	`sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
代理	如需走代理（国内用户常用）	`https://your-proxy.com/v1`（留空则直连）

提交后，渠道状态显示为「启用」，即表示已成功接入。

小技巧：One API 支持同一类型多个渠道。比如你可以添加：
渠道 A：OpenAI 免费试用额度（限制额度 10 美元）
渠道 B：OpenAI 付费账号（不限额）
渠道 C：Azure OpenAI（填入 Azure endpoint + API key）
后续可通过「负载均衡」策略自动分配请求，实现成本与性能平衡。

4.2 扩展支持：快速接入国内主流模型

One API 对中文生态支持极为友好。添加国内模型时，仅需几步：

通义千问（Qwen）：类型选Aliyun→ 密钥填 DashScope API Key → 模型选qwen-max,qwen-plus
文心一言（ERNIE Bot）：类型选Baidu→ 填入Access Token（需在百度云控制台获取）
讯飞星火（Spark）：类型选Xunfei→ 填入AppID、APIKey、APISecret（三者缺一不可）
字节豆包（Doubao）：类型选VolcEngine→ 使用火山引擎 Access Key ID + Secret

所有国内模型均预置了正确的 endpoint 和鉴权方式，无需手动拼接 URL 或构造 header。

注意：部分平台（如文心、讯飞）需先在对应云平台开通服务、获取凭证，One API 仅负责标准化接入。

4.3 高级能力：负载均衡与失败重试

当一个模型有多个渠道（例如两个不同地区的 OpenAI 代理），One API 可自动实现：

轮询（Round Robin）：请求均匀分发到各渠道
权重分配：为不同渠道设置调用概率（如主渠道 80%，备用渠道 20%）
自动故障转移：某渠道超时或返回错误时，自动重试其他渠道

开启方式：在【渠道管理】列表页，点击渠道右侧「编辑」→ 勾选「启用负载均衡」→ 设置权重值。

这对保障服务稳定性至关重要——尤其当你依赖多个第三方代理时，One API 成为了你 API 调用的“保险丝”。

5. 创建令牌：你的第一个可调用 API Key

渠道配置好后，下一步是生成客户端可用的 Token。它就像一把“万能钥匙”，对外暴露，但受 One API 全面管控。

5.1 创建令牌：3 个关键设置

进入【令牌管理】→【添加令牌】，填写：

名称：描述性命名，如ChatGPT-Next-Web 专用
过期时间：可设为“永不过期”或指定日期（建议测试期设 7 天，上线后设 1 年）
额度：限制该 Token 最大可消耗额度（单位：美元，如50表示最多消耗 50 美元）

提交后，系统生成一串以sk-开头的长字符串——这就是你的 One API Token。

5.2 三种格式一键复制：无缝对接主流客户端

One API 智能识别常用前端项目，点击 Token 右侧「复制」按钮，可直接获取：

ChatGPT-Next-Web 格式：https://your-server:13000/api+Bearer sk-xxx
AMA 问天格式：https://your-server:13000/v1+Authorization: Bearer sk-xxx
Opencat 格式：https://your-server:13000+sk-xxx

无需手动拼接，复制即用。这意味着，你只需修改前端项目的 API 地址和 Key，就能瞬间切换底层模型服务商。

5.3 权限精细化：按用户分组控制模型可见性

One API 支持「渠道分组」与「用户分组」双重控制。例如：

创建用户分组：vip（高级用户）、svip（企业客户）
在渠道中，为vip分组只勾选gpt-4-turbo和qwen-max
为svip分组额外增加claude-3-opus和gemini-1.5-pro

这样，不同等级用户登录后，只能看到并调用自己权限范围内的模型，真正实现“一平台，多层级”。

6. 实际调用演示：用 Python 发起第一个请求

配置完成后，是时候验证效果了。以下是一个标准的 OpenAI 兼容调用示例（Python + requests）：

import requests import json # 替换为你的 One API 地址和 Token BASE_URL = "http://localhost:13000/v1" TOKEN = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" headers = { "Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json" } data = { "model": "gpt-3.5-turbo", "messages": [ {"role": "user", "content": "用一句话解释什么是大语言模型？"} ], "stream": False } response = requests.post(f"{BASE_URL}/chat/completions", headers=headers, json=data) print(json.dumps(response.json(), indent=2, ensure_ascii=False))

正常响应将返回标准 OpenAI JSON 格式，包含choices[0].message.content字段。

🔁 流式响应支持：将"stream": True，即可获得逐字返回的“打字机效果”，适用于聊天界面实时渲染。

你也可以用curl快速验证：

curl -X POST "http://localhost:13000/v1/chat/completions" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "你好"}] }'

只要返回200 OK和合理文本，说明整个链路已打通。

7. 进阶实用技巧：提升日常使用效率

One API 不仅功能全，还藏有不少提升体验的“隐藏技能”：

7.1 指定渠道调用：精准控制请求走向

默认情况下，请求会由负载均衡策略分发。但有时你需要强制走某个渠道（如调试特定代理），只需在 Token 后追加-渠道ID：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-123

其中123是渠道列表页中该渠道的 ID（鼠标悬停 ID 列可见）。此功能仅对管理员创建的 Token 生效。

7.2 自定义前端界面：打造专属品牌

进入【设置】→【其他设置】，可：

修改系统名称（如改为“智算中台”）
上传 Logo 图片（支持 PNG/JPG，建议 120×40 像素）
使用 HTML/Markdown 编辑首页公告，或嵌入 iframe 展示内部文档

无需修改代码，纯后台配置，10 秒生效。

7.3 日志追踪：快速定位问题根源

【日志】模块提供双维度查询：

按用户：查看某账号的所有调用记录、消耗额度、错误详情
按渠道：统计各模型服务商的调用量、成功率、平均延迟

当某次请求失败时，点击日志中的「详情」，可查看完整的请求体、响应体、HTTP 状态码及错误堆栈，大幅缩短排障时间。

8. 总结：One API 是你大模型工程化的起点

回顾整个流程，你已经完成了：

用一条命令或一份 YAML 文件，完成 One API 的私有化部署
接入 OpenAI、通义、文心等 20+ 主流模型，无需重复开发适配逻辑
创建受控 Token，实现密钥集中管理与额度精细限制
通过分组、负载均衡、失败重试，构建高可用、可伸缩的模型服务层
用标准 OpenAI SDK 调用，零学习成本接入现有项目

One API 的本质，是把“对接大模型”的复杂性封装起来，让你专注在业务逻辑和用户体验上。它不替代大模型，而是让大模型真正成为你系统中可插拔、可监控、可运营的基础设施。

下一步，你可以：

尝试添加 Ollama 本地模型，实现完全离线推理
配置邮件通知，当额度低于阈值时自动告警
结合 Message Pusher，将错误日志推送到企业微信/钉钉
用管理 API 自动化创建用户、同步渠道，构建 DevOps 流水线

大模型应用的下半场，拼的不再是“谁家模型更强”，而是“谁的工程化能力更稳”。One API，正是你迈出这关键一步的可靠伙伴。

获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

从安装到配置：One API多模型管理平台完整使用指南