V2

概览

V2 是一个整体运行模式的更新，是从 aidy-gateway 向 aidy-router 的切换。

• 运行时配置源从 file / redis / redis-v2 切到 PostgreSQL
• 管理方式从一个整体的动态配置切到 PG 主业务表 + ConnectRPC Management API

因此，推荐迁移方式始终是：

1. 从 v1 导出旧配置
2. 转换成 V2 的 PG 实体或 seed 文件
3. 写入 PostgreSQL
4. 切换静态配置到 PG runtime
5. 再切流量

不要把 V2 当成 v1 dynamic config 的原地热升级。

核心 Breaking Changes

运行时配置与部署方式

• 不再支持旧动态配置源
  • file
  • redis
  • redis-v2
• 静态配置中的 dynamic-config 含义已经变化：
  • v1：source=file|redis，配 file / redis / enable_redis_v2 / debounce
  • v2：source=pg，配 pg_ro / pg_rw
• Redis 在当前文档化的 V2 里只继续承担 限速计数，不再承担配置中心

Management API 与管理端点

管理面 API 现在已经经过彻底的重构。

原 v1 的这些配置端点已经移除：

• GET /config/dynamic
• GET /config/dynamic/full
• GET /config/dynamic/last
• POST /config/validate
• GET /api/request-log/history

新的管理面 API 主要是资源的 CRUD，可参考 数据库 和 Management API 文档。

Route / Upstream / Provider 及配置归属模型

之前，一个 Route 对象直接绑定了一个 Upstream 对象。

在 V2 中，Route 与 Upstream 同属 Tenant 的资源，且不再一一对应。

另外，Upstream 资源的能力也已经拆分到了 Upstream 和 Provider 两层中，其中 Provider 更多的可以认为是「供应商」，提供 Base URL、Headers、请求协议等信息，而 Upstream 则提供了供应商的 API Key 定义。Upstream 与 Provider 是多对一的关系。

其它值得注意的事情：

• route 与 upstream 属于多对多关系，但现在通过 route.upstreams[] 显式绑定，而不是通过 tag / group 隐式关联
• route / consumer / api key 都可以通过 upstream_selector / model_selector 继续收紧候选，语义尽量对齐 Kubernetes matchLabels / matchExpressions
• 具体 selector 语义见 Label & Selector
• 当一个 route 绑定多个 upstream 时，会根据 route.upstreams[].priority 和 route.upstreams[].lb_weight 进行负载均衡，并根据 max_attempts 配置进行重试。
• route 不再存在 labels 字段，且无替代方案。
• 现在必须要为 upstream 配置可用的 model 列表，不再支持任意 model 透传。
• GET /models 现在不再转发到上游，而是根据数据库中的 models 配置进行聚合返回。
• route 现在不再拥有 capabilities 字段，相关能力定义已转移到 upstream/provider 上
• route 的请求 header 和 body 现不再透传。具体请阅读 Protocols 和 Request Header Overrides 文档。

关联阅读：

• Upstream / Provider / Protocol
• Protocols
• Request Header Overrides
• 模型与 Upstream 解析

认证模型变化

V2 已经从简单的 API Key 认证升级为了更加复杂的以消费者与 API Key 为核心的认证模型。同时，Route 与 Consumer/API Key 的关系也是多对多的关系。

• Route 与 Consumer：多对多
• Route 与 API Key：多对多
• Consumer 与 API Key：一对多

除了标准的 Consumer 语义，首版本为兼容 V1 额外支持了以下几种不同的认证策略（在 Route 中配置）：

1. disable_auth 禁用认证
2. legacy_bearer_auth_tokens 固定 API Key 认证
3. passthrough_auth_token 透传认证 Key

以上几项功能均仅为兼容 V1 的认证策略，不建议继续使用，且可能在未来的版本中移除（完全转向消费者与 API Key 认证）。

关联阅读：

• 网关认证 & 上游认证
• 模型与 Upstream 解析

消费者与计费

当采用消费者作为认证源时，请求会根据消费者进行配额检查及计费。

配额有两个维度：消费者与 API Key。仅限二者均有额度时才会允许请求。

关联阅读：计费

如果未在 Provider Pricing 中配置模型价格，则请求默认会被拒绝。可通过 Tenant 或 Route 配置 allow_missing_model_pricing 来允许请求。

请求日志

请求日志目前会同步写入 PostgreSQL request_logs 表，但该表原则上仅作为内部 debug 使用，建议需要日志的下游始终通过 Kafka 订阅事件。

Management API 中与 RequestLog 有关的 API 仅供 Aidy Dashboard 使用，可能随时存在 Breaking Change，不建议其它下游使用。

目前的日志结构也已经改为通过 logging.v1.RequestLog 进行定义，核心变化为：

• 单值的 upstream.request / upstream.response 语义已被数组类型的 upstream_requests 替代以记录多次尝试过程中的记录
• upstream.response.chat_completions_body 这一「流式重组 Chat Completions 响应体」已移除
• Guard 等日志不再继续放在旧的 upstream.request.guard / upstream.response.guard 位置，而是与其它（新的）插件输出一起统一归到 ext_fields 中（可参考 日志扩展字段）

关联阅读：

• 请求日志输出
• 日志扩展字段

其它变更

• 动态配置中的 global_plugin_config 字段已不再支持，且无替代方案

常见配置映射

V1 概念 / 字段	V2 对应位置	迁移说明
dynamic config (file / redis / redis-v2)	PostgreSQL runtime + seed + Management API	不再支持旧加载器
routes[].upstream	providers + upstreams + upstream_models	route 不再绑定唯一 upstream
route.auth.bearer.tokens	routes.legacy_bearer_auth_tokens 或 consumers + consumer_api_keys	长期建议迁到 consumer 模型
route.passthrough_auth_token	routes.passthrough_auth_token	字段仍在，但语义已转为 legacy auth 分支
upstream.token	upstreams.api_keys[]	当前可有多个 key 候选
route.capabilities	providers.capabilities + upstreams.capabilities	route 不再保存 capability 集
route.plugins / Route.plugin_config	plugin_configs + RoutePluginConfigService	管理面不再通过 Route 直接读写聚合配置