Web 控制台
控制台是 Hub 运维 API 的图形前端。它以 Vite + React 单页应用的形式随仓库发布在
console/ 目录下,由 Hub 旁边的反向代理提供服务——构建与服务方式见
部署。
视图
| 视图 | 展示内容 |
|---|---|
| 概览 | 机群健康优先:节点上下线摘要、收敛状态以及指向问题区域的入口。 |
| 作业 | 作业目录,包含期望与观测状态、版本以及生命周期操作(启动/停止、检查点、升级)。 |
| 作业编辑器 | 基于表单的作业规格编辑器,提交前会校验规格。 |
| 作业 DAG | 作业算子图的有向图编排视图——算子边界、分区路由与有状态算子,对应 GET /api/v1/jobs/{id}/plan。 |
| 灰度发布 | 按节点展示的灰度发布进度,支持暂停、恢复、取消与回滚操作。 |
| 运行时 | 基于节点上报的实时每节点流状态与收敛情况。 |
| 组件 | 组件注册表浏览器:展示每个注册的 kind/type 及其配置 schema 与示例,对应 arkflow components show。 |
| 配置 | 节点配置历史、差异对比、应用与回滚。Hub 模式下所有操作都经由所选节点路由;草稿是本地控制面功能。 |
| 事件 | 机群事件日志(数据与 GET /api/v1/events 相同,附带用于实时更新的 SSE 流)。 |
| 审计 | 机群审计历史(GET /api/v1/audit):已接受与被拒绝的变更,携带操作者、目标、节点与结果,并支持对存量记录的文本过滤。 |
| 设置 | 控制台偏好与连接设置。 |
按照 API 的工作方式理解控制台
控制台是期望状态 API 之上的瘦客户端,其视图将三种资源视图明确区分:
- 期望(Desired)——你想要的状态(刚保存的 Intent)。
- 观测(Observed)——节点最近一次上报的状态。
- 收敛(Convergence)——两者是否一致(
in_sync、pending、applying、degraded、blocked)。
绿色徽标表示已收敛,而不是“命令已成功”:点击某个操作后,控制台会显示该待完成操作,直到对应的节点上报到达。 如果节点离线,操作仍会被接受(Intent 是持久的),视图会把该操作显示为阻塞,直到节点重连。
当 Hub 声明高可用状态时,控制台会展示机群的高可用姿态:概览卡片显示领导角色(leader 或 standby)、租约纪元与切换次数。当所连 Hub 为备用节点导致所有请求被拒绝(503 hub_standby)时,控制台会用明确的备用提示取代通用的过期横幅,并持续轮询——该 Hub 赢得租约后提示会自动消失。诊断数据保持诚实:作业详情只渲染 API 实际度量的指标;任务页签区分观测到的运行时状态与尚未上报的期望放置。作业编辑器将分布式运行时字段——并行度变化时重分布键控状态的 rescale 开关,以及参与放置核算的每任务 resources 请求(cpu_millicores、memory_bytes)——作为表单控件提供,清空后按缺省形态序列化。
节点维护操作
概览卡片提供三个机群维护用的节点操作。每个操作触发前都会请求确认:
- 排空(Drain)(
POST /api/v1/nodes/{id}/drain)把该节点的分配迁往 其他节点——在节点下线前使用。 - 维护(Maintain)(
POST /api/v1/nodes/{id}/maintenance)把节点标记为 维护中,放置不再向它分配新任务。 - 恢复(Resume)(
DELETE /api/v1/nodes/{id}/maintenance)让节点回到 现役状态。
节点不处于 active 状态时,其概览卡片会在节点名旁边以徽标显示当前状态
(draining 或 maintenance)。
导航与 URL
每个视图都有独立的 URL 路径(/、/runtime、/jobs、/configuration、
/rollouts、/components、/events、/audit、/settings),因此视图可以
收藏、分享,并支持浏览器的前进/后退按钮。当前选中的计算节点以 node_id
查询参数的形式保存在当前路径上,切换视图时会自动保留。使用旧版 ?page=
查询参数的历史链接(例如 /?page=jobs)会自动重定向到对应路径,并保留其余
查询参数。
何时用控制台,何时用 API
- 控制台:日常观测、单个作业的生命周期变更、灰度发布监控以及事件处置 (事件 + 运行时 + 审计集中在一处)。
- API:自动化、GitOps 式配置交付以及任何需要可复现的操作——控制台的每个动作都是 HTTP API 参考中有文档的路由。
主题
控制台内置深色(默认)与浅色两套主题,基于同一组设计令牌。顶栏的主题选择器提供
深色 / 浅色 / 跟随系统 三种选择;跟随系统会读取操作系统的偏好设置。
选择持久化在 localStorage(键 arkflow.console.theme)中,并在首次绘制前应用,
刷新页面不会出现主题闪屏。
破坏性与生命周期类操作通过应用内对话框确认(焦点圈闭,Esc 取消,Enter 确认),
操作结果以 Toast 通知反馈,表格在数据加载期间显示骨架屏。
界面语言
控制台界面内置英文与简体中文两套翻译。首次加载时,控制台根据浏览器语言
(navigator.language,任何 zh* 语言标签都会选中中文)自动选择,无法识别时回退英文。
顶栏的语言切换器(中文 / English)可即时切换,选择会持久化到 localStorage,
刷新后保持不变。日期与数字格式跟随所选语言。
后端返回的消息(API 错误、事件载荷)按原样展示,控制台不做翻译。
安全注意事项
控制台是一个静态资源包,除你输入的内容外不保存任何机密;它通过你的反向代理使用运维令牌向 Hub 认证。 请将 Hub API 与控制台都放在经过认证、受保护的网络边界之后——不要把携带令牌的部署暴露在公共互联网上 (见部署)。