Kaeso 网关：位于应用和服务商之间的一个 Rust 二进制文件。它检查每个密钥和限额，转换每种格式，并记录每个请求。

第 1 步，共 8 步

密钥

API 密钥决定项目，以及它代表的成员或服务账号。密钥只以哈希形式存储，并在 30 秒内从内存中直接应答。

应用可能收到的响应

401未授权密钥缺失、未知、已停用、已归档或已过期。
403禁止访问密钥只有平台访问权限，或其成员缺少 api.request 权限。
429触发速率限制同一地址发来了过多使用未知密钥的请求。

网关从 x-api-key 读取密钥，否则从 Authorization: Bearer 读取：

x-api-key: sk-kso-…Authorization: Bearer sk-kso-…

第 2 步，共 8 步

解码

KPP 将请求体从应用的格式解码为 Kaeso 的规范格式。Kaeso 永远不会发送给服务商的内容会在这里被拒绝。

应用可能收到的响应

413内容过大请求体超过默认上限 8 MiB。
400错误请求Kaeso 无法读取该请求，或请求要求了 Kaeso 从不发送的内容，例如多个候选结果。
503不可用进行中的转换占满了内存，该请求已等待 10 秒。

两项上限都是设置项，以下是它们的默认值：

[body_limits]model_api = "8MiB"in_flight = "512MiB"

第 3 步，共 8 步

模型

模型名称在项目的目录中解析，并在发送任何内容之前，根据模型的能力检查请求。

应用可能收到的响应

404未找到模型不在项目的目录中，或该密钥无权使用它。两种情况的响应相同，因此密钥无法得知还有哪些其他模型。
400错误请求多家服务商提供了该 ID，或模型缺少请求所需的能力，例如工具或图片。

每种格式都返回同样的 404，因此每个 SDK 都会抛出它惯常的错误：

{  "error": {    "message": "The model `gpt-9` does not exist or this key may not use it.",    "type": "invalid_request_error",    "param": "model",    "code": null  }}

第 4 步，共 8 步

限额

密钥、成员和项目的所有速率和预算在 Valkey 中一次性检查。超出限额时，应用会收到带有 Retry-After 的 429。

应用可能收到的响应

429触发速率限制达到了速率限制或硬性预算。Retry-After 说明何时可以重试。
200成功超出了软性预算。请求继续进行，预算只发出提醒。
503不可用无法连接 Valkey，且该请求受硬性预算约束。

Retry-After 以整秒给出等待时间（向上取整），retry-after-ms 给出精确的等待时间：

HTTP/1.1 429 Too Many Requestsretry-after: 13retry-after-ms: 12400kaeso-request-id: req_…

第 5 步，共 8 步

服务商密钥

选择并解密项目针对该服务商的密钥，并最多在内存中保留 30 秒。

应用可能收到的响应

400错误请求项目没有该模型所属服务商的服务商密钥。
500服务器错误Kaeso 无法解密服务商密钥。

主密钥由网关自己生成，rewrap 会用当前的主密钥重新加密每个已存储的机密：

docker compose exec gateway kaeso master-key generatedocker compose exec gateway kaeso master-key rewrap

第 6 步，共 8 步

编码并发送

KPP 按照服务商的格式对请求进行编码。该格式无法表达的内容会在到达服务商之前被拒绝。

应用可能收到的响应

400错误请求服务商的格式无法表达请求所要求的内容。
502网关错误无法连接服务商，或服务商拒绝了项目的服务商密钥。
504网关超时服务商没有及时响应。

服务商拒绝项目的密钥时，您的应用收到的是请管理员检查的 502，而不是服务商的 401：

{  "type": "error",  "error": {    "type": "api_error",    "message": "The provider refused this project's provider key. Ask an organization admin to check it under Providers."  },  "request_id": "req_…"}

第 7 步，共 8 步

响应

响应会被解码，并以应用的格式重新编码（流式响应逐个事件处理），同时带上 kaeso-model 和 kaeso-provider 响应头。

应用可能收到的响应

200成功以应用自身格式返回的响应，并注明提供服务的模型和服务商。
529过载服务商过载：Anthropic 格式返回 529，OpenAI 格式返回 503。

每个响应都会标明请求；一旦确定模型，还会标明由谁提供服务：

kaeso-request-id: req_…kaeso-provider: anthropickaeso-model: claude-haiku-5-5

第 8 步，共 8 步

日志

记录用量、按请求时有效价格计算的费用以及请求日志；在组织允许时还会记录内容。

应用可能收到的响应

200成功记录日志绝不会拖慢请求：响应先发出，日志条目在内存中等待写入。
499客户端已关闭应用关闭了连接。Kaeso 会立即停止向服务商发出的请求，并按实际用量计费。

日志行在内存中等待，并分批写入 ClickHouse：

[logs]buffer_size = "256MiB"flush_interval = "1s"flush_rows = 5000

网关如何处理每个请求。

密钥留在网关中，状态存放在您已在运行的数据库里，运维方式与其他服务无异。

密钥留在网关中

服务商密钥绝不会到达您的应用，控制台中的每个操作都对照一项权限进行检查。

了解服务商密钥

您的应用持有的sk-kso-AbC1…wxyz模型调用

一个 Kaeso 密钥，只以哈希形式存储，带有有效期以及模型调用或平台访问权限。

网关持有的OpenAIAnthropicAES-256-GCM

服务商密钥，使用 AES-256-GCM 在您持有的主密钥环下进行信封加密。使用 kaeso master-key rewrap 轮换主密钥。

登录: 密码加身份验证器应用和恢复码、登录链接，以及通过各组织的 OIDC 提供商进行单点登录
权限: 细粒度权限，内置角色，每个组织最多 50 个自定义角色
审计日志: 覆盖实例、每个组织和每个项目

登录: 密码加身份验证器应用和恢复码、登录链接，以及通过各组织的 OIDC 提供商进行单点登录
权限: 细粒度权限，内置角色，每个组织最多 50 个自定义角色
审计日志: 覆盖实例、每个组织和每个项目

状态存放在您熟悉的数据库中

网关实例自身不保存任何状态，因此您可以在负载均衡器后添加更多实例。它们共享同一个 PostgreSQL、ClickHouse 和 Valkey。

阅读架构说明

每个网关实例无状态

PostgreSQL密钥、目录、限额、用量和审计日志

ClickHouse请求日志和用量汇总

Valkey速率和预算计数器、共享缓存

PostgreSQL: 密钥、目录、限额、用量和审计日志
ClickHouse: 请求日志和用量汇总
Valkey: 速率和预算计数器、共享缓存

PostgreSQL: 密钥、目录、限额、用量和审计日志
ClickHouse: 请求日志和用量汇总
Valkey: 速率和预算计数器、共享缓存

像运行任何服务一样运行它

通过 KAESO_* 变量或 TOML 文件进行配置，从文件中读取每个密钥类配置，并用您已有的工具进行监控。

阅读配置说明

kaeso.toml

1listen = "0.0.0.0:8080"2public_url = "https://kaeso.example.com"3 4[providers.anthropic]5base_url = "https://api.anthropic.com"6 7[upstream]8request_timeout = "600s"9 10[logs]11buffer_size = "256MiB"

1KAESO_LISTEN=0.0.0.0:80802KAESO_PUBLIC_URL=https://kaeso.example.com3KAESO_PROVIDERS_ANTHROPIC_BASE_URL=https://api.anthropic.com4KAESO_UPSTREAM_REQUEST_TIMEOUT=600s5KAESO_LOGS_BUFFER_SIZE=256MiB6KAESO_MASTER_KEYS_FILE=/run/secrets/master_keys

指标: Prometheus 位于端口 9100，Caddy 不会转发该端口；请保持其私有
健康检查: 进程运行时 /healthz 正常应答，/readyz 报告 PostgreSQL、Valkey 和 ClickHouse 的状态
日志: 结构化 JSON；默认保留请求日志 90 天，内容 30 天
流式响应: 每 15 秒发送一次 keepalive；应用断开时会取消对服务商的调用

指标: Prometheus 位于端口 9100，Caddy 不会转发该端口；请保持其私有
健康检查: 进程运行时 /healthz 正常应答，/readyz 报告 PostgreSQL、Valkey 和 ClickHouse 的状态
日志: 结构化 JSON；默认保留请求日志 90 天，内容 30 天
流式响应: 每 15 秒发送一次 keepalive；应用断开时会取消对服务商的调用

一个仓库，一个版本。

网关、控制台、KPP 和 Kaeso UI 一同发布，采用 MIT 许可证。

在 GitHub 上浏览源代码（在新标签页中打开）

把它放在您的应用前面。

一个 Compose 文件，包含 Caddy、网关、控制台、PostgreSQL、ClickHouse 和 Valkey，运行在您自己的服务器上。

自托管 Kaeso 阅读文档