基于 Docker 部署 One API 进行大模型接口管理与 Key 分发

项目简介

One API 是一个开源的 OpenAI 接口管理与分发系统。它支持多种主流大语言模型，包括 Azure、Anthropic Claude、Google PaLM 2 & Gemini、智谱 ChatGLM、百度文心一言、讯飞星火认知、阿里通义千问、360 智脑以及腾讯混元等。该项目旨在通过统一的 API 接口管理多个大模型的 Key，支持二次分发与配额管理，提供单可执行文件及打包好的 Docker 镜像，实现一键部署。

前置准备

在开始部署之前，请确保您的服务器环境满足以下要求：

操作系统：Linux (推荐 Ubuntu 20.04+ 或 CentOS 7+)，Windows 或 macOS 亦可。
Docker：安装并启动 Docker 服务（版本建议 20.10+）。
网络：服务器需能访问公网以拉取镜像，若使用国内镜像源请配置加速。
端口：确保 3000 端口未被占用。
数据库：根据并发量选择 SQLite（轻量级，适合测试）或 MySQL/PostgreSQL（生产环境推荐）。

部署方式

项目作者提供了多种部署方案，包括 Docker Compose、手动部署、宝塔面板等。本指南重点介绍最通用的 Docker 容器化部署。

1. 基础部署（SQLite 模式）

适用于个人学习或低并发场景，无需额外配置数据库。

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

--name one-api：容器名称。
-d：后台运行。
-p 3000:3000：映射宿主机 3000 端口到容器内部。
-v ...：挂载数据卷，持久化配置文件与日志。

2. 生产部署（MySQL 模式）

当并发量较大时，建议使用 MySQL 存储数据以保证性能。

首先确保 MySQL 服务已启动，并创建好数据库用户。

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

注意：请将 SQL_DSN 中的密码和数据库名替换为实际值。若数据库不在本地，需修改 tcp(localhost:3306) 为实际 IP。

初始配置

部署完成后，通过浏览器访问 http://服务器IP:3000。

1. 登录与初始化

首次访问会跳转到默认账号登录页。默认凭证通常为：

用户名：root
密码：123456

登录后系统会强制要求修改密码，请务必设置强密码以保障安全。

2. 渠道配置

进入后台管理界面，点击左侧菜单的 渠道管理。

点击 添加渠道。
选择对应的模型类型（如 OpenAI, Azure, 文心一言等）。
填入模型的基础信息，包括模型名称、API Base URL 等。
输入有效的 API Key。
保存后，可在渠道列表查看状态，点击测试验证连通性。

提示：部分第三方模型可能需要特定的 Header 参数，请参考官方文档补充配置。

3. 用户与令牌管理

为了将接口分发给下游应用，需要创建用户并生成 Token。

进入 用户管理，点击 添加用户。
设置用户名、邮箱及初始配额（额度限制）。建议开启每日限额以防滥用。
进入该用户的详情页，点击 生成密钥。
复制生成的 API Key，此 Key 将用于下游应用的鉴权。

客户端集成测试

完成 One API 配置后，即可对接第三方客户端进行测试。以下以 ChatGPT Next Web 为例。

1. 配置环境变量

在 Next Web 的配置文件中，修改以下参数：

OPENAI_API_KEY：填入刚才在 One API 生成的 Token。
BASE_URL：填入 One API 的服务地址，格式为 http://服务器IP:3000/v1。

2. 功能验证

启动 Next Web 应用，尝试发送一条消息。若收到正常回复，说明接口转发链路畅通。

安全与运维建议

在生产环境中部署 One API，除了基本功能外，还需关注安全性与稳定性。

1. 网络安全

防火墙策略：仅开放必要的端口（如 3000），建议配合 Nginx 反向代理，隐藏真实服务端口。
HTTPS 加密：生产环境务必配置 SSL 证书，防止 Key 在传输过程中被窃听。
访问控制：利用 Nginx 的 limit_req 模块对请求频率进行限制，防止 DDoS 攻击。

2. 数据备份

数据库备份：定期导出 MySQL 数据，避免配置丢失。
配置文件备份：挂载的数据卷中包含了关键配置，建议纳入版本控制系统或定时备份脚本。

3. 监控与告警

启用 One API 内置的日志功能，观察请求成功率与延迟。
结合 Prometheus + Grafana 监控容器资源使用情况（CPU、内存、网络 IO）。
设置配额告警，当用户额度耗尽或异常流量触发时及时通知管理员。

4. 常见问题排查

连接超时：检查服务器出站网络是否通畅，确认目标模型 API 地址未被墙。
Key 无效：核对渠道配置的 Key 是否正确，部分模型 Key 可能有过期时间。
权限拒绝：检查用户 Token 是否过期，或该用户是否拥有对应渠道的访问权限。

总结

One API 提供了一个灵活且强大的大模型接口聚合方案，特别适合企业或个人开发者统一管理多模型 Key。通过 Docker 部署可以快速搭建服务，配合合理的配额管理与安全策略，能够构建稳定的 AI 中间件层。随着支持的模型日益增多，其作为统一接入点的价值将进一步凸显。