Legate Sidecar¶

Legate Sidecar 是可信节点上的本地模型网关。它周期性拉取一个 Workspace 的版本化快照，使用与 Central 相同的 Proxy Core 执行 API Key 认证、协议解析、路由、Driver 和调用遥测。

适用场景¶

应用与 Central 跨区域或跨集群，希望本地完成数据面；
希望在本地鉴权后再把部分模型组转发 Central；
需要按 Workspace 分发不可变配置与 Driver 制品；
接受在可信节点投影 full 模型组所需上游凭据。

Sidecar 不是不受控缓存。没有有效快照时它不会猜测默认 Workspace 或旧 schema。

启动与同步¶

Sidecar 必须配置：

--control-plane：快照和制品的 Central Base URL；
--central-gateway：reference 请求转发地址；
--telemetry-base-url：调用事件上传地址；
--workspace：精确 Workspace slug；
--token：该 Workspace 的 sc-leg-...；
--instance-id：跨进程重启保持稳定的实例 ID。

每次同步下载 /api/v1/sidecar/snapshot，验证 Workspace、schema、revision、内容上限和 artifact digest；所需 WASM 下载、编译、Bind 全部成功后才原子替换当前 generation。请求持有 generation lease，因此不会看到半套新旧配置。

`full` 与 `reference`¶

full 模型组下发本地执行所需 Endpoint、模型、Driver、credential、mapping 与 API Key hash。请求完全在 Sidecar 执行，上游网络流量不会经过 Central。

reference 模型组只下发稳定身份与授权。Sidecar 本地认证 API Key 并解析模型组 ID，然后用受保护的 forwarding v1 headers 转发 Central。Central 验证 Sidecar Token、Workspace 和 envelope 关系，再按自己的最新完整配置执行。

同一个 Sidecar 可以同时服务两类模型组。

快照失败¶

首次同步失败：没有可用 generation，模型请求返回配置不可用；
已应用过快照后拉取失败：继续使用最后一个完整 generation，并上报错误；
新快照或 artifact 校验失败：拒绝部分更新，保留旧 generation；
Workspace 或 Token 不匹配：显式失败，不回退到 default。

/api/healthz 只表示进程在服务，不证明最近快照成功。应查看 Console “Sidecar → 实例”的 last pull、snapshot schema 与 revision。

实例与遥测状态¶

同一 Token 可以被多个稳定 instance-id 使用。Console 汇总 Token 下的实例总数、在线/离线与版本分布，并在实例详情显示：

hostname、Sidecar version、sync interval；
last seen / last pull / pull error；
applied snapshot schema 与 revision；
telemetry incarnation、session generation 和 started at；
last reported、covered through、queue depth、oldest queued；
dropped event count 与 counter saturated。

在线状态根据心跳和该实例报告的同步间隔计算，不等同于请求一定成功。

状态共享与安全¶

配置 Redis 时 Sidecar 与其他网关进程共享 Endpoint / Mapping breaker 状态。当前 Endpoint 没有容量字段；文本流、请求重放和图片 blob 使用 Sidecar 自己的有界资源预算。

Sidecar Token 不能代替业务 API Key。不要把 Sidecar 监听端口、Token、快照或本地制品目录暴露给不受信任网络。full 快照包含上游 credential，应把 Sidecar 主机视为具备生产 secret 权限的数据面节点。