566 lines
16 KiB
Markdown
566 lines
16 KiB
Markdown
# 设备与配置管理信息架构重设计方案
|
||
|
||
## 目标
|
||
|
||
将 RK3588 后台管理系统重设计为一个清晰、统一、面向多台视觉识别设备的运维控制台。
|
||
|
||
这次重设计的重点不是在现有页面上继续打补丁，而是彻底解决下面几个问题：
|
||
|
||
- 页面入口越来越多，但边界不清楚
|
||
- 同一个信息在多个地方重复出现，内容还不完全一致
|
||
- 用户很难判断“去哪里看状态”“去哪里做操作”“去哪里管理公共配置”
|
||
- 设备管理、配置管理、调试页面混在一起，造成认知负担
|
||
|
||
新的设计必须保证：同一种信息只有一个权威展示位置，页面职责清楚，用户能快速找到正确入口。
|
||
|
||
## 为什么现有 UI 已经不适合继续扩展
|
||
|
||
当前后台是围绕零散流程和已有接口逐步长出来的，所以会出现这些现象：
|
||
|
||
- 同一个概念在多个页面里反复出现，只是叫法略有不同
|
||
- 设备详情、设备操作、配置预览、配置修改互相重叠
|
||
- `config-friendly`、`config-ui`、`config-preview` 三套入口并行存在
|
||
- 一级导航混合了业务对象、页面功能、技术工具和调试能力
|
||
- 用户在使用时很难形成稳定心智，不知道某类信息到底应该去哪一页看
|
||
|
||
所以这次不是“优化现有导航文案”，而是重新定义整个后台的信息架构。
|
||
|
||
## 产品范围
|
||
|
||
这个后台的本质，是一个统一管理少量视觉识别设备的管理平台。设备规模通常不会超过十几台，因此设计重点应放在清晰、简洁、好判断，而不是面向超大规模设备的高密度监控墙。
|
||
|
||
当前最重要的职责有四类：
|
||
|
||
1. 发现所有设备，并清楚显示每台设备当前状态
|
||
2. 统一管理模板、profile、overlay 等公共配置资产
|
||
3. 管理单台设备的服务与配置操作
|
||
4. 记录操作日志与系统管理行为
|
||
|
||
## 设计原则
|
||
|
||
后续所有页面和交互都必须遵守这几条原则：
|
||
|
||
1. 同一个信息只允许有一个权威展示位置
|
||
例如：当前运行配置的完整权威摘要属于“设备详情”，其他页面只能显示简短摘要或跳转。
|
||
|
||
2. 查看和操作必须分离
|
||
“这台设备现在怎么样”与“我要对这台设备做什么”不能混在一个页面里。
|
||
|
||
3. 一级导航只放业务域，不放动作和技术工具
|
||
导航应该按对象组织，而不是按零散功能组织。
|
||
|
||
4. 长技术字段退居二级
|
||
设备名优先，`device_id`、路径、原始 JSON、内部字段都应降级显示。
|
||
|
||
5. 能用图标表达的状态，尽量不用大段文字
|
||
后台首先要支持快速扫视和判断，而不是让用户读说明书。
|
||
|
||
6. 每个页面只回答一个核心问题
|
||
比如：
|
||
- 现在发生了什么？
|
||
- 这台设备是什么状态？
|
||
- 我可以做哪些操作？
|
||
- 目前有哪些配置资产？
|
||
- 谁做过哪些变更？
|
||
|
||
## 参考方向
|
||
|
||
整体风格参考 ThingsBoard 这类平台型运维后台，但不是照搬它的功能复杂度。我们借鉴的是它的设计气质和组织方式：
|
||
|
||
- 左侧是稳定、克制的主导航
|
||
- 主工作区层次清楚
|
||
- 设备状态展示紧凑、易扫视
|
||
- 查看、管理、审计分开
|
||
- 风格统一、简洁，不做普通 CRUD 表单后台的拼贴感
|
||
|
||
## 官方模板参考入口
|
||
|
||
后续所有 UI 细节实现，除了参考 ThingsBoard 这类整体风格方向，还必须优先参考当前后台实际采用的 Tabler 官方文档与示例页面。
|
||
|
||
统一参考入口：
|
||
|
||
- Tabler UI 官方文档首页：
|
||
<https://docs.tabler.io/ui>
|
||
|
||
- Tabler Cards 组件文档：
|
||
<https://docs.tabler.io/ui/components/cards>
|
||
|
||
这两个页面的作用不同：
|
||
|
||
- `https://docs.tabler.io/ui`
|
||
用来查看官方组件目录、整体视觉语言和页面级组织方式。
|
||
|
||
- `https://docs.tabler.io/ui/components/cards`
|
||
用来查看卡片、标签页卡片、卡片内容分区等具体结构，尤其适合作为详情页、控制页、标签页容器的直接参考。
|
||
|
||
## 官方示例优先规则
|
||
|
||
后续实现 UI 时，必须遵守这条规则：
|
||
|
||
1. 先看 Tabler 官方页面的实际效果
|
||
2. 再看官方示例代码结构
|
||
3. 能直接复用官方结构时，不允许先自定义一个“看起来差不多”的版本
|
||
4. 只有官方没有提供合适结构时，才允许做小范围本地样式补充
|
||
|
||
这条规则尤其适用于下面这些高频区域：
|
||
|
||
- tabs / nav-tabs
|
||
- card-tabs
|
||
- card + card-body / card-header
|
||
- 表格工具栏
|
||
- 按钮层级
|
||
- 详情页与控制页的内容容器
|
||
|
||
例如：
|
||
|
||
- 如果要做标签页，就优先参考官方 `card-tabs + nav nav-tabs + tab-content + card tab-pane` 结构
|
||
- 如果要做卡片分区，就优先参考官方 `card / card-header / card-body` 结构
|
||
- 如果要做按钮、表单、tab 组合，不应先手写一套近似样式，再去慢慢调整
|
||
|
||
## 文档使用约定
|
||
|
||
以后只要文档里写到“按模板实现”“使用官方组件结构”“参考 Tabler 示例”，默认就是指向上面这两个官方入口。
|
||
|
||
也就是说，后续如果要继续调整：
|
||
|
||
- 设备详情页
|
||
- 设备控制页
|
||
- 配置页
|
||
- 审计页
|
||
- 任务页
|
||
|
||
都应该先打开官方页面看示例效果和代码，再决定如何落地，而不是只凭组件名称或经验去猜结构。
|
||
|
||
## UI 视觉系统约束
|
||
|
||
这次重设计不仅要重做信息架构，也要约束 UI 本身的表现方式，避免后续页面继续变成“每页一个风格”。
|
||
|
||
后续实现必须遵守下面这些视觉约束：
|
||
|
||
1. 优先基于统一的后台模板风格来实现
|
||
不允许在不同页面随意发明新的颜色体系、按钮样式、字体层级、卡片风格和状态表现。
|
||
|
||
2. 颜色必须克制且有明确语义
|
||
- 中性色用于背景、分隔、普通信息
|
||
- 绿色用于成功 / 在线 / 正常
|
||
- 红色用于失败 / 离线 / 异常
|
||
- 黄色或橙色用于警告 / 风险
|
||
- 主强调色只承担选中、高亮、关键入口，不应泛滥
|
||
|
||
3. 字体和字号层级必须固定
|
||
不允许为了“显眼”在局部页面随意放大、缩小或切换字体。标题、正文、说明、技术字段都应使用统一层级。
|
||
|
||
4. 组件样式必须统一
|
||
按钮、表格、摘要卡、标签、状态点、抽屉、折叠区、表单输入框都应使用统一规则，不能每页重新设计。
|
||
|
||
5. 图标优先表达状态，文字优先表达对象
|
||
状态类信息尽量图标化；对象名、配置名、操作名则保持清楚简洁，不做花哨修饰。
|
||
|
||
6. 页面视觉重心必须稳定
|
||
不允许通过随意的高饱和颜色、大块阴影、混乱圆角、过多描边来制造“设计感”。这套后台应是稳定、专业、克制的运维界面。
|
||
|
||
## 信息分层与收纳策略
|
||
|
||
后台默认只展示运维真正需要的重点信息，其他内容应当有明确的收纳方式，避免页面堆满“技术上有用但不是当前最重要”的信息。
|
||
|
||
信息展示分三层：
|
||
|
||
### 第一层：默认可见的核心信息
|
||
|
||
这是页面一打开就应该看到的信息，只保留支持判断和操作的关键内容。例如：
|
||
|
||
- 设备是否在线
|
||
- 服务是否运行
|
||
- 当前运行配置摘要
|
||
- 最近操作是否成功
|
||
- 当前可执行的关键动作
|
||
|
||
### 第二层：次要但常用的参考信息
|
||
|
||
这些信息不是第一眼最重要，但经常需要核对。应通过折叠区、展开面板或局部详情块承载，例如：
|
||
|
||
- `device_id`
|
||
- IP、hostname
|
||
- build_id、git_sha
|
||
- 配置来源中的模板 / profile / overlay 明细
|
||
- 最近一次操作的详细结果
|
||
|
||
### 第三层：低频技术信息
|
||
|
||
这些信息只在排查问题或高级使用时才需要，不能默认大面积展开。应进入抽屉、技术详情区或高级模式，例如：
|
||
|
||
- 原始 JSON
|
||
- 完整响应体
|
||
- 原始路径
|
||
- 调试输出
|
||
- 底层接口报错细节
|
||
|
||
### 收纳规则
|
||
|
||
后续所有页面都应遵守以下收纳规则：
|
||
|
||
- 默认页面只保留“判断当前状态”和“执行当前动作”需要的信息
|
||
- 次要参考信息优先进入折叠区
|
||
- 低频技术信息优先进入抽屉或高级面板
|
||
- 不能因为“也许有人会看”就把所有信息都铺在主页面上
|
||
|
||
这条规则非常重要：
|
||
页面不是数据库字段的平铺视图，而是运维任务的工作界面。
|
||
|
||
## 一级信息架构
|
||
|
||
整个系统最终只保留四个一级模块：
|
||
|
||
1. `设备`
|
||
2. `配置资产`
|
||
3. `操作审计`
|
||
4. `系统`
|
||
|
||
这四个模块正好对应产品的四个核心职责。
|
||
|
||
### 1. 设备
|
||
|
||
作用：回答“有哪些设备、每台设备当前是什么状态、哪台设备需要处理”
|
||
|
||
包含：
|
||
|
||
- 全部设备总览
|
||
- 设备列表
|
||
- 单设备详情
|
||
- 单设备控制
|
||
|
||
不包含：
|
||
|
||
- 模板 / profile / overlay 这类公共配置资产管理
|
||
- 平台级系统设置
|
||
- 全量审计日志主体内容
|
||
|
||
### 2. 配置资产
|
||
|
||
作用：回答“系统里有哪些可复用的配置资产”
|
||
|
||
包含：
|
||
|
||
- 模板
|
||
- 环境参数（Profiles）
|
||
- 覆盖项（Overlays）
|
||
- 配置发布记录
|
||
|
||
不包含：
|
||
|
||
- 设备实时状态
|
||
- 单设备服务控制
|
||
- 当前运行配置的权威展示
|
||
|
||
### 3. 操作审计
|
||
|
||
作用：回答“谁在什么时间对哪台设备做了什么，结果怎样”
|
||
|
||
包含：
|
||
|
||
- 操作历史
|
||
- 操作结果摘要
|
||
- 按时间、设备、操作者、动作类型过滤
|
||
|
||
### 4. 系统
|
||
|
||
作用：回答“后台管理系统自身如何配置和运行”
|
||
|
||
包含：
|
||
|
||
- 设备发现与注册设置
|
||
- agent 认证与访问令牌管理
|
||
- 后台服务健康状态
|
||
- 后台版本信息
|
||
- OpenAPI 与系统级入口
|
||
|
||
不包含：
|
||
|
||
- 日常设备操作
|
||
- 配置资产编辑
|
||
|
||
## 首页：设备总览
|
||
|
||
首页默认进入 `设备` 模块。
|
||
|
||
整体采用你确认过的混合结构：上方摘要，下方设备列表。
|
||
|
||
### 顶部摘要区
|
||
|
||
顶部是一排图标化摘要卡，用于快速判断整体状态。建议至少包含：
|
||
|
||
- 在线设备数
|
||
- 离线设备数
|
||
- 服务异常设备数
|
||
- 配置不一致设备数
|
||
- 最近操作失败设备数
|
||
|
||
这里不放解释性长文本，只负责总览和快速筛选。
|
||
|
||
### 主设备列表
|
||
|
||
摘要区下方是主设备列表。由于设备数量不多，不需要做极端高密度表格，应优先保证清晰易读。
|
||
|
||
每台设备只显示最关键的信息：
|
||
|
||
- 设备图标
|
||
- 有意义的设备名
|
||
- 在线状态
|
||
- media-server 状态
|
||
- 当前运行配置摘要
|
||
- 当前软件版本
|
||
- 最后心跳时间
|
||
- 快捷入口
|
||
|
||
### 设备身份显示规则
|
||
|
||
- 设备名始终是主显示信息
|
||
- `device_id` 只作为次级技术信息出现
|
||
- 冗长标识不应成为列表主视觉元素
|
||
- 技术字段可放在悬浮提示、次级说明或详情页中
|
||
|
||
## 设备域设计
|
||
|
||
每台设备下只保留两个页面：
|
||
|
||
1. `设备详情`
|
||
2. `设备控制`
|
||
|
||
这是强约束，不允许再把同类信息拆成多个平行页面。
|
||
|
||
### 设备详情
|
||
|
||
作用：只看，不操作。回答“这台设备现在是什么状态”
|
||
|
||
应展示：
|
||
|
||
- 设备名
|
||
- `device_id`、hostname、IP
|
||
- 在线 / 离线状态
|
||
- 最后心跳
|
||
- agent 版本、build_id、git_sha
|
||
- media-server 运行状态
|
||
- 当前运行配置权威摘要
|
||
- 最近状态或异常摘要
|
||
- 跳转到设备控制与操作审计
|
||
|
||
不应展示：
|
||
|
||
- 配置预览编辑器
|
||
- 候选配置上传操作
|
||
- 应用 / 回滚按钮
|
||
- 默认展开的原始 JSON 编辑区
|
||
|
||
### 设备控制
|
||
|
||
作用：只做操作。回答“我要对这台设备做什么”
|
||
|
||
应展示：
|
||
|
||
- 配置预览生成
|
||
- 上传候选配置
|
||
- 应用候选配置
|
||
- 回滚到上一份配置
|
||
- 启动 / 停止 / 重启 / 重载服务
|
||
- 当前这次操作的结果摘要
|
||
|
||
约束：
|
||
|
||
- 设备控制页可以显示少量安全上下文，例如当前配置摘要、服务状态
|
||
- 但不能重复完整设备详情页内容
|
||
|
||
### 现有配置入口的收敛方式
|
||
|
||
当前系统中以下几个入口职责重叠：
|
||
|
||
- `config-friendly`
|
||
- `config-ui`
|
||
- `config-preview`
|
||
|
||
在新架构下，这三个不再作为独立产品页面存在，而是统一收进 `设备控制`，作为同一页面中的不同操作模式，例如：
|
||
|
||
- 预览模式
|
||
- 引导编辑模式
|
||
- 高级 JSON 模式
|
||
|
||
这样设备配置操作就只有一个主入口，不再让用户在多个相似页面之间来回跳。
|
||
|
||
## 配置资产域设计
|
||
|
||
`配置资产` 用来管理可复用的配置组成部分，而不是管理某台设备当前正在运行什么。
|
||
|
||
建议拆成四个子区：
|
||
|
||
1. `模板`
|
||
2. `环境参数`
|
||
3. `覆盖项`
|
||
4. `发布记录`
|
||
|
||
### 模板
|
||
|
||
管理核心配置模板，以及模板用途、适用范围、说明等元数据。
|
||
|
||
### 环境参数
|
||
|
||
管理设备或环境差异参数，例如：
|
||
|
||
- 视频源地址
|
||
- 后台地址
|
||
- MinIO 参数
|
||
- token API
|
||
- 站点级或设备级差异项
|
||
|
||
这类差异不应再靠维护多份完整 JSON 来表达。
|
||
|
||
### 覆盖项
|
||
|
||
管理可重复使用的覆盖项，例如：
|
||
|
||
- debug 开关
|
||
- 敏感度调整
|
||
- production quiet
|
||
- 其他运行策略覆盖
|
||
|
||
### 发布记录
|
||
|
||
用于记录某次配置生成或发布的来源和结果。至少应能表达：
|
||
|
||
- 来自哪个模板
|
||
- 使用哪个 profile
|
||
- 叠加了哪些 overlays
|
||
- 生成了什么配置标识
|
||
- 应用了哪些设备
|
||
- 应用结果如何
|
||
|
||
这个区域负责把“配置资产”与“设备应用行为”连接起来，但不承担设备状态页的职责。
|
||
|
||
## 操作审计域设计
|
||
|
||
`操作审计` 是专门的操作历史页，不应再混杂进其他页面的主体区域。
|
||
|
||
每条审计记录至少应包含：
|
||
|
||
- 操作时间
|
||
- 操作者
|
||
- 目标设备
|
||
- 动作类型
|
||
- 输入摘要
|
||
- 执行结果
|
||
- 执行耗时
|
||
- 失败原因
|
||
|
||
动作类型至少包括：
|
||
|
||
- 上传候选配置
|
||
- 应用候选配置
|
||
- 回滚配置
|
||
- 重载服务
|
||
- 启动服务
|
||
- 停止服务
|
||
- 重启服务
|
||
- 批量操作
|
||
|
||
操作审计的目标是形成管理闭环，而不是暴露底层 HTTP 调试细节。
|
||
|
||
## 系统域设计
|
||
|
||
`系统` 只放平台级设置和后台自身状态，保持克制，不要再变成杂物间。
|
||
|
||
建议包含：
|
||
|
||
- 设备发现与注册设置
|
||
- 后台访问 agent 的认证设置
|
||
- 后台服务健康
|
||
- 后台版本 / build 信息
|
||
- OpenAPI 入口
|
||
|
||
不建议放入：
|
||
|
||
- 日常设备控制动作
|
||
- 模板 / profile / overlay 资产管理
|
||
|
||
## 页面与路由目标形态
|
||
|
||
实现后整体结构应逐步收敛为下面这类路由：
|
||
|
||
- `/ui/devices` -> 设备总览
|
||
- `/ui/devices/{id}` -> 设备详情
|
||
- `/ui/devices/{id}/control` -> 设备控制
|
||
- `/ui/assets/templates`
|
||
- `/ui/assets/profiles`
|
||
- `/ui/assets/overlays`
|
||
- `/ui/assets/releases`
|
||
- `/ui/audit`
|
||
- `/ui/system`
|
||
|
||
具体命名可以在实现时微调，但页面边界不应变化。
|
||
|
||
## 需要移除或并入的旧页面概念
|
||
|
||
以下内容不应再继续作为一级页面或独立主入口存在：
|
||
|
||
- `识别配置`
|
||
- `配置管理`
|
||
- `模型管理` 作为一级入口
|
||
- `高级调试` 作为一级入口
|
||
- `服务健康` 作为一级入口
|
||
- `OpenAPI` 作为一级入口
|
||
|
||
特别是以下三个配置页面，必须并入设备控制，不再平行存在：
|
||
|
||
- `config-friendly`
|
||
- `config-ui`
|
||
- `config-preview`
|
||
|
||
这次重设计的核心之一，就是用一个清晰的设备控制入口，替代多个“看起来差不多”的配置页。
|
||
|
||
## 信息归属规则
|
||
|
||
为了防止以后再次出现重复页面，后续实现必须遵守下面的信息归属：
|
||
|
||
- 全局设备状态摘要属于设备总览
|
||
- 当前运行配置的权威摘要属于设备详情
|
||
- 配置操作属于设备控制
|
||
- 模板 / profile / overlay 属于配置资产
|
||
- 操作历史属于操作审计
|
||
- 平台设置与平台健康属于系统
|
||
|
||
其他页面如果需要引用这些信息，只能显示摘要或者跳转，不能再次变成完整展示页。
|
||
|
||
## 错误状态与空状态
|
||
|
||
新架构必须能在不理想情况下仍然保持清晰：
|
||
|
||
- 离线设备也必须可见，只是状态明显不同
|
||
- 配置 metadata 缺失时，应优雅降级，而不是把页面弄乱
|
||
- 操作失败时，应展示简洁结果，并提供进入审计详情的入口
|
||
- 模板、profile、overlay 为空时，应明确告诉用户当前没有资产，而不是留白
|
||
|
||
默认主流程中，不应直接把原始 JSON、HTTP 报错或调试信息大面积暴露给用户，除非用户明确进入高级模式。
|
||
|
||
## 验证要求
|
||
|
||
第一阶段实现至少要完成：
|
||
|
||
```bash
|
||
go test ./...
|
||
```
|
||
|
||
同时 UI 层面的验证应覆盖：
|
||
|
||
- 导航中只保留批准后的一级模块
|
||
- 设备详情和设备控制已经彻底分离
|
||
- 旧的多个配置入口不再以平级页面形式存在
|
||
- 设备总览以设备名和状态为主，而不是以技术标识为主
|
||
|
||
## 非目标
|
||
|
||
这次重设计不追求以下内容：
|
||
|
||
- 面向几百台设备的超大规模监控体验
|
||
- 大量动态动画或实时监控大屏
|
||
- 与设备 / 配置 / 审计 / 系统边界无关的功能扩张
|
||
- 向普通用户暴露更多内部算法和管线参数
|
||
|
||
这次工作的目标，是把后台做得更清楚、更统一、更容易理解，而不是把它做得更大。
|