proxy-wasm-rust-sdk构建与部署完全指南Cargo编译Wasm Docker Compose一键跑通Envoy【免费下载链接】proxy-wasm-rust-sdkWebAssembly for Proxies (Rust SDK)项目地址: https://gitcode.com/gh_mirrors/pr/proxy-wasm-rust-sdkproxy-wasm-rust-sdk 是 WebAssembly for Proxies 官方 Rust SDK帮你用 Rust 编写 Envoy 代理插件一条cargo build命令编译出 Wasm 插件再用 Docker Compose 一键启动 Envoy 完成部署。本文带你从零跑通 Hello World 示例10 分钟上手。3步完成搭建环境准备清单在开始之前请确认本地环境满足以下要求依赖版本要求用途Rust≥ 1.85编译 Wasm 插件见 Cargo.toml 中rust-versionDocker Docker Compose任意较新版本运行 Envoy 容器cargo 工具链随 Rust 安装构建 Wasm 目标安装 Rust 的wasm32-wasip1编译目标只执行一次rustup target add wasm32-wasip1 提示SDK 的 release 配置已开启lto、opt-level 3和strip debuginfo编译出的 .wasm 文件更小、运行更快。第1步克隆仓库从 GitCode 获取源码git clone https://gitcode.com/gh_mirrors/pr/proxy-wasm-rust-sdk cd proxy-wasm-rust-sdk第2步Cargo 编译 Wasm 插件进入 Hello World 示例目录一条命令完成编译cd examples/hello_world cargo build --target wasm32-wasip1 --release构建成功后产物位于examples/hello_world/target/wasm32-wasip1/release/proxy_wasm_example_hello_world.wasm这个插件做了什么核心逻辑在 lib.rs代码非常短通过proxy_wasm::main!宏注册插件入口宏定义见 src/lib.rs实现RootContext的on_vm_startVM 启动时打印 Hello, World! 并设置 5 秒定时器在on_tick回调中每 5 秒打印当前时间和一个随机数。它演示了 SDK 最基础的三大能力注册入口、定时任务、日志输出是学习整个 SDK 的绝佳起点。第3步Docker Compose 一键部署 Envoy示例自带 docker-compose.yaml 和 envoy.yaml无需任何手动配置。一键启动cd examples/hello_world docker compose upCompose 文件做了两件关键的事挂载 Envoy 配置./envoy.yaml→ 容器内/etc/envoy/envoy.yaml挂载 Wasm 产物./target/wasm32-wasip1/release→/etc/envoy/proxy-wasm-plugins。而envoy.yaml通过envoy.bootstrap.wasm扩展加载插件指定 V8 运行时name: hello_world vm_config: runtime: envoy.wasm.runtime.v8 code: local: filename: /etc/envoy/proxy-wasm-plugins/proxy_wasm_example_hello_world.wasm验证运行结果约 5 秒后观察 Envoy 日志每 5 秒会多出一行[... ] wasm log: Hello, World! [... ] wasm log: Its 2026-08-27 03:39:17.849616 UTC, your lucky number is 41. [... ] wasm log: Its 2026-08-27 03:39:22.846531 UTC, your lucky number is 28. 看到wasm log:开头的日志说明你的 Wasm 插件已在 Envoy 中成功运行项目结构速览了解目录布局方便后续扩展proxy-wasm-rust-sdk/ ├── src/ # SDK 核心源码 │ ├── lib.rs # 入口宏 main! 与上下文注册 API │ ├── traits.rs # RootContext / HttpContext 等 trait 定义 │ ├── types.rs # 状态码、MapType 等类型定义 │ ├── dispatcher.rs # 宿主调用调度 │ └── hostcalls.rs # Proxy-Wasm ABI 宿主函数封装 ├── examples/ # 8 个可直接运行的插件示例 └── Cargo.toml # SDK 包定义crate 名proxy-wasm更多示例从 Hello World 到真实业务README.md 中列出了 8 个示例全部遵循「Cargo 编译 Docker Compose 部署」同一套流程示例目录功能难度HTTP 认证随机examples/http_auth_random/通过 HTTP callout 动态鉴权⭐⭐HTTP 头处理examples/http_headers/记录/修改请求响应头⭐⭐HTTP 响应体examples/http_body/流式读写响应体⭐⭐⭐HTTP 配置examples/http_config/从配置解析参数⭐⭐gRPC 认证examples/grpc_auth_random/gRPC callout 鉴权⭐⭐⭐Envoy 过滤器元数据examples/envoy_filter_metadata/读取 Envoy 元数据⭐⭐⭐Envoy TCP 路由examples/envoy_tcp_routing/基于 filter state 做 TCP 路由⭐⭐⭐⭐以http_headers为例启动后发一条请求即可在日志中看到插件记录的头信息curl localhost:10000/hello # 日志输出#2 - :method: GET / #2 - :status: 200 ...常见问题排查Q1cargo build报错 target wasm32-wasip1 not found执行rustup target add wasm32-wasip1安装编译目标。Q2Envoy 启动后立即退出日志报 wasm 加载失败检查target/wasm32-wasip1/release/下是否已生成.wasm文件——必须先编译再docker compose up因为挂载的是本地构建产物目录。Q3如何升级 Envoy 版本修改 docker-compose.yaml 中的image字段例如envoyproxy/envoy:v1.38-latest。Q4插件代码在哪里修改示例插件源码都在examples/示例名/src/lib.rsSDK 提供的 trait 与类型定义在src/traits.rs和src/types.rs可查阅 CHANGELOG.md 了解各版本 API 变更如 0.2.3 新增移除头/尾的便捷函数。总结proxy-wasm-rust-sdk 提供了「Cargo 编译 Wasm Docker Compose 部署 Envoy」的完整工作流rustup target add wasm32-wasip1准备环境cargo build --target wasm32-wasip1 --release生成插件docker compose up一键拉起 Envoy 验证效果。从 Hello World 出发再逐步尝试 HTTP 头、认证、TCP 路由等示例你就能用 Rust 为 Envoy 编写生产级的 Wasm 扩展了。祝编码愉快【免费下载链接】proxy-wasm-rust-sdkWebAssembly for Proxies (Rust SDK)项目地址: https://gitcode.com/gh_mirrors/pr/proxy-wasm-rust-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考