企业官网建设流程全解析

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-sdk

proxy-wasm-rust-sdk 是 WebAssembly for Proxies 官方 Rust SDK，帮你用 Rust 编写 Envoy 代理插件，一条cargo build命令编译出 Wasm 插件，再用 Docker Compose 一键启动 Envoy 完成部署。本文带你从零跑通 Hello World 示例，10 分钟上手。

3步完成搭建：环境准备清单

在开始之前，请确认本地环境满足以下要求：

安装 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_start：VM 启动时打印 "Hello, World!" 并设置 5 秒定时器；
• 在on_tick回调中每 5 秒打印当前时间和一个随机数。

它演示了 SDK 最基础的三大能力：注册入口、定时任务、日志输出，是学习整个 SDK 的绝佳起点。

第3步：Docker Compose 一键部署 Envoy

示例自带 docker-compose.yaml 和 envoy.yaml，无需任何手动配置。

一键启动

cd examples/hello_world docker compose up

Compose 文件做了两件关键的事：

1. 挂载 Envoy 配置：./envoy.yaml→ 容器内/etc/envoy/envoy.yaml；
2. 挂载 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: It's 2026-08-27 03:39:17.849616 UTC, your lucky number is 41. [... ] wasm log: It's 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_headers为例，启动后发一条请求即可在日志中看到插件记录的头信息：

curl localhost:10000/hello # 日志输出：#2 -> :method: GET / #2 <- :status: 200 ...

常见问题排查

Q1：cargo build报错 "target wasm32-wasip1 not found"执行rustup target add wasm32-wasip1安装编译目标。

Q2：Envoy 启动后立即退出，日志报 wasm 加载失败检查target/wasm32-wasip1/release/下是否已生成.wasm文件——必须先编译再docker compose up，因为挂载的是本地构建产物目录。

Q3：如何升级 Envoy 版本？修改 docker-compose.yaml 中的image字段，例如envoyproxy/envoy:v1.38-latest。

Q4：插件代码在哪里修改？示例插件源码都在examples/<示例名>/src/lib.rs；SDK 提供的 trait 与类型定义在src/traits.rs和src/types.rs，可查阅 CHANGELOG.md 了解各版本 API 变更（如 0.2.3 新增移除头/尾的便捷函数）。

总结

proxy-wasm-rust-sdk 提供了「Cargo 编译 Wasm + Docker Compose 部署 Envoy」的完整工作流：

1. rustup target add wasm32-wasip1准备环境；
2. cargo build --target wasm32-wasip1 --release生成插件；
3. 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