3588AdminBackend/docs/产品化评估与规划.md

产品化评估与后续规划

评估日期：2026-05-06 范围：视觉识别服务（OrangePi3588Media）+ 管理后台（3588AdminBackend）

---

零、第一性原理：这个产品到底该做什么

核心定义

边缘视频分析平台——RK3588 盒子接摄像头，本地 AI 识别（人脸、安全帽、工鞋、行为），通过网络输出结果。

目标用户

• 运维人员：管盒子、配摄像头、看告警、维护人脸库
• 管理者：看统计、看趋势、做决策

核心价值链条

摄像头画面 → AI 识别 → 结果呈现 → 异常告警 → 人员处置

用户真正要做的事就五件：看画面 → 收告警 → 查记录 → 管人员 → 配设备

管理界面五模块

模块	用户任务	当前状态
视频监控	实时看画面、回放告警片段	❌ 完全没有
告警中心	查看告警、处理告警、统计趋势	❌ 完全没有
人脸库	增删改人员、上传照片、导入导出	❌ 只能整文件替换
设备管理	设备列表、配置下发、模型/资源同步	✅ 基本完成
系统设置	备份恢复、服务状态	✅ 基本完成

设计哲学：从"工程师界面"到"管理员界面"

当前后台是技术视角——直接暴露了模板、Profile、识别单元、设备分配等底层概念，强迫用户理解系统内部构造才能使用。

但管理员根本不需要知道这些。他只需要回答三个问题：

1. 系统在正常运行吗？——看画面、看设备状态
2. 检测到什么了吗？——看告警、看统计
3. 告警对不对？——验证告警结果

所以产品应该是三层结构：

层级	面向	内容
监控层（首页）	所有人	实时画面、告警信息流、设备状态——看一眼就知道系统正常不正常
配置层（场景化）	运维人员	☑ 抽烟检测 ☑ 安全帽检测 → 选设备 → 一键启用——不暴露技术细节
专家层（高级设置）	高级用户	模板编辑、Profile参数、模型选择——现有功能保留但折叠隐藏

管理员的典型工作流：

新盒子到货 → 上电自动发现 → 在后台勾选检测场景 → 自动渲染配置下发 → 告警开始推送
     ↑                                        ↓
     └──────── 如果告警不对，打开专家设置微调 ──────────┘

技术细节（模板/Profile/Overlay/模型绑定）全部在后台自动完成，管理员只关心结果。

核心问题

系统能"配"不能"看"——配置下发做得很扎实，但管理人员看不到画面、看不到告警、看不到识别结果。就像一个监控室只有控制台没有显示器。

最紧迫的不是优化流程、加权限、做向导，而是先把"看"的能力补上。

---

一、整体架构评价

两个项目的架构基础扎实：

• media-server：插件化 DAG 流水线，JSON 配置驱动，热更新/回滚，硬件解耦抽象清晰
• managerd：分层架构（API→Service→Storage），RESTful，HTML/template 服务端渲染，无框架依赖

从产品化角度看，两边都有显著缺口，下面按优先级列出。

---

二、视觉识别服务（media-server）

✅ 优势

方面	现状
架构设计	插件+DAG 流水线，热更新、回滚、ABI 校验都有
性能目标	8路1080p实时分析、延迟<500ms，文档明确
算法能力	YOLO检测、人脸检测/识别、PPE、工鞋、行为事件，覆盖主流场景
输出能力	RTSP/HLS推流、MinIO存储、HTTP回调报警、外部API对接
硬件适配	NPU推理+MPP编解码+RGA图像处理，充分利用RK3588

❌ 需要补的

缺口	严重程度	说明
Agent 和管理后端协议不统一	高	/v1/info、/v1/models/status、/v1/resources/status、/v1/face-gallery 等端点是逐步增加的，没有完整 API 文档或版本号协商机制
Agent 配置需要手动填写	高	deploy.sh 模板文件名容易出错（如缺少 std_ 前缀），回退到交互式选择旧配置文件
人脸库上传靠文件拷贝	中	/v1/face-gallery 整体 PUT，没有单个人物增删改、没有人物照片上传接口
告警无统一管理	中	告警配置嵌在 config JSON 里，规则修改需手动编辑 JSON
日志无结构化	中	spdlog 纯文本，无结构化字段，检索困难
监控指标无持久化	中	agent 提供 /v1/metrics 但后端无收集和图表展示
配置变更无历史	低	有 last_good.json 回滚，无变更历史记录

---

三、管理后台（managerd）

✅ 优势

方面	现状
设备管理	UDP 发现 + DB持久化 + 定时刷新 + 离线设备显示
配置管理	模板+Profile+Overlay 三层配置渲染，支持预览和下发
模型/资源管理	标准目录 → 设备状态矩阵比对，SHA256一致性校验
任务系统	批量执行 + SSE 实时推送 + 审计记录

❌ 需要补的

缺口	严重程度	说明
仪表盘是摆设	极高	只汇总设备数量/在线/任务统计，无实时告警、无 NPU 使用率、无识别结果概览。作为产品首页太空了
场景配置太复杂	高	模板→Profile→识别单元→设备分配 四层概念，无向导式配置流程，用户学习成本高
告警管理缺失	高	后台看不到设备告警记录、告警截图、告警趋势
实时预览缺失	高	不能从管理后台直接查看摄像头画面
人脸库管理不完整	高	只能整文件上传 .db，不能增删改单个人物、查看人物列表、上传单张人脸照片
日志检索薄弱	中	只提供设备日志入口，无关键词搜索、时间范围过滤、导出
批量操作不完善	中	无批量升级 agent 二进制、批量重启 media-server
用户权限缺失	中	无登录、无多用户、无操作权限控制
配置导出/导入	低	无设备配置导出、批量导入
国际化	低	全部硬编码中文，出海需 i18n

---

四、两个项目之间的协同问题

问题	说明
配置下发后无验证	后端推送配置 → HTTP 200 → 但无法确认 media-server 热更新是否实际成功
设备重连后状态不一致	设备重启后 agent 不主动同步状态，需等后台 30 秒定时发现
人脸库版本漫游	设备上 cam1~cam5 各有一份 face_gallery.db，版本对齐全靠人工
模型版本管理弱	只比对 SHA256，不知道模型精度/性能差异，无效果评估

---

五、优先级规划

P0（必须做——把"看"的能力补上）

1. 视频监控

   • 从管理后台直接查看摄像头实时画面（RTSP/HLS 转发）
   • 告警片段回放（关联告警记录 + 录像片段）

2. 告警中心

   • 实时告警推送（设备 → agent → 后端 → 页面 SSE）
   • 告警记录列表（时间、设备、规则、截图、视频片段链接）
   • 告警统计趋势（按天/按规则/按设备数量变化）

3. 人脸库管理

   • 人物列表查看（姓名、照片、注册时间）
   • 新增/编辑/删除人物
   • 上传单张人脸照片 + 自动提取特征向量
   • 增量同步到设备（而不是整文件替换）

4. Dashboard 实时化

   • 把视频监控 + 告警信息流 + 设备状态整合到首页

P1（提升易用性）

4. 场景配置向导

   • 逐步引导：选模板 → 填参数 → 选视频源 → 选设备 → 预览 → 下发
   • 取代当前四层概念（模板/Profile/识别单元/设备分配）

5. Agent 主动注册

   • agent 启动时向管理后端发心跳
   • 设备上电即可被纳管，无需等待 UDP 发现

6. 配置模板渲染自动化

   • deploy.sh 默认使用模板渲染，不交互选择
   • 模板文件名修正（std_ 前缀）

P2（提升健壮性）

7. 用户认证和权限 — 登录 + 角色 + 操作日志
8. 告警规则 UI 管理 — 在后台页面上创建/编辑告警规则
9. 日志结构化 + 检索 — agent 输出 JSON 格式日志，后端提供全文检索

---

五.五、检测场景扩展规划

当前已有检测能力

场景	实现方式	状态
安全帽/工鞋/工服	YOLOv8 PPE 检测	✅ 已部署
人脸检测 + 识别	SCRFD + ArcFace	✅ 已部署
通用目标检测	YOLOv8n COCO	✅ 已部署
区域入侵	region_event 行为节点	✅ 已实现
摔倒/打架	action_recog 行为节点	✅ 已实现

需要新增的检测场景

场景	实现思路	AI 依赖	管理界面需求	优先级
抽烟检测	训练抽烟行为分类模型，或 YOLO 检测烟头+手部	需新模型	告警规则：灵敏度、时间段、区域	P0
睡岗检测	姿态估计 + 静止时长判断；或检测人体趴卧姿势	需新模型或复用 pose	告警规则：静止时长阈值、豁免区域	P0
打电话检测	检测手部靠近耳侧 + 手机目标	需新模型	同抽烟检测	P1
明火/烟雾检测	YOLO 火灾检测模型	需新模型	告警规则：灵敏度	P1
离岗检测	检测区域无人 + 超时告警	复用现有检测	告警规则：岗位区域、超时时长	P1
通道堵塞	检测通道区域内目标数量和停留时间	复用现有检测	告警规则：通道区域、堵塞阈值	P2
反光衣检测	高可见度服装分类模型	需新模型	同 PPE 检测	P2
车辆违停	车辆检测 + 停留超时	需车辆检测模型	告警规则：禁停区域、停留时长	P2

实现架构

所有新场景统一走现有插件架构，不增加新的系统复杂度：

摄像头 → 预处理 → AI检测节点 → 结果后处理 → 行为判定节点 → 告警
                                                    ↓
                                              OSD叠加 → 推流/录像

• 新增 AI 模型：编译为 .rknn，通过模型管理页面上传到设备
• 新增插件：如果现有 ai_yolo / ai_face_det 无法覆盖，实现新插入（如 ai_smoking）
• 管理界面：在告警中心增加新规则类型；在识别场景配置中增加场景选择

管理界面的场景化演进

当前配置是"技术视角"（模板→Profile→实例→设备分配），最终演进为"业务视角"：

场景选择：☑ 安全帽检测  ☑ 抽烟检测  ☐ 睡岗检测  ☑ 人脸识别
    ↓
区域设定：标定摄像头监控区域（ROI）
    ↓
规则配置：灵敏度 / 时间段 / 告警动作
    ↓
一键下发：选择设备 → 渲染配置 → 下发

---

六、技术债务清单（后续清理）

项目	说明
cmd/managerd 目录名歧义	既是源码目录又被 gitignore 匹配为二进制
模板函数分散	modelTypeLabel、resourceTypeLabel 等散落在 NewUI 中，应集中管理
agent 配置示例过时	agent.config.example.json 路径与生产环境不一致
deploy.sh 交互选择	应支持完全无交互部署（CI/CD 友好）
测试覆盖率不均匀	web 包测试 193KB，但主要是模板渲染测试，缺少 service 层集成测试