保姆级教程：One API 从安装到配置的全流程详解

本文经过修改和调整，原文出处：https://blog.csdn.net/weixin_34620658/article/details/158143965

1. 简介

• 官方项目仓库位于 GitHub: github.com/songquanpeng/one-api

2. 环境准备与前置条件

别急着敲命令，先确认这几件事是否已就绪。这一步花 2 分钟，能避免后续 90% 的部署失败。

2.1 运行环境要求

• 硬件要求：2C2G即可
• 已安装 Docker 20.10+ 最新稳定版
• 时区设置：Asia/Shanghai
• OS：推荐Linux；Windows上推荐WSL2

2.3 目录规划

mkdir -p /data/oneapi/ ;cd /data/oneapi/
chmod -R 755 /data/oneapi

3. 部署：Docker compose

3.1、MySQL 前置准备（命令行执行）

1. 建数据库 oneapi

CREATE DATABASE IF NOT EXISTS oneapi DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 创建专用账户（推荐）

替换自定义密码 OneApi@2026，按需修改

-- 创建用户，允许本地+容器访问
CREATE USER IF NOT EXISTS 'oneapi_user'@'%' IDENTIFIED BY 'OneApi@2026';
-- 赋予oneapi库全部权限
GRANT ALL PRIVILEGES ON oneapi.* TO 'oneapi_user'@'%';
-- 刷新权限
FLUSH PRIVILEGES;

如果你数据库跑在本机宿主机，容器访问不能写 localhost，要用宿主机内网IP。

3.2、docker-compose.yml 完整配置

新建：/data/oneapi/docker-compose.yml

version: "3.8"

services:
  one-api:
    image: justsong/one-api
    container_name: one-api
    restart: always
    ports:
      - "3000:3000" # 宿主机端口:容器端口，可改前面数字
    environment:
      TZ: Asia/Shanghai
      # 格式：数据库账号:数据库密码@tcp(数据库地址:3306)/数据库名
      # 重点：不要写localhost，填写宿主机真实内网IP
      SQL_DSN: "oneapi_user:OneApi@2026@tcp(192.168.1.100:3306)/oneapi"
    volumes:
      # 持久化日志、配置，宿主机路径自行更换
      - /data/oneapi/data:/data
    networks:
      - default

networks:
  default:

启动&运维命令

1. 进入yml所在目录启动

cd /data/oneapi
docker-compose up -d

2. 查看运行日志（排错）

docker-compose logs -f one-api

3. 重启服务

docker-compose restart one-api

4. 更新镜像重启

docker-compose pull && docker-compose up -d

4. 首次登录与安全加固【极其重要】

部署完成后，打开浏览器，访问 http://你的服务器IP:13000（例如 http://192.168.1.100:13000）。

你会看到 One API 的登录页。系统预置了一个超级管理员账户：

• 用户名： root
• 密码： 123456

[!WARNING]

这是最高危操作！请务必在登录后的 30 秒内完成密码修改。
系统文档已明确强调：“使用 root 用户初次登录系统后，务必修改默认密码 123456！” 这不是建议，是强制安全红线。

修改步骤：

1. 成功登录后，右上角点击头像 → 选择【个人设置】
2. 在【修改密码】区域，输入旧密码 123456，再输入两次新密码
3. 点击【保存】，系统会立即登出。用新密码重新登录即可。

完成这一步，你的 One API 实例才真正具备基础安全性。后续所有配置，都将在这个安全账户下进行。

5. 核心配置四步走：从模型接入到对外服务

One API 的强大，在于其清晰的配置逻辑：渠道（Source）→ 令牌（Token）→ 用户（User）→ 调用（Call）。我们按这个顺序，一步步配置。

1、注册并获取大模型 API Key （关键！）

One API 本身不提供模型算力，它只是“管道”。你要先从各大平台获取自己的 API Key，才能让管道通起来。

重要提醒：不要使用他人分享的公共 Key。不仅违反平台条款，更存在安全与额度失控风险。务必用自己的账号申请。

2、第一步：添加渠道（对接真实大模型）

渠道 = 你接入的每一个大模型服务商。这是整个系统的“水源”。

操作路径： 左侧菜单 → 【渠道管理】→ 【添加渠道】

关键字段填写指南（以通义千问为例）：

验证是否成功： 添加后，回到【渠道列表】，找到刚添加的条目，点击右侧【测试】按钮。如果显示 “测试成功”，说明网络连通、密钥有效、模型可用。

进阶技巧：

• 负载均衡：同一分组下添加多个同类型渠道（如两个 OpenAI 渠道），One API 会自动轮询分发请求，提升稳定性和并发能力。
• 模型重定向：用户请求 gpt-4-turbo，但你想让它实际走 gpt-4o，开启此功能并填写映射关系即可。

3、第二步：创建令牌（生成对外调用凭证）

令牌 = 你分发给客户端、程序、合作伙伴的“钥匙”。它不等于你的原始 API Key，而是经过 One API 授权、限流、审计的中间凭证。

操作路径： 左侧菜单 → 【令牌管理】→ 【添加令牌】

关键字段填写指南：

生成后，你会看到三种格式的令牌：

• sk-xxx（标准 OpenAI 格式）
• Bearer sk-xxx（HTTP Authorization 头格式）
• https://your-domain.com/v1（完整 API 地址）

这就是你对外提供的全部信息！ 客户只需把他们的 OpenAI 代码里的 https://api.openai.com/v1 换成你的地址，sk-xxx 换成这个新令牌，一切照常运行。

4、第三步：（可选）创建用户与分组（面向多租户场景）

如果你只是自己用，这步可以跳过。但如果你想搭建一个小型 AI 服务平台，给不同客户分配不同额度和模型，就需要用户体系。

操作路径： 左侧菜单 → 【用户管理】→ 【添加用户】

关键字段：

• 用户名： client_a（登录后台用）
• 显示名称： 客户A公司（界面显示名）
• 密码： StrongPassw0rd!（必须符合强度要求）
• 分组： vip（决定他能用哪些渠道）

添加后，该用户即可用 client_a 和密码登录后台，查看自己的令牌、额度、日志。管理员可在【用户管理】中随时封禁、重置密码、调整分组。

5、第四步：配置系统全局设置（让服务更专业）

最后，让 One API 更贴合你的使用习惯。

操作路径： 左侧菜单 → 【设置】→ 【其他设置】

必配项推荐：

• 系统名称： 我的AI中台（替换掉默认的 “One API”）
• 网站 Logo： 上传一张 120x120 px 的 PNG 图标
• 公告： 【重要】服务将于 2024-10-01 进行维护，请提前安排（向所有用户展示）
• 首页自定义： 粘贴一段 Markdown，写上你的服务介绍、联系方式、使用文档链接

这些设置无需重启，保存后立即生效。一个属于你自己的、品牌化的 AI 网关就此诞生。

6. 实战调用：三行代码接入你的第一个应用

配置完成，现在来验证效果。我们用最简单的 Python requests 库，模拟一次标准的 OpenAI 风格调用。

6.1 准备工作

确保你已：

• 拥有一个有效的令牌（从【令牌管理】复制）
• 知道你的 One API 访问地址（如 http://192.168.1.100:13000）

6.2 Python 示例代码（复制即用）

import requests
import json
 
# 替换为你的实际地址和令牌
BASE_URL = "http://192.168.1.100:13000/v1"
API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}
 
data = {
    "model": "qwen-max",  # 必须是你渠道中已启用的模型
    "messages": [
        {"role": "user", "content": "用一句话解释量子计算是什么？"}
    ],
    "stream": False  # 设为 True 可获得流式响应（打字机效果）
}
 
response = requests.post(f"{BASE_URL}/chat/completions", headers=headers, json=data)
print(json.dumps(response.json(), indent=2, ensure_ascii=False))

6.3 运行结果与解读

成功执行后，你将看到类似这样的 JSON 响应：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1728000000,
  "model": "qwen-max",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "量子计算是利用量子力学原理（如叠加态和纠缠态）进行信息处理的新型计算范式，能在特定问题上远超经典计算机。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 32,
    "total_tokens": 47
  }
}

这意味着：

• 请求已成功抵达 One API；
• One API 已将请求准确转发给通义千问 qwen-max 模型；
• 响应被原样返回，且结构与 OpenAI 官方 API 完全一致；
• usage 字段中的 token 消耗，已被 One API 自动记录并扣减你的令牌额度。

7. 常见问题与避坑指南

在真实部署中，你可能会遇到这些高频问题。我们提前为你梳理清楚：

7.1 测试渠道失败：连接超时

• 原因： 服务器无法访问外网（如企业内网防火墙拦截）、或目标模型平台（如 OpenAI）在国内不可达。
• 解法：
  1. 在服务器上执行 curl -v https://dashscope.aliyuncs.com，确认能否连通国内平台；
  2. 对于 OpenAI/Azure 等境外平台，需确保服务器已配置合规的网络环境（One API 本身不提供代理功能）；
  3. 在渠道配置中，尝试填写代理地址（如 http://127.0.0.1:7890），前提是本地已运行合规代理服务。

7.2 调用返回 401 Unauthorized

• 原因： 令牌错误、过期、或额度已用尽。
• 解法：
  1. 回到【令牌管理】，检查该令牌状态是否为“启用”，过期时间是否有效；
  2. 点击【查看额度】，确认剩余额度 > 0；
  3. 检查代码中 Authorization 头的格式是否为 Bearer sk-xxx（注意空格）。

7.3 添加了渠道，但在牌里没有对应模型

• 原因： 渠道的【分组】与当前登录用户的【分组】不匹配。
• 解法：
  1. 确认你登录的是 root（超级管理员），它能看到所有分组；
  2. 在【渠道管理】中，编辑该渠道，将【分组】改为 default（默认对所有用户开放）；
  3. 或在【用户管理】中，将目标用户加入该渠道所属的分组（如 vip）。

7.4 备份所有配置

• 答案： 只需备份 /opt/oneapi/data 目录下的全部文件！
  One API 使用 SQLite 数据库存储所有数据，该目录就是它的全部世界。定期压缩备份此目录，即可实现秒级恢复。