本地模型服务接入OneAPI网关时bearer token鉴权失效的排查

文章导读
bearer token 鉴权失效通常发生在两个方向:一是请求到达 OneAPI 时就没能通过校验,二是 OneAPI 成功接收,但上游模型服务拒绝转发请求。排查时先控制变量,分别用 curl 测试直接访问上游和经过 OneAPI 两条路径,快速定位是哪一段出错。不要一开始就同时改动网关和上游的多个配置。
📋 目录
  1. Ⅰ 前置条件:先确认上游服务的 token 规则
  2. Ⅱ OneAPI 渠道配置:区分调用方密钥和上游密钥
  3. Ⅲ 验证请求头在转发时是否被覆盖
  4. Ⅳ 失败时的临时回退和根治方向
A A

bearer token 鉴权失效通常发生在两个方向:一是请求到达 OneAPI 时就没能通过校验,二是 OneAPI 成功接收,但上游模型服务拒绝转发请求。排查时先控制变量,分别用 curl 测试直接访问上游和经过 OneAPI 两条路径,快速定位是哪一段出错。不要一开始就同时改动网关和上游的多个配置。

前置条件:先确认上游服务的 token 规则

本地模型服务(vLLM、Ollama、LM Studio 等)的鉴权实现并不完全一致。即便都提供 OpenAI 兼容接口,对 Authorization 头的要求也可能不同:有的要求必须带 Bearer 前缀,有的允许自定义 token 字段,还有的在启动时默认关闭鉴权。先查看上游服务的启动参数或日志,确认它期望的请求头格式。

curl -H "Authorization: Bearer 你的上游Token" http://127.0.0.1:8000/v1/models

执行位置放在运行 OneAPI 的主机或容器内,而不是只在宿主机上执行。如果返回 401,说明上游 token 本身无效或格式不对,问题不在 OneAPI;如果返回 200,说明问题出在网关转发阶段。

OneAPI 渠道配置:区分调用方密钥和上游密钥

OneAPI 中存在两类凭据:一类是调用方请求时使用的 API Key,也就是你在应用里配置的令牌;另一类是每个渠道(Channel)里填写的“密钥”,网关会用这个密钥替换请求中的 Authorization 头再转发给上游。两者不能互相替代。常见错误是把网关的 API Key 填进渠道密钥,导致上游收到一个自己不认识的 token,从而返回 401。

检查路径:先看渠道里的“代理地址”是否能被 OneAPI 所在进程访问。很多本地模型服务监听在 127.0.0.1 或宿主机端口,如果 OneAPI 运行在容器里,透传规则可能没有覆盖,也会表现为鉴权失败——因为请求根本没到达上游。再检查渠道中的模型映射,确认你调用的模型名与上游暴露的模型名对应。

验证请求头在转发时是否被覆盖

OneAPI 的默认行为是用渠道密钥替换掉调用方传进来的 Authorization 头。也就是说,你发给 OneAPI 的 token 不会继续传给上游。这个设计本身不是故障,但会让排查者误以为 token“丢失”了。要确认这个环节,可以在上游服务里临时打开访问日志,观察收到的 Authorization 头内容。

本地模型服务接入OneAPI网关时bearer token鉴权失效的排查
# 示例:在 OneAPI 所在主机上查看日志,或在上游模型服务日志中过滤 authorization
tail -f /var/log/OneAPI.log | grep authorization

如果上游日志显示 Authorization 头不是预期的 Bearer token,说明渠道密钥没填对。如果 OneAPI 直接返回 401,则先验证调用方令牌本身是否有效,比如用这个令牌请求 OneAPI 的 /models 接口。还要检查该令牌是否被设置了 IP 限制或过期时间,某些管理面板的权限限制也会让鉴权结果不稳定。

失败时的临时回退和根治方向

当线上调用已经中断,需要尽快恢复时,可以采用以下步骤,但每一步都伴随风险,普通内网测试场景更安全。

  • 临时关闭上游服务的鉴权功能(如修改启动参数或环境变量),只开放给内网访问,不暴露公网。恢复后应尽快关闭该选项。
  • 把 OneAPI 渠道密钥改为上游实际使用的 token,同时把调用方请求中的 token 改回 OneAPI 自己生成的令牌。
  • 如果上游要求两个不同的头字段,OneAPI 的通用转发功能可能不支持,需要先确认当前版本是否支持自定义请求头。若不支持,建议在 OneAPI 和上游之间加一个轻量转发层,由转发层负责拼接头字段。

根治方向是固定住三个变量:上游服务接受什么形式的 token、OneAPI 渠道密钥用什么值、调用方必须使用 OneAPI 发放的令牌。这三个环节只要有一个不匹配,鉴权就会失效。调整后不要只看返回码,要同时确认上游日志中实际收到的 Authorization 头是否符合预期。

常见问题

为什么直接访问上游成功,经过 OneAPI 就 401?
因为 OneAPI 用渠道密钥替换了你的 Authorization 头,上游是从渠道密钥中取 token 的。如果渠道密钥不是有效的上游 token,自然会被拒绝。

渠道密钥里应该填什么?
填上游服务能够识别并允许访问的 token。如果上游本身没有开启鉴权,留空可能可以,但不建议在非隔离网络中这样做。