Skip to content

Spacegate 演进评估：从服务网关到 AI 原生平台型网关 #42

Open
Feature
Open
Spacegate 演进评估：从服务网关到 AI 原生平台型网关#42
Feature
Assignees
LiJieLongRWDai
Labels
enhancementNew feature or request
@gudaoxuri

Description

@gudaoxuri
gudaoxuri
opened on Apr 20, 2026

目标：在保持 spacegate「library-first / 轻量 / 高性能 / 云原生」基因的前提下，完成三件事——

  1. 用 Proxy-Wasm 统一并精简扩展机制；
  2. 原生支持 MCP / A2A / OpenAI 兼容 / Agents 等 AI 协议，并具备高吞吐与背压能力；
  3. 将网关从「服务流量路由」升级为「AI 资产路由」，支持万级动态资产注册与按路由挂载扩展。

本文档不含代码，只产出方案与决策点，末尾汇总问题清单一次性请您回复。

0. 当前代码盘点（作为演进基线）

基于对仓库的静态分析：

  • kernel (crates/kernel)：纯 hyper/tower 构建的 HTTP/WebSocket 网关内核，核心类型 SgRequest/SgResponse/SgBody、Gateway、HttpRoute、Backend、helper_layers。已经相当"薄"，但内置了 backend_service（http_client/ws_client/static_file/echo）、injector/extractor、east-west 等业务色彩较重的模块。
  • plugin (crates/plugin)：自定义 Plugin trait（见 crates/plugin/src/lib.rs），含 code / call / create 三件套；支持静态注册、dylib 动态库注册（libloading，永不卸载）；内置 plugins 位于 crates/plugin/src/plugins（limit / header_modifier / redirect / rewrite / maintenance / inject / east_west_traffic_white_list / set_scheme / set_version / static_resource / decompression / retry / status 等，其中多个已被 // #[cfg] 注释停用）。
  • model (crates/model)：配置模型（SgGateway / SgHttpRoute / SgHttpRouteRule / SgBackendRef），对齐 Kubernetes Gateway API；plugins: Vec<P> 挂载在 gateway/route/rule/backend 四层。
  • config (crates/config)：多后端配置（fs / k8s / redis / memory）＋事件监听 (CreateListener)，支持热更新。
  • shell (crates/shell)：把 kernel + plugin + config 粘起来，对外暴露 startup_file / startup_k8s / startup_redis / startup 入口。
  • binary：spacegate（网关可执行）+ admin-server（管理面，基于 axum）。
  • extension：ext-axum（在网关里挂 axum router）+ ext-redis（共享 Redis 客户端）。

评估结论：架构分层清晰，kernel 已经 lib-first；但 plugin 机制是私有 ABI（Rust trait + dylib），在跨语言、跨版本、沙箱安全、热装卸四项上都弱于业界标准。内置 plugin 过多且功能与 kernel 耦合，是本次精简的主要对象。

评估一：基于 Proxy-Wasm 的扩展机制重构

1.1 Proxy-Wasm 能力要点（摘自 ABI v0.2.1 与 Rust SDK）

Proxy-Wasm 是 Envoy/Istio/Kuma/APISIX/MOSN/higress 等都已实现的事实标准，核心特征：

维度 ABI v0.2.1 提供能力
生命周期 proxy_on_vm_start → proxy_on_configure → proxy_on_context_create（Root / Stream）→ proxy_on_done/log/delete
HTTP 过滤链 proxy_on_request_headers/body/trailers、proxy_on_response_headers/body/trailers，返回 CONTINUE/PAUSE 可暂停流
TCP/WS proxy_on_new_connection / downstream_data / upstream_data / *_connection_close
主动请求 proxy_http_call、proxy_grpc_call/stream/send/cancel/close（插件可异步回调 LLM、鉴权、审计）
存储/队列 proxy_set/get_shared_data（带 CAS）、proxy_register/resolve/enqueue/dequeue_shared_queue + proxy_on_queue_ready
定时/指标/日志/属性 proxy_set_tick_period_milliseconds + proxy_on_tick、proxy_define/record/increment/get_metric、proxy_log、proxy_get/set_property
本地响应 proxy_send_local_response（短路返回，鉴权/限流/熔断必需）
FFI proxy_call_foreign_function / proxy_on_foreign_function（供宿主暴露高性能内置函数，如 JSON-Path、Tokenizer、CEL）
安全 每插件 VM 隔离；崩溃自动重建 + 速率限制防雪崩；内存/CPU quota；外部资源白名单

官方 proxy-wasm-rust-sdk 提供 RootContext / HttpContext / StreamContext 三个 trait 及 Context 公共 trait，开发体验与当前 spacegate Plugin 接近，但签名是按事件分片（多回调）而非「一个 call(req, inner) -> resp」的组合子。

1.2 语义对齐：spacegate Plugin → Proxy-Wasm Filter

当前 spacegate Proxy-Wasm 对应 说明
Plugin::CODE Root context 名称（vm_id / root_id） 保持 kebab-case 兼容
Plugin::create(config) proxy_on_configure（PLUGIN_CONFIGURATION 读取 JSON） 配置格式 100% 兼容
Plugin::call(req, inner) proxy_on_request_headers/body + proxy_on_response_headers/body 这是主要语义差异：当前是「包裹式 tower Layer」，proxy-wasm 是「事件式 filter chain」；需要宿主（kernel）内部用 adapter 把事件序列合成为一次 request→response
PluginError::new(status, body) proxy_send_local_response 完全一一对应
ext-redis 共享 client proxy_set/get_shared_data + proxy_http_call("redis-upstream") 更推荐走宿主暴露的 foreign function（cel.eval、redis.call），避免每插件自管连接池
dylib 插件（libloading） .wasm 插件（wasmtime/wasmer） 去掉 dylib，唯一扩展产物是 .wasm
PluginInstance 挂载到 gateway/route/rule/backend Proxy-Wasm 里通过「plugin config 作用域」表达 spacegate 的四层挂载更细，保留并映射到 wasm filter chain 的 per-route override

1.3 宿主实现路径

推荐栈：wasmtime（成熟、WASI 支持好、Bytecode Alliance 背书），或 wasmer 作为可选 feature。参考开源实现：proxy-wasm/proxy-wasm-cpp-host、Envoy Wasm extension、higress、mosn-wasm、junction-labs/junction-proxy。

  • 每个 plugin instance = 一个 Root Context，VM 可在「共享 / 独占」两种模式间配置（默认 per-worker 共享 VM，CPU 密集型 plugin 独占）。
  • 对每个 HTTP 请求创建一个 Stream Context（ID 自增），在 inner.call 前后插入 header/body 事件。
  • 异步 proxy_http_call 走网关自己的 hyper client，复用连接池与 TLS 配置，不允许 wasm 直接建 socket。
  • Shared queue 用 in-process crossbeam/tokio::mpsc 实现，跨 pod 语义由上层（Redis Streams）补齐（见评估二）。

1.4 "精简项目代码，更专注内核"

将 crates/kernel 瘦身为「真正内核」：

现状模块 处置 理由
backend_service/http_client_service 保留在内核（上游出站必须）
backend_service/ws_client_service 保留（WS 代理是一等能力）
backend_service/static_file_service 下沉到 plugin（wasm or 官方静态插件） 非内核关注点
backend_service/echo 下沉到 example 测试用途
injector / extractor 简化为「属性读写」抽象，对齐 proxy-wasm proxy_get/set_property 作为 wasm 宿主 API 底座
helper_layers/* 只保留 timeout/retry/trace/metric 等通用 tower 层 其他移到插件
plugin crate 内置 plugins（limit/redirect/rewrite/header_modifier/maintenance/inject/east_west/set_scheme/set_version/decompression/retry/status） 全部抽到独立 crate spacegate-plugins-std/，编译产物是 .wasm，随 release 发布 内核不再内嵌业务插件
ext-redis 保留为 宿主 foreign function 提供方（redis.call, redis.script），插件通过 FFI 调用 避免每个 wasm plugin 重复实现连接
ext-axum 保留，admin/管理面用

预期收益：crates/kernel 预估行数减少 20–30%，crates/plugin 变为wasm 宿主 + 官方插件集合两部分；第三方生态只需产出 .wasm（可用任何支持 proxy-wasm 的语言：Rust/Go/AssemblyScript/C++/Zig），不再强耦合 Rust ABI 与 spacegate 版本。

1.5 四形态打包策略（library / standalone / distributed / k8s）

与仓库现状对齐：spacegate 天然是 library-first，可执行形态源自同一 workspace，四种形态共用同一内核与插件制品，只在配置源、部署拓扑、默认 feature 上分化。

形态 目标用户 产物 配置源 插件来源 典型部署
library（spacegate-kernel / spacegate-shell crate） 嵌入式集成者：在自家 Rust 服务中内嵌网关能力 cargo add spacegate-shell 静态代码 / 调用方注入的 CreateListener 静态链接 + wasmtime in-process（feature 可关） 同进程
standalone（单机） 边缘节点、本地开发、单 VM 部署 单 binary spacegate + plugins/*.wasm + config.json 文件 Fs + notify 热更新 本地目录 / OCI pull 缓存到本地 systemd（已有 resource/install/spacegate.service）
distributed（分布式，非 k8s） 自建集群、裸机/VM 组、跨 AZ 多副本 同 standalone binary × N Redis 作为配置 + Asset Registry + 跨 pod 队列 + 分布式锁 OCI registry 拉取 + Redis 发布变更事件 systemd/docker-compose + 外置 Redis 集群
k8s 云原生用户 容器镜像 + Helm/Kustomize + CRD Gateway API + 自定义 CRD AIAsset / SgPolicy ConfigMap 挂载 或 OCI pull（initContainer 预热） Deployment/DaemonSet + spacegate operator

共用约束：

  • 同一 binary，通过 cargo feature 组合（fs / redis / k8s / wasm / otel…）生成不同发行制品；对应 crates/shell 现有 startup_file / startup_redis / startup_k8s 入口维持。
  • plugin 分发统一为 OCI artifact（wasm-pack / ORAS 规范，如 ghcr.io/ideal-world/plugin-ratelimit:1.0.0）；standalone 与 distributed 在启动时可选 pull 到本地缓存目录，library 形态则由调用方自行决定。
  • Asset Registry 存储后端按形态有不同默认，但用户可覆盖（详见 评估三）：library → in-memory；standalone → SQLite 本地文件；distributed → Redis；k8s → CRD + 可选 Redis 加速层。
  • library 形态默认不启用 wasmtime（保留最小体积、可 opt-in），其他三种形态默认启用。
  • distributed 形态是本次新增的一等公民，补齐「不用 k8s 也能多副本高可用」场景，直接复用 crates/config/src/service/redis 与 crates/extension/redis。

1.6 评估一小结与迁移路径

迁移分三阶段、全程保证旧配置可用：

  1. 引入 wasm 宿主：新增 crates/plugin-wasm，在 PluginRepository 里同时支持 trait-plugin、dylib-plugin、wasm-plugin；trait/dylib 标记为 deprecated。
  2. 官方插件 wasm 化：把现有 plugins/* 逐个移植为 .wasm，配置 schema 不变。
  3. 移除 dylib + 精简 kernel：删除 libloading 依赖、删除 dynamic_lib! 宏；kernel 按 1.4 表瘦身；trait-plugin 仅保留为「内置高性能 plugin」（如 proxy-wasm 表达不了的零拷贝路径）。

评估二：原生支持 MCP / Agents / OpenAI 协议

2.1 协议速览与网关侧角色

协议/规范 内容 网关能做什么
MCP（Model Context Protocol，Anthropic 主导，已入 LF） JSON-RPC 2.0 over stdio / Streamable HTTP / SSE；核心原语 tools/resources/prompts/roots/sampling，带会话与取消 反代 MCP server、多 server 聚合（federation）、工具鉴权/过滤、审计、限流、缓存 resource reads
A2A（Agent-to-Agent，Google 主导） 基于 HTTP + SSE 的 agent 互调协议，带能力发现（agent card）、任务状态机、模态协商 能力目录、身份传递（OIDC propagation）、任务级配额、跨租户隔离
OpenAI Chat/Responses/Assistants API HTTP + SSE 流式，/v1/chat/completions、/v1/responses（新）、/v1/embeddings、/v1/moderations 等 作为统一入口对外提供 OpenAI 兼容 API，后端路由到 OpenAI/Anthropic/Gemini/Bedrock/Ollama/vLLM；做 token 计费、prompt 改写、guardrails、failover
AGENTS.md / agents package 文档级规范（给 coding agent 的 README）+ 以目录/包形式分发的 agent 定义（提示词、工具、模型绑定） 在 agent 资产下作为静态路由子类型：网关把 AGENTS.md 或 agents package 目录作为一种 agent 定义来源，支持文件路径路由 / OCI artifact 拉取 / HTTP 拉取；与 A2A 协议路由并列成为 agent 资产的两种后端形态
agentgateway Rust 写的 AI 网关参考实现（LF 项目），同时做 LLM gateway / MCP gateway / A2A gateway / Inference routing，支持 CEL、Gateway API、OpenTelemetry 作为参考架构，非依赖

2.2 在 spacegate 中的实现形态

核心洞察：这些 AI 协议都是 HTTP+SSE/Streamable 的应用层协议。kernel 不需要为它们特化代码，只要提供「流式透传 + 协议识别扩展点」；协议特性放在 wasm/native plugin 里。

建议新增三个一等协议插件（随 release 发布，但仍是 plugin）：

  1. llm-gateway plugin
    • 路由键：model（从请求体 JSON 中解析，如 model: gpt-4o → 后端 upstream openai；model: claude-3-opus → anthropic）。
    • Provider adapter：OpenAI / Anthropic / Gemini / Bedrock / 本地 vLLM / Ollama 归一为 OpenAI Chat/Responses 形状。
    • 特性：token 计数与预算、prompt 改写、语义缓存（Embedding + Redis Vector，ext-redis 扩展）、多 provider failover、流式分片落盘审计。
  2. mcp-gateway plugin
    • 反代 MCP server（Streamable HTTP/SSE/stdio via sidecar）；tool federation：聚合多个后端 MCP server 的 tools/list，前缀命名空间化（fs::read_file, gh::create_issue）。
    • 鉴权：在 initialize 握手时注入 OAuth scope；tools/call 按 tool 名 ACL。
    • 观测：每 tool call 独立 span，含参数/返回摘要。
  3. a2a-gateway plugin
    • Agent card 注册 + 能力发现端点；task 状态透传；modality negotiation 无需网关干预，仅作治理面。
  4. agents-md 路由器（不是独立协议插件，归属 agent 资产的后端 adapter）
    • 将 AGENTS.md 文件或 agents package 目录作为 agent 实例的定义来源：解析出 setup/test/style 等段落与工具绑定，暴露为 A2A 兼容的 agent card；实际调用时委托给 llm-gateway + mcp-gateway。
    • 支持三种来源：本地目录、HTTP URL、OCI artifact（与 wasm plugin 共用分发通道）。

2.3 高吞吐 & 背压：模型慢响应下的积压处理

这是最硬核的需求。LLM 推理延迟 1–60s，若客户端数 × 并发 > 后端 GPU 容量，会出现请求积压。方案分层：

2.3.1 连接层 —— 内核已具备的能力

  • hyper + tokio 非阻塞 IO：一条在等待上游的连接不消耗线程，数万并发 TCP 连接在现代内核上内存成本约数百 MB，可承受。
  • HTTP/2 多路复用：上游 provider（OpenAI 等）几乎都支持 h2，避免 head-of-line。
  • SSE/Streamable HTTP：kernel 已走流式 body，不需要整包缓冲。

2.3.2 并发控制 —— 新增内核能力

采用三级队列策略（阈值触发逐级降级），配置以 per-route / per-model 为粒度：

级别 触发条件 队列实现 溢出动作
L1 in-process 并发量 < l1_max tokio::sync::Semaphore + 有界 mpsc 溢出进入 L2
L2 Redis Streams（可选，cluster-queue: true） L1 满且队列未满 XADD 投递、XREADGROUP 消费（消费组 = gateway worker set） body 大小超 body_offload_threshold 触发 S3 offload；队列长度超 l2_max 进入 L3
L3 admission control L2 也满或积压超时 - 直接返回 429 / 503 + Retry-After

要点：

  • 全局 + per-route + per-model semaphore：tokio::sync::Semaphore，超过阈值后进入 L2 排队而非立即拒绝，队列深度 / 超时可配。
  • Redis Streams 作为溢出队列（L2）：
    • 复用 crates/extension/redis 已有的 Redis 连接；
    • XADD 写入、消费组 XREADGROUP 消费，XACK 确认，at-least-once；
    • 消息体只存元数据 + body 指针（见下一条），避免大 payload 撑爆 Redis 内存；
    • 不需要独立 MQ 集群，延迟 <1ms，持久化与消费组语义对 LLM 场景足够。
  • 大 body 离线到对象存储（S3 兼容）：
    • 当请求 body > body_offload_threshold（默认 256 KB，可配）时，在入队前把 body 流式上传到 S3 兼容存储（MinIO / 阿里 OSS / AWS S3 / Cloudflare R2）并获取 s3://bucket/key 指针；Redis 队列中只存请求元数据 + body 指针 + content-length + content-type；
    • 消费端（可能是另一个 pod 的 gateway worker）从 S3 拉取 body 再发往上游，流式 GET 与上游 POST 的 body 直接 pipe，避免内存整包加载；
    • 使用预签 URL 或网关侧凭证；请求完成或超时后异步删除对象（生命周期规则兜底）；
    • 对响应 body同样适用：若上游流式响应需要跨 pod 转发（例如排队请求被另一 pod 接手后要把 SSE 流回给最初客户端），则不走 S3，而是用 Redis Pub/Sub + 会话粘性；S3 仅用于入站请求积压这一主要场景。
    • 走 aws-sdk-s3 或更轻量的 rust-s3；作为可选 feature s3-offload。
  • 混合策略：library / standalone 默认只启用 L1（in-process，关闭 Redis 依赖）；distributed / k8s 形态开启 L2；S3 offload 独立开关（即使开 L2 也可以不开 S3，用户评估自家 Redis 容量）。
  • 优先级队列：支持 X-Priority: 0-9 头或路由配置指定，高优先级插队（Redis 使用多个 stream + 加权轮询；in-process 用 BinaryHeap）。
  • 反压观测：semaphore 使用率、队列深度、S3 offload 命中率、L2→L3 溢出率全部上报到 OpenTelemetry。

2.3.3 背压传导

  • 排队超过 queue-timeout-ms → 直接 503 + Retry-After（服务降级）。
  • 客户端 HTTP/2 流：利用 WINDOW_UPDATE 自然背压（hyper 支持），不主动读 body 就能让客户端慢下来。
  • 上游健康度感知路由（类似 agentgateway 的 inference routing）：后端 vLLM/triton 通过 header 或 /metrics 上报 GPU util、KV cache、queue depth；网关按 EWMA 评分加权 LB。

2.3.4 流式响应保序与取消

  • SSE/chunked 下取消传播：客户端断连 → tokio CancellationToken 传到上游 HTTP 调用 → 释放 GPU。这是省成本的核心，kernel 需要显式保证，当前实现需审计（见问题清单 Q6）。

2.3.5 幂等与重放

  • 插件层提供 idempotency-key 去重（Redis SETNX + TTL），失败自动重试或直接返回缓存结果；大模型调用费钱，必不可少。

2.4 轻量化保证

  • MQ 层只用 Redis Streams（可选），不引入 Kafka / NATS / Pulsar。
  • 大 body 溢出只用 S3 兼容协议（AWS S3 / MinIO / 阿里 OSS / R2 / Ceph RGW 通吃），不内嵌对象存储。
  • 向量缓存用 Redis 的 RediSearch/Vector（可选 feature）或走外部向量库 via HTTP plugin；不内嵌向量引擎。
  • Tokenizer：走宿主 foreign function，核心用 tiktoken-rs/tokenizers（HF），编进内核或作为单独的"高权限插件"。
  • 观测：OpenTelemetry 作为一等能力内建（trace/metric/log 三合一，OTLP 导出），不内嵌 Prometheus 抓取服务器；library 形态下 OTel 为 opt-in feature。

评估三：从服务网关演进为 AI 原生平台型网关

3.1 资产模型（Asset Taxonomy）

建议把网关的「路由对象」从"HTTP Route → Backend"扩展为"AI Asset Route → Asset Instance"：

资产类型 典型协议 路由键 后端形态
api HTTP/gRPC path + method service / URL（现状）
model OpenAI-compat HTTP+SSE model 字段 + provider openai/anthropic/vllm/ollama
mcp-server Streamable HTTP / SSE / stdio MCP server name + tool prefix HTTP URL / 本地进程（sidecar）
agent A2A HTTP+SSE 或 AGENTS.md / agents package agent id + capability HTTP URL（A2A）/ 本地目录 / HTTP URL / OCI artifact（agents.md）
skill 内部定义，通常是「一组 prompt + 工具绑定」 skill id 复合：prompt template + model ref + mcp tools ref
cli stdio / HTTP tunnel cli name WebSocket 隧道 / exec endpoint
knowledge HTTP（检索接口）+ 向量查询 kb id + query 向量 DB / ES / 文档服务

统一抽象：Asset { kind, id, version, tenant, app, metadata, endpoints, policies, plugins }，其中 tenant / app 字段对接管理面的三层权限（见 3.5）。

3.2 是否继续用 Kubernetes Gateway API？

结论：部分沿用，但需要自定义 CRD 补齐 AI 资产语义。

Gateway API 的优势：生态、kubectl/UI 工具、多租户 RBAC、状态条件机 (status.conditions)。

劣势与不足：

  • Gateway API 的 HTTPRoute 是以 HTTP 匹配为中心，无法表达"按 JSON body 的 model 字段路由"、"按 MCP method 路由"。可走 ExtensionRef 但体验差。
  • 万级路由 (10k+) 在 k8s controller-runtime reconcile 性能上会成为瓶颈（API Server 事件风暴、etcd 单 key 大小、informer 内存）。Gateway API 典型压测量级为千级。
  • 动态注册/注销一个 asset 实例 → 一个 k8s 资源创建/删除 → 秒级延迟；对"agent/skill/model 实时上下线"偏慢。

建议分层：

  1. 控制面（声明式、低频、审计）：Gateway API + 自定义 CRD AIAsset（kind=model/mcp/agent/skill/…），用 Gateway API 的 parentRefs 机制把 AIAsset 绑定到 Gateway，通过 Gateway API policy attachment（GEP-713）挂 plugin。
  2. 数据面注册表（命令式、高频、运行时）：独立的 Asset Registry（sqlite / redis / postgres + 内存索引），网关直接读；提供 HTTP admin API 与 gRPC 注册流。
    • 支持 TTL 心跳（agent 每 30s 续约，过期自动下线，契合动态注册/注销）。
    • 支持批量订阅（SSE 或 long-poll），网关 worker watch registry diff 增量更新内存路由树。
    • 万级路由：内存索引用 radix tree（path）+ hashmap（exact keys）+ trigram（语义），加载时间 ms 级。
  3. 双通道同步：k8s CRD → operator → Asset Registry（单向）；Asset Registry 自身也允许非 k8s 场景下直接写（standalone 部署）。

判断表：

场景 推荐机制
企业把 100 个生产模型配置进网关 Gateway API + AIAsset CRD
一个 k8s Job 启动的临时 agent 注册 5 分钟后消失 Asset Registry（直接 HTTP 注册+心跳）
10k+ 工具列表（MCP tool federation） Asset Registry（CRD 不合适）
静态 standalone 部署 Asset Registry backed by local file / redis

3.3 万级路由的匹配性能

  • 路由树编译：每次 registry 变更 → 后台线程编译新 RouteTable → 通过 ArcSwap 原子切换，读路径零锁。
  • 匹配算法：
    • host → hashmap
    • path → radix tree
    • AI asset 维度（model/tool/agent-id）→ perfect hash（fxhash + 两级表）
    • body JSON 字段（model: "xxx"）→ lazy parsing，仅读前 N KB
  • 内存评估：1 万路由 × 每条 ~2KB 元数据 ≈ 20MB，可接受。
  • 热点优化：LRU 缓存 (host, path, asset_key) → route_id 以省去 tree 查询。

3.4 扩展能力按路由挂载

spacegate 当前模型已经天然支持"插件挂到 gateway/route/rule/backend"四层（见 crates/model/src/http_route.rs plugins: Vec<P>）。扩展到 AI 资产时：

AIAsset
  ├─ policies: [rate-limit, token-budget, guardrail, cache, audit, auth, ...]
  └─ plugins:  [wasm ref / builtin ref]  ← 通过评估一的 proxy-wasm 机制实现
  • plugin 引用 = code + instance-name + spec(JSON)，与现状一致，无 schema 破坏。
  • 新增策略组 (PolicyGroup)：允许多个 asset 共享策略组，减少重复配置（类似 Envoy 的 RouteAction 共享）。
  • per-call dynamic plugins：某些场景（A/B 实验、金丝雀）需要按请求头动态选择插件链；可用"meta-plugin"（一个 plugin 根据条件调用另一组 plugins），无需内核改动。

3.5 管理面（admin-server）演进与三层 RBAC

权限模型升级为 平台 → 租户 → 应用 三层，所有资产路由必须归属到某一应用：

Platform (superadmin)
  ├─ Tenant A
  │    ├─ App A-1   ──┬─ AIAsset(api)   ──┐
  │    │              ├─ AIAsset(model) ──┤
  │    │              └─ AIAsset(mcp)    ──┤
  │    └─ App A-2   ──── AIAsset(agent)  ──┤
  └─ Tenant B                              │
       └─ App B-1   ──── AIAsset(skill)  ──┤
                                           ▼
                                    spacegate 数据面路由表
  • 角色与权限：
    • PlatformAdmin：管理所有租户、全局配置、wasm plugin 仓库、OCI 凭证、全局 guardrail 策略。
    • TenantAdmin：在本租户内创建/删除应用，管理租户级配额（token 预算、QPS、存储）。
    • AppAdmin：在本应用内创建/管理资产路由、绑定插件策略、查看观测数据。
    • AppViewer：只读。
  • 资产归属与路由隔离：一条请求进入网关后先解析 tenant + app（来自 host / path 前缀 / JWT claim / 显式 header），匹配限定在该 app 的资产子集内；跨 app 路由需显式授权（类似 k8s ServiceEntry）。
  • 租户隔离点：配额（token / QPS / 存储）、凭证（OpenAI API key 等 provider 密钥）、审计日志、OTel resource attributes。
  • Admin UI：基于 hai-framework 全新重写，覆盖：
    • Asset Catalog（按 tenant/app 树状浏览）+ CRUD
    • Playground（直接在 UI 调 tool / 调 model，便于开发调试）
    • Observability（LLM 账单、token 耗用、p99、排队深度、S3 offload 命中率）
    • RBAC 管理（用户 / 角色 / 租户 / 应用）
    • Plugin 仓库（OCI artifact 浏览与实例化）
  • API：Asset Registry 提供 /v1/{tenant}/{app}/assets/* REST + /v1/watch SSE；平台/租户 scope 走独立前缀 /v1/platform/* /v1/tenants/*。

综合架构图（目标态）

┌──────────────────────────────────────────────────────────────────────────┐
│                          Clients / Agents / Apps                         │
└──────────┬───────────────────────────────────────────────────────────────┘
           │ HTTP/1.1 · H2 · WS · SSE · Streamable-HTTP
           ▼
┌──────────────────────── spacegate-kernel (瘦内核) ────────────────────────┐
│  listener → tls → h2/h1 mux → route-table(ArcSwap) → filter-chain → up   │
│                         │                                                │
│                         ├─ proxy-wasm host (wasmtime)  ◀── .wasm plugins │
│                         │     ├─ llm-gateway                              │
│                         │     ├─ mcp-gateway                              │
│                         │     ├─ a2a-gateway                              │
│                         │     ├─ rate-limit / auth / cache / guardrail   │
│                         │     └─ 3rd-party OCI wasm                       │
│                         │                                                │
│                         ├─ native fast-path plugins (少量, tower Layer)  │
│                         │                                                │
│                         └─ foreign functions: redis / tokenizer / cel    │
└────────────┬─────────────────────────────────┬────────────────────────────┘
             ▼                                 ▼
   ┌──────────────────┐              ┌─────────────────────┐
   │ Asset Registry   │◀─── watch ───│  Config Sources     │
   │ (radix+hash)     │              │  ├─ fs / redis      │
   │ + TTL heartbeat  │              │  └─ k8s (Gateway API + AIAsset CRD)
   └──────────────────┘              └─────────────────────┘
             ▲
             │ HTTP admin API / SSE
    ┌────────┴────────┐
    │ admin-server UI │
    └─────────────────┘
             ▲
             │
Upstreams: OpenAI · Anthropic · Gemini · Bedrock · vLLM · Ollama · MCP servers · A2A agents · HTTP APIs · WS · Static

三个评估的关联与实施顺序

[评估一] Proxy-Wasm 扩展机制  ─┐
                                 ├─→ [评估二] AI 协议作为一等 wasm plugin（llm/mcp/a2a/agents.md）
[内核瘦身 + 流式 + 背压 + OTel] ─┘                         │
                                                        ▼
                                [评估三] Asset Registry + 万级动态路由 + 三层 RBAC + per-route plugin 挂载
                                                        │
                                                        ▼
                                 library / standalone / distributed / k8s 四形态同一制品

建议里程碑（相对顺序，不给时间估算；用户确认「不考虑兼容」，故为硬切）：

  1. M0 流式取消传播修复（独立 PR，不阻塞后续）：客户端断连 → CancellationToken → 上游 HTTP/WS 调用取消。
  2. M1 Proxy-Wasm 宿主 + kernel 瘦身：新增 crates/plugin-wasm（wasmtime，feature flag）；一次性移除 trait-plugin 的第三方口子与 dylib 机制（保留少量高频内置 plugin 作为 native fast-path）；精简 kernel 模块（见 1.4）。
  3. M2 背压与队列基础设施：per-route/per-model semaphore + 三级队列（L1 in-process / L2 Redis Streams / L3 admission）+ S3 body offload + 幂等键；OpenTelemetry 内建。
  4. M3 llm-gateway wasm plugin MVP：OpenAI-compat 入口、多 provider adapter、token 计费（仅 OpenAI-compat 范围）。
  5. M4 mcp-gateway wasm plugin MVP：单 server 反代 + tool federation + tool ACL。
  6. M5 Asset Registry + 三层 RBAC + 动态注册 API：可插拔存储后端（SQLite/Redis/Postgres/k8s CRD），TTL 心跳，P99 ≤ 5s 生效。
  7. M6 a2a-gateway + agents.md 路由器：agent 资产两种后端形态全部打通。
  8. M7 高级特性：语义缓存（Redis Vector，可选）、guardrails 集成（Moderations + regex + webhook）、inference-aware LB、OIDC/JWT 鉴权统一下发 proxy_property。
  9. M8 全新 Admin UI：基于 hai-framework 重写；OCI plugin 仓库、Playground、账单与观测视图。

决策记录（Q1–Q22 已确认）

以下为用户已确认的决策，作为后续 RFC 与 PR 的依据。

A. 范围与取舍

编号 决策
Q1 兼容期 一次性移除 现有 Rust Plugin trait 对第三方的入口 + dylib 机制；不做长期兼容。内置高频 plugin 以 native fast-path 形式保留（见 Q2/Q4）。
Q2 性能敏感插件 允许保留极少数原生 Rust fast-path 插件（tower Layer 形式），用于 proxy-wasm 表达不了的零拷贝/极端高 QPS 场景。
Q3 WASM runtime wasmtime + feature flag；不引入 wasmer。
Q4 内置插件去留 挑选使用率最高的保留在 kernel 作为默认行为，其余全部 wasm 化。初选 native 保留清单（最终以使用率统计为准）：rewrite / redirect / header-modifier / maintenance / static-resource。

B. AI 协议与性能

编号 决策
Q5 AGENTS.md agent 资产同时包含 A2A 协议路由 与 AGENTS.md / agents package 文件路由 两种后端形态（见 2.1 / 3.1）。
Q6 流式取消传播 作为 M0 独立 PR 先行修复，不阻塞后续里程碑。
Q7 跨 pod 队列后端 限定 Redis Streams，不预留 NATS。
Q8 Token 计费范围 仅覆盖 OpenAI-compat 调用，其他 provider 的差异化计价后续再扩。
Q9 语义缓存 内置 embedding + 向量近邻缓存，可选配置启用；默认实现用 Redis Vector / RediSearch；外部 Milvus/Qdrant 通过 plugin 扩展。
Q10 Guardrails 要集成：默认支持 regex + OpenAI Moderations + 外部 webhook 三类；作为官方 wasm plugin 发布。

C. 资产注册与 k8s

编号 决策
Q11 路由规模上限 10 万条 路由为设计上限；数据结构用 radix tree + perfect hash + LRU 热点缓存，RouteTable 通过 ArcSwap 原子切换。
Q12 动态注册 SLA 注册→可用 P99 ≤ 5s 即可；无需走 k8s etcd，采用独立 Asset Registry。
Q13 Asset Registry 存储后端 允许用户可选，默认值按形态：library=in-memory、standalone=SQLite、distributed=Redis、k8s=CRD（可选叠加 Redis 加速层）。
Q14 多实例一致性 最终一致（各副本独立 watch），无需读主。
Q15 Gateway API 迁移 不考虑兼容，重构可直接破坏现有 HTTPRoute 配置；新 CRD AIAsset/SgPolicy 为唯一推荐形态。
Q16 鉴权与身份 采用推荐方案：网关统一做 OIDC/JWT 验签，claims 作为 proxy_property 下发所有 plugin；workload identity（SPIFFE）列为后续可选。
Q17 管理面权限 三层 RBAC：平台 / 租户 / 应用；所有资产路由必须绑定到某个应用，详见 3.5。

D. 非功能与交付

编号 决策
Q18 二进制体积 可放宽，不再以 6MB 为硬约束；library 形态下 wasmtime / OTel / s3-offload 等均为 opt-in feature，保持嵌入成本最低。
Q19 OCI plugin 分发 OCI registry + HTTP/file 下载都要支持（OCI 为首选，HTTP 为离线/内网备份）。
Q20 观测 OpenTelemetry 作为一等能力内建（trace / metric / log 三合一，OTLP 导出）。
Q21 Admin UI 基于 hai-framework 全新重写所有 UI；旧 sdk/admin-client 不再演进。
Q22 License 与治理 考虑捐赠 Linux Foundation / CNCF，模块命名与依赖策略向基金会标准靠拢（LF 友好 license、DCO、CODEOWNERS 完善）。

附录 A：用于 GitHub 的 Issue 模板（可直接发布）

标题：[RFC] Spacegate 2.0: AI-Native Platform Gateway —— Proxy-Wasm + MCP/A2A/OpenAI + 10 万级动态资产路由

标签建议：rfc / epic / breaking-change / ai-gateway

Background

Spacegate 目前是一个 library-first、基于 hyper/tower 的轻量云原生 HTTP 网关，扩展机制基于私有 Rust Plugin trait + dylib。随着 AI 原生场景（LLM / MCP / A2A / Agents）兴起，现有模型在以下方面不再够用：

  • 扩展机制非标准，跨语言/跨版本/沙箱能力弱；
  • 缺乏对 MCP/A2A/OpenAI-compat 等 AI 协议的一等支持；
  • 路由模型仍以「HTTP Route → Backend」为中心，无法表达模型、工具、agent、skill 等多种 AI 资产；
  • 缺乏面向 LLM 慢响应场景的背压与队列能力。

详细评估见仓库根目录 ASSESSMENT.md。

Goals

  1. 扩展机制标准化：用 Proxy-Wasm ABI v0.2.1 + wasmtime 替换私有 trait + dylib，第三方插件产物统一为 .wasm，通过 OCI registry 或 HTTP 分发。
  2. AI 原生协议支持：原生支持 OpenAI-compat / MCP / A2A，AGENTS.md / agents package 作为 agent 资产后端形态之一。
  3. 平台型资产路由：新增 AIAsset 模型（kind = api / model / mcp-server / agent / skill / cli / knowledge），支持 10 万 条路由、P99 ≤ 5s 的动态注册/注销、三层 RBAC（平台/租户/应用）。
  4. 高吞吐与背压：三级队列（in-process → Redis Streams → admission control），大 body 自动 offload 到 S3 兼容对象存储，客户端断连→上游取消传播。
  5. 四形态对齐：library / standalone / distributed / k8s 共用同一内核与插件制品。

Non-Goals

  • 不保留对现有 Plugin trait / dylib / HTTPRoute 配置的兼容性（一次性破坏升级，breaking change）。
  • 不引入 Kafka / NATS / Pulsar 等独立 MQ。
  • 不内嵌向量引擎（用 Redis Vector 或外部 via plugin）。
  • 不内嵌对象存储（依赖外部 S3 兼容服务）。
  • 本期不对 Anthropic/Gemini/Bedrock 做差异化 token 计费（仅 OpenAI-compat 范围）。

Key Decisions (from Q1–Q22)

见 ASSESSMENT.md 决策记录 的四张表。

Milestones (child issues)

  • M0 流式取消传播修复（客户端断连 → 上游 HTTP/WS CancellationToken）
  • M1 Proxy-Wasm 宿主（wasmtime, feature flag）+ kernel 瘦身 + 移除 dylib + 精选 native fast-path plugin
  • M2 三级队列 + S3 body offload + 幂等键 + OpenTelemetry 内建
  • M3 llm-gateway wasm plugin MVP（OpenAI-compat 入口、多 provider、token 计费）
  • M4 mcp-gateway wasm plugin MVP（反代 + tool federation + tool ACL）
  • M5 Asset Registry + 三层 RBAC（平台/租户/应用）+ 动态注册 API（可插拔存储后端）
  • M6 a2a-gateway + agents.md 路由器
  • M7 语义缓存（Redis Vector, 可选）+ Guardrails（regex + Moderations + webhook）+ inference-aware LB + OIDC/JWT 统一鉴权
  • M8 基于 hai-framework 的全新 Admin UI（Asset Catalog / Playground / Observability / RBAC / Plugin 仓库）

Architecture

见 ASSESSMENT.md 综合架构图。

Breaking Changes

  • 移除 spacegate_plugin::Plugin trait 的第三方注册入口与 dynamic_lib! 宏；第三方必须迁移到 .wasm。
  • 移除 crates/plugin/src/plugins/* 中的业务插件，迁至独立 spacegate-plugins-std crate 并产出 .wasm。
  • 配置 schema：旧 HTTPRoute JSON/K8s CRD 不再被消费；新 AIAsset 为唯一路由模型。
  • 二进制体积：6 MB 硬约束放开，按形态分化。

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

Feature

Fields

No fields configured for Feature.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions