Maofeng
2650b8ef14
Document Component project requirements, live preview behavior and options, package construction, WIT dependency locking and replacement, Registry publishing, and CLI environment variables. Link the root and Console guides to the maintained CLI reference and remove links to excluded design documents.
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# Wasmeld
|
||
|
||
Wasmeld 是面向 WebAssembly Component 的服务运行与管理平台。内部服务编译为
|
||
Component，在受限 Wasmtime Sandbox 中以常驻 Actor 运行，并通过稳定 WIT 契约
|
||
暴露能力。
|
||
|
||
Runtime 内置版本化 Host Capability Registry。注册 Component 时会直接读取其 WIT
|
||
imports，只链接实际请求且版本完全匹配的 Host 能力；未知能力会被拒绝。能力不需要在
|
||
`.wasmpkg` 中重复声明，管理面会展示每个服务版本解析出的完整接口标识。
|
||
|
||
当前 Host 能力：
|
||
|
||
- `wasmeld:clock/monotonic-clock@0.1.0`：Actor 内单调时钟
|
||
- `wasmeld:kv/store@0.1.0`：按服务隔离、跨 Revision 共享的持久化二进制 KV
|
||
|
||
## 结构
|
||
|
||
```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
|
||
```
|
||
|
||
后端会启动本地管理 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'
|
||
```
|
||
|
||
管理面：
|
||
|
||
```bash
|
||
cd console
|
||
npm run dev
|
||
```
|
||
|
||
## 组件开发
|
||
|
||
Console 启动后，使用开发模式监听组件源码和本地 WIT `replace`：
|
||
|
||
```bash
|
||
cargo run -p wasmeld-package --bin wasmeld -- \
|
||
dev components/echo/Cargo.toml
|
||
```
|
||
|
||
首次构建和每次源码变化都会自动完成 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` 设置。默认允许本地 `replace` 更新 `wit.lock`；若开发
|
||
期间不允许 WIT 契约发生变化，再添加 `--locked`。
|
||
|
||
构建组件：
|
||
|
||
```bash
|
||
cargo run -p wasmeld-package --bin wasmeld -- \
|
||
pack components/echo/Cargo.toml --locked
|
||
```
|
||
|
||
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 的业务协议。
|
||
|
||
发布 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 来源。
|
||
|
||
完整命令、开发选项、组件包格式和 WIT 依赖说明见
|
||
[`wasmeld-package` CLI 文档](crates/wasmeld-package/README.md)。
|