AionUi Web Host 包解析：零 Electron 依赖的 WebUI 宿主架构与 aioncore 进程编排实战

AionUi Web Host 包解析零 Electron 依赖的 WebUI 宿主架构与 aioncore 进程编排实战【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi导读aionui/web-host是 AionUi 中负责承载 WebUI 的宿主包它的核心价值在于彻底剥离 Electron 依赖仅用 Node.js 原生http、net与child_process模块即可完成「拉起或复用 aioncore 后端进程 托管前端 SPA 反向代理 API/WebSocket 密码鉴权配置」这一整套宿主职责。阅读本文后你将掌握startWebHost的完整配置模型、aioncore 子进程的生命周期管理机制、静态服务与反向代理的路由设计以及如何在 Electron 主进程或纯 Node CLI 中复用这套能力。一、包定位与核心职责packages/web-host/README.md将该包描述为 WebUI host package for AionUi - zero Electron dependency。它在整个仓库中的位置介于后端aioncore与前端out/renderer构建产物之间是 WebUI 能够以纯 Web 形态独立运行的骨架。从 包入口 与 package.json 可以看到该包对外暴露三大模块模块文件职责backend-launcherbackend-launcher.tsspawn 或复用已存在的 aioncore 进程管理其启动、健康检查与崩溃重启static-serverstatic-server.ts托管out/renderer的 SPA 静态资源并反向代理/api、/ws到后端auth由后端 aionui-auth crate 承载密码重置、修改、校验及配置读写bcrypt session值得注意的一点是README 中提到的 auth 职责从源码结构看并非由 web-host 包自身实现而是把/login、/logout、/api/auth/*等路径直接反向代理给后端的 aionui-auth crate见 static-server.ts 的设计注释与forwardToBackend路由。web-host 本身不持有任何持久化配置端口与allowRemote的解析由调用方Electron 主进程、bun run webuiCLI负责——这是 index.ts 注释明确说明的设计契约。二、快速上手startWebHost使用示例README 给出了最简调用方式下面结合 types.ts 中的完整类型定义进行展开import { startWebHost } from aionui/web-host; const handle await startWebHost({ app: { version: 1.0.0, isPackaged: false, resourcesPath: /path/to/resources, userDataPath: /path/to/userData, }, staticDir: /path/to/out/renderer, backend: { kind: ownBackend, resolveBackend: () /path/to/aioncore, }, }); console.log(WebUI running at ${handle.url}); await handle.stop();2.1 选项模型逐字段解析WebHostOptions的完整字段见 types.tsapp: AppMetadata宿主环境注入的应用元信息包含version版本号、isPackaged是否打包产物、resourcesPath资源目录、userDataPath用户数据目录。这四个字段是 backend-launcher 构造 spawn 参数与错误诊断信息的基础。staticDir: string前端 SPA 构建输出目录即out/renderer由 static-server 托管。port?: numberWebUI 对外监听端口缺省时使用 static-server 内置的默认端口25808见 static-server.ts。allowRemote?: boolean是否允许局域网访问。为true时监听0.0.0.0并计算可广播的networkUrl缺省false时仅监听127.0.0.1见 static-server.ts。dataDir?: string/logDir?: string传给后端的数据库数据目录与日志目录。其中dataDir在ownBackend模式下是必填的——startBackend若检测到dataDir为空会直接抛错见 backend-launcher.ts。dirs?: BackendSystemDirs系统目录三元组{ cacheDir, workDir, logDir }。它们会被注入为AIONUI_{CACHE,WORK,LOG}_DIR环境变量后端通过/api/system/info上报这些目录。若省略后端会继承process.env很可能拿到父 shell 留下的过期值因此源码注释建议显式传入见 types.ts。backend二选一的判别联合类型{ kind: ownBackend; resolveBackend: BackendBinaryResolver }由本包 spawn 后端resolveBackend是一个返回 aioncore 二进制路径的函数{ kind: useExistingBackend; port: number }复用外部已运行的后端端口此时startWebHost会创建一个stop为 no-op 的假 handle见 index.ts。2.2 返回值WebHostHandlestartWebHost返回的组合句柄见 types.ts字段含义portWebUI 实际监听端口backendPort后端 aioncore 实际运行端口url推荐访问地址远程开启时为networkUrl否则为localUrllocalUrl本机访问地址http://127.0.0.1:portnetworkUrl?/lanIP?仅allowRemote开启时存在局域网访问地址及其 IPstop()依次停止 static-server 与 backendstop()的顺序语义在 index.ts 中有严格约定先停静态服务、再停后端且 static-server 启动失败时会先回滚停止已启动的后端再抛错避免资源泄漏index.ts。这一行为在 start-web-host.test.ts 中以待办测试的形式被明确记录下来。三、backend-launcheraioncore 子进程生命周期管理3.1 起源从 Electron 迁移而来backend-launcher.ts头部注释明确说明它是在 M4 里程碑从packages/desktop/src/process/backend/lifecycleManager.ts迁移而来去除了对app.*的 Electron 依赖改为构造器注入的AppMetadata与BackendBinaryResolver而 spawn 参数、/health超时、SIGTERM/SIGKILL 及崩溃重启窗口等运行时行为与桌面版逐字节保持一致见 backend-launcher.ts。3.2 端口发现与 fetch 兼容性findAvailablePort负责挑选后端端口其中蕴含一个容易被忽视的细节浏览器fetch对一批端口是禁止访问的如 21、22、25、53、110、554、587、989、993、995 等完整黑名单见 backend-launcher.ts。因此挑选端口时必须避开这些 fetch 禁用端口否则 WebUI 的前端 API 调用会被浏览器拦截。该函数最多尝试 50 次FETCH_COMPATIBLE_PORT_MAX_ATTEMPTS每次通过临时监听127.0.0.1:0获取系统分配的空闲端口再校验其不在黑名单内backend-launcher.ts。3.3 spawn 参数与环境变量buildSpawnArgsbackend-launcher.ts构造 aioncore 启动参数关键项如下参数说明--port port后端监听端口--data-dir path数据库数据目录--parent-pid pid父进程 PID用于后端感知宿主退出--log-level level日志级别默认打包产物为info开发环境为debug可被AIONUI_LOG_LEVEL覆盖--app-version ver应用版本--managed-resources-mode bundled仅打包产物isPackaged时追加--dump-prompts仅非打包且设置AIONUI_DUMP_PROMPTS1时追加--log-dir/--work-dir日志与工作目录显式提供时追加--local本地模式标志--recover-corrupted-database数据库损坏恢复标志recoverCorruptedDatabase为 true 时追加buildSpawnEnvbackend-launcher.ts做两件事其一剥离PREBUILDS_ONLY环境变量——该变量只应作用于 Electron 进程自身的 node-gyp-build 原生模块若透传给 aioncore 派生的 Agent CLI如 cursor-agent会导致其携带的build/Release原生模块被 node-gyp-build 跳过在 ACP 握手前中止其二注入AIONUI_CACHE_DIR/AIONUI_WORK_DIR/AIONUI_LOG_DIR供后端/api/system/info上报。3.4 就绪判定stdout 标记 /health轮询双通道后端的「就绪」信号来自两个通道的竞速backend-launcher.ts权威标记aioncore 在axum::serve真正开始服务后向 stdout 输出整行AIONCORE_READY无负载的裸标记端口则来自更早的AIONCORE_LISTENING json行其中包含{host:127.0.0.1,port:N}。健康轮询对http://127.0.0.1:port/health每 200ms 轮询一次默认超时 30 秒waitForHealth的timeoutMs 30_000。任一通道先命中即视为就绪。若健康检查超时但进程仍存活且设置了allowPendingOnHealthTimeout启动器可以选择保留进程并在后台继续等待continueWaitingForHealth会以无限超时继续轮询由onHealthTimeout/onReady回调通知调用方——这为桌面端区分「可恢复的慢启动」与「必须杀死的启动失败如数据库恢复」提供了依据backend-launcher.ts。3.5 崩溃重启与边界错误崩溃重启运行期间子进程意外退出时handleCrash在 60 秒窗口内最多重启 3 次重启延迟按2^(n-1) * 1000ms指数退避1s/2s/4s超过上限则进入error状态backend-launcher.ts。数据目录实例守卫当另一个 aioncore 已持有同一 contenteditable="false">【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考