管理后台位于 /admin/,保留总览、开发板、DTB、会话租约、TFTP、Server 配置。
开发板页面用紧凑筛选栏搜索名称、板型、MAC,并按板型、标签、状态筛选;
已配置、发现设备和虚拟设备通过标签页切换。状态与常用编辑操作优先展示。
新建板卡的顺序为:填写电源配置 → 手动上电 → 选择发现的 MAC 或手工输入 → 保存。 上电只要求所选电源模块的必要参数,不要求板卡 ID、MAC、串口或 Session。 选择发现设备不会自动填写板型、电源或串口,保存前不会生成半成品板卡。 QEMU 使用已有虚拟设备,保留原来的真实网络发现与匹配校验。
选择 axloader 后,BoardEditor 隐藏手动串口开关、SN/path;可选启用“指定串口参数”并持久化保存,未启用时不配置覆盖,保存 serial: null。
指定参数优先于 axloader 上报,未指定时使用上报值或固件默认 115200/8N1。切回 U-Boot 保留编辑中的手动串口草稿。实际参数、端口、错误和 SerialRuntimeStatus
由会话的 SSE 展示;serial_manager 展示发现请求数与候选监听数。没有黑名单界面。
继电器配置继续保留,server 在发现前排除其所有路径别名和 SN。
httpboot 是唯一 HTTP Boot kind;uefi_http 和 boot_arch 不再兼容读取,旧配置必须由部署人员修正。内核按不透明字节上传,server 不读取 ELF 架构。设备架构取自 axloader /status 的开放字符串 arch,发现列表和 BoardEditor 原样只读展示,包括 future-isa 等未枚举名称;离线或未发现时显示未知。boardToFormState() 和 buildRequestPayload() 不保留人工架构状态,选择 MAC 只改变绑定。
BoardOta 的上传、排队、任务历史和取消操作不按 CPU 架构隐藏;设备离线或未发现时
仍可先排队。服务端保存非空且不超过 32 MiB 的镜像字节、标签、长度及 SHA-256,
由 axloader 校验格式、Machine 和平台兼容性。实际 ota 状态缺失时不下发镜像,
任务保留可见的等待原因;设备返回 503 后,等待状态、能力或代次变化再尝试。
面板通过现有 ota SSE 资源展示 Job.phase 和 Job.error,包含设备 HTTP 状态与
受限响应体;顶层 {code,message} 会保留。不可解码或截断的响应报告
invalid_device_response。202 仅表示暂存,
待新槽实际运行、确认且摘要匹配后任务才成功。409 延迟重试和网络错误的有限退避
由服务器处理;用户仍可查看错误或取消非终态任务。完整状态规则见
装载器升级。
开关机命令提交后由服务器持有,关闭页面不取消、不自动断电。实体板没有电源 反馈时,只显示命令完成。电源资源正在执行操作或属于使用中/释放中的板卡时, 冲突请求返回 409。Custom 命令只能按相同命令配置识别资源,不能推断不同命令 是否控制同一物理设备。Linux 管理端 Custom 命令限时 60 秒,超时终止并回收该 命令创建的进程组。既有 CLI 电源契约不变。
表单始终保留用户输入;其他客户端改变配置时显示冲突提示,由用户选择载入 服务器版本。列表更新不清空内容,重连不重置筛选与滚动。会话剩余时间是本地 时钟显示,不发起网络请求。强制释放返回后继续显示释放过程,实际完成后才移除。
POST /api/v1/admin/power-actions:
{
"request_id": "client-generated-unique-id",
"action": "on",
"power_management": {
"kind": "zhongsheng_relay",
"key": { "kind": "serial_number", "value": "relay-serial" }
}
}action 为 on 或 off,power_management 复用板卡配置的三个变体。
返回 202:{ "id": "...", "action": "on", "state": "running", "message": null }。
终态为 succeeded 或 failed,通过 SSE 的 power_actions 发布,也可单次查询
GET /api/v1/admin/power-actions/{id}。
同一服务器进程内,同一请求 ID 和相同参数返回原操作;改变参数返回 409。 请求 ID 长度为 1–128 字符。当前最多保留 4096 个操作,不丢弃幂等键,新请求超限 返回 503。进程重启后操作记录不恢复,查询返回 404;客户端不能自动重发未知动作。 发生网络错误时 UI 提供查询入口,清除提示不会执行额外电源动作。
GET /api/v1/admin/events 使用 text/event-stream。同一页面只创建一个连接。
服务端保活不包含业务更新;代理应关闭 SSE 缓冲并允许长连接。
id: <epoch>:<revision>
event: snapshot
data: {"epoch":"...","revision":1,"kind":"snapshot","data":{"boards":[],"sessions":[],"loaders":[]}}
后续事件名为 update,信封字段相同,data 仅包含改变的资源集合。
集合键包括 quarantined_boards、boards、runtimes、sessions、loaders、ota(镜像和升级任务)、virtual、dtbs、
serial、serial_manager、network、server、tftp、tftp_status、overview、power_actions。
集合更新是该集合的完整替换;消失的实体表示删除。前端按稳定 ID/MAC/name
合并并复用未变化的对象,不重新挂载整张表或表单。
事件投影由单一发布器串行维护。业务模块提交后使相关集合失效,由发布器读取 对应所有者;没有后台循环调用全部 GET。快照和 revision 在同一同步边界取出, 订阅在读取快照前建立,读取期间发生的变化会进入后续更新,不会漏掉。
浏览器重连通过 Last-Event-ID 请求重放。服务器保留最近 256 条更新;epoch
不同、游标非法、超过保留窗口或消费者落后时发送新快照。客户端遇到 revision
跳跃会重新订阅获取快照。读取单个资源失败时发送 { "error": "..." },客户端
保留该资源最后一次成功的数据并展示错误。
Loader 的在线期限为 10 秒、设备记录保留 24 小时,到期会主动发布变化。
Linux 使用 inotify 监听串口设备节点、netlink 监听网卡/IPv4、systemd D-Bus
监听服务状态、SIGCHLD 监听 QEMU 退出;QEMU 串口连接变化单独通知。
这些监听需要新增 notify、netlink-sys、zbus 依赖;命令组清理由 nix 提供。
非 Linux 平台仍接收应用内部事件,系统级热插拔监听目前仅在 Linux 启用。
前端使用 React、TypeScript、Vite、Tailwind 和官方 shadcn 源码组件,pnpm 固定 为 10.33.0。Prettier 用于维护 TSX/样式的一致格式;测试采用 Vitest、React Testing Library 和 Playwright。构建继续复制前端到 Cargo 输出目录、冻结锁文件安装、 构建并嵌入资源;不提交依赖目录或构建产物。
pnpm --dir ostool-server/webui install --frozen-lockfile
pnpm --dir ostool-server/webui test
pnpm --dir ostool-server/webui build
cargo test -p ostool-server
cargo build -p ostool-server
pnpm --dir ostool-server/webui exec playwright install chromium
pnpm --dir ostool-server/webui test:e2e浏览器测试启动临时目录下的真实服务器及 Vite 代理,使用 TCP 4174/4175、UDP
2998,要求端口空闲;不会修改宿主服务或 /etc/ostool-server。自定义服务器二进制
使用 OSTOOL_TEST_SERVER_BIN,已有 Chromium 可用 PLAYWRIGHT_CHROMIUM_EXECUTABLE。
测试覆盖真实电源提交、UDP/HTTP 发现、SSE 更新、双客户端冲突、Loader 无请求
离线、DTB 管理、会话释放、配置保存和移动端布局。
启动逐文件读取板卡 TOML。语法错误、不支持的枚举、缺失必填字段、校验失败、
文件名与 ID 不一致或重复 MAC 的文件移动到
<board_dir>/quarantine/<UTC时间>-<UUID>/<原文件名>,原始字节保持不变。
同目录的 reason.json 保存来源、备份路径、时间和完整原因,启动日志报告本次
隔离的配置。开发板页面的 Boards 将 quarantined_boards 与已加载的 boards
核对,仅提示尚未恢复同名配置的隔离记录。配置恢复并成功加载后,即使板卡已禁用,
旧错误也不再作为待修复问题显示;历史备份及原因仍保留。备份名称不会覆盖之前的
文件,下次启动不再扫描隔离目录。
目录按文件名排序加载;重复 MAC 保留排序最前的有效配置,隔离后续冲突文件。 其余有效板卡继续提供服务。修正备份文件后,管理员可将其放回板卡配置目录并 在维护窗口重启加载;系统不自动猜测旧字段含义或自动恢复隔离文件。
目录读取、文件读取或备份移动失败仍作为存储错误报告,保留源文件,不以丢失 配置为代价继续启动。顶层服务器配置错误不属于板卡逐文件隔离范围。
U-Boot 通过串口启动,无需绑定 MAC。切换到 U-Boot 后隐藏 MAC 选择器,保存时不提交网络身份;切回网络启动时保留尚未保存的 MAC 草稿。