配置模板化与渲染设计

目标

以模板为核心管理 RK3588 设备配置，避免为了设备差异、测试参数或临时调参复制完整配置文件。

第一阶段采用离线渲染方式：模板、设备 profile、测试 overlay 合成为一个 root config，再由现有 media-server -c 加载。这样不改变运行入口，也能复用已有 templates / instances 展开逻辑。

目录约定

configs/
  templates/       # 长期维护的 pipeline 模板
  profiles/        # 设备、现场、摄像头差异参数
  overlays/        # 测试或运行场景覆盖
  generated/       # 渲染产物，不手工维护

当前标准模板

configs/templates/workshop_face_shoe_alarm.json 从 configs/full_pipeline_1080p_test_alarm.json 提炼而来，包含当前最完整链路：

RTSP 输入
RGB 预处理
SCRFD 滑窗人脸检测
MobileFaceNet 人脸识别
YOLOv8n 人体检测
人体跟踪
动态 ROI 鞋检测
鞋人关联和颜色判断
OSD
HLS/RTSP 发布
告警、截图、录像、MinIO 上传、External API 上传

模板中保留 DAG、插件结构和生产默认阈值。设备差异通过占位符表达，例如 ${rtsp_url}、${publish_hls_path}、${publish_rtsp_port}、${publish_rtsp_path}、${channel_no}。共享外部服务参数继续保留为模板参数，例如 ${minio_endpoint}、${external_get_token_url}。短视频验证、临时放宽阈值或打开高频日志，应通过 overlay 完成，不应直接改模板。

当前主线模板已明确内收两类默认值：

gallery.path 固定为 ./models/face_gallery.db，由部署时复制到安装目录，不再要求 profile 显式填写 face_gallery_path
rga_gate 在 workshop_face_shoe_alarm 中固定为 main_pipeline_rga，不再作为主 profile 字段

Profile

configs/profiles/local_3588_test.json 描述具体设备或测试盒子的参数。多台设备或多路相机应新增 profile 或在同一 profile 中新增 instances，而不是复制完整 pipeline。

当前主 profile 推荐只保留设备级字段，例如：

display_name
device_code
site_name
rtsp_url
publish_hls_path
publish_rtsp_port
publish_rtsp_path
channel_no

像 face_gallery_path、rga_gate 这类工程运行默认值，不再进入普通 profile 主字段。

Overlay

Overlay 用于测试或运行场景覆盖：

configs/overlays/face_debug.json：打开人脸识别和陌生人候选诊断日志。
configs/overlays/shoe_debug.json：打开鞋子关联和颜色判断 debug。
configs/overlays/face_test_sensitive.json：恢复人脸短视频测试用的灵敏触发阈值。
configs/overlays/shoe_test_sensitive.json：恢复鞋子短视频测试用的灵敏触发阈值。
configs/overlays/production_quiet.json：关闭高频 debug 日志，适合正式运行。

Overlay 支持 instance_overrides."*"，可以一次覆盖所有 instance；也可以使用具体 instance 名只覆盖单路相机。 --overlay 可以指定多次，后指定的 overlay 覆盖同名字段。建议将 debug overlay 和 test-sensitive overlay 分开组合，避免把测试阈值误带入生产。

渲染命令

python tools/render_config.py \
  --template configs/templates/workshop_face_shoe_alarm.json \
  --profile configs/profiles/local_3588_test.json \
  --overlay configs/overlays/face_debug.json \
  --overlay configs/overlays/face_test_sensitive.json \
  --out configs/generated/local_3588_face_debug.json

生产运行通常不加 test-sensitive overlay；需要安静日志时可叠加 configs/overlays/production_quiet.json。

设备运行：

./build/media-server -c configs/generated/local_3588_face_debug.json

configs/generated/*.json 是生成物，不纳入 git，不应手工修改。

运行时展开

渲染工具输出的是包含 templates / instances 的 root config。media-server 加载时继续使用现有 ExpandRootConfig 展开成 graphs。

本次补充了 template executor 保留逻辑，确保从完整配置提炼模板时不会丢失 graph executor 参数。

4.1 KiB Raw Blame History Unescape Escape