tinyjs 架构内幕:txiki.js 后端与原生 WebView 如何靠 Unix Socket 协议高效协同

原创2026-10-16 13:00:212,301 阅读

tinyjs 架构内幕:txiki.js 后端与原生 WebView 如何靠 Unix Socket 协议高效协同

tinyjs 是一个让你用纯 JavaScript 构建原生桌面应用的轻量框架:~6 MB 的安装包里只有两个真实文件——一个基于 txiki.js 的后端运行时,和一个用 C++ 写的原生 WebView 启动器。两者之间不跑 HTTP、不开任何端口,而是通过一条位于私有临时目录中的 Unix Socket 管道,用极简的换行分隔协议高效协同。

tinyjs 桌面应用框架:6MB 的 txiki.js 后端加原生 WebView

三层架构:两个进程 + 一个网页

tinyjs 的架构可以概括成"两个进程、一条管道":

┌──────────────────────┐  Unix Socket  ┌──────────────────────────┐
│ 后端(txiki.js)      │◄────────────►│ 启动器(C++,~1–2 MB)   │
│ 你的 main.js          │  行协议        │ · WebView 窗口          │
│ + runtime/bridge.js   │               │ · 原生菜单/对话框/托盘   │
└──────────────────────┘               └──────────┬───────────────┘
                                                  │ 注入 window.__invoke / eval
                                        ┌──────────▼────────────┐
                                        │ 你的页面(file://)     │
                                        │ tiny.api.call(...)      │
                                        └────────────────────────┘
  • 后端进程:由 txiki.js 运行你的 src/backend/main.js,拥有完整的系统能力(文件、网络、进程、SQLite、FFI),并附带桥接库 runtime/bridge.js。
  • 启动器进程:平台相关的 C++ 程序(macOS 为 native/launcher-macos.cc、Windows 为 native/launcher-win.cc、Linux 为 native/launcher-linux.cc),负责开 WebView 窗口、渲染你的 index.html,以及一切原生 UI 操作。
  • 页面:纯 HTML/CSS/JS,被加载为真正的 file:// 文档——这样多文件前端和 WebGPU 这类需要安全上下文的 API 才能正常工作。

Tiny Deck:tinyjs 示例应用,前端跑 WebGPU 渲染、后端提供系统数据

上图是官方示例 Tiny Deck:左侧 GPU 面板由前端的 WebGPU 直接渲染,而顶部的系统时钟、CPU 负载等数据则来自后端——两者正是通过这条管道协同。

为什么选 Unix Socket,而不是起一个 HTTP 服务?

不少 Electron 之外的方案会让后端起一个本地 HTTP 服务、前端用 fetch('http://127.0.0.1:端口') 通信。tinyjs 刻意避开了这条路,原因写在 runtime/bridge.js 的开头注释里:"No network, no ports"。

  1. 零端口暴露:没有监听端口,就没有端口冲突,也没有被局域网扫描或本机其他进程误连的可能。
  2. 私有目录隔离:Socket 文件建在一个权限 0700 的全新临时目录里(runtime/bridge.js),其他用户根本无法访问,安全边界由文件系统直接保证。
  3. 协议极简:换行分隔的文本行 + JSON 载荷,无需 HTTP 头部、状态码、Content-Length 那一整套,调试时直接就能看到人话。
  4. 生命周期天然绑定:关窗即结束。窗口一关,启动器进程退出,后端检测到管道断开后自动清理退出——没有残留的僵尸服务。

在 runtime/bridge.js 中,后端用 tjs.listen('pipe', sockPath) 开始监听,随后把 Socket 路径作为命令行参数传给启动器(runtime/bridge.js)。启动器侧则是标准的 POSIX 流程:socket(AF_UNIX, SOCK_STREAM) → connect(),见 native/launcher-linux.cc。

一次 api.call() 的完整旅程

前端与后端的 RPC 协议只有几种行格式(完整定义见 runtime/bridge.js 的注释):

方向 行格式 含义
启动器 → 后端 CALL <id> <json-参数> 页面调用了 tiny.api.call(...)
后端 → 启动器 RET <id> 0 <json> 应答:resolve(状态 0)或 reject
后端 → 启动器 EVAL <js> 在页面里执行 JS(后端推送事件)
后端 → 启动器 TITLE / SIZE / DLG / QUIT 窗口标题、尺寸、原生对话框、退出

具体链路是这样的:

  1. 页面调用 await tiny.api.call('hello', { name: 'world' })。前端 shim 其实薄得惊人——核心就是 runtime/tiny.js 中的一行:window.__invoke(JSON.stringify({ method, params }))。
  2. 启动器收到消息后,拼成 CALL 42 ["hello",{"name":"world"}] 一行,写入 Socket。
  3. 后端 bridge 解析参数,调用你 export const api 里定义的 hello 函数。
  4. 后端回 RET 42 0 {"result":"hi world"},启动器用这个值 resolve 掉页面里那个 Promise。

启动器侧的读取循环非常朴素:一个专用线程不断 read() Socket,按 \n 切分完整行后派发到 UI 线程执行,见 native/launcher-linux.cc。而 tiny.js 整个客户端在构建时会被 native/gen-client.sh 内联为 C 字符串常量 TINY_CLIENT_JS,直接编译进每个启动器——所以页面上永远有 tiny 全局对象,无需任何 <script> 标签。

后端推送:让页面"活"起来

管道是双向的,后端不仅能应答,还能主动"推"。比如你在后端写:

export function init(app) {
  setInterval(() => app.push('tick', Date.now()), 1000);
}

页面侧用 tiny.api.on('tick', (t) => ...) 接收。push 经 EVAL 行抵达页面后调用 window.__emit 分发事件。像实时可视化、定时状态刷新、通知提醒这类场景全靠它。

amp:Winamp 风格桌面播放器,频谱可视化由后端推送的音频数据驱动

上图的 amp 示例就是一个典型:频谱数据来自后端的音频采样,每秒多次推送到页面,前端画布实时绘制——全部走这条私有管道,页面端只关心数据本身。

多窗口:同一条管道,按窗口寻址

tinyjs 支持一个后端服务多个 WebView 窗口。协议用 @<窗口id> 后缀做寻址:CMD@side 指定操作某个子窗口,裸的 CMD 则指主窗口(native/launcher-linux.cc 中的 peel_target 就是干这件事的)。后端可通过 app.openWindow() 开窗、app.window('id') 单独控制某窗口,页面侧的 tiny.win.* 则自动只作用于自己所在的窗口。

Nib:Markdown 编辑器,主窗口与弹出的"新文档"子窗口共享同一个后端

上图 Nib 编辑器里悬浮的"New Document"小窗,就是由主窗口通过 tiny.win.open() 打开的第二窗口——两个 WebView、一套后端、一条管道。

跨平台:同一套协议,三种传输

三端运行完全相同的 runtime 和协议,差异只在启动器实现和传输层(见 README.md 的 Portability 章节):

平台 启动器 WebView 传输层
macOS launcher-macos.cc WebKit Unix Socket
Linux launcher-linux.cc GTK3 + WebKitGTK 4.1 Unix Socket
Windows launcher-win.cc WebView2 命名管道 \\.\pipe\…

Windows 没有 Unix Socket,改用命名管道;由于 Windows 管道的默认权限允许任何用户只读连接,tinyjs 额外加了一道握手:启动器连接后必须先发送一行 HELLO <随机令牌>(令牌只存在于后端传给启动器的环境变量里),验证通过才放行——只读的连接永远发不出令牌,见 runtime/bridge.js。libuv 的 pipe 抽象统一了两种传输,后端代码一行都不用改。

安全设计:这条管道为什么可信

  • 0700 私有目录:Socket 文件对其他用户不可见,从文件系统层面挡住了本机攻击者。
  • 无网络面:不监听任何 TCP/UDP 端口,攻击面只有本机同用户进程。
  • 来源戳记:启动器在每条 CALL 末尾附上 WebKit 报告的真实来源(origin),后端的 API 能力门(tinyjs.json 的 "api" 字段)据此判断调用是否被允许——页面自报的身份不算数。
  • 失败即关闭:安全配置写错(如拼错的预设名)会拒绝一切访问并打印警告,而不是静默放行。

想深入源码?从这里开始

整套架构的智慧在于"克制":不引入微框架、不引入本地服务器、不把前端当服务端,只用操作系统早就提供的 Unix Socket 加几十行协议,就把一个完整桌面应用拆成了"有系统权限的后端"与"只画界面的前端"两个各司其职的进程。

登录后查看全文
tinyjsapp