配置参考

ScootGate 使用 TOML 配置，并对所有结构启用未知字段拒绝。拼写错误、未知引用、非法 URL 或越界参数会使进程启动失败，不会静默采用近似配置。

完整可运行结构：

顶层

字段	必填	说明
`instance_id`	是	节点稳定标识，不能为空
`server`	是	客户端 API listener
`health`	否	独立健康 listener
`auth`	是	授权快照控制面
`egress`	是	唯一 Provider 出口代理
`api`	否	API 大小与超时边界
`routing`	否	负载与熔断参数
`routing_source`	否	`static` 或 `snapshot`
`credentials`	视模式	Provider 凭据引用
`backends` / `models`	static 必填	本地路由数据
`usage`	否	非权威磁盘 outbox
`mqtt`	是	用量和快照通知
`shutdown`	否	有界停机
`log`	否	JSON 日志级别

`[server]` 与 `[server.tls]`

字段	默认值	约束
`listen`	无	必填 `IP:port`
`max_concurrent_requests`	`1024`	`1..=16384`
`request_head_timeout_ms`	`5000`	`1..=60000`，同时约束 TLS 握手
`tls.cert`	无	PEM 证书链路径
`tls.key`	无	PEM 私钥路径

生产 API listener 必须配置 TLS。未配置时为明文开发模式。

`[health]`

字段	默认值	约束
`listen`	`127.0.0.1:9091`	必须与 API listener 不同
`max_concurrent_requests`	`64`	`1..=16384`
`request_head_timeout_ms`	`5000`	`1..=60000`

`[auth]`

字段	默认值	说明
`snapshot_url`	无	必填完整 URL；ScootGate 追加 `since`
`token`	无	必填控制面 Bearer token
`cache_path`	`./data/scootgate-auth-snapshot.json`	摘要快照缓存
`poll_interval_secs`	`30`	必须大于 0

配置文件包含 auth.token，生产应由 secret manager 渲染到 0600 文件。

`[egress]`

字段	默认值	说明
`kind`	无	`http_connect` 或 `socks5`
`addr`	无	必填 `host:port`
`username`	无	必填专用服务账号
`password`	无	必填密码
`tls`	`false`	是否验证 TLS 并加密到代理
`connect_timeout_ms`	`10000`	`1..=60000`

没有“direct”类型，也没有代理失败后的直连回落。

`[api]`

字段	默认值	约束
`max_request_body_bytes`	`1048576`	`1..=67108864`
`response_head_timeout_ms`	`30000`	`1..=300000`；选择、连接、TLS、写入和响应头共享
`stream_idle_timeout_ms`	`300000`	`1..=3600000`

`[routing]`

字段	默认值	约束
`max_pre_send_attempts`	`2`	`1..=2`；包含首次尝试

`[routing.load_balancing]`

字段	默认值	约束
`algorithm`	`weighted_p2c`	`weighted_p2c` 或 `weighted_random`
`ewma_alpha`	`0.2`	`(0, 1]`
`initial_first_byte_ms`	`1000`	`1..=600000`
`slow_start_secs`	`30`	`0..=3600`

`[routing.circuit_breaker]`

字段	默认值	约束
`failure_threshold`	`3`	`1..=1000`
`failure_window_secs`	`30`	`1..=3600`
`cooldown_secs`	`30`	`1..=3600`
`half_open_max_requests`	`1`	固定为 `1`
`throttle_cooldown_secs`	`10`	`0..=3600`

`[routing_source]`

默认：

[routing_source]
mode = "static"

Snapshot 模式字段：

字段	默认值	说明
`mode`	`static`	设为 `snapshot`
`snapshot_url`	空	snapshot 模式必填
`token_env`	空	保存控制面 token 的环境变量名
`cache_path`	`./data/scootgate-routing-snapshot.json`	最后有效快照
`poll_interval_secs`	`30`	大于 0
`max_stale_secs`	`300`	不小于 poll interval

Static 模式禁止设置 snapshot_url / token_env；snapshot 模式禁止本地 [backends] / [models]。

`[credentials.<id>]`

每项必须且只能设置一个来源：

[credentials.provider-a]
env = "PROVIDER_A_API_KEY"

或：

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

环境变量缺失、文件不可读或值为空会启动失败。secret 不会序列化到路由快照。

`[backends.<id>]`

字段	默认值	说明
`protocol`	无	`openai_compatible` 或 `anthropic_messages`
`upstream`	无	只有 scheme/host/port 的 origin
`credential_ref`	无	必须引用本地 credential
`max_inflight_per_node`	`64`	`1..=65536`
`enabled`	`true`	是否参与选择

生产 upstream 必须为 HTTPS；HTTP 只允许 loopback。URL 不得包含 path、 query、fragment、userinfo 或内嵌凭据。

`[models.<public-name>]` 与 targets

[models.chat-fast]
protocol = "openai_compatible"
enabled = true

[[models.chat-fast.targets]]
backend = "provider-a"
model = "real-model-a"
weight = 100
supports_stream = true
supports_tools = true
supports_json_schema = true

target 字段	默认值	说明
`backend`	无	必须存在且协议匹配
`model`	无	转发时写入的真实模型名
`weight`	`100`	`1..=1000000`
`supports_stream`	`true`	是否支持流式响应
`supports_tools`	`true`	是否支持 tools
`supports_json_schema`	`true`	是否支持 JSON schema

所有 ID 长度为 1..=128，字符限于 A-Z a-z 0-9 . _ : -。

`[usage]`

字段	默认值	约束
`schema`	`2`	固定 `2`
`delivery`	`mqtt_outbox`	固定值
`authoritative`	`false`	固定 `false`
`outbox_path`	`./data/usage-outbox`	非空持久目录
`max_outbox_bytes`	`1073741824`	大于 0
`flush_interval_ms`	`500`	`1..=60000`
`on_full`	`drop_newest`	固定值

`[mqtt]`

字段	默认值	说明
`broker`	无	必填，无 path
`username`	空	可选；设置 password 时必须非空
`password`	空	可选
`topic_prefix`	`scootgate`	不允许通配符或空白
`client_id`	`scootgate-{instance_id}`	可覆盖
`queue_capacity`	`1024`	大于 0

Broker scheme 支持 mqtt / tcp（默认端口 1883）与 mqtts / ssl / tls / tcps（默认端口 8883）。

`[shutdown]` 与 `[log]`

字段	默认值	说明
`shutdown.grace_period_secs`	`30`	必须大于 0
`log.level`	`info`	tracing filter level

日志为 JSON。若设置 RUST_LOG，它会覆盖由 log.level 构造的默认过滤器。

Keyboard shortcuts

ScootGate