One API 保姆级部署教程：自托管大模型统一网关，一套 OpenAI 接口聚合所有 LLM

本文所有命令与配置均照搬 One API 官方仓库 README（github.com/songquanpeng/one-api，main 分支）与仓库内 .env.example、docs/API.md 等文件，未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

One API 是由开发者 songquanpeng（JustSong）开源的大模型统一网关 / 分发系统。官方 README 副标题为："通过标准的 OpenAI API 格式访问所有的大模型，开箱即用"。它在各类大模型上游（OpenAI、Azure OpenAI、Anthropic Claude、Google Gemini、Mistral、字节豆包、百度文心、阿里通义、讯飞星火、智谱 ChatGLM、腾讯混元、Moonshot、DeepSeek、xAI、Groq、Ollama 等）与你的应用之间充当反向代理：上游各家模型的不同协议被 One API 统一改写成 OpenAI Chat Completions 格式，下游只需要一个 API Base + 一个令牌就能调用所有模型。

官方同时提供 Docker 镜像 justsong/one-api（Docker Hub）与 ghcr.io/songquanpeng/one-api（GitHub Container Registry），稳定版与 alpha 版分别发布。项目在 GitHub（songquanpeng/one-api）持续活跃维护（核验日期 2026-11-01），官方在线演示站为 https://openai.justsong.cn/ 。

二、功能拆解

按官方 README「功能」一节，One API 的核心能力如下：

三、官方/GitHub 链接

• GitHub 仓库：https://github.com/songquanpeng/one-api
• 官方在线演示：https://openai.justsong.cn/
• Docker Hub 镜像（稳定版）：https://hub.docker.com/r/justsong/one-api
• GHCR 镜像（稳定版）：https://github.com/songquanpeng/one-api/pkgs/container/one-api
• Docker Hub 镜像（alpha 版）：https://hub.docker.com/r/justsong/one-api-alpha
• Release 下载（二进制 / 源码）：https://github.com/songquanpeng/one-api/releases/latest
• 仓库内 API 文档：https://github.com/songquanpeng/one-api/blob/main/docs/API.md
• 主题列表：https://github.com/songquanpeng/one-api/tree/main/web/README.md

四、环境要求

官方 README 提供四种原生部署方式：基于 Docker、宝塔面板一键、Docker Compose、手动编译。最常用、官方文档最完整的是 Docker 方式。

• 操作系统：官方 Docker 镜像为 Linux 容器镜像，需在 Linux 主机（或 macOS / Windows 上的 Docker Desktop）运行 Docker。
• 软件依赖：仅需 Docker（如使用 Docker Compose 方式还需 docker-compose）。手动编译方式额外需要 Node.js + npm（构建前端）与 Go（构建后端）。
• 端口：容器内默认监听 3000；官方示例 -p 3000:3000，第一个 3000 是宿主机端口，可按需修改。
• 数据库：默认使用 SQLite（零依赖，数据落盘在挂载卷 /data 下的 one-api.db）；并发量较大或多机部署时官方要求切换到 MySQL（或 PostgreSQL，"适配中"）。
• 硬件：官方 README 未给出最低硬件指标；官方多机部署章节建议高并发场景搭配 Redis 缓存。
• 数据目录：官方示例将宿主目录 /home/ubuntu/data/one-api 挂载为容器内 /data，数据与日志都保存在此。

五、部署步骤

方式 A：Docker 部署（官方 README「基于 Docker 进行部署」）

步骤 1：准备数据目录

mkdir -p /home/ubuntu/data/one-api

逐段解释：mkdir -p 递归创建目录；/home/ubuntu/data/one-api 是官方示例给出的数据持久化宿主路径，请确保该目录存在且对当前用户可写，或改成你自己的路径。

预期输出参考： 命令成功，无输出。

步骤 2：使用 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

逐段解释：
- docker run 启动一个新容器；
- --name one-api 给容器命名为 one-api；
- -d 后台运行；
- --restart always 容器退出或 Docker 守护进程重启后自动拉起（即官方提供的开机自启方式）；
- -p 3000:3000 将宿主 3000 端口映射到容器 3000 端口，官方 README 注明："其中，-p 3000:3000 中的第一个 3000 是宿主机的端口，可以根据需要进行修改"；
- -e TZ=Asia/Shanghai 设置容器时区为上海；
- -v /home/ubuntu/data/one-api:/data 将宿主数据目录挂载到容器 /data，SQLite 数据库文件与日志都保存在这里；
- justsong/one-api 是官方 Docker Hub 镜像名。

预期输出参考： 输出一串容器 ID（长哈希字符串），回到命令行提示符。

步骤 2（备选）：使用 MySQL 启动（官方原命令）

官方 README 原文："使用 MySQL 的部署命令，在上面的基础上添加 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi"，请自行修改数据库连接参数"。官方示例命令：

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 /home/ubuntu/data/one-api:/data justsong/one-api

逐段解释：与步骤 2 相同，额外多了一个环境变量 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi"，告诉 One API 连接外部 MySQL 数据库（用户 root、密码 123456、主机 localhost:3306、库名 oneapi）。官方 README 注明："注意需要提前建立数据库 oneapi，无需手动建表，程序将自动建表"；"如果使用本地数据库：部署命令可添加 --network="host" 以使得容器内的程序可以访问到宿主机上的 MySQL"。

步骤 3：确认容器运行状态

docker ps --filter name=one-api

逐段解释：docker ps 列出运行中容器，--filter name=one-api 按名字过滤。

预期输出参考： 看到 one-api 容器 STATUS 为 Up ...，PORTS 列显示 0.0.0.0:3000->3000/tcp。

方式 B：Docker Compose 部署（官方 README「基于 Docker Compose 进行部署」）

官方 README 原文："仅启动方式不同，参数设置不变，请参考基于 Docker 部署部分"。仓库提供了基于 MySQL 的 compose 文件，官方命令：

# 目前支持 MySQL 启动，数据存储在 ./data/mysql 文件夹内
docker-compose up -d

# 查看部署状态
docker-compose ps

逐段解释：docker-compose up -d 在当前目录读取 docker-compose.yml 后台启动全部服务（One API + MySQL）；docker-compose ps 查看本 compose 项目的容器状态。官方注明"数据存储在 ./data/mysql 文件夹内"。

方式 C：手动编译部署（官方 README「手动部署」）

步骤 1：拉取源码并构建前端

git clone https://github.com/songquanpeng/one-api.git

# 构建前端
cd one-api/web/default
npm install
npm run build

逐段解释：git clone 克隆源码；进入 web/default 前端目录后用 npm 安装依赖并构建生产包。

步骤 2：构建后端

cd ../..
go mod download
go build -ldflags "-s -w" -o one-api

逐段解释：回到仓库根目录；go mod download 下载 Go 依赖；go build -ldflags "-s -w" -o one-api 编译为单一可执行文件 one-api。

步骤 3：运行

chmod u+x one-api
./one-api --port 3000 --log-dir ./logs

逐段解释：chmod u+x 给可执行文件加执行权限；./one-api 启动服务；--port 3000 指定监听端口；--log-dir ./logs 指定日志目录。

方式 D：宝塔面板一键部署（官方 README）

官方 README「通过宝塔面板进行一键部署」：① 安装宝塔面板 9.2.0 及以上；② 在宝塔面板中安装 Docker 服务；③ 在应用商店搜索 One-API 并安装，配置域名等基本信息即可。详细步骤另见官方 issue #175（https://github.com/songquanpeng/one-api/issues/175）。

六、配置参数详解

官方 README「环境变量」一节明确列出了全部可调参数。系统本身开箱即用，可通过环境变量或命令行参数配置。

1. 命令行参数（官方「命令行参数」一节）：

2. 关键环境变量（官方「环境变量」一节）：

官方 README 同时注明："One API 支持从 .env 文件中读取环境变量，请参照 .env.example 文件，使用时请将其重命名为 .env"。

3. Nginx 反向代理参考配置（官方 README 原文）：

server{
   server_name openai.justsong.cn;  # 请根据实际情况修改你的域名

   location / {
          client_max_body_size  64m;
          proxy_http_version 1.1;
          proxy_pass http://localhost:3000;  # 请根据实际情况修改你的端口
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-For $remote_addr;
          proxy_cache_bypass $http_upgrade;
          proxy_set_header Accept-Encoding gzip;
          proxy_read_timeout 300s;  # GPT-4 需要较长的超时时间，请自行调整
   }
}

逐段解释：server_name 改为自己的域名；proxy_pass 指向本机 One API 的 3000 端口；client_max_body_size 64m 允许较大的请求体；proxy_read_timeout 300s 长超时以适配 GPT-4 类长响应。

4. HTTPS 配置（官方 README 原文，使用 Let's Encrypt certbot）：

# Ubuntu 安装 certbot：
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
# 生成证书 & 修改 Nginx 配置
sudo certbot --nginx
# 根据指示进行操作
# 重启 Nginx
sudo service nginx restart

七、启动与运维

• 启动 / 停止 / 重启： Docker 方式启动即上面的 docker run；停止 docker stop one-api；启动已存在容器 docker start one-api；重启 docker restart one-api。
• 后台常驻 / 开机自启： 官方命令中带的 --restart always 即官方提供的自启策略——容器异常退出或 Docker 守护进程重启后自动拉起。
• 修改端口： 官方 README 注明："-p 3000:3000 中的第一个 3000 是宿主机的端口，可以根据需要进行修改"，即把宿主端口改成想要的端口（如 -p 8080:3000），容器内端口保持 3000 不变。
• 查看日志： docker logs -f one-api 跟踪容器日志（Ctrl+C 退出跟踪不停止容器）。手动部署方式日志输出在 --log-dir 指定目录。
• 数据持久化： 官方示例 -v /home/ubuntu/data/one-api:/data，SQLite 数据库文件 one-api.db 与日志均落在该宿主目录。
• 更新命令（官方 README 原文）： docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower -cR（使用 Watchtower 自动拉取并重启更新）。
• 镜像拉取失败备选： 官方 README："如果上面的镜像无法拉取，可以尝试使用 GitHub 的 Docker 镜像，将上面的 justsong/one-api 替换为 ghcr.io/songquanpeng/one-api 即可"。
• 启动失败加特权： 官方 README："如果启动失败，请添加 --privileged=true，具体参考 https://github.com/songquanpeng/one-api/issues/482"。

八、实操验证

1. 浏览器访问 http://服务器IP:3000/，看到 One API 登录页（官方 README："访问 http://localhost:3000/ 并登录"）。
2. 使用初始账号登录：用户名 root，密码 123456（官方 README 原文："初始账号用户名为 root，密码为 123456"）。
3. 登录后进入管理后台，左侧菜单「渠道」→ 新建渠道，填入某上游（如 OpenAI）的 API Key 与分组。
4. 左侧菜单「令牌」→ 新增令牌，复制生成的 sk-xxx 令牌。
5. 用官方 README 给出的 OpenAI 官方库环境变量方式验证调用：

OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1"

逐段解释：把 OPENAI_API_KEY 设为上一步生成的令牌，把 OPENAI_API_BASE 设为你的 One API 地址（末尾带 /v1）。官方 README："你需要在各种用到 OpenAI API 的地方设置 API Base 为你的 One API 的部署地址……API Key 则为你在 One API 中生成的令牌"。

预期输出参考： 用 OpenAI SDK 发起一次 chat completion 请求，One API 后台「日志」页能看到这条请求记录，令牌额度相应扣减。
6. 官方 README 还说明可以在令牌后加渠道 ID 指定走某个渠道：Authorization: Bearer ONE_API_KEY-CHANNEL_ID，"需要是管理员用户创建的令牌才能指定渠道 ID"。

登录与安全（重要）

• 官方默认账号密码： 用户名 root，密码 123456。官方 README 顶部 WARNING 原文："使用 root 用户初次登录系统后，务必修改默认密码 123456！"
• 登录地址： http://服务器IP:3000/。
• 首次登录修改密码： 登录后进入右上角个人设置（"个人设置"页面）修改密码。
• 密码重置： 官方 README 注明支持"通过邮箱进行密码重置"（需在系统设置中配置好 SMTP）。管理员也可在后台「用户」管理中重置其他用户密码。
• 密码配置存放位置： 密码以哈希形式存于数据库——SQLite 方式为 /data/one-api.db（即宿主 /home/ubuntu/data/one-api/one-api.db）；MySQL 方式为 SQL_DSN 指定的库。SESSION_SECRET 环境变量用于签名会话 cookie，不属于密码。
• 安全提醒：部署完成后必须立即登录并把 123456 改成强密码；公网部署建议按官方 Nginx + certbot 配置 HTTPS；高并发务必设置 SQL_DSN 切到 MySQL，避免 SQLite 成为瓶颈。

九、故障排查

案例 1：启动失败，需加 --privileged=true

• 报错原文（官方 README 引用 issue #482）：容器启动即退出，日志中常见权限类错误（如无法挂载 /data 或访问设备失败）。
• 报错原因：官方 README 原文："如果启动失败，请添加 --privileged=true，具体参考 https://github.com/songquanpeng/one-api/issues/482"。
• 分步解决：① docker rm -f one-api 删除失败容器；② 在原 docker run 命令中追加 --privileged=true 后重新执行；③ docker ps 确认 Up。

案例 2：渠道测试报错 invalid character '<' looking for beginning of value

• 报错原文（官方 README「常见问题」第 4 条）：

invalid character '<' looking for beginning of value

• 报错原因：官方 README 原文——"这是因为返回值不是合法的 JSON，而是一个 HTML 页面。大概率是你的部署站的 IP 或代理的节点被 CloudFlare 封禁了"。
• 分步解决：① 检查渠道配置的代理 / 镜像地址是否返回 HTML 拦截页；② 更换出口 IP 或代理节点；③ 在 One API 中重新点「测试」按钮验证。

案例 3：ChatGPT Next Web 前端报错 Failed to fetch

• 报错原文（官方 README「常见问题」第 5 条）：

Failed to fetch

• 报错原因：官方 README 原文——"部署的时候不要设置 BASE_URL。检查你的接口地址和 API Key 有没有填对。检查是否启用了 HTTPS，浏览器会拦截 HTTPS 域名下的 HTTP 请求"。
• 分步解决：① 启动 chatgpt-next-web 容器时去掉 BASE_URL 环境变量；② 在 Next Web 页面的设置里把接口地址填成 One API 地址（如 https://openai.justsong.cn），API Key 填 One API 令牌；③ 用 HTTPS 暴露 One API（按官方 Nginx + certbot 配置）。

案例 4：当前分组负载已饱和，请稍后再试

• 报错原文（官方 README「常见问题」第 6 条）：

当前分组负载已饱和，请稍后再试

• 报错原因：官方 README 原文——"上游渠道 429 了"。
• 分步解决：① 到「渠道」页查看对应渠道的状态与余额；② 给同一分组增加备用渠道做负载均衡；③ 调低客户端并发或等待上游限流恢复。

案例 5：升级后数据丢失（SQLite 未挂载卷）

• 报错原因：官方 README「常见问题」第 7 条——"如果使用 SQLite，需要按照我所给的部署命令挂载 volume 持久化 one-api.db 数据库文件，否则容器重启后数据会丢失"。
• 分步解决：① 确认 docker run 命令中包含 -v /home/ubuntu/data/one-api:/data；② 若之前漏挂载，立即 docker cp one-api:/data/one-api.db ./one-api.db 把数据拷出；③ 用带卷挂载的命令重建容器。

十、升级、回滚与卸载

升级（官方 README 原文命令）：

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower -cR

逐段解释：这是 Watchtower 官方镜像，挂载 Docker socket 后会自动检查并拉取所有正在运行容器的新镜像，-cR 即 monitor all / restart running。官方 README 同时注明（常见问题第 8 条）："一般情况下不需要"手动改数据库 schema，"系统将在初始化的时候自动调整"；如需手动变更会在更新日志中说明。

手动升级： 也可 docker pull justsong/one-api 拉新镜像后 docker stop one-api && docker rm one-api，再按原 docker run 命令（相同 -v 挂载）重新运行。

回滚： 官方未提供一键回滚命令；可将镜像标签改为旧版本（如 justsong/one-api:旧版本号）后重新 docker run。官方 README「常见问题」第 7 条注明：使用 MySQL 时升级不丢数据；使用 SQLite 时数据在 /data 卷中保留，旧版本可读取。

卸载： docker stop one-api && docker rm one-api 删除容器。如需彻底清理数据：删除宿主数据目录 /home/ubuntu/data/one-api（此操作永久删除 one-api.db 与日志，先备份）。镜像可 docker rmi justsong/one-api。

十一、商用许可合规说明

• 许可证：MIT License（仓库 LICENSE 文件：MIT License, Copyright (c) 2023 JustSong）。
• MIT 协议允许自由使用、修改、分发与商用（包括闭源商业产品），但必须保留原始版权声明与许可文本。
• 额外署名要求（官方 README「注意」一节原文）： "本项目使用 MIT 协议进行开源，在此基础上，必须在页面底部保留署名以及指向本项目的链接。如果不想保留署名，必须首先获得授权。同样适用于基于本项目的二开项目。"——即商用部署时，页面底部需保留 One API 署名与回链；如需去除需联系作者授权。
• 官方 README 同时提示合规风险："使用者必须在遵循 OpenAI 的使用条款以及法律法规的情况下使用，不得用于非法用途"，并提醒"根据《生成式人工智能服务管理暂行办法》的要求，请勿对中国地区公众提供一切未经备案的生成式人工智能服务"。