跳到主要内容

网关认证 & 上游认证

网关认证​

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

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

  1. routes.disable_auth = true
  2. routes.passthrough_auth_token = true
  3. routes.legacy_bearer_auth_tokens 非空
  4. 默认走 consumer_api_keys

如果某条 route 最终没有装配任何认证插件，请求会被允许通过。

disable_auth​

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

适合：

  • 内网联调
  • 明确不需要客户端鉴权的 route
  • 临时排障

passthrough_auth_token​

当 route 开启 passthrough_auth_token = true 时：

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

这是一个兼容开关，不建议作为长期主认证模型扩展。

legacy_bearer_auth_tokens​

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

Authorization: Bearer <token>

行为：

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

consumer_api_keys​

默认认证链路是 consumer_api_keys：

Authorization: Bearer <api-key>

运行时会：

  1. 根据完整 key 查到 consumer_api_keys
  2. 关联到 consumers
  3. 检查 key 和 consumer 是否属于当前 tenant

多认证插件语义​

认证插件支持同时存在多个，组合语义是 AND：

  • 所有认证插件都返回成功，请求才通过
  • 只要有一个失败，请求就失败

上游认证​

上游认证和网关认证是两条不同链路。

当前上游凭证存放在 upstreams.api_keys JSON 数组中，而不是独立表。

运行时会把每个 upstream 的可用 api_keys 展开成独立候选。

如果 upstream 没有任何 key，会补一个“空 token 候选”。

这些候选会按顺序进入真正的转发与 fallback。

可用 key 的筛选条件是：

  • disabled_at IS NULL
  • expires_at 未过期
  • key 非空

排序规则：

  • upstream.priority 越大越优先；不同优先级之间始终是高优先级在前
  • upstream_api_key 继承所属 upstream 的优先级，不再有独立优先级语义
  • 仅在同优先级内，按 upstream_api_key.lb_weight 优先、否则回退到 upstream.lb_weight 做加权随机无放回排序
  • 单次请求最多保留前 route.max_attempts 个候选；默认 2

被命中的候选 key 会写入转发时使用的上游 token。