🚀 使用 Docker Compose 部署 One API（API 聚合管理工具）

🚀 使用 Docker Compose 部署 One-API

One-API 是一个开源的接口管理与分发系统，支持多种主流大模型服务，提供统一的 API 密钥管理和分发功能。通过 Docker Compose 部署可以大大简化安装流程，并确保环境一致性。

📝 项目简介

One-API 是一个统一的接口管理与分发系统，专为简化和优化用户与大模型 API 的交互而设计。它能够帮助开发人员更轻松地管理 API 请求，提供统一的 API 接口、请求路由以及安全管理。

核心特点：

多模型支持：支持多种主流 AI 服务，包括 OpenAI ChatGPT 系列、Anthropic Claude 系列、Google PaLM2/Gemini 系列等众多国内外大模型
开箱即用：通过 Docker 镜像形式实现一键部署，降低使用门槛
高性能：采用 Go 语言开发，确保高性能运行
集中管理：提供统一的 API 密钥管理和分发功能，简化多 AI 服务的接入和管理
灵活部署：支持 SQLite 和 MySQL 等多种数据库后端

📝 项目简介2

One-API 是一款开源的 API 网关与聚合管理工具，核心功能是集中管理各类 AI 模型 API（如 OpenAI、Anthropic、国内大模型等），支持密钥分发、流量控制、计费统计、多模型适配等，适合个人或企业统一管理 API 资源，避免重复开发密钥与权限系统。

本次部署为 完整生产级方案，包含三大组件：

One-API 核心服务：提供 Web 管理界面与 API 转发功能；
MySQL 数据库：存储 API 渠道配置、用户密钥、使用记录等核心数据（比 SQLite 更适合多用户与高并发）；
Redis 缓存：加速 API 调用响应，缓存临时数据，提升系统性能。

核心特点

多 API 聚合：支持整合 OpenAI、ChatGLM、Claude 等数十种模型 API，统一接口格式，避免对接不同模型的重复开发；
密钥管理：可生成多个子密钥，分别绑定不同模型与权限（如限制调用次数、速率），方便团队或用户分发；
流量控制：支持按用户 / 密钥设置调用限额、QPS 限制，防止 API 滥用；
数据持久化：通过 MySQL 存储配置与记录，Redis 加速访问，确保服务稳定与数据安全；
可扩展性：支持多机部署（主从节点），适应高并发场景；
日志与监控：详细记录 API 调用日志，提供健康检查机制，便于问题排查与运维。

🔧 部署前准备

系统环境要求

操作系统：支持 Linux、Windows、macOS
Docker 引擎：版本 20.10+
Docker Compose：版本 2.0+
硬件资源：
内存：至少 2GB
存储空间：至少 10GB 可用空间

环境检查

检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态
检查 Docker 版本 bash docker --version
检查 Docker Compose 版本 bash docker compose version 确保版本为 2.0 以上
创建部署目录

   mkdir -p /home/compose/one-api && cd /home/compose/one-api

⚙️ 配置 Docker Compose

准备配置文件

创建 docker-compose.yml 文件：

#version: '3.4'

services:
  # 1. One-API 核心服务
  one-api:
    image: "${REGISTRY:-docker.io}/justsong/one-api:latest"  # 官方最新镜像
    container_name: one-api
    restart: always  # 容器退出后自动重启
    command: --log-dir /app/logs  # 指定日志目录
    ports:
      - "3000:3000"  # 端口映射：主机 3000 → 容器 3000（Web 与 API 访问）
    volumes:
      - ./data/oneapi:/data  # 应用数据持久化
      - ./logs:/app/logs     # 日志持久化
    environment:
      # 数据库连接配置（格式：用户名:密码@tcp(数据库容器名:端口)/数据库名）
      #- SQL_DSN=oneapi:your_db_password@tcp(db:3306)/one-api  # 必须修改密码！
      - SQL_DSN=oneapi:123456@tcp(db:3306)/one-api  # 修改此行，或注释掉以使用 SQLite 作为数据库
      - REDIS_CONN_STRING=redis://redis  # Redis 连接地址（容器名访问）
      - SESSION_SECRET=your_random_string    # 必须修改为随机字符串（如用 openssl rand -hex 16 生成）
      - TZ=Asia/Shanghai  # 时区同步
      # 多机部署参数（单节点无需开启）
#      - NODE_TYPE=slave  # 多机部署时从节点取消注释该行
#      - SYNC_FREQUENCY=60  # 需要定期从数据库加载数据时取消注释该行
#      - FRONTEND_BASE_URL=https://your-domain.com  # 多机部署时从节点取消注释该行
    depends_on:
      - redis  # 依赖 Redis 启动后再启动
      - db    # 依赖 MySQL 启动后再启动
    healthcheck:
      # 健康检查：定期访问状态接口，确保服务正常
      test: [ "CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' | awk -F: '{print $2}'" ]
      interval: 30s
      timeout: 10s
      retries: 3


  # 2. Redis 缓存服务
  redis:
    image: "${REGISTRY:-docker.io}/redis:latest"  # 官方 Redis 镜像
    container_name: redis
    restart: always  # 自动重启
    volumes:
      - ./data/redis:/data  # 新增：Redis 数据持久化（默认配置未挂载，建议添加）

# 3. MySQL 数据库服务
  db:
    image: "${REGISTRY:-docker.io}/mysql:8.2.0"  # 官方 MySQL 8.2 镜像
    restart: always
    container_name: mysql
    volumes:
      - ./data/mysql:/var/lib/mysql   # 数据库数据持久化（核心！）
    ports:
      - '3306:3306'  # 数据库端口映射（本地管理用，公网建议删除）
    environment:
      TZ: Asia/Shanghai   # 设置时区
      MYSQL_ROOT_PASSWORD: 'OneAPI@justsong' #'your_root_password'  # 必须修改！默认密码不安全
      MYSQL_USER: oneapi  # 数据库专用用户（固定）
      MYSQL_PASSWORD: '123456'   #'your_db_password'  # 必须与 SQL_DSN 中的密码一致！
      MYSQL_DATABASE: one-api  # 数据库名（固定）# 自动创建数据库

关键配置说明

镜像选择：
One-API：使用 justsong/one-api:latest 官方镜像
数据库：使用 MySQL 8.2.0 作为持久化存储
缓存：使用 Redis 提升性能
端口映射：3000:3000 将容器内的 3000 端口映射到宿主机的 3000 端口
数据持久化：
./data/oneapi:/data：One-API 数据目录
./logs:/app/logs：应用日志目录
./data/mysql:/var/lib/mysql：MySQL 数据目录
环境变量：
SQL_DSN：数据库连接字符串
REDIS_CONN_STRING：Redis 连接字符串
SESSION_SECRET：会话加密密钥，应设置为随机字符串
TZ：时区设置
健康检查：配置了完善的健康检查机制，确保服务稳定性

🚀 启动与验证

启动服务

docker compose up -d

验证服务状态

检查容器运行状态 bash docker compose ps 应该看到 one-api、redis、mysql 三个服务都处于 Up 状态
查看服务日志 bash docker compose logs -f one-api
访问 Web 界面 在浏览器中访问 http://你的服务器IP:3000

初始登录

用户名：root
初始密码：123456
重要：首次登录后立即修改密码

（2）访问 One-API 管理界面

打开浏览器，输入 http://服务器IP:3000（如内网 http://192.168.1.100:3000）；
首次访问会显示登录界面，默认管理员账号：admin@example.com，默认密码：123456；
登录后会强制要求修改默认密码（输入新密码并确认），完成后进入管理后台，说明服务正常。

（3）验证数据库连接

在管理后台点击「系统设置」→「数据库状态」，若显示 “连接正常”，说明 MySQL 配置正确；点击「缓存状态」，显示 “连接正常” 说明 Redis 配置正确。

🔌 基础配置与使用

系统配置检查

登录后，首先检查以下基础配置：

系统状态：确认所有服务正常运行
数据库连接：验证 MySQL 连接状态
Redis 连接：确认缓存服务正常工作

添加渠道

进入渠道管理
在左侧菜单中找到"渠道"管理
点击"添加新渠道"
配置渠道参数
渠道类型：选择对应的大模型平台（如 OpenAI、Azure 等）
API Key：填写对应平台的 API 密钥
基础 URL：根据需要配置 API 端点
模型列表：系统会自动获取支持的模型
渠道测试
添加完成后测试渠道连通性
确认模型列表正确加载

令牌管理

创建访问令牌
进入"令牌"管理页面
点击"添加新令牌"
配置令牌权限
设置令牌名称和权限范围
绑定可访问的渠道和模型
设置请求次数限制

多机部署配置（可选）

对于需要多机部署的场景：

environment:
  - NODE_TYPE=slave
  - SYNC_FREQUENCY=60
  - FRONTEND_BASE_URL=https://your-domain.com

🔌 基础配置与使用2

One-API 核心使用流程是 “添加 API 渠道→创建访问密钥→测试调用”，新手可按以下步骤操作：

1. 步骤 1：添加 API 渠道（核心功能）

API 渠道是 One-API 对接外部模型的入口（如 OpenAI 的 API），以添加 OpenAI 渠道为例：

进入管理后台→「渠道管理」→「添加渠道」；
填写渠道信息：
- 渠道名称：自定义（如 “OpenAI 官方”）；
- API 类型：选择 OpenAI；
- API 密钥：填写你的 OpenAI API Key（如 sk-xxxx）；
- API 基础 URL：默认 https://api.openai.com（国内需代理可修改）；
- 模型列表：选择支持的模型（如 gpt-3.5-turbo、gpt-4）；
点击「提交」，渠道状态显示 “正常” 即添加成功。

2. 步骤 2：创建访问密钥（用于调用 API）

密钥用于客户端调用 One-API 转发的模型，可限制权限：

进入「密钥管理」→「创建密钥」；
配置密钥参数：
- 密钥名称：自定义（如 “我的测试密钥”）；
- 权限设置：选择允许访问的渠道（如 “OpenAI 官方”）；
- 调用限制：设置 QPS（每秒调用次数）、每日限额（如 100 次）；
点击「提交」，生成密钥（如 sk-xxxx），复制保存（仅显示一次）。

3. 步骤 3：测试 API 调用

使用生成的密钥调用 One-API，验证转发功能：

1.复制调用地址：http://服务器IP:3000/v1/chat/completions（与 OpenAI 接口格式一致）； 2.使用 curl 测试（替换 your_key 为生成的密钥）：

    curl http://服务器IP:3000/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer your_key" \
      -d '{
        "model": "gpt-3.5-turbo",
        "messages": [{"role": "user", "content": "Hello!"}]
      }'

3.若返回类似以下内容，说明调用成功：

    {"id":"...","object":"chat.completion","created":1690000000,"model":"gpt-3.5-turbo","choices":[...]}

4. 步骤 4：用户管理（多用户场景）

若需多用户使用，可创建子用户并分配权限：

进入「用户管理」→「创建用户」；
填写用户名、邮箱、密码，设置角色（如 “普通用户”）；
子用户登录后可管理自己的密钥，但无法修改渠道配置（管理员权限隔离）。

🛠️ 维护与管理

日常维护操作

1.服务启停

   # 停止服务
   docker compose down

   # 启动服务
   docker compose up -d

2.数据备份

   # 备份整个数据目录
   tar -czf one-api-backup-$(date +%Y%m%d).tar.gz ./data

3.服务更新

   # 进入部署目录
   cd /home/compose/one-api

   # 拉取最新镜像并重启
   docker compose pull
   docker compose down
   docker compose up -d

监控与日志

1.查看实时日志

   docker compose logs -f one-api

2.监控服务健康

   docker compose ps

3.检查资源使用

   docker stats

性能优化

数据库优化
定期清理日志和缓存数据
监控数据库性能指标
Redis 调优
根据使用情况调整内存配置
设置合适的缓存过期时间

🐛 常见问题排查

1. 无法访问 Web 界面

问题现象：浏览器访问 http://IP:3000 无响应

解决方案： - 检查防火墙设置： bash # 开放 3000 端口 ufw allow 3000 - 验证容器状态：docker compose ps - 查看服务日志：docker compose logs one-api

2. 数据库连接失败

问题现象：One-API 无法连接 MySQL 数据库

解决方案： - 检查 MySQL 容器状态：docker compose logs db - 验证数据库连接参数 - 确认网络连通性

3. 渠道测试失败

问题现象：添加渠道后测试连接失败

解决方案： - 检查 API 密钥有效性 - 验证网络代理设置（如需要） - 确认模型支持情况

4. 健康检查失败

问题现象：容器健康状态异常

解决方案： - 检查系统资源使用情况 - 查看详细错误日志 - 确认依赖服务正常运行

通过本教程，您应该已经成功部署并配置了 One-API 服务。One-API 的强大统一接口管理功能将为您提供便捷的多模型 API 管理体验。如果在使用过程中遇到其他问题，可以参考项目官方文档或相关社区资源。

🐛 常见问题排查2

1. 登录失败（提示 “用户名或密码错误”）

原因 1：默认密码未修改，或修改后遗忘。解决：重置管理员密码（进入 One-API 容器执行）：

    docker exec -it one-api ./one-api --reset-password
    # 按提示输入新密码，重启容器后生效

原因 2：数据库连接失败，无法验证账号。解决：检查 SQL_DSN 配置，确保密码正确，重启 MySQL 容器：docker compose restart db。

2. API 调用提示 “模型不存在”

原因：调用的模型未在渠道中配置，或渠道未启用。

解决： 1. 进入「渠道管理」，确认渠道状态为 “正常”； 2. 编辑渠道，在「模型列表」中添加调用的模型（如 gpt-3.5-turbo）； 3. 确认密钥权限包含该渠道（「密钥管理」→ 编辑密钥 → 检查权限）。

3. 数据库连接频繁断开（日志显示 “connection refused”）

原因 1：MySQL 容器内存不足，频繁重启。解决：增加服务器内存（建议 4GB+），或限制 MySQL 内存占用（在 db 服务添加 deploy: resources: limits: memory: 1G）。
原因 2：SQL_DSN 中数据库地址错误（非 db 容器名）。解决：确保 SQL_DSN 中数据库地址为 tcp(db:3306)（容器名访问），而非 IP 地址。

4. Redis 缓存未生效（调用延迟高）

原因：Redis 连接配置错误，或未挂载数据导致缓存丢失。

解决： 1. 检查 REDIS_CONN_STRING=redis://redis 配置是否正确； 2. 确认 Redis 容器正常运行：docker compose ps redis； 3. 添加 Redis 数据挂载（如配置中补充 volumes: - ./data/redis:/data），重启 Redis。

5. 日志显示 “API 调用失败”（渠道返回错误）

原因：外部 API 密钥无效、网络不通，或渠道 URL 错误。

解决： 1. 进入「渠道管理」→ 点击渠道的「测试」按钮，检查连接状态； 2. 验证 API 密钥有效性（直接用外部 API 测试，排除密钥问题）； 3. 若为国内服务器，检查是否需代理（修改渠道「API 基础 URL」为代理地址）。

通过以上步骤，新手可成功部署 One-API 并实现 API 聚合管理。One-API 适合个人整合多模型 API，也适合企业搭建内部 API 网关，后续可探索多机部署、自定义域名、SSL 加密等高级功能，具体参考 One-API 官方文档。