导读：你可以把这篇当成 One API 本地部署流程来用。One API 是一个开源的 AI API 聚合管理平台，可以把多个模型服务商统一到一套 OpenAI 兼容接口下。本文重点讲本地部署：先用 Docker 跑起来，再完成管理员初始化、渠道配置、令牌创建和一次真实 API 调用验证。

系列文章导航

  1. One API 部署教程(一)：本地部署完整指南
  2. One API 部署教程(二)：Render 免费部署全攻略
  3. One API 部署教程(三)：使用指南

本地部署适合什么场景

本地部署的目标不是“马上给生产业务用”，而是先把 One API 的核心链路跑通：

1
应用请求 → One API → 渠道配置 → 模型服务商 → 返回结果
场景是否适合本地部署说明
学习 One API 后台功能适合不需要公网和域名
测试 DeepSeek/OpenAI 等渠道适合可以快速验证模型名和 Key
团队长期共享 API 网关不适合应使用 VPS/内网服务器部署
给线上应用稳定调用不适合本地机器关机、断网都会影响服务

如果你需要临时公网演示，可以看下一篇 Render 免费部署 One API；如果只是学习，先在本机跑通最稳。

准备工作

开始前确认三件事：

  1. 电脑已安装 Docker；
  2. 终端能执行 docker --version；
  3. 你手里至少有一个 AI 服务商的 API Key，用于后续渠道测试。

官方参考与 资料来源：

这两个 官方来源 是镜像、Docker 参数和部署行为的主要依据。本文给的是个人本地验证路径；如果官方镜像、端口或配置项变化，应以官方仓库和 Docker 文档为准。

验证 Docker：

1
2
docker --version
docker ps

如果 docker ps 报权限错误，Linux 用户需要检查 Docker 用户组；Windows/Mac 用户要确认 Docker Desktop 已启动。

方法一：Docker 命令行部署

这是最快的本地体验方式，适合第一次安装。

Step 1：准备数据目录

建议先创建一个单独目录保存 One API 数据，避免容器删除后数据丢失：

1
mkdir -p ./one-api-data

Step 2：拉取镜像

1
docker pull justsong/one-api

如果镜像拉取失败，可以查看 One API 官方仓库，确认当前推荐镜像地址。不要随便使用不明来源镜像，API 网关会接触你的密钥。

Step 3：启动容器

1
2
3
4
5
6
7
docker run --name one-api \
  -d \
  --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ${PWD}/one-api-data:/data \
  justsong/one-api

参数说明：

参数作用为什么重要
--name one-api容器名称后续方便查看日志和重启
-d后台运行关闭终端后容器继续运行
--restart always自动重启电脑重启后自动拉起容器
-p 3000:3000端口映射浏览器通过 localhost:3000 访问
-v ...:/data数据持久化保存账号、渠道、令牌等数据
TZ=Asia/Shanghai时区日志和账单时间更直观

Step 4：查看运行状态

1
docker ps

如果容器没有运行，查看日志：

1
docker logs one-api --tail 100

方法二：Docker Compose 部署

如果你希望配置更清晰，推荐使用 Docker Compose。后续接 MySQL、Redis 或反向代理时也更容易扩展。

创建 docker-compose.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
version: '3'

services:
  one-api:
    image: justsong/one-api
    container_name: one-api
    restart: always
    ports:
      - "3000:3000"
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./one-api-data:/data

启动：

1
docker compose up -d

查看日志：

1
docker compose logs -f

停止：

1
docker compose down

如果你的环境还在使用旧版命令，可能需要把 docker compose 改成 docker-compose。

第一次访问和管理员安全

浏览器打开：

1
http://localhost:3000

首次访问时，根据页面提示创建管理员账号。某些部署方式可能存在默认账号，例如 root / 123456。如果看到默认账号，登录后第一件事就是修改密码。

安全建议：

  1. 管理员密码不要和其它网站重复；
  2. 不要把 One API 暴露到公网后仍使用弱密码；
  3. 不要在文章截图、issue、聊天记录里暴露真实 API Key；
  4. 生产环境应使用 HTTPS、反向代理和访问控制；
  5. 定期备份数据目录。

添加第一个渠道

以 DeepSeek 或 OpenAI 兼容渠道为例，后台大致流程是：

  1. 进入 渠道管理；
  2. 点击 添加渠道；
  3. 选择服务商类型；
  4. 填写 API Key；
  5. 配置模型列表；
  6. 保存后测试渠道状态。

建议第一次只添加一个渠道。多个渠道同时配置时，如果调用失败，很难判断是哪个 Key、模型名或代理地址有问题。

创建令牌并测试调用

进入 令牌管理，创建一个测试令牌。然后在终端发起请求：

1
2
3
4
5
6
7
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "你好，用一句话确认服务正常"}]
  }'

成功时，你应该看到模型返回的内容。这个测试比“页面能打开”更重要，因为它验证了完整链路：

  1. 本地端口可访问；
  2. One API 能识别令牌；
  3. 渠道 API Key 有效；
  4. 模型名匹配；
  5. 返回结果能正常透传。

Windows PowerShell 调用示例

PowerShell 对引号处理和 Bash 不一样，建议先把 JSON 放进变量：

1
2
3
4
5
6
7
$body = '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'

Invoke-RestMethod `
  -Uri "http://localhost:3000/v1/chat/completions" `
  -Method Post `
  -Headers @{"Content-Type"="application/json"; "Authorization"="Bearer sk-你的令牌"} `
  -Body $body

如果你使用 Git Bash，也可以直接用前面的 curl 写法。

常见错误排查

错误表现可能原因解决方式
localhost:3000 打不开容器没启动或端口被占用docker ps、docker logs one-api
容器反复重启数据目录权限或配置错误检查 one-api-data 权限和日志
登录后数据丢失没有挂载 /data使用 -v ./one-api-data:/data
API 返回 401令牌错误确认 Authorization: Bearer sk-...
API 返回模型不存在模型名没配置检查渠道模型列表
调用超时上游服务商网络问题换渠道、检查代理或服务商状态
Docker 拉取失败镜像源网络问题换网络或参考官方镜像说明

本地部署风险边界和决策矩阵

本地部署不是生产方案。你可以用下面的 decision matrix 判断是否继续留在本机：

判断问题如果答案是“是”建议
是否只有自己测试？是保持本地 Docker 即可
是否需要手机、服务器或队友访问？是迁移到公网或内网服务器
是否接入真实付费 API Key？是增加备份、强密码和访问控制
是否每天自动化调用？是不建议依赖个人电脑本地服务
是否需要长期稳定响应？是使用 VPS / 内网服务器 / 容器平台

简单公式：

1
本地部署价值 = 学习成本低 + 调试快 - 稳定性风险 - 共享访问成本

只要“稳定性风险”和“共享访问成本”开始影响使用，就该迁移。

什么时候该从本地迁移到线上

本地部署跑通后，如果出现以下需求，就该考虑线上部署：

  • 需要多设备访问同一个 One API；
  • 要给自动化脚本、服务器或团队成员调用；
  • 希望接入自定义域名和 HTTPS；
  • 需要更稳定的运行时间；
  • 需要定期备份和监控。

迁移路径可以是：

  1. Render 免费部署：适合短期演示；
  2. VPS + Docker Compose：适合长期使用；
  3. 内网服务器：适合团队内部 API 网关。

相关内链

总结

One API 本地部署的关键不是把容器跑起来，而是完成“持久化数据、管理员安全、渠道配置、令牌调用”这一整条链路。只要你能用测试令牌成功调用一次 /v1/chat/completions，后续再迁移到 Render、VPS 或内网服务器就会清晰很多。