wsh 架构
本页说明桌面应用各部分是如何相互通信的:Electron 主进程、界面渲染进程、wavesrv 后端进程,
以及在本地或远程主机上运行的 wsh 命令行工具。这是写给好奇的用户看的,不是逐行代码讲解——
wsh 面向用户的用法见 wsh 命令 和 wsh 参考手册。
四个组成部分
- Electron 主进程 —— 应用的原生外壳。它负责创建窗口、管理系统托盘和原生菜单,并启动其他
一切组件。它从不直接与你的 shell 或 SSH 主机通信,这部分工作全部交给
wavesrv。 - 渲染进程 —— 每个窗口内的网页,也就是你实际操作的 React 界面(标签页、分栏、小组件、 终端视图本身)。它无法直接访问文件系统或进程,任何操作都要通过下面的某条通道发出。
- wavesrv —— 一个 Go 进程,Electron 主进程在每次启动时把它作为子进程拉起。它持有本地
SQLite 数据库、你的终端会话、SSH/WSL 连接,以及所有其他部分都要接入的 RPC 路由器。如果
wavesrv退出,应用会自行关闭(没有无头恢复机制)。 - wsh —— 可以在任意终端分栏里运行的命令行工具(
cmd/wsh)。无论终端是本地的还是远程主机 上的,它都是同一套 RPC 系统的一个轻量客户端。
Electron main --spawns--> wavesrv (Go)
| | \
(native OS calls) SQLite RPC router
| | \
Renderer <--WebSocket/HTTP--+ wsh (local or remote)
渲染进程如何连接 wavesrv
渲染进程从不直接打开原始套接字,而是使用两条通道,且认证方式相同:
/wave/service(HTTP) —— 用于请求/响应式调用的单一端点:创建标签页、更新某个设置、 移动一个分栏。服务端通过反射派发这些调用,根据服务名和方法名(pkg/service/service.go) 找到并调用对应的 Go 函数。前端的WOS.callBackendService(...)最终打到的就是这里。/ws?tabid=<id>(WebSocket) —— 每个标签页一条的长连接,用于处理所有非请求/响应式的 内容:对象(标签页、分栏、工作区)的实时更新、终端输出、进程事件。前端通过wpsSubscribeToObject()订阅具体对象,更新发生时会被主动推送,而不是靠轮询获取。
认证方式。 应用每次启动时,Electron 主进程都会在内存中生成一个随机密钥,并通过
TERMIA_AUTH_KEY 环境变量传给 wavesrv。随后它会悄悄把同一个值作为 X-AuthKey 请求头,
附加在渲染进程发往 wavesrv 的每一次 HTTP 和 WebSocket 请求上。wavesrv 会拒绝任何没有匹配
请求头的连接。由于这个密钥是每次运行时新生成的,且只在你机器上的这两个进程之间共享,所以你
应用之外的任何东西都无法连进 wavesrv。
wavesrv 一旦就绪就会打印出它的监听地址(包含 WAVESRV-ESTART 字样的一行);Electron
主进程解析这一行,从而在加载页面之前知道该把渲染进程指向哪个本地端口。
推送更新从哪里来。 wavesrv 内部有一个小型发布/订阅广播器,后端的任何组件都可以向它
投递事件——某个对象发生变化、某个终端产生了输出、某个连接的状态发生了翻转。广播器会把每个
事件与订阅了该类事件的路由 id 做匹配,再交给下面会提到的同一个 RPC 路由器,由它经 WebSocket
连接推送给对应标签页。这就是为什么前端的对象订阅感觉是"实时"的——它并不是在轮询
wavesrv,而是守在一条已经打开的连接上等通知。
wsh RPC 层
在 wavesrv 内部,所有后端功能都以 RPC 命令的形式暴露(完整列表在
pkg/wshrpc/wshrpctypes.go),并由一个按路由 id 分流的路由器统一派发——比如某个具体
SSH/WSL 连接对应 conn:<connection-name>,某个正在运行的分栏背后的进程对应
controller:<blockId>,某个标签页对应 tab:<tabId>。任何能持有一条 RPC 连接的对象——渲染
进程、终端分栏的控制器,或是一个 wsh 进程——都会在某个路由 id 下注册自己,路由器再把消息
转发给对应的路由。不管调用方是界面本身还是你手动敲的一条 wsh 命令,走的都是同一套机制。
本机上的 wsh
在本地终端分栏里运行 wsh 时,它会连接应用数据目录下一个名为 wave.sock 的 Unix 域套接字
(各平台的具体路径见 emain/platform.ts),并用 wavesrv 在启动这个 shell 时发给它的一枚
签名令牌进行认证。这枚令牌同时携带了路由上下文——它属于哪个分栏、哪个标签页——所以路由器
无需你指定就知道该把命令的响应发到哪里。
如果某个终端还拿不到这样的令牌(比如 shell 启动的最早阶段),wsh 可以退回到直接在终端
数据流里打印 OSC 转义序列的方式通信;wavesrv 和终端渲染层会在显示输出前识别并剥离这些
序列。这条路径主要是作为一种引导机制存在。
远程主机上的 wsh(通过 SSH)
连接远程主机时,wavesrv 不只是通过 SSH 打开一个 shell——它还会额外建立一条专门给 wsh
用的通道,好让远程分栏(编辑器、文件预览、小组件)具备和本地分栏一样的能力:
wavesrv请求 SSH 连接把一个 Unix 域套接字转发回自己 (streamlocal-forward@openssh.com)。这一步只有在 SSH 服务端允许的情况下才能成功; 见下文的"常见故障点"。- 它检查远程主机上
~/.termia/bin/wsh是否已经存在兼容版本。如果缺失或过旧,wavesrv会把适配该远程操作系统/架构的正确二进制文件拷贝过去并赋予可执行权限——根据你的连接设置, 这一步可能会弹出一次性的授权提示。 wavesrv通过同一个 SSH 会话在远程主机上启动wsh connserver。这是一个体量很小的常驻 辅助进程,并不是wavesrv的完整副本——它只负责在远程主机和第 1 步打开的套接字之间 中转 RPC 流量。- connserver 用和本地
wsh相同的方式完成认证(一枚签名令牌,通过 SSH 标准输入而不是 网络请求送达),随后路由器把它注册到conn:<connection-name>这个路由下。从此以后,你 在该连接上的分栏里做的任何事——打开文件、运行wsh命令、预览图片——都走这同一条转发 套接字,而不会再新开 SSH 会话。
如果 wsh 无法安装,或者套接字无法转发,连接依然可以作为一个普通的 SSH 终端使用;你只是
失去了依赖 wsh 的那些额外能力(文件预览、远程编辑、远程小组件,以及该主机上的 wsh
命令行本身)。
Shell 集成
不论本地还是远程,打开一个新 shell 时都会加载一小段启动脚本(针对你使用的 shell 分别准备了
bash、zsh、fish、PowerShell 版本)。这段脚本做几件事:把对应平台的 wsh 二进制加入
PATH、设置合理的 UTF-8 locale 默认值、发出让应用追踪当前工作目录的转义序列,并且用一枚
一次性令牌(通过 TERMIA_SWAPTOKEN 环境变量传入)换取你这次真实会话的环境变量和额外的
初始化脚本——这就是终端能拿到诸如按连接区分的环境变量、而不会让系统上其他进程看到这些变量
的原理。
常见故障点
- SSH 服务端屏蔽了套接字转发。 如果远程
sshd关闭了AllowStreamLocalForwarding(或更宽泛的AllowTcpForwarding),wavesrv就无法打开上面说的转发套接字。SSH 终端 会话本身依然可用,只是依赖wsh的功能用不了。 - 远程
wsh无法安装或版本过旧。 如果拷贝步骤失败(没有写权限、系统/架构不受支持,或 你拒绝了安装提示),wavesrv会退回为纯 SSH 会话。 - 升级之后本地
wsh版本滞后。 应用数据目录里的本地二进制会随应用版本自动保持同步; 远程主机只有在重新连接时才会拿到更新后的wsh,因为安装动作只在每次建立连接时执行一次。