配置说明

simple-ai-gateway 的运行时配置全部来自一个 YAML 文件,启动时通过 --config 或环境变量 GATEWAY_CONFIG 指定。本文档列出全部字段、默认值与可选取值,示例见 config/example.*.yaml。

文件根结构:

server: { ... }
storage: { ... }
admin: { ... }
providers: { ... }
routes: [ ... ]
limits: [ ... ]
budgets: [ ... ]
observability: { ... }

修改该文件会被自动监听并热重载,无需重启进程(由 gateway-api/reload 负责)。

环境变量

下列环境变量在启动时被读取,不在 YAML 中:

server

storage

通过 profile 字段区分三种形态(serde tagged enum,profile 之外的字段按形态填):

profile: lite

单进程 SQLite + 进程内缓存。适合小规模 / 开发。

storage:
  profile: lite
  sqlite:
    path: ./data/gateway.db
    max_size_mb: 10240
    log_retention_days: 30
  cache:
    l1_memory_mb: 256
    l2_max_size_mb: 1024

注意:GATEWAY_WORKERS>1 与 lite 不兼容,网关会拒绝启动。

profile: standard

Postgres + Redis,可横向扩展。

storage:
  profile: standard
  postgres:
    url: postgres://gateway:gatewaypass@postgres:5432/gateway
    max_connections: 32
  redis:
    url: redis://redis:6379/0
  cache:
    l1_memory_mb: 256
    l2_max_size_mb: 1024

profile: memory

全内存,无持久化。重启即失,只用于测试。

storage:
  profile: memory
  cache:
    l1_memory_mb: 64
    l2_max_size_mb: 256

admin

gateway_keys

可选数组,声明式预置一批 gateway API key。每次进程启动 + 配置热重载都会与库里 origin='config' 的行做一次同步:新增的写入、删除的丢弃、name/scopes 等元数据有变更则更新。

gateway_keys:
  - id: prod-svc                          # 稳定 id,日志/限流/预算靠它关联
    name: prod-svc
    project_id: default                   # 可省略,默认取 server.default_project_id
    secret: sk-gw-live-xxxxxxxxxxxxxxxx   # 直接写明文,或 env://PROD_SVC_KEY 从环境变量读
    scopes: []                            # 可省
  - id: ci-readonly
    name: ci
    secret: env://CI_GATEWAY_KEY

约束与行为:

• 启动期校验:id 唯一、name/secret 非空,明文 secret 必须带 sk-gw-live- 或 sk-gw-test- 前缀。
• Admin API 拒绝 revoke origin='config' 的 key(返回 400,提示从 YAML 移除)。UI 列表里这些 key 带 config 徽标且没有 Revoke 按钮。
• 配置文件里移除某条 key 后下一次热重载会从库里删除它(此后该明文 key 无法再认证)。要"暂时禁用",直接从 YAML 删掉即可。
• 明文 secret 会被 redacted 处理,不会出现在 Debug 日志里 —— 但 YAML 在磁盘上是明文,操作时注意文件权限;若想做最小权限注入,把 secret 写成 env://...。

providers

map<string, ProviderConfig>,key 是上游身份名(被 routes[].primary.provider 和 fallbacks[].provider 引用)。URL /v1/{namespace}/* 中的 namespace 是另一个独立概念,默认与该 key 同名,可通过 match.namespace 解耦。

providers:
  openai:                          # key = openai → 隐式 kind = openai
    base_url: https://api.openai.com
    credential: env://OPENAI_API_KEY
    headers:
      X-Custom: value
  anthropic:
    base_url: https://api.anthropic.com
    credential: env://ANTHROPIC_API_KEY
  doubao:                          # 任意名字
    kind: openai                   # ← 显式声明走 OpenAI 协议
    base_url: https://ark.cn-beijing.volces.com/api/v3
    credential: env://DOUBAO_API_KEY

支持的 kind

未设置 kind 时,系统直接拿 providers map 的 key 名去匹配上表 —— 所以历史配法 providers.openai: { ... }、providers.anthropic: { ... } 仍然有效。但只要 key 名不是 openai / anthropic 之一,就必须写 kind,否则启动期 validate 拒绝加载。

接入一个新的 OpenAI 兼容供应商

只需要一条配置,不需要改任何代码:

providers:
  deepseek:
    kind: openai
    base_url: https://api.deepseek.com
    credential: env://DEEPSEEK_API_KEY

  groq:
    kind: openai
    base_url: https://api.groq.com/openai
    credential: env://GROQ_API_KEY

  local-vllm:
    kind: openai
    base_url: http://10.0.0.5:8000
    credential: env://VLLM_TOKEN

如果上游需要额外固定 header(比如 Azure OpenAI 的 api-version 查询参数走 header,或自定义路由 key),写在 headers: 里即可。如果上游使用完全不同的 auth 协议(非 OpenAI、非 Anthropic),才需要在 crates/gateway-core/src/providers/ 加一个新 adapter,详见 开发指南。

routes

每条路由把"哪些请求"绑定到"上游身份和代理策略(缓存、重试、回退)"。按数组顺序匹配,第一条同时满足以下条件的命中:

1. URL 中的 /v1/{namespace}/... 段等于 match.namespace(必填,启动时校验);
2. 若 match.model_prefix 有值,请求体里的 model 字段以该前缀开头。

注意:namespace(URL 段)与 primary.provider(providers 表里的 key)是两个独立概念。命名相同是约定,不是要求。让它们不同,就能实现"客户端继续叫 /v1/openai/...,但后端偷偷转发给 azure"这类场景。

providers:
  openai:                          # 上游身份:实际网络目的地 + 凭证
    base_url: https://api.openai.com
    credential: env://OPENAI_API_KEY
  azure-prod:
    base_url: https://prod.openai.azure.com
    credential: env://AZURE_KEY

routes:
  # 透明迁移:客户端用的还是 /v1/openai/...,网关后端走 azure
  - match:
      namespace: openai
      model_prefix: gpt-
    primary:
      provider: azure-prod         # ← 与 namespace 不同
    cache: { enabled: true, ttl: 3600 }

  # 兜底:其他 openai 请求(o1- 等)继续走真正的 OpenAI,默认无缓存
  - match:
      namespace: openai
    primary:
      provider: openai

没有匹配的路由(或 routes: [])时:网关直接返回 404(错误码 not_found)。namespace 必须显式登记在 routes[] 里才能被代理 —— 最简写法:

- match: { namespace: openai }
  primary: { provider: openai }

这样 /v1/openai/... 就会按默认重试 3 次/500ms 退避、无缓存、无 fallback 的方式转发到 providers.openai。启动时如果发现某条 route 缺 match.namespace,网关会直接拒绝加载配置。

match

如果同一 namespace 配多套策略,把更具体的放在数组前面,兜底的放后面。

primary / fallbacks (RouteTarget)

trigger 取值(参考 crates/gateway-core/src/proxy/retry.rs):

cache

缓存 key 来自请求体 + 路径的 blake3 摘要。流式响应也会被缓存(replay 时按原 chunk 边界发回),前提是请求体确定性(temperature == 0 且 top_p >= 0.999)且大小 ≤ 20 MB。要绕开确定性检查,可在路由上设置 allow_nondeterministic: true,或在请求头加 X-Gateway-Cache-Force: 1。

retry

limits

数组,每条规则独立检测;命中任意一条即拒绝请求(HTTP 429)。

limits:
  - target: { type: key, id: "*" }
    rpm: 1000
    tpm: 200000
    concurrency: 50
  - target: { type: project, id: default }
    rpm: 5000
  - target: { type: global }
    concurrency: 200

target

度量字段(都可省略)

budgets

数组,每条独立累计。命中 block 阈值会拒绝后续请求(HTTP 402),notify 阈值会触发 webhook。

budgets:
  - name: monthly-team-budget
    target:
      project_id: default
      # 或 gateway_key_id: xxx
    period: monthly
    amount_usd: 500.0
    thresholds:
      - { at: 0.8, action: notify, webhook: https://hooks.example.com/budget }
      - { at: 1.0, action: block }

成本由启动时通过 --pricing-catalog(或环境变量 GATEWAY_PRICING_CATALOG)指定的 pricing-catalog.json 计算,未知模型按 0 计。默认读取工作目录下的 pricing-catalog.json。

observability

observability:
  metrics: true
  tracing:
    enabled: true
    format: json
    otlp_endpoint: null

校验规则

启动时 AppConfig::validate() 会做以下检查,失败立即退出:

• 所有 routes[].primary.provider 必须在 providers 中存在。
• 所有 routes[].fallbacks[].provider 必须在 providers 中存在。

其他不一致(如未知 limit.target.type)在运行时被忽略而非拒绝,便于在多版本间平滑过渡。