yovision/docs/其他项目的文档/跌倒检测视频接入系统 — 演示与验证开发方案.md

🧪 跌倒检测视频接入系统 — 演示与验证开发方案

来源：Notion · https://app.notion.com/p/3af401dc38a6815297c0f1645631e26f 导出时间：2026-08-01

版本 v1 · 配套文档：《线上生产开发方案》。本文档描述演示与前期验证阶段的做法，与生产架构的关系必须清晰界定。

1. 本阶段的目的（先划清边界）

演示阶段有两个完全不同的目标，容易被混为一谈，必须分开处理：

目标	用什么做	产出
A. 摄像头兼容性验证	MiBeeNvr（现成 NVR）	采购白名单
B. 效果演示给非技术干系人	MiBeeNvr	可看的界面
C. 架构风险验证	200 行自研骨架 + mediamtx	生产代码

关键判断：MiBeeNvr 不是「v0 版本」

Mi-Bee-Studio/MiBeeNvr 在架构上替代的是 mediamtx（它自带 HLS/WebRTC/HTTP-FLV/RTMP/SRT 全套媒体服务），而不是生产方案里要自研的设备管理层。

演示版:  MiBeeNvr（一个 exe，全包）
生产版:  mediamtx + 生成的 API 客户端 + 自研骨架 + 对账器 + NAT 隧道
         ↑ 没有一行代码从演示版继承

它跑通了，对生产架构零验证。NAT 穿透、path 对账、按需拉流、多租户这些真正会翻车的地方，它一个都不涉及（它假设摄像头与自己在同一局域网）。

因此：不要把它包装成第一版系统然后计划后续替换，替换是推倒重来而非迭代。

2. 目标 A/B：MiBeeNvr 作为测试台

2.1 项目基本情况

项	值
仓库	Mi-Bee-Studio/MiBeeNvr
许可	MIT
技术栈	Go + Svelte 5 + SQLite，CGO_ENABLED=0 单二进制
Web UI	端口 9090，内置登录、实时预览、录像、系统指标
规模定位	树莓派 3B / 1GB 内存可跑（homelab 场景）

2.2 为什么适合做兼容性测试台

• ONVIF 摄像头接入局域网后后台自动登记，无需手动扫描
• 认证摄像头进入「待激活」状态等待补凭据；未认证的直接开始录制
• IP 自愈：摄像头换 IP（Wi-Fi 漫游换 AP）时按序列号自动重定位并重连，使用 unicast 探测，可跨路由子网
• 一条 install.sh，10 分钟起来，界面上直接看哪个型号能发现、能出流、能 PTZ

比自己写测试代码快得多，失败信息本身就有价值：某型号它都认不出来，说明该型号 ONVIF 实现有问题，直接从采购清单划掉。

2.3 部署

# 方式一：一键安装
curl -fsSL https://raw.githubusercontent.com/Mi-Bee-Studio/MiBeeNvr/main/install.sh | sudo bash

# 方式二：预编译二进制
wget https://github.com/Mi-Bee-Studio/MiBeeNvr/releases/latest/download/mibee-nvr-amd64
chmod +x mibee-nvr-amd64
./mibee-nvr-amd64 init --password <yourpassword>
./mibee-nvr-amd64 -config mibee-nvr.yaml
# 打开 http://localhost:9090

2.4 使用红线

允许	禁止
实验室环境接自购测试摄像头	接入真实住户家中的摄像头
给干系人做效果演示	作为生产系统的第一版上线
阅读源码借鉴设计	作为长期依赖引入 go.mod

理由：项目 84 star / 10 fork / 1 watcher，且功能面异常宽（SRT、WebRTC WHEP、小米 TUTK P2P、WebDAV、FTP、浏览器端 ONNX 推理、时移录制等），一个体量如此的项目在短时间做出这么宽的面，大概率有大量 AI 辅助生成，不能假设它被真实压测过。本项目是养老场景，摄像头对着卧室和卫生间，未经充分验证的组件出安全问题后果不是技术问题。

2.5 值得借鉴的源码

internal/onvif/     ONVIF 封装（与 EdgeX device-onvif-camera 对比着读）
internal/camera/    健康监控 + 自动修复状态机
internal/store/     SQLite schema 设计

重点看两处真实踩坑设计：IP 自愈（序列号而非 IP 作身份）和待激活状态机（批量开通的中间态）。这两点自己从零设计想不到。

前端 go:embed 打包成单二进制的做法，将来给自研服务加 Web UI 时可直接参考。

3. 目标 C：架构验证骨架（生产代码）

这部分是真正要写的东西，约 200 行，全部为生产代码而非丢弃品。

3.1 范围

mediamtx（配置文件里写死 5 路测试摄像头）
        +
单个 Go 程序:
    ONVIF 连接 -> GetStreamUri -> 调 mediamtx API 建 path -> 每 30s 探活

跑通之后就已经站在生产架构上了，后面是往上加（SQLite、对账、隧道、多租户），不是推倒。

3.2 代码结构

cmd/edge-agent/main.go
internal/
  onvif/      连接、GetProfiles、GetStreamUri、SetSystemDateAndTime
  store/      先用 SQLite，schema 与生产 Postgres 保持一致
  mtx/        oapi-codegen 生成的客户端 + 薄封装
  reconcile/  最小对账循环（幂等 + 退避）
  probe/      探活 goroutine

3.3 从第一天就要遵守的约定

约定	原因
设备身份用序列号，不用 IP	DHCP / Wi-Fi 漫游会换 IP
建 path 前先查是否存在	盲目 add 会踢掉正在推流的 publisher
改配置前比对哈希	同上；没变就不调 API
重试用指数退避	无事务，只能靠幂等重试
并发限流（信号量 8）	避免打爆 mediamtx API
设备状态含 pending_activation	批量开通必然有凭据待补的中间态

3.4 mediamtx 侧最小配置

api: yes
apiAddress: :9997

pathDefaults:
  sourceOnDemand: yes
  sourceOnDemandCloseAfter: 30s
  rtspTransport: tcp

4. 摄像头兼容性验证清单（M0 出口标准）

采购 3-5 个候选型号，这是整个项目第一件要做的事。

4.1 必过项

验证项	通过标准	不通过的后果
GetProfiles	返回至少两个 profile（主码流 + 子码流）	无法自动获取子码流，需人工配置
GetStreamUri	返回可用的 RTSP URL	无法自动化开通
SetSystemDateAndTime	调用成功且生效	事件时间戳不可信
子码流规格	可设为 640x360 或 704x576 左右	带宽和算力估算失效
编码格式	支持 H.264	H.265 浏览器无法原生预览
WS-Security 认证	digest 或 usernametoken 任一可用	认证失败
RTSP over TCP	长时间稳定不断流	家庭网络下 UDP 丢包严重

4.2 加分项

• 支持 ONVIF 事件订阅（移动侦测）
• 支持修改 GOP 长度（影响回捞缓存的关键帧间隔）
• 支持创建独立的只读用户（不必用 admin 凭据接入）

4.3 结论落地

任何一项必过项失败的型号，直接从采购清单划掉。后期写兼容代码的成本远高于换型号。验证结果整理成表格，作为采购白名单归档。

5. 阶段产出如何流入生产

演示阶段产出	流向
采购白名单	生产方案的硬件选型
骨架代码（onvif / store / mtx / reconcile）	直接成为生产代码基础
MiBeeNvr 的设计借鉴（IP 自愈、待激活态）	写进生产的对账器与状态机
MiBeeNvr 的界面截图	干系人沟通材料
MiBeeNvr 本身	不进入生产

6. 关于 Web 管理界面

生产组合（mediamtx + 自研服务）没有现成的管理界面。三个选择：

1. 前期不做 UI — 用 REST API + 脚本撑过验证期。250 路的开通本来就是批量脚本，不该手点。
2. 临时用 go2rtc 的 1984 页面看流状态 — 但它默认无密码，局域网内任何人可访问，必须在配置里关闭或用防火墙隔离。
3. 正式做时长在自研服务上 — 因为要展示的是「家庭 -> 摄像头 -> 流状态」的业务视图，第三方面板展示的是「path 列表」，不是一回事。

补充：mediamtx 本身没有管理后台，作者明确表示精力有限、优先保证核心稳定，欢迎社区贡献。社区面板有 mediamtx-dashboard、lgcshy/mediamtx-ui、nabaco/mediamtx-ui、bcanfield/mediamtx-connect 等，均为独立进程通过 API 对接，可按需临时使用。