2026-07-27 05:03:24 +08:00
|
|
|
|
# Wasmeld
|
|
|
|
|
|
|
|
|
|
|
|
Wasmeld 是面向 WebAssembly Component 的服务运行与管理平台。内部服务编译为
|
|
|
|
|
|
Component，在受限 Wasmtime Sandbox 中以常驻 Actor 运行，并通过稳定 WIT 契约
|
|
|
|
|
|
暴露能力。
|
|
|
|
|
|
|
2026-07-29 19:13:51 +08:00
|
|
|
|
Runtime 内置版本化 Host Capability Registry。注册 Component 时会直接读取其 WIT
|
|
|
|
|
|
imports，只链接实际请求且版本完全匹配的 Host 能力；未知能力会被拒绝。能力不需要在
|
|
|
|
|
|
`.wasmpkg` 中重复声明，管理面会展示每个服务版本解析出的完整接口标识。
|
|
|
|
|
|
|
2026-07-29 19:37:19 +08:00
|
|
|
|
当前 Host 能力：
|
|
|
|
|
|
|
|
|
|
|
|
- `wasmeld:clock/monotonic-clock@0.1.0`：Actor 内单调时钟
|
|
|
|
|
|
- `wasmeld:kv/store@0.1.0`：按服务隔离、跨 Revision 共享的持久化二进制 KV
|
|
|
|
|
|
|
2026-07-27 05:03:24 +08:00
|
|
|
|
## 结构
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
crates/wasmeld-runtime Component Runtime 与 Sandbox
|
|
|
|
|
|
crates/wasmeld-console 管理 API 与持久化
|
|
|
|
|
|
crates/wasmeld-package wasmeld CLI、组件包与 WIT 依赖管理
|
|
|
|
|
|
components/ 示例 Component
|
|
|
|
|
|
console/ TanStack Start 管理面
|
|
|
|
|
|
wit/ Wasmeld WIT package 源码
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 启动
|
|
|
|
|
|
|
|
|
|
|
|
后端：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cargo +stable run -p wasmeld-console
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-29 16:32:21 +08:00
|
|
|
|
后端会启动本地管理 API `127.0.0.1:8080` 和公开数据面
|
|
|
|
|
|
`0.0.0.0:8081`。注册 Component 后，通过管理 API 激活一个版本：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST http://127.0.0.1:8080/api/v1/deployments/echo/activate \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"revision":"0.1.0"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
客户端只访问 Gateway，并以原始二进制请求调用活动版本：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl http://127.0.0.1:8081/v1/services/echo/invoke \
|
|
|
|
|
|
-H 'Content-Type: application/octet-stream' \
|
|
|
|
|
|
--data-binary 'hello'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-27 05:03:24 +08:00
|
|
|
|
管理面：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cd console
|
|
|
|
|
|
npm run dev
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-29 20:26:25 +08:00
|
|
|
|
## 组件开发
|
|
|
|
|
|
|
|
|
|
|
|
Console 启动后，使用开发模式监听组件源码和本地 WIT `replace`：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cargo run -p wasmeld-package --bin wasmeld -- \
|
|
|
|
|
|
dev components/echo/Cargo.toml --locked
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
首次构建和每次源码变化都会自动完成 WIT 同步、Debug 编译、打包、注册和 Deployment
|
|
|
|
|
|
切换。默认使用 `echo-dev` 这类独立服务 ID，并根据 Component 内容生成
|
|
|
|
|
|
`0.1.0-dev.h<hash>` Revision，不会覆盖正式服务。新版本构建、校验或启动失败时，上一
|
|
|
|
|
|
版本继续运行；切换成功后旧开发 Revision 会被注销并释放。
|
|
|
|
|
|
|
|
|
|
|
|
管理面每 5 秒刷新一次，可以直接在调用面板预览新版本。只构建并部署一次可使用
|
|
|
|
|
|
`--once`；其它选项包括 `--id`、`--console`、`--release` 和 `--poll-ms`。管理 API
|
|
|
|
|
|
地址也可通过 `WASMELD_CONSOLE` 设置。
|
|
|
|
|
|
|
2026-07-27 05:03:24 +08:00
|
|
|
|
构建组件：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cargo run -p wasmeld-package --bin wasmeld -- \
|
|
|
|
|
|
pack components/echo/Cargo.toml --locked
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-29 19:37:19 +08:00
|
|
|
|
KV 示例组件：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cargo run -p wasmeld-package --bin wasmeld -- \
|
|
|
|
|
|
pack components/kv-probe/Cargo.toml --locked
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
`kv-probe` 接受 `set:<key>:<value>`、`get:<key>` 和 `delete:<key>`，用于验证 Host KV
|
|
|
|
|
|
能力；它不是公开 Gateway 的业务协议。
|
|
|
|
|
|
|
2026-07-27 05:03:24 +08:00
|
|
|
|
发布 WIT Package：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cargo run -p wasmeld-package --bin wasmeld -- \
|
|
|
|
|
|
wit publish wit/service --registry http://127.0.0.1:8080
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
组件在 `wasmeld.toml` 中声明 Registry 和精确版本依赖，`wasmeld wit fetch` 会递归
|
|
|
|
|
|
解析依赖、生成 `wit/deps`，并将完整解析结果记录在 `wit.lock`。本地开发可使用
|
|
|
|
|
|
`[replace]` 临时覆盖 Registry 来源。
|
