One API 部署与配置完全指南

One API 简介

One API 是一个开源的 AI API 管理和分发平台，支持将多个 AI 供应商的API统一为一个接口格式（兼容OpenAI格式），实现负载均衡、令牌管理、用量计费等功能。非常适合需要管理多个API Key或搭建API中转服务的场景。

Docker 部署（推荐）

创建数据目录

mkdir -p /opt/one-api/data

启动容器

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

Nginx 反向代理配置

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/ssl/certs/api.example.com.pem;
    ssl_certificate_key /etc/ssl/certs/api.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE支持
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
    }
}

初始化配置

登录管理后台

访问 https://api.example.com，默认管理员账号：

• 用户名：root
• 密码：123456

⚠️ 首次登录后立即修改密码！

添加渠道（Channel）

渠道是API供应商的接入配置：

创建令牌（Token）

令牌是分发给用户的访问密钥：

• 设置额度限制
• 限制可用模型
• 设置过期时间
• 启用/禁用IP白名单

渠道配置示例

OpenAI 渠道

DeepSeek 渠道

Anthropic 渠道

负载均衡策略

同一模型可配置多个渠道，One API自动负载均衡：

• 优先级：数字越小优先级越高
• 权重：同优先级按权重分配
• 自动重试：某渠道失败自动切换

使用方式

部署完成后，将 Base URL 改为 One API 地址，使用 One API 生成的令牌即可：

from openai import OpenAI

client = OpenAI(
    api_key="sk-one-api-token-xxx",  # One API 令牌
    base_url="https://api.example.com/v1"  # One API 地址
)

# 像使用 OpenAI 一样调用
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

数据备份

# 备份SQLite数据库
cp /opt/one-api/data/one-api.db /opt/one-api/data/one-api.db.bak

# 或导出MySQL
mysqldump -u root -p one_api > one_api_backup.sql

常见问题

Q: 渠道报错 401？
A: 检查API Key是否正确，是否已过期。

Q: 流式输出中断？
A: Nginx需关闭 proxy_buffering，确保SSE正常传输。

Q: 如何查看日志？
A: docker logs one-api -f --tail 100