Skip to content
JINGHAN YU edited this page Nov 9, 2026 · 11 revisions

WebUI 是 weflow serve 的网页界面(#130),本页说明它的托管、版本管理和内部结构,各页面的功能和用法见 WebUI 使用。代码位于 web/,开发环境见 web/README.zh-CN.md。

网页

serve 在 /ui/ 下提供网页。使用哪个网页由以下规则依次决定:

  1. 加 --api-only 时不提供网页。
  2. --ui-dir 指定的目录,只对本次运行有效;目录中没有 index.html 时启动报错。
  3. --web-version 指定的版本,只对本次运行有效,需要时先下载。
  4. weflow web use 选定的版本;没有选定时,使用这个 weflow 的默认版本,即构建时 web/package.json 中的版本。二进制中只记录版本号,不含网页本身。

第 4 种情况下版本还没下载时,服务立刻启动,先用本机已有的、适用的最新版本,没有就只提供 API,同时在后台下载。下载完成后发出事件 webui_ready,失败时发出 webui_unavailable,已有的版本保持不变。

本机已有但不适用于这个 weflow 的版本(例如由更新的 weflow 下载的)不会显示。选定的版本不适用时,服务端给出警告并改用本机其他适用的版本;本机没有其他适用版本时,下载这个 weflow 的默认版本,与没有选定过时相同(#635)。

令牌

有网页时,启动提示给出带令牌的地址 http://127.0.0.1:18108/ui/?token=…(带 --json 时为 uiUrl),令牌经过百分号编码。stderr 是终端时,服务端会打开浏览器,--no-browser 可以关闭。

网页把令牌存在当前标签页的 sessionStorage 中,并从地址栏去掉。令牌不写入 localStorage,也不进入构建产物。收到 HTTP 401 时提示重新输入。

静态文件的规则

路径 行为
/ui 308 跳转到 /ui/
/ 有网页时 302 跳转到 /ui/,查询参数保留
/ui/chat 等无扩展名路径 不是文件时返回 index.html,由网页处理
带扩展名的文件或 /ui/assets/ 下的文件不存在 404
/ui/ 以外的未知路径 JSON 格式的 404
.. 和指向目录外的链接 404

网页的文件不需要令牌,但 Host 检查照样进行,只响应 GET 和 HEAD。

构建出的资源(/ui/assets/,文件名随内容变化)长期缓存。index.html 等文件带 Cache-Control: no-cache,所以新版本立刻生效。所有文件带 X-Content-Type-Options: nosniff,网页还带 Referrer-Policy: no-referrer。

网页的版本

网页和 weflow 分开发布(#148),作为 OCI artifact 发布在 ghcr.io/334456777/weflow-web:<版本>,由 weflow 自己下载,不需要 Docker、ORAS、Bun 或 Node.js。没有网页时 CLI 和 API 照常使用。发布流程见发布与 CI。

命令 作用
web info 正在使用的版本、选定的版本、默认版本、本机已有的版本
web list [--remote] 本机已有的版本;--remote 列出已发布的版本及其是否适用
web install <版本> 下载并校验
web use <版本> 选定 serve 显示的版本
web update 下载并选定适用的最新版本,正式版优先于预发布版
web prune 删除既没有选定、也不是默认版本的版本;正在显示的版本保留

适用条件。 版本需要的 API 正是这个 weflow 提供的(/health 的 apiVersion),并且它要求的最低 weflow 版本不高于这个 weflow。manifest 中写有这两项,不适用的版本在下载前就被拒绝;下载后、每次安装、选定或显示时都会再次检查。

切换。 网页跟随选定的版本时,通过服务端自己的 API 发出的 web use 或 web update 立刻生效,不用重启,刷新网页后就是新版本。在终端里运行的,下次启动才生效。

校验(webui.rs)。

  • 下载内容必须与 manifest 给出的大小和 SHA-256 一致。
  • 在限制下解压到单独的目录:压缩包最大 64 MB,解压后最多 256 MB、10,000 个文件,不允许指向目录外的路径和链接。
  • 检查 index.html、元数据和版本之后,用一次重命名放到正式位置。
  • 下载失败、损坏或中断时,已有的版本保持不变;同时下载同一版本时只保留一份。

存放。 版本保存在 <home>/cache/web/<版本>/,选定的版本记在 <home>/cache/web/current。正在运行的 serve 对显示的版本持有 .lock-<版本> 的共享锁,web prune 删除前检查这个锁,服务无论以什么方式结束,锁都会释放。

访问仓库的方式遵循 OCI Distribution API,WEFLOW_WEB_REGISTRY 可以指定其他仓库。

内部结构

技术栈

项目 选择
框架 React 19、TypeScript
构建 Vite
包管理与脚本 Bun,不需要 Node.js(#359、#364)
测试 bun test 和 happy-dom(#361)
图标 Phosphor,只保留用到的粗细

目录

路径 内容
src/api/ 调用命令 API,每个领域一个文件;contract.gen.ts 由契约生成
src/shell/ 侧栏、连接状态、预览对话框、页面路由
src/chat/、moments/、payments/、contacts/、resources/、analytics/、reports/、footprint/、insights/、exports/、backup/、settings/ 各功能页
src/jobs/ 后台任务,各页共用
src/calendar/ 网页自己的日历(#224):单月视图、选择日期范围和单个日期,日期用本地时间的 YYYY-MM-DD 表示
src/i18n/ 界面语言
src/mock/ 未连接服务时显示的示例记录
src/styles/tokens.css 设计令牌
plugins/ Vite 插件:包体积上限、图标粗细、版本元数据
scripts/ 开发服务器、契约生成、i18n 检查

请求与状态

src/api/client.ts 是所有调用的入口,call 返回 data 或抛出 ApiError(含状态码、错误码和 details)。能走 /api/ 的读取都走进程内路由(#413)。图片、语音和视频用媒体元素直接请求,令牌放在 access_token 查询参数中。

useRead。 把一次读取表示为 loading、ready 或 error。键变化时重新读取,并通过 AbortController 取消上一次请求。

keptRead。 用于多个视图共享、只随服务端和账号变化的读取,例如联系人列表(#402)。同时请求的视图共享一个请求,重新打开视图时直接取得结果,失败的结果不保留。视图离开时不取消请求,因为其他视图可能在等待。

账号隔离

页面保存的记录属于特定的服务端和账号。api/scope.ts 管理当前的作用域(#198):

  • /health/events 的 data 在每次启动 weflow serve、每次配置变化时都会改变。
  • data 变化或服务端失联后恢复时,开始新的作用域。
  • 新作用域开始时清空所有保存的内容,旧作用域请求的结果不再保留。

连接状态与实时消息

网页只保持一条事件流(#221),并据此显示连接状态:

  • 流一断开,指示立刻变为「未连接」,然后按 1、2、4 秒直到最长 30 秒的间隔重连,上下浮动五分之一。
  • 网络恢复、切回标签页或点「重新检测」时立即重连。
  • 空闲时不发任何请求。
  • 网页和服务在同一台机器上时,断网不会切断两者的连接,所以只立即重新确认一次,不直接变红。

打开「实时消息」时(默认打开),网页改为保持 /api/push/messages 这条流,左下角显示「实时」。收到消息事件后重新读取会话列表和打开的会话从最后一条消息往后的部分;撤回或断线恢复时还重读最新的一页。

后台任务

jobs/useJobs.ts 被所有页面共用(#211)。服务端默认一次只运行一个任务,网页最多打开一条事件流,跟随第一个运行中的任务。其余任务(排队中的,以及 --max-tasks 调大后同时运行的)通过每 2 秒重新读取列表观察。

性能

  • VirtualList 只渲染可见的行(#159):行高固定,绝对定位在一个与全部内容等高的容器中,几千个会话滚动时不会产生几千个元素。
  • plugins/sizeBudget.ts 限制首屏需要加载的 JavaScript:700 kB,gzip 后 200 kB,超出时构建失败。
  • 英文翻译是单独的 chunk,需要英文时才下载。
  • 聊天窗口使用游标分页,列表请求用 fields 只取需要的键。

语言

界面跟随服务端的语言(#439):

  • 文字以中文原文作键:t('…')。
  • 英文在 src/i18n/en.ts,变量写 {name},英文的计数写 {n|one|other}。
  • 模块顶层的标签用 msg() 标出,显示时再 t()。
  • 日期和星期用 formatDate、relativeDay,基于 Intl。
  • bun run i18n --check 在 CI 中检查缺失和多余的英文。
  • 读取的数据中的中文写 // i18n-ignore: <原因>。

设计语言

界面使用新拟态(Neumorphism)风格(#191、#220):表面同色,靠凸起和凹陷的阴影区分层次。

  • 字号、控件高度、圆角等写成设计令牌,集中在 styles/tokens.css(#192)。
  • 时长和缓动也在令牌中,脚本从那里读取,所以「减少动画」开关和 prefers-reduced-motion 对脚本同样生效(#193)。
  • HoverTrack 实现悬停凹陷的平移:指针移到另一个可点击元素时,凹陷从上一个位置滑过去(#232)。
  • roving.ts 实现列表的键盘焦点移动(#195)。
  • 手机布局有返回按钮、底部导航和全屏会话(#335)。

示例数据

src/mock/ 是未连接服务时显示的示例记录,用于聊天、朋友圈、支付列表和控制台,并标明是示例。令牌错误或仍在检测连接时不显示。

测试

  • src/api/contract.test.ts 把 weflow-cli 生成的 contract/samples.json 交给网页自己的代码,验证读取和显示,见服务端实现。
  • web.yml 在 web/ 变动时运行契约检查、兼容性检查、i18n 检查、类型检查、测试和构建。
  • bun run dev 同时启动 Vite 和读合成账号的 weflow serve,WEFLOW_DEV_ACCOUNT=bench 改用规模接近真实的基准账号。

Clone this wiki locally