349 lines
9.7 KiB
Markdown
349 lines
9.7 KiB
Markdown
# 以 Profile 为中心的配置设计
|
||
|
||
## 目的
|
||
|
||
明确 `template`、`profile`、`overlay` 三层之间的字段边界，使后台管理系统能够把 `profile` 当作一等配置资产，而不是仅仅把它当成一个下拉选项。
|
||
|
||
目标运行模型如下：
|
||
|
||
- 一台物理设备对应一份 profile
|
||
- template 可以在多台设备、多个现场之间复用
|
||
- overlay 只负责 debug、灵敏度和临时运行模式
|
||
- media-server 的内部实现参数默认不暴露给普通用户
|
||
|
||
该设计建立在现有模板渲染工作流之上，不会回到手工维护多份完整 JSON 的旧模式。
|
||
|
||
## 当前背景
|
||
|
||
当前受维护的配置来源为：
|
||
|
||
- template：`configs/templates/workshop_face_shoe_alarm.json`
|
||
- profile：`configs/profiles/local_3588_test.json`
|
||
- overlays：`configs/overlays/*.json`
|
||
- 生成配置：`configs/generated/*.json`
|
||
|
||
从现有配置文件看，当前实际情况是：
|
||
|
||
- `template` 已经承载了流水线骨架、节点图、模型、告警结构和默认阈值
|
||
- `overlay` 当前的定位基本正确，已经主要用于 debug / 测试 / 安静运行模式
|
||
- `profile` 已经开始承载设备独特属性，例如 `rtsp_url`，但同时又混入了共享的外部服务配置
|
||
|
||
这类混放是当前的核心问题。它会让后台很难把 profile 清晰地表达成“设备/现场身份与设备级接入配置”。
|
||
|
||
## 设计目标
|
||
|
||
1. 让 `profile` 成为单台设备身份与设备级接入配置的唯一归属层。
|
||
2. 让方案级共享配置继续通过 template 复用。
|
||
3. 保持 overlay 小而纯粹，专注运行模式。
|
||
4. 阻止底层实现细节泄漏到面向用户的配置界面。
|
||
5. 支持多模板并存，且每个模板都能灵活对接不同的外部服务和存储后端。
|
||
|
||
## 字段归属边界
|
||
|
||
### Template
|
||
|
||
`template` 负责方案级共享配置。
|
||
|
||
典型内容包括：
|
||
|
||
- DAG 结构：`nodes`、`edges`
|
||
- 插件/节点选择
|
||
- 共享模型默认值
|
||
- 共享算法默认值
|
||
- 共享告警动作结构
|
||
- 共享外部服务配置
|
||
- 共享存储配置
|
||
- 默认发布协议结构
|
||
|
||
以 `workshop_face_shoe_alarm.json` 为例，适合归属于 template 的内容包括：
|
||
|
||
- 节点类型和节点 ID
|
||
- 模型路径和模型尺寸
|
||
- 跟踪器模式及默认阈值
|
||
- 告警规则结构
|
||
- 快照/录像上传结构
|
||
- External API 动作结构
|
||
- 发布输出结构
|
||
|
||
重要规则：
|
||
|
||
- template 中的共享服务字段必须保持“可编辑模板参数”的属性
|
||
- 不能把它们当成写死的常量
|
||
|
||
这样才能支持不同 template 对接不同 MinIO 或不同外部告警服务。
|
||
|
||
### Profile
|
||
|
||
`profile` 负责设备级身份和设备级运行绑定。
|
||
|
||
一份 profile 对应一台物理设备。
|
||
|
||
典型内容包括：
|
||
|
||
- 业务显示名
|
||
- 站点身份
|
||
- 设备本地输入源
|
||
- 设备本地发布输出参数
|
||
- 设备本地资源路径
|
||
- 外部系统需要的设备级业务标识
|
||
|
||
当前已经明显适合保留在 profile 的字段：
|
||
|
||
- `rtsp_url`
|
||
|
||
本设计建议新增的 profile 字段：
|
||
|
||
- `display_name`
|
||
- `device_code`
|
||
- `site_name`
|
||
- `publish_hls_path`
|
||
- `publish_rtsp_port`
|
||
- `publish_rtsp_path`
|
||
- `channel_no`
|
||
|
||
后台设备列表应优先展示 `display_name`。像 `device_id`、`hostname` 这样的技术标识，应该收纳到设备详情页。
|
||
|
||
### Overlay
|
||
|
||
`overlay` 负责短周期运行模式。
|
||
|
||
允许的用途包括：
|
||
|
||
- debug 开关
|
||
- 测试灵敏度
|
||
- 安静生产模式
|
||
- 临时验证行为
|
||
|
||
当前已经比较符合这一定位的 overlay：
|
||
|
||
- `face_debug.json`
|
||
- `shoe_debug.json`
|
||
- `face_test_sensitive.json`
|
||
- `shoe_test_sensitive.json`
|
||
- `production_quiet.json`
|
||
|
||
overlay 不应承载：
|
||
|
||
- 设备身份
|
||
- 设备本地视频源
|
||
- 每台设备自己的输出主机/路径/端口
|
||
- 长期稳定的外部服务归属
|
||
|
||
### 程序内部默认参数与高级设置
|
||
|
||
以下内容不应进入普通后台主配置编辑：
|
||
|
||
- `cpu_affinity`
|
||
- queue 实现细节
|
||
- `rga_max_inflight`
|
||
- 底层 tensor / 输入输出假设
|
||
- 插件之间的内部 glue 参数
|
||
- 其他容易配坏、主要面向工程调试的字段
|
||
|
||
这些参数应按两类处理：
|
||
|
||
#### 1. 程序内部默认参数
|
||
|
||
如果某些参数在当前部署模式下应固定，则应直接回收到程序默认、模板默认或部署默认，不再暴露成配置字段。
|
||
|
||
当前明确建议内收的字段：
|
||
|
||
- `face_gallery_path`
|
||
- 应由部署流程将人脸库放到约定默认目录
|
||
- 不应允许在后台中修改
|
||
- `rga_gate`
|
||
- 如果最终确认始终固定使用同一组 RGA 资源分组，则应回收到模板默认或程序默认
|
||
- 当前 `workshop_face_shoe_alarm` 已固定为 `main_pipeline_rga`
|
||
|
||
#### 2. 高级设置
|
||
|
||
如果某些字段仅在工程调试、特殊部署或排障时才需要保留，则可以在 UI 中进入“高级设置”，并默认折叠，不进入日常运维主流程。
|
||
|
||
## 标准 Profile 模型
|
||
|
||
建议把单个 profile 组织为以下几组字段：
|
||
|
||
### 1. 设备身份
|
||
|
||
- `display_name`
|
||
- `device_code`
|
||
- `site_name`
|
||
|
||
### 2. 输入源
|
||
|
||
- `rtsp_url`
|
||
|
||
### 3. 输出发布
|
||
|
||
- `publish_hls_path`
|
||
- `publish_rtsp_port`
|
||
- `publish_rtsp_path`
|
||
- `channel_no`
|
||
|
||
原因：
|
||
|
||
- 发布输出是设备级属性，不是共享属性
|
||
- 它天然包含设备自己的 IP / 主机 / 端口 / 路径语义
|
||
- 它往往直接决定外部系统如何消费这台盒子的输出流
|
||
|
||
### 4. 设备本地资源
|
||
|
||
- 仅保留未来确有设备差异的本地资源路径
|
||
- 当前不建议把 `face_gallery_path` 暴露为 profile 字段
|
||
- 当前不建议把 `rga_gate` 暴露为 profile 字段
|
||
- 只有在后续确认不同设备之间确实存在差异时，才考虑进入高级设置
|
||
|
||
## Template 参数模型
|
||
|
||
当某些外部服务属于“方案级共享配置”时，它们应保留在 template，而不是塞进每台设备自己的 profile。
|
||
|
||
建议由 template 管理的共享字段包括：
|
||
|
||
- `minio_endpoint`
|
||
- `minio_bucket`
|
||
- `minio_access_key`
|
||
- `minio_secret_key`
|
||
- `external_get_token_url`
|
||
- `external_put_message_url`
|
||
- `tenant_code`
|
||
|
||
原因：
|
||
|
||
- 这类配置通常在同一类部署方案中是共享的
|
||
- 如果把它们复制进每台设备的 profile，会造成重复和漂移
|
||
- 不同 template 仍然可能对接不同共享服务，因此它们必须保持 template 级可编辑，而不是写死
|
||
|
||
## 渲染参数迁移方向
|
||
|
||
当前 template 中已经存在的占位符包括：
|
||
|
||
- `${rtsp_url}`
|
||
- `${face_gallery_path}`
|
||
- `${minio_endpoint}`
|
||
- `${minio_bucket}`
|
||
- `${minio_access_key}`
|
||
- `${minio_secret_key}`
|
||
- `${external_get_token_url}`
|
||
- `${external_put_message_url}`
|
||
- `${tenant_code}`
|
||
- `${name}`
|
||
|
||
本设计建议下一步按以下方向迁移：
|
||
|
||
### 保留为 profile 驱动占位符
|
||
|
||
- `${rtsp_url}`
|
||
|
||
### 保留为 template 驱动占位符
|
||
|
||
- `${minio_endpoint}`
|
||
- `${minio_bucket}`
|
||
- `${minio_access_key}`
|
||
- `${minio_secret_key}`
|
||
- `${external_get_token_url}`
|
||
- `${external_put_message_url}`
|
||
- `${tenant_code}`
|
||
|
||
当前 `workshop_face_shoe_alarm` 已将 `rga_gate` 从占位符体系中移除，改回模板默认。
|
||
|
||
当前主线模板已将人脸库路径固定为 `./models/face_gallery.db`，后续由部署默认目录解决。
|
||
|
||
### 新增为 profile 驱动占位符
|
||
|
||
- `${display_name}`，如后续用于后台展示元数据或业务标签
|
||
- `${publish_hls_path}`
|
||
- `${publish_rtsp_port}`
|
||
- `${publish_rtsp_path}`
|
||
- `${channel_no}`
|
||
|
||
## 输出发布部分的调整
|
||
|
||
当前 template 中的 publish 输出结构本身是合理的，但其中部分字段不应再写成固定值。
|
||
|
||
建议调整为：
|
||
|
||
- 输出协议结构继续保留在 template
|
||
- 每台设备不同的输出值改为引用 profile 字段
|
||
|
||
建议演进方向：
|
||
|
||
- HLS 输出路径：使用 `${publish_hls_path}`
|
||
- RTSP server 端口：使用 `${publish_rtsp_port}`
|
||
- RTSP server 路径：使用 `${publish_rtsp_path}`
|
||
- External API 中的 `channelNo`：改为使用 `${channel_no}`，不再直接使用 `${name}`
|
||
|
||
原因：
|
||
|
||
- 当前 `${name}` 把实例名和外部业务通道语义混在了一起
|
||
- 对外平台通道号应当是明确字段，而不是靠实例名隐式复用
|
||
- 输出路径和端口显然属于单设备运行属性
|
||
|
||
## 对后台管理模型的影响
|
||
|
||
这套字段边界意味着后台应逐步演进成以下资产模型：
|
||
|
||
### Device
|
||
|
||
由 agent 发现得到的运行对象：
|
||
|
||
- device ID
|
||
- hostname
|
||
- agent 可达性
|
||
- media-server 状态
|
||
- 当前应用配置元数据
|
||
|
||
### Profile
|
||
|
||
与设备一对一绑定的配置资产：
|
||
|
||
- 在独立的 profile 详情页中编辑
|
||
- 承载设备身份、输入、输出和本地资源设置
|
||
|
||
### Template
|
||
|
||
可复用的方案资产：
|
||
|
||
- 在独立的 template 详情页中编辑
|
||
- 承载流水线结构和共享服务参数
|
||
|
||
### Overlay
|
||
|
||
运行模式资产：
|
||
|
||
- 在预览/下发流程中进行选择
|
||
- 不作为长期设备身份配置的主要承载层
|
||
|
||
## 对 UI 的直接含义
|
||
|
||
后台不应再把 profile 仅仅当成一个下拉框。
|
||
|
||
最小方向应当是：
|
||
|
||
1. profile 成为配置资产中的一等对象
|
||
2. 每台设备详情页都要明确显示当前绑定的 profile
|
||
3. 设备显示名应该来自 profile，而不是直接来自 agent 默认命名
|
||
4. 预览/应用页面只负责“选择 profile”，而不应成为 profile 的主要编辑入口
|
||
|
||
## 迁移路径
|
||
|
||
这套设计不要求立刻重写全部配置。更实际的迁移路径是：
|
||
|
||
1. 先定义标准 profile 字段模型
|
||
2. 把 template 中的发布输出字段参数化
|
||
3. 把共享外部服务配置从 profile 迁到 template 参数
|
||
4. 将 `face_gallery_path` 收回部署默认目录
|
||
5. 若模板中的 `rga_gate` 已固定，则收回模板默认或程序默认
|
||
6. 在后台引入 profile 页面和设备-profile 绑定界面
|
||
7. overlay 保持现状，仅做必要清理
|
||
|
||
## 暂不覆盖的内容
|
||
|
||
本设计当前不包含以下内容：
|
||
|
||
- 完整的后台 profile 编辑页布局
|
||
- template 编辑器的 UI schema 生成方式
|
||
- 老 profile JSON 的自动迁移工具
|
||
- template 与 profile 的权限模型
|
||
|
||
这些内容应放到下一轮设计和实施计划中继续展开。
|