跳到主要内容

网关认证 & 上游认证

网关认证​

网关认证指的是网关是否允许请求通过网关（进而继续执行一些处理、转发到上游等）。

当为网关配置了 RouteAuth 时，即为开启网关认证，此时客户端请求时必须提供正确的认证信息（目前仅支持 Bearer Token）。

无认证​

当并未配置认证时，网关不会对请求进行认证，而是透明传递所有请求头到上游。

Bearer Token（OpenAI 兼容 API Key）​

当 RouteAuth 的 auth 字段选择了 bearer 时，网关会根据配置的 RouteAuth.BearerAuth 中的 tokens 字段对请求进行认证。

请求网关时，需使用 Authorization: Bearer <token> 头。

该认证方式与 OpenAI 的认证方式一致，因此对于大多数 AI 应用的客户端，选择「OpenAI 兼容」模式即可。

认证失败​

当认证未通过时，网关会采用模拟 OpenAI 的方式返回失败信息。具体而言，会返回 401 状态码，并返回如下格式的 body

{
  "error": {
    "aidy_request_id": "01k0x8krwgqsekg4ss26vp90h0",
    "code": "invalid_api_key",
    "message": "Incorrect API key provided: xxx",
    "param": null,
    "type": "invalid_request_error"
  }
}

其中

  • type：固定为 invalid_request_error
  • code：根据实际情况（OpenAI 的行为），可能为 null 或字符串
  • param 根据实际情况，可能为 null 或对象
  • message：错误信息，字符串
  • aidy_request_id：网关生成的 Request ID（可以利用该字段的存在与否判断认证错误是由上游返回还是网关返回）

上游认证​

上游认证指的是网关带什么 Token 给上游服务。

带有特定 Token​

当在 Upstream 中指定了 token 字段（且 Route 配置未开启 passthrough_auth_token 选项）时，网关会将配置的 token 按照一定方式（不同 UpstreamType 可能不同）传递给上游。

警告

请特别注意，如果此时未指定 RouteAuth，则网关会将任何请求（不进行认证）带有配置的 Token 转发到上游。 如果 Aidy 服务运行在公网，这通常是不安全的行为。

透明传递 Token​

当满足以下条件之一时，网关会不对请求头做任何授权头方面的修改，即 Aidy 完全不存储任何上游 Token，直接传递客户端请求 Aidy 时发送的授权头给上游。

  1. 当未配置网关认证且未配置上游认证时
  2. 当未配置网关认证且开启了 Route 的 passthrough_auth_token 选项时
备注

如果开启了 passthrough_auth_token（即明确启用了 token 透传）：

  1. 不能同时开启网关认证（配置 RouteAuth）—— 这属于错误的配置，会直接导致配置验证失败
  2. Upstream 中的 token 字段会被忽略

不带任何 Token​

当配置了网关认证，但未在上游配置中指定 Token 时，网关不会带任何 Token 给上游。