跳到主要内容

wsh 架构

本页说明桌面应用各部分是如何相互通信的:Electron 主进程、界面渲染进程、wavesrv 后端进程, 以及在本地或远程主机上运行的 wsh 命令行工具。这是写给好奇的用户看的,不是逐行代码讲解—— wsh 面向用户的用法见 wsh 命令 和 wsh 参考手册。

四个组成部分​

架构示意:Electron 与本机 wavesrv 通信,由后端路由到本机或远端 wsh。
架构示意:Electron 与本机 wavesrv 通信,由后端路由到本机或远端 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 用的通道,好让远程分栏(编辑器、文件预览、小组件)具备和本地分栏一样的能力:

  1. wavesrv 请求 SSH 连接把一个 Unix 域套接字转发回自己 (streamlocal-forward@openssh.com)。这一步只有在 SSH 服务端允许的情况下才能成功; 见下文的"常见故障点"。
  2. 它检查远程主机上 ~/.termia/bin/wsh 是否已经存在兼容版本。如果缺失或过旧,wavesrv 会把适配该远程操作系统/架构的正确二进制文件拷贝过去并赋予可执行权限——根据你的连接设置, 这一步可能会弹出一次性的授权提示。
  3. wavesrv 通过同一个 SSH 会话在远程主机上启动 wsh connserver。这是一个体量很小的常驻 辅助进程,并不是 wavesrv 的完整副本——它只负责在远程主机和第 1 步打开的套接字之间 中转 RPC 流量。
  4. 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,因为安装动作只在每次建立连接时执行一次。