跳到主要内容

网关认证 & 上游认证

网关认证​

网关认证决定一条请求是否允许继续进入 Aidy 的治理与转发链路。

当前的认证优先级固定为：

  1. routes.disable_auth = true -> 禁用认证
  2. routes.passthrough_auth_token = true -> 透传认证 Key
  3. routes.legacy_bearer_auth_tokens 非空 -> 固定 API Key 认证
  4. 默认 -> 消费者 API Key 认证

disable_auth 禁用认证​

当 route 设置 disable_auth = true 时，直接跳过所有认证。

仅适合：

  • 内网可信场景
  • 临时排障

passthrough_auth_token 透传认证 Key​

当 route 开启 passthrough_auth_token = true 时：

  • 本地认证直接放行
  • Aidy 不消费客户端传入的 Authorization
  • 转发给上游时会保留原始 Authorization
危险

这是一个兼容开关，不建议使用。

  1. 该功能仅限 chat-completions 协议使用，且无法和协议转换能力兼容
  2. 该功能无法和多上游能力兼容，且无法和单上游但定义了多个 key 的场景兼容
  3. 该功能无法和请求头覆盖能力兼容

「无法兼容」的定义：

  1. 可能目前无法正常工作
  2. 可能现在可以正常工作，但未来无法正常工作

legacy_bearer_auth_tokens 固定 API Key 认证​

当 route 配置了 legacy_bearer_auth_tokens，且未命中前两个分支时，会按 route 自带的 Bearer Token 列表做认证：

Authorization: Bearer <token>

行为：

  • 命中列表则通过
  • 不命中返回 OpenAI 风格 401
  • 认证结束后会消费掉该 Authorization
危险

这是一个兼容开关，不建议使用。

  1. 该功能仅限 chat-completions 协议使用，与其它协议不兼容
  2. 该功能将在未来的小版本中移除，请尽快切换为使用消费者进行认证

consumer_api_keys 消费者 API Key 认证​

默认认证链路是 consumer_api_keys：

Authorization: Bearer <api-key> # chat-completions 和 open-responses 协议
x-api-key: <api-key> # claude-messages 协议

运行时会：

  1. 根据完整 key 查到 consumer_api_keys
  2. 关联到 consumers
  3. 检查 key 和 consumer 是否属于当前 tenant
  4. 过滤已禁用、已吊销或已过期的 key，以及已禁用的 consumer

具体条件是：

  • consumers.disabled_at is null
  • consumer_api_keys.disabled_at is null
  • consumer_api_keys.revoked_at is null
  • consumer_api_keys.expires_at is null or consumer_api_keys.expires_at > now()

上游认证​

上游认证指的是请求已经通过了「网关认证」的授权以后，即将转发给上游大模型 API 时，发送什么 API Key。

该 Key 是在 upstream 表的 api_keys 中定义的。

  1. 一个 upstream 可以定义多个 key，这些 key 会参与候选展开与负载均衡。
  2. 如果 upstream 没有定义任何 key，会按照无认证头的形式进行转发。

扩展阅读： 模型与 Upstream 解析