One API 部署教程(一)：本地部署完整指南

导读：One API 是一个开源的 AI API 聚合管理平台，可以让你用一个统一的接口调用多个 AI 平台的 API。

系列文章导航

方法一：Docker 命令行部署

这是最直接的部署方式，不需要额外配置文件。

准备工作

首先需要安装 Docker：

Windows/Mac：

下载并安装 Docker Desktop
启动 Docker Desktop

Linux：

1 2	# 验证安装 docker --version

Step 1: 拉取镜像

从 Docker Hub 拉取最新镜像：

1	docker pull justsong/one-api

提示：如果上面的镜像无法拉取，可以尝试使用 GitHub 的 Docker 镜像：ghcr.io/songquanpeng/one-api

Step 2: 运行容器

使用 SQLite（适合个人使用）

SQLite 是最简单的选择，不需要额外配置数据库：


# 运行容器
docker run --name one-api \
  -d \
  --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ${PWD}/one-api:/data \
  justsong/one-api

提示：你可以根据需要修改数据保存路径，只需更改 -v 参数中的宿主机路径即可。

使用 MySQL（适合高并发）

如果你的并发量较大，建议使用 MySQL 数据库：

docker run --name one-api \
  -d \
  --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ${PWD}/one-api:/data \
  justsong/one-api

注意：请根据实际情况修改数据库连接参数。

参数说明：

-d - 后台运行
--name one-api - 容器名称
--restart always - 自动重启（容器意外退出或系统重启后自动启动）
-p 3000:3000 - 端口映射（第一个 3000 是宿主机端口，可以根据需要修改）
-e TZ=Asia/Shanghai - 设置时区
-e SQL_DSN - MySQL 数据库连接字符串（可选）
-v ${PWD}/one-api:/data - 数据持久化（你可以根据需要修改宿主机路径）

提示：数据和日志会保存在 ${PWD}/one-api 目录中，请确保该目录存在且具有写入权限。你可以根据需要修改为其他路径。

Step 3: 访问 One API

部署完成后，打开浏览器访问 http://localhost:3000

首次访问会要求注册，第一个注册的用户就是管理员。

默认账号：如果系统自动创建了 root 账号，用户名为 root，密码为 123456。登录后请立即修改密码！

如果启动失败：

可以尝试添加 --privileged=true 参数。

方法二：Docker Compose 部署

如果需要更清晰的配置管理，或者计划后续添加其他服务（如 MySQL、Redis），可以使用 Docker Compose。

Step 1: 创建 docker-compose.yml

在项目目录下创建 docker-compose.yml 文件：

version: '3'

services:
  one-api:
    image: justsong/one-api
    container_name: one-api
    restart: always
    ports:
      - "3000:3000"
    environment:
      - TZ=Asia/Shanghai
      # 如果使用 MySQL，取消下面这行的注释并修改连接参数
      # - SQL_DSN=root:123456@tcp(mysql:3306)/oneapi
    volumes:
      - ${PWD}:/data

Step 2: 启动服务

# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止
docker-compose down

Step 3: 访问 One API

打开浏览器，访问：http://localhost:3000

手动部署、Nginx 反向代理配置、多机部署（高级）

这些方式目前还没有在本地环境进行实际测试，后续会补充完整的实战教程。
如果你对这些部署方式感兴趣，可以先查看官方 GitHub 仓库获取详细的配置说明。

初始配置

部署完成后，需要进行一些基本配置才能正常使用。

注册管理员账号

第一次访问时，会跳转到注册页面。填写用户名、密码、邮箱，完成注册。第一个注册的用户自动成为管理员。

提示：如果使用 Docker 部署且没有修改默认配置，系统会自动创建一个 root 账号：
用户名：root
密码：123456
登录后请立即修改密码！

登录后台

使用刚注册的账号登录，进入管理后台。

配置渠道

点击顶部菜单 “渠道” → “新建渠道”，添加你的 AI 平台 API Key。

以 DeepSeek 为例：

名称: DeepSeek
类型: DeepSeek
API Key: 你的 DeepSeek API Key
权重: 100
状态: 启用

其他平台的配置类似，选择对应的类型，填入 API Key 即可。

创建令牌

点击顶部菜单 “令牌” → “新建令牌”。

名称: 随便起，比如 “测试令牌”
过期时间: 可以选择永不过期
额度: 可以设置使用额度（可选）

创建完成后返回令牌列表页面，点击复制会得到一个sk-**的令牌。

测试 API 调用

Linux/Mac 用户：

curl http://localhost:3000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer sk-你的令牌" 
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "你好"}]
  }'

Windows PowerShell 用户：

方法 1: 使用 curl.exe（分两步执行）

第一步：定义 JSON 变量

1	$jsonBody = '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'

第二步：发送请求

Invoke-RestMethod -Uri "http://localhost:3000/v1/chat/completions" -Method Post -Headers @{"Content-Type"="application/json"; "Authorization"="Bearer sk-你的key="} -Body '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'