Repository navigation
WebUI.zh cn
WebUI 是 CompileGateway 的浏览器入口:一个 React + Fluent UI 单页应用,由 daemon 在自己的 HTTP 端口上提供,除了本页末尾列出的那几项"给机器用"的能力之外,与 CLI 等价。
- 它是用 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安全警告。
桌面本体 compilegateway 是一个独立的终端样式窗口:上半屏滚日志、下半屏是输入框,另有 diag <名称> 可以给某台客户机单独开一个窗口。那个日志区是"本地、永远都在"的视角 —— 端口被占用、HTTP 服务根本没起来时,它照样要能显示,而那正是最需要看日志的时候。WebUI 的 日志 页签则是通过 HTTP 看同一个 daemon 的远端视角:它锁定在一台客户机上,能在实时尾巴和任意一天的落盘历史之间切换,还能按来源筛选。想知道"服务到底起没起来"看窗口;想事后查某台目标机的构建输出看 日志 页签。日志文件本身见 配置与日志。
有一项能力刻意只留给 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 盖在了外层之上,细节见 故障排查。
← 首页