ScootGate

ScootGate 是一个独立部署、默认拒绝的 AI Provider API 网关，由本仓库独立开发、 测试和发布。

它提供 OpenAI POST /v1/chat/completions、GET /v1/models 与 Anthropic POST /v1/messages 兼容入口，使用控制面下发的 SHA-256 API-key 授权快照鉴权，按公共模型目录把请求路由到多个加权后端（改写为后端真实 模型名并注入上游凭据），并强制所有 Provider 流量经配置的 HTTP CONNECT 或 SOCKS5 代理出站。代理不可用时请求失败，不会回落直连。

边界

• ScootGate 不管理用户、租户、套餐或 API key，只消费版本化授权快照。
• 客户端凭据不会透传给 Provider；上游凭据由 ScootGate 注入。
• MQTT 只承载幂等用量事件和授权刷新通知，不是授权事实来源。
• 配置 [server.tls] 后 API listener 原生终止 TLS（最低 TLS 1.2）； 未配置时为开发用明文模式，生产环境必须二选一提供 TLS 终止。
• 请求"可能已到达 Provider"后绝不自动重试，避免重复计费副作用； 仅当确定字节未发出时才在后端间至多改选一次。

本地运行

需要 Rust 1.88 或更新版本：

cp scootgate.example.toml scootgate.toml
# 修改控制面、上游代理、Provider 和 MQTT 配置
cargo run --release -- --config scootgate.toml

健康接口位于 [health].listen：

• /healthz：进程存活；
• /readyz：已加载有效授权快照且服务可接流量；snapshot 路由模式下还要求 持有路由表且控制面未失联超过 max_stale_secs（过期只转 unready， 旧表继续服务）。

健康响应中的 usage_outbox 提供积压事件数、字节数、最老事件年龄和累计丢弃数。

配置模型

完整示例见 scootgate.example.toml。必填边界包括：

• [server]：API 监听地址；可选 [server.tls]（cert/key）开启原生入口 TLS；
• [auth]：控制面快照 URL、专用 token 和摘要缓存；
• [egress]：HTTP CONNECT/SOCKS5 上游代理地址及专用服务身份；
• [credentials.<id>]：上游凭据引用，env 或 file 二选一， 启动时缺失即拒绝启动，凭据明文不进配置文件；
• [backends.<id>]：后端 origin（协议、upstream、凭据引用、在途上限）；
• [models.<公共模型名>]：公共模型目录，每个模型带加权 targets （backend/model/weight 与能力标记）；
• [routing]（可选）：负载算法（weighted_p2c/weighted_random）与熔断参数；
• [routing_source]（可选）：路由数据来源。默认 static（读本地 [backends]/[models]）；snapshot 模式改由控制面版本化下发路由快照 （校验后原子替换、坏快照整体拒绝、版本严格单调、缓存供重启热加载）， 此时本地 [backends]/[models] 必须为空，凭据仍只在本地 [credentials] 解析，控制面 token 经 token_env 环境变量提供；
• [usage]（可选）：固定 schema 2 的非权威磁盘 outbox。事件落盘后才经 MQTT QoS 1 投递，PUBACK 后删除，重启按稳定 event_id 重放；磁盘达到 max_outbox_bytes 时按 drop_newest 丢新并计数，数据面继续服务。 token 字段只取 Provider 原生 usage，缺失时为 null，不按字节估算；
• [api]（可选）：请求体上限与响应超时；
• [mqtt]：用量上报（schema 2）、授权通知与路由快照通知通道。

额外私有 CA 可通过 SCOOTGATE_EXTRA_CA_CERTS 指定；其值是平台路径分隔符 连接的 PEM 文件列表。不存在跳过证书校验的配置。

容器

docker build -t scootgate:local .
docker run --rm \
  -v "$PWD/scootgate.toml:/etc/scootgate/scootgate.toml:ro" \
  scootgate:local

容器以无特权 scootgate 用户运行，运行时缓存目录为 /app/data。

文档

• 在线文档（mdBook）：软件功能手册、 客户端／控制面／MQTT／健康协议规范，以及 static／snapshot 完整部署场景； 由 main 分支自动发布。

工程资料

• 项目画像与方向（roadmap）：目标状态、非目标铁律、 方向意图与验收矩阵（业务能力覆盖矩阵的唯一事实来源）。
• 分布式模型路由与后端负载均衡开发草案： 目标架构、配置模型、负载算法、故障边界、实施阶段与验收标准。阶段 0–5 （新配置模型、入口 TLS、模型路由、负载均衡、熔断与安全改选、snapshot 路由快照、可靠用量 outbox）已落地；dns-controller 与 /metrics 仍为规划能力。

质量与验收

覆盖底线：每个一级功能必须有 Happy Path 进程级测试；高风险功能必须覆盖失败 路径；涉及权限的功能必须验证有权与无权两种角色；会修改系统状态的操作必须验证 失败后的恢复；新增一级功能必须同步登记 验收矩阵。

质量门禁

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo audit
cargo test --locked
cargo llvm-cov --locked --all-targets --summary-only --fail-under-lines 80
cargo build --release --locked

进程级测试覆盖独立监听、授权快照、强制上游代理出站、OpenAI/Anthropic/Ollama 兼容转发、SSE、公共模型目录、多后端加权负载、熔断与安全改选、上游凭据 停用与限流冷却、原生入口 TLS、用量事件、MQTT 通知和有界停机。

来源与许可

ScootGate 在本仓库独立演进，并按 MIT 许可证发布，见 LICENSE。