Doni/safesight-edge
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bbb787dfbd
safesight-edge/docs/superpowers/specs/2026-04-20-profile-centered-config-design.md

9.7 KiB
Raw Blame History

以 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 的权限模型

这些内容应放到下一轮设计和实施计划中继续展开。