OneAPI部署教程：Linux/Windows双平台Docker镜像快速上手

牛新哲

176人浏览 · 2026-02-25 00:55:55

牛新哲 · 2026-02-25 00:55:55 发布

OneAPI部署教程：Linux/Windows双平台Docker镜像快速上手

通过标准的 OpenAI API 格式访问所有主流大模型，开箱即用

1. 什么是OneAPI？

OneAPI是一个强大的LLM API管理和分发系统，它让你可以用统一的OpenAI API格式访问几乎所有主流大模型。想象一下，你只需要记住一种API调用方式，就能同时使用OpenAI、Google Gemini、文心一言、通义千问等20多种大模型——这就是OneAPI带来的便利。

这个工具特别适合需要同时使用多个AI模型的开发者，或者想要为团队提供统一AI接口的技术负责人。你不用再为每个模型学习不同的API文档，也不用担心密钥管理混乱的问题。

2. 核心功能一览

在开始部署之前，先快速了解OneAPI能为你做什么：

2.1 多模型统一接入

支持超过25种主流大模型，包括：

OpenAI ChatGPT系列（含Azure OpenAI）
Anthropic Claude系列（支持AWS Claude）
Google PaLM2/Gemini系列
国内模型：文心一言、通义千问、讯飞星火、ChatGLM等
新兴模型：Moonshot、百川、DeepSeek、零一万物等

2.2 强大的管理功能

密钥管理：统一管理所有模型的API密钥
负载均衡：智能分配请求到多个渠道
流量控制：设置令牌额度、过期时间、访问权限
用户管理：支持多种登录方式（邮箱、GitHub、飞书等）

2.3 企业级特性

支持多机部署和高可用
实时监控和报警通知
自定义界面和品牌设置
完整的API管理接口

3. 环境准备与快速部署

OneAPI提供了Docker镜像，让部署变得极其简单。无论你用的是Linux还是Windows，都能快速上手。

3.1 系统要求

操作系统：Linux（推荐）或 Windows 10/11
Docker：已安装Docker和Docker Compose
内存：至少2GB可用内存
磁盘空间：至少1GB可用空间

3.2 一键部署命令

打开终端或命令行工具，执行以下命令：

# 创建部署目录
mkdir oneapi && cd oneapi

# 下载docker-compose配置文件
curl -O https://raw.githubusercontent.com/songquanpeng/one-api/main/docker-compose.yml

# 启动服务
docker-compose up -d

就是这么简单！三行命令就能启动OneAPI服务。

3.3 Windows系统特别说明

如果你在Windows上使用Docker Desktop，操作步骤基本相同：

打开PowerShell或命令提示符
依次执行上面的命令
确保Docker Desktop正在运行

Windows系统可能需要管理员权限，如果遇到权限问题，请以管理员身份运行命令行工具。

4. 初始配置与安全设置

服务启动后，打开浏览器访问 http://localhost:3000 就能看到登录界面。

4.1 首次登录重要提示

安全警告：使用root用户初次登录系统后，务必立即修改默认密码 123456！这是保护你系统安全的第一步。

登录后请立即：

进入用户设置
修改默认密码为强密码
建议启用双因素认证

4.2 基本配置步骤

完成密码修改后，按照以下步骤进行初始配置：

添加模型渠道：在"渠道"页面添加你要使用的AI模型API密钥
设置访问令牌：创建用于API调用的访问令牌
配置用户权限：根据需要设置用户访问权限
调整系统设置：自定义系统名称、Logo等外观设置

5. 快速上手示例

让我们通过一个实际例子来看看OneAPI如何使用。

5.1 API调用示例

假设你已经设置好了OpenAI和文心一言的渠道，下面是如何通过统一的API格式调用不同模型：

import openai

# 配置OneAPI端点（替换为你的实际地址和密钥）
openai.api_base = "http://localhost:3000/v1"
openai.api_key = "你的访问令牌"

# 调用OpenAI模型
response_openai = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己"}]
)

# 调用文心一言模型（使用相同的API格式！）
response_wenxin = openai.ChatCompletion.create(
    model="wenxin",  # 这是在OneAPI中配置的模型名称
    messages=[{"role": "user", "content": "你好，请介绍一下你自己"}]
)

print("OpenAI回复:", response_openai.choices[0].message.content)
print("文心一言回复:", response_wenxin.choices[0].message.content)

5.2 流式传输示例

OneAPI支持流式传输，可以实现打字机效果：

import openai

openai.api_base = "http://localhost:3000/v1"
openai.api_key = "你的访问令牌"

response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "写一个关于人工智能的短故事"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.get("content"):
        print(chunk.choices[0].delta.content, end="", flush=True)

6. 实用技巧与进阶配置

6.1 负载均衡配置

如果你有多个相同模型的API密钥，可以配置负载均衡来提高可用性：

在渠道页面添加多个相同模型的渠道
系统会自动在这些渠道间分配请求
当某个渠道失败时，自动切换到其他渠道

6.2 自定义模型映射

你可以重命名模型标识符，让前端调用更简单：

{
  "model_mappings": {
    "my-gpt": "gpt-3.5-turbo",
    "my-wenxin": "wenxin"
  }
}

6.3 环境变量配置

通过环境变量可以自定义很多设置：

# docker-compose.yml中的环境变量示例
environment:
  - SQL_DSN=mysql://root:password@mysql:3306/oneapi
  - PORT=3000
  - SESSION_SECRET=your-secret-key
  - THEME=dark  # 启用暗色主题

7. 常见问题解答

7.1 端口冲突怎么办？

如果3000端口已被占用，可以修改docker-compose.yml中的端口映射：

ports:
  - "3001:3000"  # 将外部端口改为3001

7.2 如何备份数据？

OneAPI的数据存储在数据库中，建议定期备份：

# 备份数据库
docker exec one-api-mysql mysqldump -u root -p password oneapi > backup.sql

# 恢复数据库
docker exec -i one-api-mysql mysql -u root -p password oneapi < backup.sql