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.
224 lines
5.4 KiB
Markdown
224 lines
5.4 KiB
Markdown
# Wasmeld CLI
|
||
|
||
`wasmeld-package` 提供 `wasmeld` 命令，用于：
|
||
|
||
- 开发、编译和打包 WebAssembly Component
|
||
- 监听源码并将开发版本自动部署到 Wasmeld Console
|
||
- 解析、锁定和替换 WIT Package 依赖
|
||
- 构建并发布版本化 WIT Package
|
||
|
||
Runtime 不接收 Rust 源码。CLI 会先将 Rust 编译为 WebAssembly Component，再生成
|
||
`.wasmpkg` 或上传到 Console。
|
||
|
||
## 运行
|
||
|
||
在项目工作区内可以直接运行：
|
||
|
||
```bash
|
||
cargo +stable run -p wasmeld-package --bin wasmeld -- <command>
|
||
```
|
||
|
||
Component 默认使用 Rust `1.90.0` 和 `wasm32-wasip2` 目标构建。可以通过
|
||
`WASMELD_COMPONENT_TOOLCHAIN` 指定其它已安装工具链。
|
||
|
||
## Component 项目
|
||
|
||
一个可打包的 Component 至少需要：
|
||
|
||
```text
|
||
component/
|
||
├── Cargo.toml
|
||
├── wasmeld.toml
|
||
├── wit.lock
|
||
├── src/lib.rs
|
||
└── wit/world.wit
|
||
```
|
||
|
||
`Cargo.toml` 必须提供 `cdylib` Target 和 Wasmeld 元数据：
|
||
|
||
```toml
|
||
[package]
|
||
name = "echo-component"
|
||
version = "0.1.0"
|
||
|
||
[package.metadata.wasmeld]
|
||
id = "echo"
|
||
world = "component:echo/echo-component@0.1.0"
|
||
|
||
[lib]
|
||
crate-type = ["cdylib"]
|
||
```
|
||
|
||
`version` 成为正式包的 Revision；`id` 是服务 ID；`world` 必须与 Component 实际导出的
|
||
WIT World 一致。
|
||
|
||
## 边写边预览
|
||
|
||
先启动 Console：
|
||
|
||
```bash
|
||
cargo +stable run -p wasmeld-console
|
||
```
|
||
|
||
再启动开发循环：
|
||
|
||
```bash
|
||
cargo +stable run -p wasmeld-package --bin wasmeld -- \
|
||
dev components/echo/Cargo.toml
|
||
```
|
||
|
||
开发循环会监听 Rust、Cargo、WIT 清单以及本地 `replace` WIT 源，并执行：
|
||
|
||
```text
|
||
同步 WIT 依赖
|
||
→ Debug 编译
|
||
→ 生成 .wasmpkg
|
||
→ 注册开发 Revision
|
||
→ 启动并切换 Deployment
|
||
→ 注销上一开发 Revision
|
||
```
|
||
|
||
默认服务 ID 为 `<id>-dev`，Revision 为 `<version>-dev.h<component-hash>`。正式服务不会
|
||
被覆盖。构建、校验或启动失败时不会切换 Deployment，上一版本继续提供服务。
|
||
|
||
管理面默认每 5 秒刷新一次，也可以直接调用开发服务：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8081/v1/services/echo-dev/invoke \
|
||
-H 'Content-Type: application/octet-stream' \
|
||
--data-binary 'hello'
|
||
```
|
||
|
||
开发选项：
|
||
|
||
| 选项 | 作用 |
|
||
| --- | --- |
|
||
| `--console <url>` | Console 管理 API，默认 `http://127.0.0.1:8080` |
|
||
| `--id <service-id>` | 覆盖默认的 `<id>-dev` 服务 ID |
|
||
| `--once` | 构建、部署一次后退出，适合脚本和 CI |
|
||
| `--release` | 使用 Release 而不是 Debug 构建 |
|
||
| `--locked` | 要求依赖与现有 `wit.lock` 完全一致 |
|
||
| `--poll-ms <n>` | 源码扫描间隔，最小 100 ms，默认 350 ms |
|
||
|
||
也可以通过 `WASMELD_CONSOLE` 设置管理 API 地址。退出 `wasmeld dev` 不会停止当前开发
|
||
Deployment；它会继续运行，直到手工停止、切换或注销。
|
||
|
||
只修改 Rust 源码且不允许契约变化时使用 `--locked`。需要同步修改本地 WIT `replace`
|
||
时不要使用该选项，CLI 会更新 `wit.lock`。
|
||
|
||
## 打包 Component
|
||
|
||
```bash
|
||
cargo +stable run -p wasmeld-package --bin wasmeld -- \
|
||
pack components/echo/Cargo.toml --locked
|
||
```
|
||
|
||
默认执行 Release 构建并输出：
|
||
|
||
```text
|
||
dist/echo-0.1.0.wasmpkg
|
||
```
|
||
|
||
可用选项：
|
||
|
||
| 选项 | 作用 |
|
||
| --- | --- |
|
||
| `--output <path>`、`-o <path>` | 指定输出文件 |
|
||
| `--no-build` | 使用现有 Release Component 制品 |
|
||
| `--locked` | 禁止 WIT 依赖解析结果改变 |
|
||
|
||
`.wasmpkg` 是受约束的 ZIP，固定包含：
|
||
|
||
```text
|
||
package.toml
|
||
component.wasm
|
||
```
|
||
|
||
`package.toml` 记录服务 ID、Revision、World 和 Component SHA-256。运行时资源限制不由
|
||
组件声明，而是在 Console 注册时由平台策略注入。
|
||
|
||
## WIT 依赖
|
||
|
||
`wasmeld.toml` 使用精确版本：
|
||
|
||
```toml
|
||
schema_version = 1
|
||
|
||
[wit]
|
||
root = "wit"
|
||
|
||
[registry]
|
||
url = "http://127.0.0.1:8080"
|
||
|
||
[dependencies]
|
||
"wasmeld:service" = "0.1.0"
|
||
"wasmeld:kv" = "0.1.0"
|
||
|
||
[replace."wasmeld:service"]
|
||
path = "../../wit/service"
|
||
```
|
||
|
||
依赖解析结果写入 `wit.lock`，源码开发时应提交该文件。解析出的 `wit/deps/` 是生成目录，
|
||
不应提交。
|
||
|
||
同步依赖：
|
||
|
||
```bash
|
||
wasmeld wit fetch --manifest components/echo/wasmeld.toml
|
||
```
|
||
|
||
校验锁定结果且禁止变化：
|
||
|
||
```bash
|
||
wasmeld wit fetch --manifest components/echo/wasmeld.toml --locked
|
||
```
|
||
|
||
`wit tidy` 当前与 `wit fetch` 使用相同的确定性解析和物化流程。查看根依赖和有效来源：
|
||
|
||
```bash
|
||
wasmeld wit graph --manifest components/echo/wasmeld.toml
|
||
```
|
||
|
||
添加本地替换：
|
||
|
||
```bash
|
||
wasmeld wit replace wasmeld:service@0.1.0 \
|
||
--path ../../wit/service \
|
||
--manifest components/echo/wasmeld.toml
|
||
```
|
||
|
||
包级替换可以省略 `@version`。精确版本替换的优先级更高。移除替换：
|
||
|
||
```bash
|
||
wasmeld wit replace wasmeld:service@0.1.0 \
|
||
--drop \
|
||
--manifest components/echo/wasmeld.toml
|
||
```
|
||
|
||
## WIT Package
|
||
|
||
将 WIT 源目录构建为标准二进制 WIT Package：
|
||
|
||
```bash
|
||
wasmeld wit build wit/service \
|
||
--output dist/wit/wasmeld-service-0.1.0.wasm
|
||
```
|
||
|
||
发布到 Console 的不可变 WIT Registry：
|
||
|
||
```bash
|
||
wasmeld wit publish wit/service \
|
||
--registry http://127.0.0.1:8080
|
||
```
|
||
|
||
Registry 地址也可以通过 `WASMELD_REGISTRY` 设置。相同 Package 版本不可覆盖；协议变化
|
||
应发布新版本，并由 Component 在 `wasmeld.toml` 中显式选择。
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 作用 |
|
||
| --- | --- |
|
||
| `WASMELD_COMPONENT_TOOLCHAIN` | Component Rust 工具链，默认 `1.90.0` |
|
||
| `WASMELD_CONSOLE` | `wasmeld dev` 使用的 Console 管理 API |
|
||
| `WASMELD_REGISTRY` | `wit publish` 使用的 Registry 地址 |
|