跳到主要内容

Management API

Aidy 的 management 端口同时提供：

  • 运维 HTTP 路由：/health、/ready、/metrics、/debug/pprof/*、/dashboard/*
  • 基于 ConnectRPC 的管理面 API

默认监听 :12581。

HTTP 路由​

GET /health​

curl http://localhost:12581/health

成功响应：

{"status":"ok"}

GET /ready​

检查 PG runtime store 是否可访问：

curl http://localhost:12581/ready

成功时：

{"status":"ready"}

GET /metrics​

Prometheus 指标端点。

GET /debug/pprof/*​

标准 Go pprof。

ALL /proxy?url=...​

Dashboard Chat 使用这个路由把浏览器请求代理到目标上游，以规避 CORS。

ConnectRPC 资源​

当前管理面覆盖这些资源：

  • tenants
  • providers
  • provider_pricings
  • routes
  • route_plugin_configs
  • upstreams
  • upstream_models
  • consumers
  • consumer_api_keys
  • request_logs

关键模型变化​

Provider​

  • protocol 支持：
    • chat-completions
    • open-responses
    • claude-messages
  • metadata 已删除
  • status 已删除
  • 新增 check_model
  • 新增 disabled_at

Provider Pricing​

  • provider_pricings 取代了旧的 pricing_plans / pricing_plan_items
  • 定价直接挂在 provider 上，按 (provider_id, model) 唯一
  • global provider 的 pricing 使用空 tenant_id
  • tenant provider 的 pricing 会和 provider 的 source_ref_id 对齐
  • pricing 字段是原样存储的 jsonb
  • pricing 现在固定使用 aidy.v2.ext.billing.Pricing 的 canonical protobuf JSON：basePricing + 可选 adjustments
  • 所有 rate 数值都表示每 1,000,000 tokens 的 credit
  • 不再接受旧的 input/output/unit/unit_size/currency 结构

Upstream​

当前字段直接使用：

  • base_url
  • headers
  • compat
  • request_header_overrides
  • api_keys
  • check_model
  • disabled_at
  • api_keys 直接内嵌在 upstream 中

补充约束：

  • headers 当前只接受扁平 string -> string 映射
  • request_header_overrides 当前不支持覆盖、删除或透传 Host

Upstream API Key​

Management API 仍保留 Upstream API Key 相关 RPC，便于 dashboard 做局部编辑，但底层存储已经不是独立表。

当前字段重点是：

  • id
  • tenant_id
  • upstream_id
  • name
  • key
  • priority
  • lb_weight
  • disabled_at
  • expires_at

Route​

当前 Route 资源新增：

  • max_attempts：单次请求进入真实转发/fallback 计划的最大候选数，默认 2

Upstream Model​

  • 字段使用 model
  • DB 主键是 (upstream_id, model)
  • API 返回的 id 只是前端展示用的合成值
  • is_alias 表示该行是否为 alias
  • alias 直接作为 upstream_models 中的独立行

认证相关 route 字段​

当前 route 相关的认证字段是：

  • disable_auth
  • legacy_bearer_auth_tokens
  • passthrough_auth_token

优先级：

  1. disable_auth
  2. passthrough_auth_token
  3. legacy_bearer_auth_tokens
  4. 默认 consumer_api_keys

Route Plugin Configs​

管理面不再通过 Route.plugin_config 读写插件配置。

当前改为独立的 RoutePluginConfigService，分成两类接口：

  • 聚合接口：
    • ListRoutePluginConfigs
    • GetRoutePluginConfig
    • CreateRoutePluginConfig
    • UpdateRoutePluginConfig
    • DeleteRoutePluginConfig
  • 明细接口：
    • GetAllRoutePluginConfigs
    • ReplaceAllRoutePluginConfigs

语义区别：

  • RoutePluginConfig 是 route 级资源，直接持有 entries
  • 明细接口直接面向 plugin_configs 表的 route 级全量替换

写入约束：

  • Create / Update 不接受空 entries
  • 清空配置应使用 DeleteRoutePluginConfig
  • 明细 ReplaceAllRoutePluginConfigs 允许空 entries，语义等同于清空该 route 的全部 plugin_configs
  • 明细请求中的 tenant_id 不接受客户端指定，统一由 route 推导
  • 明细请求中的 (plugin_key, plugin_sub_key) 必须唯一

注意：

  • 运行时 route.plugin_config 仍然存在
  • 它不是管理面 Route 资源的一部分，而是 runtime 读取 plugin_configs 表后聚合出来的视图

协议转换​

当前 route 还包含协议转换字段：

  • protocol_transformation_type

允许值：

  • enabled
  • if-different-protocol
  • disabled

默认值：

  • if-different-protocol

当前状态：

  • 该字段仍会通过管理面校验并持久化到 runtime 配置
  • 当前 chat 主线路径已经固定采用“入站协议解析为 IR -> 按候选 upstream 协议组装请求 -> 成功响应再按入站协议回组装”的模型
  • 也就是说，当前运行时不会再按 enabled / if-different-protocol / disabled 这三种值切换不同转发行为
  • 非 chat 路径这轮仍不做跨协议转换

当前支持的协议判断：

  • 请求协议按请求路径判断：
    • /chat/completions
    • /responses
    • /messages
  • 上游协议按 upstream -> provider -> protocol 判断

分组​

用于选 upstream 的分组字段有：

  • routes.groups
  • consumers.groups
  • consumer_api_keys.groups
  • upstreams.group

语义：

  • route / consumer / api key 的空数组表示“不限制”
  • upstream 仍然只有一个 group
  • 如果最终没有任何显式分组约束，则回落到 upstream 的 default 组

Request Logs​

Management API 现在提供只读的 request log 查询：

  • RequestLogService/ListRequestLogs
  • RequestLogService/GetRequestLog
  • RequestLogService/GetFullRequestLog

用途主要是给 dashboard 的 Request Logs 页面查看近期请求日志。

当前行为：

  • 只读，不提供 create / update / delete
  • ListRequestLogs 需要 tenant_id
  • ListRequestLogs.limit 未传时默认 100
  • 单次最大 limit = 500
  • GetRequestLog 返回 PG 摘要
  • GetFullRequestLog 返回 request_logs.raw 反序列化后的完整日志视图

返回内容对应 request_logs 表中的 PG 摘要字段：

  • request
  • response
  • upstream_requests
  • timing
  • duration
  • ext_fields

其中 ext_fields 是松散的扩展字段对象；当前已知字段定义见 日志扩展字段。

注意：

  • route_labels 不在这里返回，因为它不落 PG
  • body 也不在这里返回，因为 request_logs 在入库时会单独裁剪成摘要
  • upstream_requests 是数组，按真实尝试顺序保存每次上游 request/response 摘要与 attempt metadata

GetFullRequestLog：

  • 复用同一个 RequestLog message，不新增 full 专用 schema
  • 优先读取 request_logs.raw
  • 只要 raw 存在，就返回完整 body
  • raw 为空时会自动回退到 PG 摘要映射