SGL Model Gateway WASM 中间件实战基于 WebAssembly Component Model 的 API Key 鉴权【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本文以 sgl-model-gateway 仓库中的 wasm-guest-auth 示例 为核心系统讲解如何用 Rust 与 WebAssembly Component Model 为网关编写一个 API Key 鉴权中间件从 WIT 接口绑定、on_request钩子实现到构建.component.wasm、通过/wasmREST API 热部署挂载到OnRequest阶段再到用 curl 验证401 Unauthorized与放行逻辑。读完本文你将掌握在 sgl-model-gateway 上开发、构建、部署与调试 WASM 中间件的完整链路并理解其与网关源码中执行管线middleware.rs的对应关系。背景为什么用 WASM 给网关写鉴权中间件sgl-model-gateway 是 SGLang 生态中负责请求路由与转发的网关组件它通过--enable-wasm开关见 router_args.py启用 WebAssembly 支持允许开发者以 WASM 组件的形式注入自定义中间件逻辑而不必修改网关核心代码或重新编译 Rust 二进制。wasm-guest-auth正是这一能力的官方示例它是一个基于WebAssembly Component Model编写的 API Key 鉴权中间件会对打到/api和/v1路径的请求校验 API Key缺失或非法即返回401 Unauthorized。选择 WASM 作为中间件载体带来三个直接收益语言无关与隔离中间件以独立 WASM 组件运行与网关进程隔离逻辑更新无需重启网关按请求阶段挂载通过attach_points将模块挂到OnRequest/OnResponse阶段网关在对应管线节点执行链式组合多个中间件按部署顺序依次执行见 examples/wasm/README.md可与其他中间件如日志、限流自由编排。示例能力与默认行为依据 wasm-guest-auth README该中间件对/api与/v1前缀路径的请求依次支持以下三种 Key 携带方式方式Header 示例Authorization: Bearer keyAuthorization: Bearer secret-api-key-12345Authorization: ApiKey keyAuthorization: ApiKey secret-api-key-12345x-api-keyx-api-key: secret-api-key-12345校验失败Key 缺失或不匹配返回401 Unauthorized校验通过返回Action::Continue请求继续沿网关管线流转默认 API Keysecret-api-key-12345挂载点仅使用OnRequest阶段OnResponse钩子为空实现。注意该示例对/api、/v1之外的路径不做鉴权直接Continue这是刻意为之的演示行为生产环境中需结合自身路由前缀调整判断范围。环境准备与构建前置依赖构建与运行需要以下工具链与 examples/wasm/README.md 一致# 1. Rust 最新稳定版工具链含 rustup # 2. WebAssembly 组件目标 rustup target add wasm32-wasip2 # 3. WASM 工具集用于组件封装与校验 cargo install wasm-tools # 4. 以 WASM 模式启动 sgl-model-gateway # 例如通过 Python 绑定启动时携带 --enable-wasm其中wasm32-wasip2目标与wasm-tools是 Component Model 开发的两块基石前者让 Rust 直接编译到 WASI Preview 2 组件模型后者负责将产物封装/校验为.component.wasm组件格式。一键构建脚本仓库为每个示例都提供了build.sh。以 wasm-guest-auth 为例脚本build.sh自动完成四件事检查cargo、wasm-tools是否就绪缺失即报错退出检查wasm32-wasip2目标是否安装未安装则自动rustup target add wasm32-wasip2执行cargo build --target wasm32-wasip2 --release编译出模块用wasm-tools print判断产物是否已是组件格式已是组件则直接复制为wasm_guest_auth.component.wasm否则用wasm-tools component new封装。构建命令cd examples/wasm-guest-auth ./build.sh成功产物位于target/wasm32-wasip2/release/下wasm_guest_auth.wasm核心 WASM 模块wasm_guest_auth.component.wasm部署时使用的组件文件file_path指向它。若不想逐个构建也可在 examples/wasm 目录批量构建全部三个示例auth / logging / ratelimit。核心实现源码逐段解析中间件本体是一个约 70 行的 Rust 文件src/lib.rs其中包含四个关键部分。1. WIT 接口绑定与导出类型wit_bindgen::generate!({ path: ../../../src/wasm/interface, world: sgl-model-gateway, }); use exports::sgl::model_gateway::{ middleware_on_request::Guest as OnRequestGuest, middleware_on_response::Guest as OnResponseGuest, }; use sgl::model_gateway::middleware_types::{Action, Request, Response};wit_bindgen::generate!依据网关的 WIT 世界定义sgl-model-gateway生成绑定代码示例通过实现middleware_on_request::Guest与middleware_on_response::Guest两个特征来履行中间件契约。middleware_types中提供了网关侧与组件侧共用的Action、Request、Response类型。对应的网关侧执行管线位于 middleware.rs网关把 axum 请求转换为WasmRequest含method、path、query、headers、body、request_id、now_epoch_ms等字段调用组件后根据返回的Action决定后续行为。2. 期望 API Key 常量/// Expected API Key (in production, this should be passed as configuration) const EXPECTED_API_KEY: str secret-api-key-12345;源码注释明确提示生产环境应将密钥改为通过配置注入而非硬编码在组件中。这与仓库 README 的“Customization”一节对应——修改此处常量并重新构建即可更换密钥。3. Header 查找辅助函数fn find_header_value( headers: [sgl::model_gateway::middleware_types::Header], name: str, ) - OptionString { headers .iter() .find(|h| h.name.eq_ignore_ascii_case(name)) .map(|h| h.value.clone()) }eq_ignore_ascii_case保证 Header 名大小写不敏感如Authorization与authorization均可命中这是 HTTP 语义下的必要健壮性处理。4. OnRequest 钩子鉴权主逻辑impl OnRequestGuest for Middleware { fn on_request(req: Request) - Action { // API Key Authentication // Check for API key in Authorization header for /api routes if req.path.starts_with(/api) || req.path.starts_with(/v1) { let api_key find_header_value(req.headers, authorization) .and_then(|h| { h.strip_prefix(Bearer ) .or_else(|| h.strip_prefix(ApiKey )) .map(|s| s.to_string()) }) .or_else(|| find_header_value(req.headers, x-api-key)); // Reject if API key is missing or invalid if api_key.as_deref() ! Some(EXPECTED_API_KEY) { return Action::Reject(401); } } // Authentication passed, continue processing Action::Continue } }这段代码完整实现了 README 中描述的全部三种 Key 携带方式执行逻辑为路径筛选req.path以/api或/v1开头才进入鉴权分支提取 Key优先读取authorization头剥离Bearer或ApiKey前缀若该头不存在或前缀不匹配则回退读取x-api-key头比对判定提取值与EXPECTED_API_KEY不相等含缺失场景即返回Action::Reject(401)网关据此将响应置为 401见 middleware.rs 中Action::Reject(status)的处理匹配则Action::Continue放行。OnResponse钩子为空实现恒返回Continue符合“鉴权只看请求”的职责边界。部署通过 REST API 热加载组件启动网关先确保网关以 WASM 模式运行# 以 Python 绑定启动为例省略其余路由参数 python -m sglang_router.launch_server ... --enable-wasm对应参数定义在 router_args.pyPython 绑定测试 test_pyo3_binding.py 中也以--enable-wasm覆盖了该路径。提交部署请求网关提供/wasmREST API 管理模块实现见 route.rs部署中间件curl -X POST http://localhost:3000/wasm \ -H Content-Type: application/json \ -d { modules: [{ name: auth-middleware, file_path: /absolute/path/to/wasm_guest_auth.component.wasm, module_type: Middleware, attach_points: [{Middleware: OnRequest}] }] }参数含义字段说明name模块名用于后续查询与去重按名称匹配file_path组件文件绝对路径即wasm_guest_auth.component.wasmmodule_type固定为Middlewareattach_points挂载点鉴权中间件必须挂在{Middleware: OnRequest}从 route.rs 可以看出POST /wasm并非直接注册模块而是把WasmModuleConfigRequest包装成Job::AddWasmModule提交到异步任务队列随后以最长 300 秒的超时轮询任务状态成功后再从模块管理器中按名称反查 UUID 回填结果。也就是说部署是异步完成的接口返回即代表任务已受理。其他管理接口GET /wasm列出全部模块并附带执行指标总执行次数、成功/失败次数、总耗时、最大耗时、平均耗时便于观测中间件运行健康度DELETE /wasm/:uuid按 UUID 卸载模块见 route.rs。验证与测试部署完成后用 curl 验证鉴权行为# 未携带 Key应返回 401 curl -v http://localhost:3000/api/test # 携带合法 Bearer Key应放行 curl -v http://localhost:3000/api/test \ -H Authorization: Bearer secret-api-key-12345同样可以验证ApiKey前缀与x-api-key头两种方式以及“错误 Key 返回 401”的负向用例。若需观察执行管线内部行为可参考仓库集成测试 wasm_test.rs该测试套件覆盖了 WASM 模块的增删查、工作流集成与执行错误处理其中使用WasmModuleManager::with_default_config()初始化管理器见第 47-49 行是理解模块管理生命周期的重要参考。自定义与故障排查修改 API Key编辑 src/lib.rs 中的常量后重新构建并重新部署const EXPECTED_API_KEY: str your-secret-key;生产化建议将密钥改为运行时配置注入而非硬编码常量源码注释亦如此建议结合网关的限流中间件wasm-guest-ratelimit与日志中间件wasm-guest-logging做组合防护三个模块可一次性全部部署执行顺序即部署顺序任一模块返回Reject后链上后续模块不再执行见 examples/wasm/README.md。常见问题排查按 wasm-guest-auth README 的清单逐项核对确认 Key 一致请求头中的 Key 是否与EXPECTED_API_KEY完全一致确认 Header 与路径Header 格式是否为Bearer/ApiKey/x-api-key三者之一且请求路径以/api或/v1开头确认挂载阶段模块是否挂载到OnRequest阶段——attach_points若误配为OnResponse鉴权不会生效检查网关日志查看路由器日志中的错误输出配合GET /wasm返回的执行指标失败次数、平均耗时定位问题。小结通过 wasm-guest-auth 示例可以看到 sgl-model-gateway 的 WASM 中间件机制全貌用wit_bindgen绑定网关 WIT 世界实现on_request/on_response钩子返回Action经build.sh产出组件文件再借/wasmREST API 热挂载到请求管线的OnRequest阶段。网关侧 middleware.rs 与 wasm_test.rs 则为理解执行时序与模块管理提供了源码级依据。以此为模板你可以把任意请求级策略鉴权、改写、校验以 WASM 组件形式注入网关实现业务逻辑与网关核心的解耦。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SGL Model Gateway WASM 中间件实战：基于 WebAssembly Component Model 的 API Key 鉴权
SGL Model Gateway WASM 中间件实战基于 WebAssembly Component Model 的 API Key 鉴权【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本文以 sgl-model-gateway 仓库中的 wasm-guest-auth 示例 为核心系统讲解如何用 Rust 与 WebAssembly Component Model 为网关编写一个 API Key 鉴权中间件从 WIT 接口绑定、on_request钩子实现到构建.component.wasm、通过/wasmREST API 热部署挂载到OnRequest阶段再到用 curl 验证401 Unauthorized与放行逻辑。读完本文你将掌握在 sgl-model-gateway 上开发、构建、部署与调试 WASM 中间件的完整链路并理解其与网关源码中执行管线middleware.rs的对应关系。背景为什么用 WASM 给网关写鉴权中间件sgl-model-gateway 是 SGLang 生态中负责请求路由与转发的网关组件它通过--enable-wasm开关见 router_args.py启用 WebAssembly 支持允许开发者以 WASM 组件的形式注入自定义中间件逻辑而不必修改网关核心代码或重新编译 Rust 二进制。wasm-guest-auth正是这一能力的官方示例它是一个基于WebAssembly Component Model编写的 API Key 鉴权中间件会对打到/api和/v1路径的请求校验 API Key缺失或非法即返回401 Unauthorized。选择 WASM 作为中间件载体带来三个直接收益语言无关与隔离中间件以独立 WASM 组件运行与网关进程隔离逻辑更新无需重启网关按请求阶段挂载通过attach_points将模块挂到OnRequest/OnResponse阶段网关在对应管线节点执行链式组合多个中间件按部署顺序依次执行见 examples/wasm/README.md可与其他中间件如日志、限流自由编排。示例能力与默认行为依据 wasm-guest-auth README该中间件对/api与/v1前缀路径的请求依次支持以下三种 Key 携带方式方式Header 示例Authorization: Bearer keyAuthorization: Bearer secret-api-key-12345Authorization: ApiKey keyAuthorization: ApiKey secret-api-key-12345x-api-keyx-api-key: secret-api-key-12345校验失败Key 缺失或不匹配返回401 Unauthorized校验通过返回Action::Continue请求继续沿网关管线流转默认 API Keysecret-api-key-12345挂载点仅使用OnRequest阶段OnResponse钩子为空实现。注意该示例对/api、/v1之外的路径不做鉴权直接Continue这是刻意为之的演示行为生产环境中需结合自身路由前缀调整判断范围。环境准备与构建前置依赖构建与运行需要以下工具链与 examples/wasm/README.md 一致# 1. Rust 最新稳定版工具链含 rustup # 2. WebAssembly 组件目标 rustup target add wasm32-wasip2 # 3. WASM 工具集用于组件封装与校验 cargo install wasm-tools # 4. 以 WASM 模式启动 sgl-model-gateway # 例如通过 Python 绑定启动时携带 --enable-wasm其中wasm32-wasip2目标与wasm-tools是 Component Model 开发的两块基石前者让 Rust 直接编译到 WASI Preview 2 组件模型后者负责将产物封装/校验为.component.wasm组件格式。一键构建脚本仓库为每个示例都提供了build.sh。以 wasm-guest-auth 为例脚本build.sh自动完成四件事检查cargo、wasm-tools是否就绪缺失即报错退出检查wasm32-wasip2目标是否安装未安装则自动rustup target add wasm32-wasip2执行cargo build --target wasm32-wasip2 --release编译出模块用wasm-tools print判断产物是否已是组件格式已是组件则直接复制为wasm_guest_auth.component.wasm否则用wasm-tools component new封装。构建命令cd examples/wasm-guest-auth ./build.sh成功产物位于target/wasm32-wasip2/release/下wasm_guest_auth.wasm核心 WASM 模块wasm_guest_auth.component.wasm部署时使用的组件文件file_path指向它。若不想逐个构建也可在 examples/wasm 目录批量构建全部三个示例auth / logging / ratelimit。核心实现源码逐段解析中间件本体是一个约 70 行的 Rust 文件src/lib.rs其中包含四个关键部分。1. WIT 接口绑定与导出类型wit_bindgen::generate!({ path: ../../../src/wasm/interface, world: sgl-model-gateway, }); use exports::sgl::model_gateway::{ middleware_on_request::Guest as OnRequestGuest, middleware_on_response::Guest as OnResponseGuest, }; use sgl::model_gateway::middleware_types::{Action, Request, Response};wit_bindgen::generate!依据网关的 WIT 世界定义sgl-model-gateway生成绑定代码示例通过实现middleware_on_request::Guest与middleware_on_response::Guest两个特征来履行中间件契约。middleware_types中提供了网关侧与组件侧共用的Action、Request、Response类型。对应的网关侧执行管线位于 middleware.rs网关把 axum 请求转换为WasmRequest含method、path、query、headers、body、request_id、now_epoch_ms等字段调用组件后根据返回的Action决定后续行为。2. 期望 API Key 常量/// Expected API Key (in production, this should be passed as configuration) const EXPECTED_API_KEY: str secret-api-key-12345;源码注释明确提示生产环境应将密钥改为通过配置注入而非硬编码在组件中。这与仓库 README 的“Customization”一节对应——修改此处常量并重新构建即可更换密钥。3. Header 查找辅助函数fn find_header_value( headers: [sgl::model_gateway::middleware_types::Header], name: str, ) - OptionString { headers .iter() .find(|h| h.name.eq_ignore_ascii_case(name)) .map(|h| h.value.clone()) }eq_ignore_ascii_case保证 Header 名大小写不敏感如Authorization与authorization均可命中这是 HTTP 语义下的必要健壮性处理。4. OnRequest 钩子鉴权主逻辑impl OnRequestGuest for Middleware { fn on_request(req: Request) - Action { // API Key Authentication // Check for API key in Authorization header for /api routes if req.path.starts_with(/api) || req.path.starts_with(/v1) { let api_key find_header_value(req.headers, authorization) .and_then(|h| { h.strip_prefix(Bearer ) .or_else(|| h.strip_prefix(ApiKey )) .map(|s| s.to_string()) }) .or_else(|| find_header_value(req.headers, x-api-key)); // Reject if API key is missing or invalid if api_key.as_deref() ! Some(EXPECTED_API_KEY) { return Action::Reject(401); } } // Authentication passed, continue processing Action::Continue } }这段代码完整实现了 README 中描述的全部三种 Key 携带方式执行逻辑为路径筛选req.path以/api或/v1开头才进入鉴权分支提取 Key优先读取authorization头剥离Bearer或ApiKey前缀若该头不存在或前缀不匹配则回退读取x-api-key头比对判定提取值与EXPECTED_API_KEY不相等含缺失场景即返回Action::Reject(401)网关据此将响应置为 401见 middleware.rs 中Action::Reject(status)的处理匹配则Action::Continue放行。OnResponse钩子为空实现恒返回Continue符合“鉴权只看请求”的职责边界。部署通过 REST API 热加载组件启动网关先确保网关以 WASM 模式运行# 以 Python 绑定启动为例省略其余路由参数 python -m sglang_router.launch_server ... --enable-wasm对应参数定义在 router_args.pyPython 绑定测试 test_pyo3_binding.py 中也以--enable-wasm覆盖了该路径。提交部署请求网关提供/wasmREST API 管理模块实现见 route.rs部署中间件curl -X POST http://localhost:3000/wasm \ -H Content-Type: application/json \ -d { modules: [{ name: auth-middleware, file_path: /absolute/path/to/wasm_guest_auth.component.wasm, module_type: Middleware, attach_points: [{Middleware: OnRequest}] }] }参数含义字段说明name模块名用于后续查询与去重按名称匹配file_path组件文件绝对路径即wasm_guest_auth.component.wasmmodule_type固定为Middlewareattach_points挂载点鉴权中间件必须挂在{Middleware: OnRequest}从 route.rs 可以看出POST /wasm并非直接注册模块而是把WasmModuleConfigRequest包装成Job::AddWasmModule提交到异步任务队列随后以最长 300 秒的超时轮询任务状态成功后再从模块管理器中按名称反查 UUID 回填结果。也就是说部署是异步完成的接口返回即代表任务已受理。其他管理接口GET /wasm列出全部模块并附带执行指标总执行次数、成功/失败次数、总耗时、最大耗时、平均耗时便于观测中间件运行健康度DELETE /wasm/:uuid按 UUID 卸载模块见 route.rs。验证与测试部署完成后用 curl 验证鉴权行为# 未携带 Key应返回 401 curl -v http://localhost:3000/api/test # 携带合法 Bearer Key应放行 curl -v http://localhost:3000/api/test \ -H Authorization: Bearer secret-api-key-12345同样可以验证ApiKey前缀与x-api-key头两种方式以及“错误 Key 返回 401”的负向用例。若需观察执行管线内部行为可参考仓库集成测试 wasm_test.rs该测试套件覆盖了 WASM 模块的增删查、工作流集成与执行错误处理其中使用WasmModuleManager::with_default_config()初始化管理器见第 47-49 行是理解模块管理生命周期的重要参考。自定义与故障排查修改 API Key编辑 src/lib.rs 中的常量后重新构建并重新部署const EXPECTED_API_KEY: str your-secret-key;生产化建议将密钥改为运行时配置注入而非硬编码常量源码注释亦如此建议结合网关的限流中间件wasm-guest-ratelimit与日志中间件wasm-guest-logging做组合防护三个模块可一次性全部部署执行顺序即部署顺序任一模块返回Reject后链上后续模块不再执行见 examples/wasm/README.md。常见问题排查按 wasm-guest-auth README 的清单逐项核对确认 Key 一致请求头中的 Key 是否与EXPECTED_API_KEY完全一致确认 Header 与路径Header 格式是否为Bearer/ApiKey/x-api-key三者之一且请求路径以/api或/v1开头确认挂载阶段模块是否挂载到OnRequest阶段——attach_points若误配为OnResponse鉴权不会生效检查网关日志查看路由器日志中的错误输出配合GET /wasm返回的执行指标失败次数、平均耗时定位问题。小结通过 wasm-guest-auth 示例可以看到 sgl-model-gateway 的 WASM 中间件机制全貌用wit_bindgen绑定网关 WIT 世界实现on_request/on_response钩子返回Action经build.sh产出组件文件再借/wasmREST API 热挂载到请求管线的OnRequest阶段。网关侧 middleware.rs 与 wasm_test.rs 则为理解执行时序与模块管理提供了源码级依据。以此为模板你可以把任意请求级策略鉴权、改写、校验以 WASM 组件形式注入网关实现业务逻辑与网关核心的解耦。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
