笙亿网络策划

在ONE-API中接入本地Ollama渠道并配置令牌鉴权的完整指南

约 5 分钟读完 41 阅
文章导读
在 ONE-API 中接入本地 Ollama，本质上是把 Ollama 当作一个 OpenAI 兼容的渠道注册进 ONE-API，再由 ONE-API 的令牌机制对外暴露。Ollama 默认不校验请求密钥，因此渠道密钥这里通常只是占位；真正对客户端生效的鉴权，是后续在 ONE-API 中创建的访问令牌。
📋 目录
  1. 一 前置准备
  2. 二 在 ONE-API 中新增 Ollama 渠道
  3. 三 配置令牌鉴权和访问令牌
  4. 四 用 curl 验证请求链路
  5. 五 失败时的回退与排查
A A

在 ONE-API 中接入本地 Ollama，本质上是把 Ollama 当作一个 OpenAI 兼容的渠道注册进 ONE-API，再由 ONE-API 的令牌机制对外暴露。Ollama 默认不校验请求密钥，因此渠道密钥这里通常只是占位；真正对客户端生效的鉴权，是后续在 ONE-API 中创建的访问令牌。

前置准备

开始前先确认四件事：

  • Ollama 服务正常运行，并已拉取至少一个模型。可用 curl http://localhost:11434/api/tags 看到模型列表。
  • ONE-API 已经部署并可访问管理后台。默认管理地址通常是 http://localhost:3000，登录后进入渠道管理页。
  • 如果 ONE-API 和 Ollama 分别运行在 Docker 容器中，注意 localhost 指向容器自身；需要把渠道地址改为宿主机可访问的地址，例如 http://host.docker.internal:11434（仅本机 Docker Desktop 环境可用）。
  • 确定要在 ONE-API 中使用的模型名称，例如 llama3 或 qwen2.5，这个名称要同时出现在 Ollama 模型中。

在 ONE-API 中新增 Ollama 渠道

  1. 登录 ONE-API 管理后台，进入“渠道”页面，点击“添加渠道”。
  2. 渠道类型选择 Ollama。
  3. “名称”可填 local-ollama，用于区分。
  4. “代理地址”填写 Ollama 的 Base URL，注意不要写 /v1。例如 http://localhost:11434。
  5. “密钥”一项，如果 Ollama 本身没有开启鉴权，可以先填任意值，例如 ollama；若你的 Ollama 部署已通过环境变量或反向代理要求 API Key，这里填对应的 Key。
  6. “模型”里填入你已经在 Ollama 中拉取好的模型名，多个模型用逗号或换行分隔。
  7. 保存后，在渠道列表里看到该渠道状态为“已启用”。如果 ONE-API 会做连通性测试，观察是否通过；即使未自动测试，也可用下一步验证。

配置令牌鉴权和访问令牌

这一步是外部调用真正使用的鉴权层。客户端请求应打到 ONE-API 的 OpenAI 格式地址，并用 ONE-API 生成的令牌来认证，而不是直连 Ollama 的 11434。

  1. 在 ONE-API 左侧菜单进入“令牌”页，点击“添加令牌”。
  2. 选择该令牌可访问的模型范围。为测试方便，可以先选择“所有模型”。
  3. 创建后，页面会展示完整的令牌字符串，例如 sk-abc123...，只在本次显示，请立即复制并保存。
  4. 如果你希望 Ollama 本身也能校验一个固定密钥，需要在 Ollama 侧额外配置。一个通用做法是在 Ollama 启动时设置 API Key 环境变量（具体变量名取决于部署环境），或者在其前置 Nginx 中校验请求头。ONE-API 渠道密钥只负责与 Ollama 通信，不能代替这一层。

用 curl 验证请求链路

推荐先验证 Ollama 直连，再验证 ONE-API 转发。

在ONE-API中接入本地Ollama渠道并配置令牌鉴权的完整指南
curl http://localhost:11434/api/tags

返回模型列表后，再通过 ONE-API 调用一个补全请求。注意替换地址、端口、令牌和模型名。

curl http://localhost:3000/v1/chat/completions -H "Authorization: Bearer sk-abc123..." -H "Content-Type: application/json" -d '{"model":"llama3","messages":[{"role":"user","content":"你好"}]}'

如果返回包含 choices 字段，说明渠道链路和令牌鉴权都已生效。若返回 401，先检查令牌是否有效、是否过期；若返回 404，检查 ONE-API 中渠道模型名是否和 Ollama 中的模型名完全一致。

失败时的回退与排查

  • Ollama 无法访问：先执行 curl http://localhost:11434/api/tags，确认服务本身正常；若 ONE-API 在容器内，把渠道地址改为宿主机 IP 或 host.docker.internal。
  • ONE-API 返回“上游渠道错误”：查看 ONE-API 运行日志，通常可以看到实际错误码。常见原因是模型名不匹配、Ollama 的 API 格式差异、或者密钥被 Ollama 拒绝。
  • 令牌鉴权失败：确认请求头格式为 Authorization: Bearer sk-...，且在 ONE-API 中该令牌未被删除或限制。
  • 如果只是想在本地临时用，不打算暴露给其他机器，可以保持 Ollama 不对本地局域网开放；让 ONE-API 绑定在回环地址，避免外部直接访问 11434。