Skip to content

WebUI.zh cn

C-F0x edited this page Oct 26, 2026 · 1 revision

WebUI

WebUI 是 CompileGateway 的浏览器入口:一个 React + Fluent UI 单页应用,由 daemon 在自己的 HTTP 端口上提供,除了本页末尾列出的那几项"给机器用"的能力之外,与 CLI 等价。

WebUI 是什么

  • 它是用 Vite 从 webui-src 构建到 webui/dist 的单页应用,产物在编译期嵌进二进制(rust-embed,src/server.rs)。运行时不需要 node_modules,也不需要另装一个 Web 服务器:静态页面和资源都由 daemon 自己发。
  • 打开 http://<主机>:<端口>/。这个地址就是 daemon 启动时打出来的那个,也写在 GET /api/status 里;port: 0 时由系统挑一个空闲端口,真实端口记在 runtime.json。
  • 同一个 daemon、同一套 API。命令行 和 MCP 打的是完全相同的接口,所以从这里发起的任务和别处发起的没有区别 —— 项目锁和 job 记录都一样。
  • 页面语言跟着服务端走:config.json 的 language(auto / zh-Hans / en-US)决定加载哪份文案表,在配置页改完整个页面立刻跟着换。
  • 操作按钮一律是图标 + Tooltip;下面凡是引号里的文字都是界面上的真实文案。

界面骨架

  • 左侧边栏五项:状态、配置、客户机、构建类型、工作流。进入实例视图后,顶部一条客户机芯片同样能换机器,不必先返回列表。
  • 侧边栏底部显示版本和本页的访问地址;需要登录且已登录时多一个 退出登录。
  • 首次 /api/status 还没回来时整页只有一个转圈;这个请求失败就没有半成品页面,直接显示 加载失败:{msg}。
  • 导航、页签、客户机芯片都保留文字;操作按钮只有图标,靠悬停看 Tooltip。

打开页面与登录

请求来自哪里 会发生什么
本机(回环 127.0.0.1 / ::1) 一律放行,即使设置了凭据也不出登录页。
其他设备,未设置凭据 同样放行;lan / wan 都不强制要求凭据。
其他设备,已设置凭据 先出登录页:用户名、密码、确定。POST /api/login 成功后下发会话 Cookie(HttpOnly,12 小时)。
同一来源 IP 登录太频繁 429;页面显示 尝试过于频繁,请在 {s} 秒后重试。
从其他设备改凭据 用户名 / 密码 两个输入框被禁用,并提示 访问凭据只允许在本机(127.0.0.1)修改。
  • lan 与 wan。 监听模式 选 lan — 仅本机访问 (localhost / 127.0.0.1) 时只绑 127.0.0.1;选 wan — 允许其他设备访问 (本机IP:端口) 时绑 0.0.0.0,别的设备可以用 本机IP:端口 打开。
  • wan 的警告是常驻的。 wan 且没设凭据时,每页顶部都有一条黄色横幅 安全警告,直到设好凭据为止;/api/status 把同一件事报成 warning: "wanWithoutAuth"。
  • 登录限流按来源 IP 独立计算。 登录限流间隔(秒)(即 auth.loginIntervalSeconds)是同一来源 IP 两次尝试之间的最小间隔;0 = 不限流,上限 86400。
  • 没有"忘记密码"流程。 凭据只在本机免登录状态下修改,所以别的设备不可能靠重置密码把这个 daemon 拿走。
  • 页面总能打开,数据不总能拿到。 静态资源(/、JS 包、样式)刻意不鉴权 —— 登录页本身必须先能加载;而所有 /api/* 都鉴权,所以未登录的人只看得到一层空壳。
  • 放在反向代理后面时,daemon 看到的来源地址永远是代理那台机器:所有外部用户共用一个限流桶,而且经过代理一定改不了凭据(返回 authLocalOnly,这是设计如此)。请转发 X-Forwarded-Proto: https,这样会话 Cookie 才会带上 Secure;daemon 不信任 X-Forwarded-For。详见 配置与日志。
  • 页面几乎不存状态:刷新会重新读 /api/status、/api/config、/api/clients、/api/projects,任何 /api/* 返回 401 都会把浏览器带回登录页。

状态页

只读的运行信息,每个值都来自 /api/status:

行 显示什么
版本 程序名与版本号。
访问地址 这个 WebUI 所在的地址。
监听端口 实际绑定的端口。
监听模式 lan — 仅本机访问 (localhost / 127.0.0.1) 或 wan — 允许其他设备访问 (本机IP:端口)。
语言 auto、zh-Hans 或 en-US。
访问凭据 用户名加 已设置,或 未设置。
其他设备 是 / 否 —— 当前请求是不是来自回环以外的地址。
MCP(AI agent) 生效中的端点加 N 个工具,或 配置里开着,但没在监听(端口可能被占用)。,或 已关闭。
配置文件 config.json 在哪里。

这一页没有任何按钮,也没有列表:项目、任务和 job 历史都在 客户机 → 某台客户机 → 项目 下面。

客户机页

客户机 管理所有 SSH 目标机(clients.json,和 config.json 同目录)。

  • 搜索匹配 名称 / IP / 端口 / 标签,支持部分匹配与正则;正则语法不合法时退回普通包含判断。
  • 浏览态是一行一张卡片,不带任何操作按钮;点卡片本身进入这台机器的实例视图(点击卡片打开这台实例)。
  • 编辑 让所有客户机一起进入可编辑状态。此时工具栏变成 新增客户机 + 搜索框 + 完成;点 完成 把新增、修改、删除一次性提交。
  • 单台字段:名称、IP 地址、端口(默认 22)、验证方式、标签、基准目录,以及单机独占选项 同一台客户机一次只跑一个任务(开启后该客户机上的多项目任务严格串行排队)。
  • 验证方式 二选一:登录信息(用户名 + 密码)或 密钥文件(用户名 + 路径,选择… / 选择私钥文件 弹的是 daemon 那台机器上的文件选择框),后者还有 密钥口令。
  • 密钥只写不读。 接口从不回传密码或口令原文,所以输入框留空 = 不改已保存的值(留空则不修改)。删除 会先问 确定删除这台客户机?,然后只把卡片从草稿里去掉;直到点 完成 整体提交才真正落盘。
  • 标签 完全自定义:每个标签右上角有关闭按钮,最右边有 新建标签 加号。
  • 测试连接 和主机指纹不在这一页。 它们在实例视图里,因为测试会真的开一次 SSH,结果属于那台机器的日志。

实例页

点开一台客户机就是它的实例视图:顶部一条客户机芯片(不用回列表就能换机器),标题是客户机名与 主机:端口 · 验证方式,右上角有 测试连接 和 返回列表。下面是四个页签。

状态 页签

  • 连接信息:IP 地址、端口、验证方式、标签、主机密钥。
  • 基准目录 —— 这台机器上放源码 / 产物的根。保存并校验 会真的连上去跑 mkdir -p 再取回 pwd:成功就把解析后的绝对路径记下来,显示在 远程落点 一行;失败一律不落盘,并把远端报错原样显示。
  • 记录的主机指纹(TOFU)。 首次连接成功时记下的指纹会显示出来;之后指纹变了就拒绝连接,直到你明确决定。
    • 清除记录:清掉记录,下次连接按首次信任重新处理。
    • 从 known_hosts 导入:在 daemon 那台机器上挑一份 known_hosts,不用先连一次就认领对应的钥匙。@revoked 的、CA 的、同一台机器有好几把钥匙的都会被拒绝并说明原因。
    • 导出 known_hosts 行:导出一行标准 known_hosts,可以直接追加进 ~/.ssh/known_hosts;这需要记录里有公钥原文,只有指纹时页面会如实说明。
    • 测试连接 撞到指纹不一致时会弹出标题为 主机指纹和记录的不一样 的对话框,把记录值和新值并排摆出来,确认入口是 信任这个新指纹。这是一次需要判断的信任动作,不是重试。

环境 页签

  • 检测目标机环境 用一次 SSH 会话跑完全部探针(90 秒超时)。在那之前页面只读服务端缓存,并显示 还没检测过。点上面的按钮连上去查一次。
  • 结果按平台分组(xcode / gradle / flutter / dart / rust / common),每项给出自己的版本,或者 缺失;工具在但读不出版本时显示 有,但读不出版本。一组里一个都没命中会标成 全部缺失。
  • 磁盘 显示可用 / 总量、已用百分比和挂载点。
  • Xcode 实例 逐个列出 /Applications/Xcode*.app,带各自的版本号与 Build、许可徽标(许可已接受 / 许可未接受),以及 构建时 DEVELOPER_DIR=<dir> —— 构建任务可以按次传它,不必改目标机的全局 xcode-select。

日志 页签

  • 一个终端样式的面板,显示这台客户机的日志域。面板固定深色是刻意的:它是日志面,不是普通卡片。
  • 日志范围 在 实时(内存里最近 4000 条,每 1.5 秒刷新,增量拉取)和某一天的落盘历史之间切换(YYYY-MM-DD 文件,标题列从上往下是时间 / 来源 / 日志域)。
  • 来源复选框初始是 全部来源 加 webui、cli、mcp,实际出现过的其他来源会自动补进来;被隐藏的行会提示 已隐藏 {n} 条。
  • 测试连接 的结果、构建输出、以及和主机指纹有关的安全动作,都写到这里。

项目卡片(在实例页里)

项目 列出登记在这台客户机上的宿主机源码目录:每张卡片有 名称、宿主机目录、远程落点,另有两行元信息 —— 排除、最近同步(或 尚未同步),以及 产物、构建于(或 还没构建过)。导入项目文件夹 打开 daemon 侧的目录选择框(GET /api/browse)登记一个目录;移除登记不会删除任何文件。

卡片操作(都是图标 + Tooltip):

操作 做什么
新增构建任务 打开任务对话框新建一个任务。
项目文件树 只读地看客户机侧和宿主机侧的文件树。
推送源码 tar over SSH 把源码推上去;确认框里带 先清空远程目录(覆写)(默认关,意思是"同名覆盖,远端多出来的保留")。
拉取 把远端目录拉回宿主托管目录。
导出压缩包 打包并下载的对话框(见下)。
删除 只移除这条登记。
  • 文件树。 对话框有 客户机 / 宿主 两个页签、上一层、可点的面包屑和 根目录。每一行都能复制相对路径(复制相对路径(文件任务里直接填它));文件点开是受控预览(二进制只报大小和时间,过长的内容只显示前面一段),符号链接带 符号链接 徽标,用当前路径新建文件任务 会用当前目录预填一个 copy / move / delete / export 任务。路径一律相对项目根;.. 和绝对路径在保存阶段就被拒。
  • 导出压缩包。 对话框上半是 已有的压缩包(名字、大小、时间,各带一个 下载 链接),并显示 目录(宿主侧的 exports/);下半新建一个:客户机 / 宿主 单选、要打包的路径(默认取最近一次构建产物)、输出文件名(留空 = <项目名>-<unix 时间戳>.zip),最后 开始导出。
  • job 状态条。 有 job 占着这个项目时,卡片上会出现转圈、类型徽标、标题、已运行 {s} 秒,以及取消按钮(取消任务,确认文案是 取消这个任务?远端命令会断开连接。)。此时同一个项目再起一个 job 会被 daemon 拒绝(projectBusy),直到前一个结束。
  • 结果横幅。 job 结束后卡片显示结果(完成 / 失败 / 已取消,以及退出码)、一句 构建输出已写入这台客户机的日志页。,多步任务还会逐步列出一行。若有步骤失败,会出现按钮 从第 N 步重试,按 job 里记录下来的输入快照从失败那一步继续。
  • 构建任务。 每行显示任务名、类型徽标(构建 / 推送 / 拉取 / 复制 / 剪切 / 删除 / 导出)、构建任务的 签名 / 不签名 徽标,以及该类型的关键字段(构建:manifest、变量、产物路径;文件任务:来源 → 目标 与覆盖标记)。行内操作:执行构建、预览命令(标题为 将要执行的命令 的对话框,带 复制)、加入批量工作流、编辑 JSON 参数(直接编辑任务对象原文,和 cgw tasks save --body 等价)、编辑构建任务、删除。破坏性类型会先确认并写明具体路径(这是删除任务:目标 <路径> 会被直接删掉,不能撤销。,move 与开覆盖的 copy 类似)。
  • 任务对话框 承载全部七种类型:先选类型,再只显示相关字段 —— 来源、目标、要删除的路径、来源列表 与 添加来源、路径(相对路径,不能写 .. 或绝对路径)、输出文件名、签名模式(签名 / 不签名)、产物路径、产物列表、使用哪个 Xcode。从文件树里选 可以从项目文件树里挑一个路径。
  • 批量工作流。 一条 batch 是有序的任务引用列表。行里显示名称、{n} 步 和任务名连成的链路;操作是 执行批量工作流、编辑批量工作流、编辑 JSON 参数、删除。对话框提供 名称、添加步骤、上移、下移;步骤按顺序执行,任意一步失败就停下、后续记为 skipped。步骤级变量(steps[].variables)目前只有 编辑 JSON 参数 能写。
  • 最近任务。 卡片区下方列出这台客户机最近几条 job:标题、类型、状态(执行中 / 完成 / 失败 / 已取消)、已运行时间、消息,以及有失败步骤可续跑时的重试按钮。

构建类型页

构建类型 就是 manifest 编辑器;每种构建类型由一份 manifest/<id>.json 完整定义。

  • 从磁盘刷新 是 WebUI 上唯一一个需要手动点的地方,原因很实在:那些 JSON 是你的文件,你在编辑器里改了、用 git 拉了一份、或让别的工具写了文件,daemon 都看不到。刷新会重读目录并告诉你新增 / 变化 / 删除了什么。
  • 补齐缺失模板 只在一份自带模板从磁盘上消失时出现,而且只写回不存在的那几份,你改过的一律不碰。
  • 新建 manifest 会问 新 manifest 的文件名(id),然后用一份起始模板建文件;id 撞车时先问一遍(这个构建类型已经有了)。
  • 每张卡片显示:显示名、platform、自带同名时的 随程序附带 徽标、id、include.paths、步骤、产物、缓存、变量;校验不过的文件会在卡片上列出错误。
  • 操作:编辑 manifest(原始 JSON 文本域,配 格式化、取消、保存;保存前服务端会校验并把问题逐条列出来)、导出 JSON(浏览器下载 <id>.json)、删除 manifest。
  • 探测。 顶部输入框填一个宿主机目录,点 探测 会告诉你有哪几种构建类型命中,并列出 命中: 的路径与 缺少: 的路径。一份 manifest 的 include.paths 必须全部存在才算命中。

工作流模板页

工作流 承载跨项目工作流模板(workflows/<id>.json)的集中管理与参数化实例化:

  • 模板库浏览: 卡片直观展示模板名称、ID 徽标、说明、定义的输入参数数量、包含任务数以及步骤执行链路。
  • 模板操作:
    • 新建模板: 输入模板 ID, 基于骨架模版生成新流水线定义;
    • 从磁盘刷新: 手动重读 workflows/ 目录, 同步外部编辑变动;
    • 补齐缺失模板: 自动恢复被误删的内置官方模板;
    • 编辑 JSON: 原始 JSON 文本域, 配备自动格式化与服务端即时合法性校验;
    • 导出 JSON: 浏览器下载 <id>.json;
    • 删除模板: 经确认后从磁盘移除模板定义(不影响已实例化的目标项目)。
  • 应用到项目 (Apply) 对话框:
    • 选择目标项目(下拉列表聚合全部登记项目);
    • 动态参数表单: 自动根据模板内 variables 提取输入框, 标示必填项并预填默认值;
    • 变更预检(Preview): 服务端预演返回将要生成的任务列表、确定的批量工作流 ID(wf-<模板 id>)以及名称冲突清单;
    • 冲突覆盖开关: 若目标项目已存在同名任务或 Batch, 可勾选 覆盖同名任务与工作流 完成安全替换;
    • 点击 确认应用: 提交后在目标项目内即时生成任务与批量流水线。

配置页

顶部那张卡片是通用设置:

字段 说明
监听端口 0 = 自动挑选一个空闲端口。写死的端口被占用时直接报错,不重试。
语言 auto / zh-Hans / en-US;页面跟着它走。
监听模式 lan 或 wan;标着 需要重启程序才生效。
登录限流间隔(秒) 0 = 不限流,上限 86400。
日志保留天数 超过天数的按天日志文件会被删掉;默认 7,上限 3650。
日志目录 只读:每日文件放在哪里。
额外允许的宿主目录 每行一个绝对路径。浏览目录、登记项目、按目录探测构建类型共用这一套。
同一台客户机一次只跑一个任务 即 hostLock,默认关。打开后同一台客户机上的另一个项目会拿到 hostBusy,而不是并行跑。
用户名、密码、清除已保存的密码 访问凭据;不是本机来源时禁用。
  • 保存 的结果是 已保存。 或 已保存。端口和监听模式的改动需要重启程序才生效。
  • MCP(AI agent) 单独一张卡片,因为它的行为不同:启用 MCP、MCP 监听范围、MCP 端口、只读的 当前生效 一行,以及 客户端填这个地址 配 复制地址。它跑在自己的端口上(默认 3994,0 = 自动挑),和 WebUI 那个端口互不干扰,而且 MCP 这几项改完立即生效,不用重启。 端口绑不上会当场报错,并且原来那个能用的端口继续服务。
  • 这里会出现的提示:MCP 监听在 wan 且没设凭据时的提醒、默认 MCP 端口被迫让位时的说明,以及页面顶部那条常驻的 wan 安全警告。

CLI 窗口里的实时日志区 vs WebUI 的 日志 页

桌面本体 compilegateway 是一个独立的终端样式窗口:上半屏滚日志、下半屏是输入框,另有 diag <名称> 可以给某台客户机单独开一个窗口。那个日志区是"本地、永远都在"的视角 —— 端口被占用、HTTP 服务根本没起来时,它照样要能显示,而那正是最需要看日志的时候。WebUI 的 日志 页签则是通过 HTTP 看同一个 daemon 的远端视角:它锁定在一台客户机上,能在实时尾巴和任意一天的落盘历史之间切换,还能按来源筛选。想知道"服务到底起没起来"看窗口;想事后查某台目标机的构建输出看 日志 页签。日志文件本身见 配置与日志。

WebUI 不做的事

有一项能力刻意只留给 CLI / HTTP / MCP,因为它是给机器用的,不是给人点的:

  • JSON Schema。 cgw schema [名称] 与 GET /api/schema/{名称} 返回 manifest、task、batch、client、project、workflow 六份 draft-07 schema,另有 MCP 资源 cgw://schema/<名称>。WebUI 上没有 schema 查看页。

两点相关事实:

  • manifest/ 与 workflows/ 目录没有文件监听;页面上的 从磁盘刷新 就是那个显式刷新事件,等价于 cgw manifests refresh 与 cgw workflows refresh。
  • 原生选择框都在 daemon 侧:选择…、导入项目文件夹、从 known_hosts 导入 列的都是 daemon 那台机器上的文件(/api/browse、/api/dialog/pick-file、/api/dialog/pick-folder),不是"打开网页那台设备"上的。

哪一页解决哪个问题

想做的事 去哪里
看版本、端口、监听模式、凭据状态、MCP 地址 状态
新增 / 修改 / 删除 SSH 目标机 客户机
判断某台目标机到底能不能构建这个工程 客户机 → 某台机器 → 环境
看着构建或同步往下滚 客户机 → 某台机器 → 日志
改某台机器用的根目录 实例 → 状态 → 基准目录
重建虚拟机后重新认领主机指纹 实例 → 状态 → 信任这个新指纹 / 从 known_hosts 导入
推送源码、拉取产物、跑一个任务 实例 → 项目 → 项目卡片
按顺序跑多个任务、失败后续跑 项目卡片 → 批量工作流、执行批量工作流、从第 N 步重试
打个 zip 并下载 项目卡片 → 导出压缩包
编辑构建命令模板 构建类型
跨项目工作流模板管理、预览与参数化应用到项目 工作流
改端口、语言、凭据、限流、日志保留、允许目录、hostLock 配置
让 AI 客户端连上这个 daemon 配置 → MCP(AI agent) → 客户端填这个地址
拿 JSON Schema 不在这里 —— 用 命令行 或 HTTP API

备注

设置 什么时候生效
监听端口、监听模式 重启程序之后。
语言 立即生效 —— 整个页面跟着服务端的值换。
用户名、密码、清除已保存的密码 立即生效,且只允许从本机改。
登录限流间隔(秒) 立即生效;每次登录尝试都重新读。
日志保留天数 立即生效。
额外允许的宿主目录 立即生效。
同一台客户机一次只跑一个任务 立即生效。
MCP(AI agent) 整组,含端口 立即生效;daemon 会当场解绑再绑。
  • 日志来源 webui 是怎么来的。 这个页面发出的每个请求都带 X-Client: webui,daemon 把它记成日志行的来源,也记成 job 的 source。所以 webui 会出现在 日志 页签的来源复选框里(初始是 webui、cli、mcp,实际出现过的会自动补进来)、读历史时的来源列里,以及这个页面发起的每个 job 的 source 字段里。页面本身不写日志,这个标记完全来自请求头。
  • 用收窄代替滚动:实时面板只保留内存里最近 4000 条,历史按天读,每条落盘记录还带一个日志域(global / client / project / job),CLI 里对应 --scope。
  • 某个页面一进去就整片纯色、点不动,几乎总是 Fluent 的 Portal 盖在了外层之上,细节见 故障排查。

← 首页

Clone this wiki locally