docs(console): document Host-page and embedded build workflows
- explain the persistent Host and disposable iframe ownership model - define SDK compatibility and PWA cache boundaries - document independent debug servers and release embedding - record Node, npm, NPM, and WASMELD_BUILD_WEB requirements - update repository structure and startup commands
This commit is contained in:
Maofeng
@@ -34,9 +34,9 @@ Host driver <- validated operation <- raw effect <-
|
||||
```text
|
||||
crates/wasmeld-runtime Component Runtime 与 Sandbox
|
||||
crates/wasmeld-console 管理 API 与持久化
|
||||
└── web/ Solid + Tailwind v4 管理面
|
||||
crates/wasmeld-package wasmeld CLI、组件包与 WIT 依赖管理
|
||||
components/ 示例 Component
|
||||
console/ TanStack Start 管理面
|
||||
wit/ Wasmeld WIT package 源码
|
||||
```
|
||||
|
||||
@@ -65,13 +65,26 @@ curl http://127.0.0.1:8081/v1/services/echo/invoke \
|
||||
--data-binary 'hello'
|
||||
```
|
||||
|
||||
管理面：
|
||||
管理面开发服务器：
|
||||
|
||||
```bash
|
||||
cd console
|
||||
cd crates/wasmeld-console/web
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
打开 `http://127.0.0.1:3000`。开发期间 Rust 和 Web 独立增量构建；Release 构建会自动
|
||||
构建 Web 并嵌入 `wasmeld-console`：
|
||||
|
||||
```bash
|
||||
cargo +stable build --release -p wasmeld-console
|
||||
./target/release/wasmeld-console
|
||||
```
|
||||
|
||||
此时管理面直接由 `http://127.0.0.1:8080` 提供，不需要部署单独的静态站点。Host +
|
||||
iframe 页面生命周期、PWA 缓存和前端目录约定见
|
||||
[`Console Web 文档`](crates/wasmeld-console/web/README.md)。
|
||||
|
||||
## 组件开发
|
||||
|
||||
Console 启动后，使用开发模式监听组件源码和本地 WIT `replace`：
|
||||
|
||||
@@ -10,6 +10,7 @@
|
||||
- 通过独立 Gateway 转发原始二进制调用
|
||||
- 为导入 `wasmeld:kv/store@0.1.0` 的 Component 提供持久化 KV
|
||||
- 暴露调用计数、状态和最近事件
|
||||
- 在 Release 可执行文件中嵌入 Solid + Tailwind v4 管理面
|
||||
|
||||
Wasm 制品保存在本地文件系统。服务 manifest、调用计数和最近 256 条事件通过
|
||||
[Toasty](https://github.com/tokio-rs/toasty) 写入本地 libSQL 数据库，默认路径是
|
||||
@@ -38,6 +39,25 @@ Console 或 Runtime 重启后可由 Wasmtime 直接复用；缓存不包含 Acto
|
||||
cargo +stable run -p wasmeld-console
|
||||
```
|
||||
|
||||
Debug 构建只启动 API，不构建或提供 Web 静态文件。前端开发服务器需要单独启动：
|
||||
|
||||
```bash
|
||||
cd crates/wasmeld-console/web
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Release 构建会自动使用 `package-lock.json` 构建并嵌入管理面：
|
||||
|
||||
```bash
|
||||
cargo +stable build --release -p wasmeld-console
|
||||
./target/release/wasmeld-console
|
||||
```
|
||||
|
||||
发布构建要求 Node.js 22.13+ 和 npm。可用 `NPM` 指定 npm 可执行文件；设置
|
||||
`WASMELD_BUILD_WEB=1` 可以在非 Release Cargo 构建中验证嵌入流程。前端结构和 PWA
|
||||
边界见 [`web/README.md`](web/README.md)。
|
||||
|
||||
进程默认启动两个独立 Listener：
|
||||
|
||||
- 管理 API：`127.0.0.1:8080`
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
# Wasmeld Console Web
|
||||
|
||||
管理面使用 Solid 和 Tailwind CSS v4。它不是传统单文档 SPA，而是由一个常驻 Host
|
||||
文档和一个可替换 Page iframe 组成：
|
||||
|
||||
```text
|
||||
index.html / src/host
|
||||
├── 导航、搜索、弹窗、通知
|
||||
├── 管理 API 轮询和共享状态
|
||||
└── page.html?view=<view>&instance=<n>
|
||||
└── src/pages/<view>
|
||||
```
|
||||
|
||||
Host 始终只保留一个 iframe。切换一级页面时，Host 先发送 `dispose`，再销毁 iframe
|
||||
并创建新的文档。页面所属的 Solid reactive owner、事件监听器、第三方 UI 库和页面局部
|
||||
缓存会随文档一起释放，避免长期导航后把各页面资源都留在同一个 JavaScript realm 中。
|
||||
|
||||
iframe 是资源生命周期边界，不是安全边界。Host 和 Page 都是 Wasmeld 自己构建并同源
|
||||
发布的可信代码；Wasm 服务的安全边界仍然在后端 Wasmtime Sandbox 和 Host Capability
|
||||
Registry 中。
|
||||
|
||||
## 目录
|
||||
|
||||
```text
|
||||
src/host/ 常驻 Host Shell 和 Host-owned dialogs
|
||||
src/components/ui/ 跨页面复用的无业务 UI
|
||||
src/lib/ API client、领域模型和纯函数
|
||||
src/primitives/ Solid reactive primitives；Solid 不使用 React Hooks 约定
|
||||
src/pages/ 每个 iframe 页面一个目录和独立懒加载 chunk
|
||||
src/sdk/ Host/Page postMessage 协议与两侧 client
|
||||
src/styles/ Tailwind v4 theme 和共享组件样式
|
||||
```
|
||||
|
||||
`src/sdk/protocol.ts` 中的 `SDK_VERSION` 是文档间协议版本。新增可选消息可以保持原版本；
|
||||
删除字段、改变字段语义或产生不兼容状态时必须升级版本，并让两侧同时发布。消息接收端
|
||||
同时检查 origin、source、channel 和 version，不接收任意窗口的控制命令。
|
||||
|
||||
## 开发
|
||||
|
||||
先在仓库根目录启动 Rust 后端：
|
||||
|
||||
```bash
|
||||
cargo +stable run -p wasmeld-console
|
||||
```
|
||||
|
||||
再启动 Web 开发服务器：
|
||||
|
||||
```bash
|
||||
cd crates/wasmeld-console/web
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
打开 `http://127.0.0.1:3000`。Vite 开发环境默认连接
|
||||
`http://127.0.0.1:8080`；设置页可以覆盖该地址。Debug Cargo 构建不会调用 npm，
|
||||
因此 Rust 与 Web 的增量开发互不阻塞。
|
||||
|
||||
常用检查：
|
||||
|
||||
```bash
|
||||
npm run format:check
|
||||
npm run lint
|
||||
npm test
|
||||
npm audit --audit-level=high
|
||||
```
|
||||
|
||||
## 发布与嵌入
|
||||
|
||||
Release 构建由 `../build.rs` 自动执行：
|
||||
|
||||
```bash
|
||||
cargo +stable build --release -p wasmeld-console
|
||||
```
|
||||
|
||||
构建脚本使用 `npm ci` 严格读取 `package-lock.json`，将 Vite 输出写入 Cargo
|
||||
`OUT_DIR`，再由 Rust `include_dir!` 嵌入可执行文件。发布机器必须提供 Node.js 22.13+
|
||||
和 npm。可以用 `NPM=/absolute/path/to/npm` 指定 npm；只有需要调试嵌入行为时，才在
|
||||
非 Release 构建中设置 `WASMELD_BUILD_WEB=1`。
|
||||
|
||||
Release 管理 Listener 同时服务 `/`、`/page.html`、静态资源、PWA manifest 和
|
||||
`/sw.js`。资源路径必须精确存在，不做 SPA fallback。带内容哈希的 `assets/` 使用长期
|
||||
immutable 缓存，其它入口使用 `no-cache`。
|
||||
|
||||
## PWA 边界
|
||||
|
||||
一个 Host-owned service worker 管理整个应用：
|
||||
|
||||
- 构建时预缓存 Host、Page 和带哈希静态资源。
|
||||
- 文档请求使用 network-first，离线时分别回退到 `index.html` 或 `page.html`。
|
||||
- `/api/*` 和 `/healthz` 永远走网络，不缓存运行状态或管理操作。
|
||||
- 新 worker 激活时删除旧的 `wasmeld-*` 缓存。
|
||||
|
||||
PWA 只提供安装和静态壳离线能力。没有后端连接时页面会显示离线状态，不会用旧 API
|
||||
响应伪造 Runtime 状态。
|
||||
Reference in New Issue
Block a user