快速开始

ScootGate 不是单机模拟 Provider：启动前必须准备授权快照控制面、强制出站代理、 Provider 凭据和 MQTT broker。本章给出最短可用路径；生产部署应继续阅读生产最佳实践。

1. 获取程序

从 GitHub Release 下载对应平台的压缩包，或使用 Rust 1.88+ 从源码构建：

cargo build --release --locked

二进制只接受一个配置参数：

scootgate --config /path/to/scootgate.toml

也可以使用短参数 -c。

2. 选择路由模式

模式	配置来源	适用场景
`static`（默认）	本地 `[backends]` 与 `[models]`	单节点、路由变化少
`snapshot`	控制面版本化路由快照	多节点、集中热更新

首次部署建议从经过测试的完整示例开始：

两种模式严格互斥，不能把本地路由与远端快照合并。

3. 准备依赖

至少需要：

授权快照端点：按控制面快照协议返回客户端 API key 的 SHA-256 摘要；
出站代理：支持 HTTP CONNECT 或 SOCKS5，并为 ScootGate 分配专用身份；
Provider 凭据：由环境变量或只读文件提供；
MQTT broker：接收用量事件并发送快照更新通知；
持久目录：保存授权／路由缓存和用量 outbox；
生产 TLS 证书：配置到 [server.tls]。

4. 写入配置

开发环境可以从仓库示例开始：

cp scootgate.example.toml scootgate.toml

必须替换所有 REPLACE_WITH_... 占位符，并设置真实控制面、代理、Provider、 MQTT 和文件路径。生产环境不要提交渲染后的配置。

Static 模式至少包含：

instance_id = "gate-a"

[server]
listen = "127.0.0.1:8081"

[auth]
snapshot_url = "https://control.example.com/auth-snapshot"
token = "REPLACE_WITH_CONTROL_TOKEN"

[egress]
kind = "http_connect"
addr = "proxy.internal.example.com:8443"
username = "gate-a"
password = "REPLACE_WITH_PROXY_PASSWORD"
tls = true

[credentials.provider]
file = "/run/secrets/provider-api-key"

[backends.provider]
protocol = "openai_compatible"
upstream = "https://api.example.com"
credential_ref = "provider"

[models.chat]
protocol = "openai_compatible"
targets = [{ backend = "provider", model = "real-model" }]

[mqtt]
broker = "mqtts://mqtt.internal.example.com:8883"

完整字段和默认值见配置参考。

5. 启动并等待就绪

./scootgate --config scootgate.toml

启动日志报告 listener 已绑定后，继续检查独立 health listener：

curl --fail http://127.0.0.1:9091/readyz

只有返回 200 才能接入流量。无授权快照或 snapshot 路由尚未加载时会返回 503，这是 fail-closed 的预期行为。

6. 验证客户端 API

列出公共 OpenAI-compatible 模型：

curl --fail \
  -H 'Authorization: Bearer YOUR_SCOOTGATE_CLIENT_KEY' \
  http://127.0.0.1:8081/v1/models

发送聊天请求：

curl --fail \
  -H 'Authorization: Bearer YOUR_SCOOTGATE_CLIENT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"chat","messages":[{"role":"user","content":"ping"}]}' \
  http://127.0.0.1:8081/v1/chat/completions

生产 TLS 场景应使用 https:// 并验证配置证书的信任链，不要使用 -k。

7. 验证安全边界

上线前至少执行：

使用未知或吊销 key，请求必须返回 401；
停止出站代理，请求必须失败且 Provider 不得收到直连；
使用未知模型，请求必须在出网前失败；
停止 MQTT，API 继续服务且 outbox 积压增长；
向 snapshot 控制面发布非法版本，当前路由不得被覆盖。

完整验收步骤见生产最佳实践。

Keyboard shortcuts

ScootGate