Docker部署One API中转服务完整教程

开发者小布
4 阅读5分钟

===

引言

One API 是一个开源的 OpenAI 接口管理与分发系统，支持将多个 AI 模型 API 统一管理，对外提供兼容 OpenAI 格式的接口。对于需要自建 API 中转服务的开发者来说，它是目前最流行的选择之一。

本文将手把手带你用 Docker 完整部署 One API，包括数据库配置、负载均衡设置和日常运维管理。当然，如果你不想折腾服务器，文末也会介绍一个省心的替代方案。

一、One API 是什么？

One API（项目地址：github.com/songquanpeng/one-api）是一个基于 Go 语言开发的 OpenAI 接口管理系统，主要功能：

  • 多渠道管理：统一管理 OpenAI、Claude、Gemini、Azure OpenAI 等多个上游 API

  • 令牌管理：创建多个 API Key，设置不同的额度和权限

  • 用量统计：实时查看各渠道和令牌的使用情况

  • 负载均衡：多个同类渠道自动轮询，提高稳定性

  • 兼容 OpenAI 格式：下游应用无感切换

适合场景：团队内部共享 API、对外提供 AI 服务、多模型统一接入管理。

二、环境准备

服务器要求

  • 操作系统：Ubuntu 20.04 / 22.04（推荐）或 CentOS 7+

  • 内存：最低 1GB，推荐 2GB+

  • 存储：20GB+

  • 需要有公网 IP（如果需要外网访问）

安装 Docker

# Ubuntu 安装 Docker
curl -fsSL https://get.docker.com | sh

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version

安装 Docker Compose

# 安装最新版 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

sudo chmod +x /usr/local/bin/docker-compose

# 验证
docker-compose --version

三、方案一：SQLite 快速部署（单机版）

适合个人使用或小规模测试。

创建部署目录

mkdir -p /opt/one-api/data
cd /opt/one-api

创建 docker-compose.yml

version: '3.4'

services:
  one-api:
    image: justsong/one-api:latest
    container_name: one-api
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      - SESSION_SECRET=your-random-secret-string-change-this
      - SQL_DSN=          # 留空则使用 SQLite
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O- http://localhost:3000/api/status | grep -o '\"success\":true' | head -c 20"]
      interval: 30s
      timeout: 10s
      retries: 3

启动服务

docker-compose up -d

# 查看日志
docker-compose logs -f

访问 http://your-server-ip:3000，默认账号 root，密码 123456（首次登录务必修改）。

四、方案二：MySQL 生产级部署（推荐）

数据存储在 MySQL，支持高并发，适合生产环境。

docker-compose.yml（含 MySQL）

version: '3.4'

services:
  mysql:
    image: mysql:8.0
    container_name: one-api-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: your-strong-password
      MYSQL_DATABASE: oneapi
      MYSQL_USER: oneapi
      MYSQL_PASSWORD: your-db-password
    volumes:
      - ./mysql-data:/var/lib/mysql
    networks:
      - one-api-network
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: one-api-redis
    restart: always
    command: redis-server --requirepass your-redis-password
    volumes:
      - ./redis-data:/data
    networks:
      - one-api-network

  one-api:
    image: justsong/one-api:latest
    container_name: one-api
    restart: always
    ports:
      - "3000:3000"
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      - TZ=Asia/Shanghai
      - SESSION_SECRET=your-random-session-secret
      - SQL_DSN=oneapi:your-db-password@tcp(mysql:3306)/oneapi
      - REDIS_CONN_STRING=redis://:your-redis-password@redis:6379
      - SYNC_FREQUENCY=60
    volumes:
      - ./logs:/app/logs
    networks:
      - one-api-network

networks:
  one-api-network:
    driver: bridge

启动与验证

# 启动所有服务
docker-compose up -d

# 检查状态
docker-compose ps

# 查看 one-api 日志
docker-compose logs -f one-api

五、配置 Nginx 反向代理（HTTPS）

# /etc/nginx/sites-available/one-api
server {
    listen 80;
    server_name api.yourdomain.com;
    return 301 https://$host$request_uri;
}

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

    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;

    # 安全头
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;

    # 流式响应关键配置
    proxy_buffering off;
    proxy_cache off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        
        # 超时设置（流式输出需要较长时间）
        proxy_read_timeout 300s;
        proxy_connect_timeout 30s;
    }
}

```bash
# 申请 SSL 证书
sudo certbot --nginx -d api.yourdomain.com

# 启用配置
sudo ln -s /etc/nginx/sites-available/one-api /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

六、One API 核心配置

1. 添加上游渠道

登录管理后台 → 渠道 → 添加渠道：

  • OpenAI：填入 API Key，选择支持的模型

  • Claude（Anthropic）：填入 Anthropic API Key

  • Azure OpenAI：填入 Endpoint、API Key、部署名

2. 创建令牌

令牌 → 添加令牌，可设置：

  • 令牌名称和额度

  • 有效期

  • 允许的模型范围

3. 设置渠道权重

同一类型多个渠道时，可设置权重实现负载均衡：

渠道A（权重3）+ 渠道B（权重1）→ 75%请求走A，25%走B

七、日常运维

更新到最新版本

cd /opt/one-api
docker-compose pull
docker-compose up -d

数据备份

#!/bin/bash
# backup.sh - 每天凌晨2点执行

BACKUP_DIR="/backup/one-api"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# 备份 MySQL
docker exec one-api-mysql mysqldump -u oneapi -pyour-db-password oneapi > \
    $BACKUP_DIR/mysql_$DATE.sql

# 保留最近30天
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete

echo "备份完成: $BACKUP_DIR/mysql_$DATE.sql"

# 添加定时任务
crontab -e
# 添加：0 2 * * * /opt/one-api/backup.sh

监控告警

# 检查服务健康状态
docker inspect --format='{{.State.Health.Status}}' one-api

# 查看资源使用
docker stats one-api --no-stream

八、常见问题排查

问题1：容器启动失败

# 查看详细日志
docker-compose logs --tail=100 one-api

# 常见原因：
# - 数据库连接失败：检查 SQL_DSN 格式和密码
# - 端口占用：sudo lsof -i :3000

问题2：流式响应中断

需确保 Nginx 的 proxy_buffering off 已设置，且 proxy_read_timeout 足够长。

问题3：某渠道频繁失败

在渠道设置中查看测试结果，检查：

  • API Key 是否有效

  • 余额是否充足

  • 该渠道是否支持所请求的模型

九、自建 vs 直接使用现成平台

说实话，自建 One API 有一定的运维成本：

对比项

自建 One API

直接用 jiekou.ai

初始成本

服务器费用（￥50-200/月）

无

运维成本

需要自己维护、更新、备份

平台负责

稳定性

取决于自己服务器

专业团队保障

上游成本

需要自己购买各平台 API Key

平台统一采购

适合场景

有特殊定制需求、大规模使用

快速上手、中小规模

如果你的主要目的是稳定调用 GPT-4o、Claude 等主流模型，不想花时间在运维上，jiekou.ai 是个不错的选择：国内直连，支持主流模型，按量计费，注册即用，10分钟就能接入到自己的项目。

当然，如果你需要完全私有化部署、需要对 API 流量有完整控制权，自建 One API 仍然是最灵活的方案。

总结

本文完整介绍了用 Docker 部署 One API 的全流程：

  1. SQLite 快速版：适合个人测试，一行命令启动

  2. MySQL 生产版：适合团队使用，高并发稳定

  3. Nginx 反向代理：配置 HTTPS，提升安全性

  4. 日常运维：更新、备份、监控一套完整流程

部署过程中遇到问题，优先查看 docker-compose logs，大多数问题都能在日志里找到原因。

💡 懒人提示：不想搭服务器？直接访问 jiekou.ai，注册充值，获得 API Key，修改代码里的 base_url 即可，真的只需要10分钟。

avatar
文章
阅读
粉丝