WebUI 使用指南

本文档定位：WebUI · 快速上手。 环境部署（Controller + 存储节点）见《项目环境部署》，本文介绍 WebUI 各页面功能与「设备入池 → 绑定 → 克隆 → 上线」核心操作流程。 所有页面操作都等价于调用 Control Plane API（API 优先设计：WebUI 只是 API 的一个客户端）。

访问与鉴权

• 入口：浏览器打开 http://<Controller IP>:4838（WebUI 端口）。
• Token：部署时若设置了 IPXE_CP_TOKEN，页面顶部需填入对应 Bearer Token（部署时构建注入 VITE_CP_TOKEN 的版本免填）。
• 语言：右上角「中 / EN」切换界面语言，与操作无关，仅影响显示。

顶部导航共五个页面：Dashboard（仪表盘）/ Workers / Devices（设备池）/ Agents / Operations。

页面分区

Dashboard（仪表盘，/）

• 统计卡：Workers 总数、Agents 健康/总数。
• 最近操作：最近 10 条审计流水，点「查看全部 →」跳转 Operations 页。

Workers（/workers）

Worker 清单（worker_id 即 hostname，一一对应）：

• 列：worker_id、状态、绑定设备 MAC、就绪度（ready 绑定且系统盘就绪 / partial 绑定或已有盘 / idle 两者皆无）、Agent、创建时间。
• 操作：创建（单台，可带 MAC 直接绑定）、批量创建（数量 + 命名前缀，如 worker- 生成 worker-01…）、行内查看详情 / 删除。
• 行点击进入 Worker 详情页。
• 工具栏右侧「页面介绍」按钮：弹层逐项说明顶部操作按钮、筛选、列表列、行交互。

Devices（设备池，/devices）

设备台账页面（三实体模型的设备实体，绑定关系权威在设备侧）：

• 工具栏：
  • 自动注册开关：控制未知 MAC 设备上报指纹时是否自动入池（开 = 自动入池等待绑定；关 = 只上报不入池）。
  • + 注册设备：手动录入 MAC（+ 可选 UUID / 厂商 / 型号 / 序列号）入池。
  • 登记设备入池：批量粘贴 MAC 清单登记入池（逐项独立，重复跳过；鼠标悬停提示「不涉及绑定」——本操作不产生 Worker 绑定，绑定须走「绑定向导」）。
  • 绑定向导：设备 ↔ Worker 绑定（见下方核心流程）。
  • 多选解绑：勾选设备批量解绑（设备回池，系统盘保留在 Worker）。
• 列表：按入池时间（first_seen）排序；MAC 旁有复制按钮；状态（pooled 池中 / bound 已绑定 / revoked 已注销）、绑定 Worker、指纹摘要、来源（ipxe 自动入池 / manual 手动）、首次上报时间。
• 行展开详情：完整指纹（厂商/型号/序列号/CPU/内存等）、UUID、末次上报、绑定记录（历史绑定/解绑事件，最新在前，换绑显示旧 Worker → 新 Worker）。
• 工具栏「页面介绍」按钮：弹层逐项说明页面各功能区。

Worker 详情（/workers/:id）

• 系统盘管理：创建系统盘（第一步选 OS；第二步：克隆方式 Master 母盘克隆或 Empty 空白盘、母盘文件名下拉自动扫描存储节点、大小）、磁盘列表（IQN / 文件名 / 来源 / 状态）、删除。
• 默认启动配置：default_os（仅可选已挂载的系统盘）→ 推导链 default_os > boot.menu_default > reboot；未配置时循环重启等待。
• 解绑 / 删除等管理操作。

Agents（/agents）

存储节点（Agent + iSCSI 后端）清单：健康状态（live 在线 / 异常）、角色能力（disk / cd）、标签；+ 添加 Agent（两步探测注册：填 Agent ID / API 地址 / Token → 探测自动获取参数 → 确认数据面地址 → 添加，写入 agents.yml）、行内编辑（改 base_url / token / 角色 / 启用状态）、停用；点进行查看该节点 LUN 列表（/agents/:id）。

• 工具栏「页面介绍」按钮：弹层逐项说明工具栏、Agent 卡片、行交互。

Operations（/operations）

审计日志（state/operations.jsonl 的增量查询）：所有管理操作按时间倒序，含操作码、状态、参数明细；用于追溯绑定、建盘、注册等全部历史。

核心操作流程（快速上线）

以「新机器 → 无盘 Worker」为例：

1. 设备入池

• 自动入池：自动注册开关为「开」时，机器通电（PXE 引导）即自动入池，无需人工登记。
• 手动入池：Devices 页「注册设备」/「登记设备入池」录入（自动注册关闭时使用）。

2. 绑定 Worker（绑定向导）

Devices 页 →「绑定向导」→ 默认顺序分配模式：

1. 左栏勾选池中未绑定设备（按入池时间排序，支持搜索 / 全选）。
2. 右栏勾选可用 Worker（按勾选顺序分配；Worker 不足时填写补建前缀自动批量创建差额）。
3. 底部汇总条确认「已选设备 N 台 → Worker N 个」→ 预览配对表 → 导出 TSV 核对（可选）→ 二次确认执行。

也可切换到清单配对模式：粘贴 mac, worker_id 逐行配对（指纹比对列为可选申报值）。

绑定后设备状态变为 bound，下次 PXE 引导即按 Worker 配置执行。

3. 克隆系统盘

Workers 页 → 点 Worker 进详情 →「创建系统盘」：

表单字段	填写
操作系统（OS）	对应母盘系统（如 Windows / Debian）
克隆方式（Type）	Master（母盘克隆）；Empty（空白盘，后续自行装机）
母盘文件名	下拉选择 _tpl_xxx.img（列表自动扫描存储节点）

创建即完成（reflink 秒级克隆），自动创建 iSCSI Target 与 IQN，全程无需命令行。

4. 设置默认启动

Worker 详情页「默认启动配置」→「默认系统」选择刚克隆的盘 → 保存。下次开机自动直达系统，无需 iPXE 菜单手动选择。

5. 验证

重启 Worker：iPXE → iSCSI 登录 → 系统启动 Logo → 桌面/登录界面。Workers 页确认盘状态（IQN / 来源 master: _tpl_xxx.img）。

常见问题

问题	处理
页面提示 401 / Token 无效	核对 webui/app/.env 的 VITE_CP_TOKEN 与 control_plane/control_plane.env 的 IPXE_CP_TOKEN 一致（VITE_ 变量构建时注入，修改后需重新构建）
机器通电但设备池没有新设备	① 自动注册开关是否开启；② Operations 页看是否有 device.report 记录（开关关闭时只上报不入池）
绑定向导左栏没有设备	设备须先入池（状态 pooled）且未绑定；已绑定设备不参与分配
克隆下拉没有母盘	母盘文件命名须含 _tpl_ 前缀（如 _tpl_windows_25h2.img），且已上传到存储节点的镜像目录
Worker 引导停在 iPXE 菜单	未设置默认启动：Worker 详情页配置「默认系统」，或菜单手动选择对应系统项