730 lines
34 KiB
Markdown
730 lines
34 KiB
Markdown
# 🏗️ 跌倒检测视频接入系统 — 线上生产开发方案
|
||
|
||
> 来源：Notion · https://app.notion.com/p/3af401dc38a681c29985ffdbd0e9f3d1
|
||
> 导出时间：2026-08-01
|
||
|
||
> 版本 v1 · 面向 200 户 / 250 路 IP 摄像头的跌倒检测视频接入系统。本文档描述**生产环境**架构与开发规范。演示与验证阶段见配套文档《演示与验证开发方案》。
|
||
|
||
# 1. 目标与约束
|
||
|
||
| 项 | 值 |
|
||
| --- | --- |
|
||
| 接入规模 | 约 200 个家庭，250 路 IP 摄像头 |
|
||
| 业务目标 | 视频流分析实现摔倒动作检测 |
|
||
| 关键约束 | 摄像头位于家庭路由器 NAT 之后，中心机房无法主动访问 |
|
||
| 未来扩展 | 毫米波雷达等异构传感器（架构必须预留） |
|
||
| 技术栈 | Go 为主，媒体层复用成熟开源组件 |
|
||
|
||
# 2. 架构总览
|
||
|
||
系统分为三个平面，接缝要尽可能少。
|
||
|
||
| 平面 | 组件 | 职责 |
|
||
| --- | --- | --- |
|
||
| 流控制面 | mediamtx + 自研 Go 编排服务 | path 生命周期、按需拉流、录制、对账 |
|
||
| 设备业务面 | 自研 Go 服务（单 exe）+ Postgres | 家庭/摄像头台账、凭据、在线状态、开通与停用 |
|
||
| 感知面 | 自研推理服务 | 抽帧、姿态模型、跌倒判定 |
|
||
|
||
## 2.1 控制面与数据面分离（核心决策）
|
||
|
||
这是解决 NAT 问题的关键：
|
||
|
||
- **控制面走隧道**：每户边缘盒子跑 WireGuard，中心服务通过隧道访问摄像头的 ONVIF 端口。ONVIF 控制流量极小，只在配置和探活时产生。
|
||
- **数据面走推流**：视频不走隧道。边缘盒子主动把流推到中心 mediamtx（RTSP announce / SRT / RTMP）。
|
||
|
||
### IP 规划
|
||
|
||
每户分配一个不冲突的内网段，摄像头地址确定化：
|
||
|
||
```
|
||
10.<户号高位>.<户号低位>.0/24
|
||
摄像头固定从 .10 起分配
|
||
```
|
||
|
||
这样设备地址可预测，不依赖自动发现，也便于对账。
|
||
|
||
# 3. 组件选型
|
||
|
||
| 组件 | 仓库 | 角色 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| mediamtx | bluenviron/mediamtx | 媒体路由 | MIT，Go，单二进制。协议互转、按需拉流、录制、鉴权回调、Prometheus |
|
||
| gortsplib | bluenviron/gortsplib | RTSP 库 | mediamtx 作者同款。用于自研 worker 拉流并做帧级丢弃 |
|
||
| ONVIF 库 | IOTechSystems/onvif 或 use-go/onvif | 设备控制 | 前者是 EdgeX device-onvif-camera 内部使用的增强版 |
|
||
| API 客户端 | 自行用 oapi-codegen 从 mediamtx OpenAPI 生成 | mediamtx 控制 | 见 3.1 |
|
||
| 边缘推流 | mediamtx 或 go2rtc | 边缘盒子 | 杂牌摄像头兼容性差时用 go2rtc 兜底 |
|
||
|
||
## 3.1 关于 mediamtx-sdk-go
|
||
|
||
zbiljic/mediamtx-sdk-go 是个人项目，用 ogen 从官方 OpenAPI 规范生成。**建议自行生成客户端**，避免依赖第三方更新节奏：
|
||
|
||
```bash
|
||
# 从 mediamtx 仓库取 apidocs/openapi.yaml
|
||
oapi-codegen -package mtxapi -generate types,client openapi.yaml > mtxapi/client.go
|
||
```
|
||
|
||
好处是版本跟随实际部署的 mediamtx，不会因上游停更而受阻。
|
||
|
||
# 4. 关键设计决策
|
||
|
||
## 4.1 mediamtx 只管流，不管设备
|
||
|
||
mediamtx 的数据模型里没有 camera 实体，只有 path（名字 + source URL + 配置）。它不知道 URL 背后是哪个品牌、是否同一台设备的两条码流、这户是否欠费。
|
||
|
||
必须自建设备业务面。三条硬约束：
|
||
|
||
1. **API 改的配置不落盘** — mediamtx 重启后通过 API 添加的 path 全部消失。设备台账必须在自己的数据库，服务启动时 replay。
|
||
2. **改配置会踢掉当前发布者** — 任何通过 API 的 path 配置变更都会触发 path reload，断开正在推流的 source，即使改动本身与它无关。因此改配置前必须先判断「真的变了吗」，没变绝对不调 API。
|
||
3. **没有 enable/disable 开关** — 只能删除 path，不能停用。
|
||
|
||
## 4.2 按需拉流（sourceOnDemand）
|
||
|
||
```yaml
|
||
pathDefaults:
|
||
sourceOnDemand: yes
|
||
sourceOnDemandStartTimeout: 10s
|
||
sourceOnDemandCloseAfter: 30s
|
||
```
|
||
|
||
语义：只有 reader 连上来时才去连摄像头，没人看就断开。对本系统等价于「AI worker 订阅 = 开始分析，取消订阅 = 自动停止拉流」，是最省带宽和算力的开关方式。
|
||
|
||
## 4.3 停用某路摄像头的四种粒度
|
||
|
||
按副作用从轻到重：
|
||
|
||
| 需求 | 做法 | 效果 |
|
||
| --- | --- | --- |
|
||
| 暂停分析，流保留 | worker 取消订阅 | 配合 sourceOnDemand 自动停止拉流，随时恢复 |
|
||
| 立即断开，允许重连 | `POST /v3/rtspsessions/kick/{id}`（RTMP/SRT/WebRTC 各有对应接口） | 断一次，客户端会重连 |
|
||
| 永久拒绝 | 鉴权服务对该 path 返回 401 + kick | 推不上来，且无需改 mediamtx 配置 |
|
||
| 彻底移除 | `DELETE /v3/config/paths/delete/{name}` | path 消失，重启后靠自有库恢复 |
|
||
|
||
标准组合：先 kick 断开、再让鉴权拒绝 = 立刻生效且不会重连。
|
||
|
||
## 4.4 鉴权用 HTTP 回调
|
||
|
||
```yaml
|
||
authMethod: http
|
||
authHTTPAddress: http://control-plane:8080/mtx-auth
|
||
paths:
|
||
"~^home-.*$":
|
||
source: publisher
|
||
```
|
||
|
||
每次边缘端推流，mediamtx POST 到自有鉴权服务，带 user/password/path/IP/action。返回 200 或 401 即控制了「哪些摄像头允许接入」。注销、欠费、隐私模式全部在自有业务库判断，mediamtx 侧零配置变更。
|
||
|
||
## 4.5 为雷达预留
|
||
|
||
未来接入毫米波雷达后，架构会发生一次反转：雷达 7x24 常开做一级触发，视频做二级确认。
|
||
|
||
- 算力：常态 GPU 占用接近零，只在事件时唤醒推理。250 路常态推理需 2-4 张卡，改为触发式后一张即可。
|
||
- 隐私：卫生间、卧室只放雷达不放摄像头；客厅摄像头平时不解码不存储。这是养老场景能否落地的分水岭。
|
||
- 误报：纯视觉对遮挡/逆光/坐下误报高，纯雷达对快速坐下和弯腰误判，两级串联是行业标准做法。
|
||
|
||
当前阶段的设计要求：设备表结构不要写死为「摄像头表」，预留 device_type；编排服务的触发入口要独立成一个 handler，将来接雷达告警时不用改动流控制逻辑。
|
||
|
||
# 5. 数据模型
|
||
|
||
```sql
|
||
-- 家庭
|
||
CREATE TABLE households (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
code TEXT UNIQUE NOT NULL,
|
||
subnet CIDR NOT NULL,
|
||
status TEXT NOT NULL,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||
);
|
||
|
||
-- 设备（不要命名为 cameras，为雷达预留）
|
||
CREATE TABLE devices (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
household_id BIGINT NOT NULL REFERENCES households(id),
|
||
device_type TEXT NOT NULL,
|
||
serial TEXT UNIQUE NOT NULL,
|
||
vendor TEXT,
|
||
model TEXT,
|
||
onvif_addr TEXT,
|
||
onvif_user TEXT,
|
||
onvif_secret TEXT,
|
||
state TEXT NOT NULL,
|
||
last_seen_at TIMESTAMPTZ
|
||
);
|
||
|
||
-- 流绑定
|
||
CREATE TABLE stream_bindings (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
device_id BIGINT NOT NULL REFERENCES devices(id),
|
||
mtx_instance TEXT NOT NULL,
|
||
path_name TEXT NOT NULL,
|
||
rtsp_url TEXT,
|
||
profile_token TEXT,
|
||
enabled BOOLEAN NOT NULL DEFAULT true,
|
||
UNIQUE (mtx_instance, path_name)
|
||
);
|
||
|
||
-- 对账状态
|
||
CREATE TABLE sync_state (
|
||
binding_id BIGINT PRIMARY KEY REFERENCES stream_bindings(id),
|
||
desired_hash TEXT,
|
||
applied_hash TEXT,
|
||
last_error TEXT,
|
||
retry_after TIMESTAMPTZ
|
||
);
|
||
```
|
||
|
||
字段说明：device_type 取 camera / radar / button；state 取 pending_activation / active / disabled；onvif_secret 需加密存储；rtsp_url 存 ONVIF GetStreamUri 返回的子码流地址。
|
||
|
||
**设计要点**：以序列号而非 IP 作为设备身份。家庭 Wi-Fi 漫游或 DHCP 续租会导致 IP 变化，按序列号重定位是唯一可靠的做法。
|
||
|
||
# 6. 对账器（Reconciler）
|
||
|
||
系统最容易出竞态的地方，也是自研工作量的核心。
|
||
|
||
## 6.1 职责
|
||
|
||
数据库是唯一真相源，**mediamtx 和 Savant 都是被驱动的从属状态**。对账器持续把三者拉齐。
|
||
|
||
关键原则：**水平触发（level-triggered）而非边沿触发（edge-triggered）**。对账器不处理「事件」，只不断比对期望状态与实际状态并向期望收敛。这是处理部分失败的唯一可行方案（见 6.5）。
|
||
|
||
```go
|
||
func (r *Reconciler) Sync(ctx context.Context) error {
|
||
desired := r.db.EnabledBindings() // 真相源
|
||
actual := r.mtx.ListPaths(ctx) // 生成的 API 客户端
|
||
|
||
add, del, update := diff(desired, actual)
|
||
|
||
sem := semaphore.NewWeighted(8) // 限流，别打爆 API
|
||
for _, b := range add {
|
||
// 幂等：已存在则跳过，绝不盲目 add（会踢掉 publisher）
|
||
// 重试：指数退避，失败写回 sync_state.retry_after
|
||
}
|
||
for _, b := range update {
|
||
// 关键：先比对 desired_hash 与 applied_hash
|
||
// 没变就绝对不调 API
|
||
}
|
||
// del 同理
|
||
}
|
||
```
|
||
|
||
## 6.2 必须处理的边界情况
|
||
|
||
| 情况 | 处理 |
|
||
| --- | --- |
|
||
| mediamtx 重启 | path 数量骤降触发全量重建；也要有定时全量对账兜底 |
|
||
| 配置变更踢 publisher | 变更前比对哈希；确需变更时先标记为维护窗口 |
|
||
| API 批量失败 | 无事务。第 137 个失败时前 136 个已生效，必须幂等重试而非回滚 |
|
||
| 并发打满 | 信号量限流到 8 并发 |
|
||
| path 漂移 | 定时全量 diff，处理人工在 mediamtx 侧的手改 |
|
||
| 设备离线 vs 无人订阅 | 两者在 mediamtx 侧表现相同，靠自有探活区分 |
|
||
|
||
## 6.3 探活
|
||
|
||
独立 goroutine，对每个 active 设备定期做 ONVIF 轻量调用（如 GetSystemDateAndTime），指数退避，更新 devices.last_seen_at。**不要用 path 在线状态代替设备在线状态**。
|
||
|
||
## 6.4 双系统对账：mediamtx + Savant
|
||
|
||
引入 Savant（第 9 节）后，一个设备的完整开通需要在**两个独立系统**上各做一次操作，而两者之间**没有分布式事务**。
|
||
|
||
### 数据模型调整
|
||
|
||
第 5 节的 `sync_state` 拆成每系统一行：
|
||
|
||
```sql
|
||
DROP TABLE sync_state;
|
||
|
||
CREATE TABLE sync_state (
|
||
binding_id BIGINT NOT NULL REFERENCES stream_bindings(id),
|
||
system TEXT NOT NULL, -- 'mediamtx' | 'savant'
|
||
desired_hash TEXT,
|
||
applied_hash TEXT, -- NULL = 尚未生效
|
||
last_error TEXT,
|
||
attempt INT NOT NULL DEFAULT 0,
|
||
retry_after TIMESTAMPTZ,
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||
PRIMARY KEY (binding_id, system)
|
||
);
|
||
|
||
-- 便于运维发现中间态
|
||
CREATE VIEW binding_health AS
|
||
SELECT b.id, b.path_name,
|
||
bool_and(s.desired_hash = s.applied_hash) AS converged,
|
||
max(s.attempt) AS max_attempt
|
||
FROM stream_bindings b JOIN sync_state s ON s.binding_id = b.id
|
||
WHERE b.enabled
|
||
GROUP BY b.id, b.path_name;
|
||
```
|
||
|
||
一个 binding 只有当**两行都收敛**时才算真正开通。`converged = false` 的就是中间态，必须在 Grafana 上可见。
|
||
|
||
### 操作顺序（不对称，必须遵守）
|
||
|
||
| 动作 | 顺序 | 理由 |
|
||
| --- | --- | --- |
|
||
| **开通** | mediamtx 先 → Savant 后 | 流必须先存在，Savant 才能挂上去；反之 Savant 会反复重试连不存在的源 |
|
||
| **停用** | Savant 先 → mediamtx 后 | 先停消费再断流；反之 Savant 会看到源断开并报错告警 |
|
||
|
||
建立和拆除是逆序的，这一点要写进代码注释，很容易被后来人改错。
|
||
|
||
### ⚠️ 关键耦合：Savant source = mediamtx reader
|
||
|
||
`sourceOnDemand: yes` 的语义是「有 reader 才拉流」。**Savant 挂上 source 就是一个 reader**，也就是说：
|
||
|
||
- 挂载 Savant source → mediamtx 立即开始拉流 → 产生带宽和连接开销
|
||
- 卸载 Savant source → 30s 后（`sourceOnDemandCloseAfter`）mediamtx 自动断流
|
||
|
||
因此：**「暂停分析」必须通过卸载 Savant source 实现，不能只在 Python 插件里 `return`**。后者会让 mediamtx 持续拉流、带宽白烧，而监控上看起来一切正常。
|
||
|
||
这也意味着第 4.3 节「停用粒度」表格里的第一行（暂停分析）具体实现就是卸载 Savant source。
|
||
|
||
## 6.5 部分失败：不回滚，只收敛
|
||
|
||
典型场景：mediamtx path 建好了，Savant source 挂载失败。
|
||
|
||
**错误做法**：回滚删掉 mediamtx path。回滚本身也会失败，那时候你需要回滚的回滚，无限递归。
|
||
|
||
**正确做法**：保留已成功的部分，把失败的那行 `sync_state` 标为未收敛 + 退避重试。下一轮对账会看到 mediamtx 已收敛（跳过）、Savant 未收敛（重试）。
|
||
|
||
代价：**会有一个无人消费的 mediamtx path 短暂存在**。因为 `sourceOnDemand` 的存在，这个 path 没有 reader 就不会拉流，**成本接近零**。这是 `sourceOnDemand` 给双系统对账带来的额外好处——中间态是安全的。
|
||
|
||
### 重试预算
|
||
|
||
| 参数 | 值 |
|
||
| --- | --- |
|
||
| 初始退避 | 5s |
|
||
| 退避倍率 | 2x，上限 5min |
|
||
| 告警阈值 | `attempt > 5` 且持续 > 15min → 告警 |
|
||
| 放弃阈值 | 不放弃。持续重试，靠告警引入人工 |
|
||
|
||
不设放弃阈值是故意的：对账器放弃了，设备就静默地不工作了，而这是养老监护场景不可接受的失败模式。
|
||
|
||
## 6.6 孤儿资源清理
|
||
|
||
对账不只是「把缺的补上」，还要「把多的删掉」。三类孤儿：
|
||
|
||
| 类型 | 成因 | 处理 |
|
||
| --- | --- | --- |
|
||
| mediamtx 有 path，DB 无 | 人工手改、旧版本残留 | 删除（但先日志，不静默） |
|
||
| Savant 有 source，DB 无 | 同上 | 卸载 |
|
||
| DB 有 binding，两边都无且长期未收敛 | 开通失败后无人处理 | 告警，不自动删 DB |
|
||
|
||
**清理动作必须有安全闸**：单轮对账删除量超过总量的 10%（如 25 路）时**停止并告警**，不执行。这道闸是防数据库连接异常或查询 bug 导致的「期望集合意外为空」——那会把 250 路全部拆掉。
|
||
|
||
## 6.7 完整循环
|
||
|
||
```go
|
||
func (r *Reconciler) Sync(ctx context.Context) error {
|
||
desired := r.db.EnabledBindings() // 真相源
|
||
if len(desired) == 0 && r.lastDesiredCount > 0 {
|
||
return ErrSuspiciousEmptyDesired // 6.6 安全闸
|
||
}
|
||
|
||
mtxActual, err1 := r.mtx.ListPaths(ctx) // 分片内所有实例
|
||
svActual, err2 := r.savant.ListSources(ctx)
|
||
if err1 != nil || err2 != nil {
|
||
return errors.Join(err1, err2) // 拿不到实际状态就不动作
|
||
}
|
||
|
||
plan := buildPlan(desired, mtxActual, svActual)
|
||
// plan 内部已按 6.4 的顺序约束排序：
|
||
// teardown: savant 先 → mtx 后
|
||
// setup: mtx 先 → savant 后
|
||
|
||
for _, step := range plan {
|
||
if !step.DueForRetry(now) { continue } // 退避窗口未到
|
||
if step.DesiredHash == step.AppliedHash { continue } // 没变，绝不调 API
|
||
|
||
sem.Acquire(ctx, 1) // 每系统独立限流
|
||
go func() {
|
||
defer sem.Release(1)
|
||
if err := step.Apply(ctx); err != nil {
|
||
r.db.MarkFailed(step, err) // 退避，不回滚
|
||
return
|
||
}
|
||
r.db.MarkApplied(step) // applied_hash = desired_hash
|
||
}()
|
||
}
|
||
}
|
||
```
|
||
|
||
**两个独立的限流预算**：mediamtx API 和 Savant API 各自 8 并发，不共享信号量。否则一个系统变慢会饿死另一个。
|
||
|
||
**循环周期**：正常 30s；有未收敛项时降到 5s；另有每 10min 一次的全量对账（含孤儿扫描）。
|
||
|
||
## 6.8 必须暴露的指标
|
||
|
||
| 指标 | 用途 |
|
||
| --- | --- |
|
||
| `reconciler_unconverged_bindings{system}` | 核心健康指标，持续 > 0 即异常 |
|
||
| `reconciler_apply_duration_seconds{system,action}` | 发现 API 变慢 |
|
||
| `reconciler_orphans_detected{type}` | 有人手改了生产系统 |
|
||
| `reconciler_safety_brake_triggered` | 安全闸触发，**应该直接呼叫**人 |
|
||
| `reconciler_loop_duration_seconds` | 循环超时 = 规模到顶，该分片了 |
|
||
|
||
# 7. mediamtx 配置要点
|
||
|
||
```yaml
|
||
api: yes
|
||
apiAddress: :9997
|
||
|
||
metrics: yes
|
||
metricsAddress: :9998
|
||
|
||
authMethod: http
|
||
authHTTPAddress: http://control-plane:8080/mtx-auth
|
||
|
||
pathDefaults:
|
||
sourceOnDemand: yes
|
||
sourceOnDemandCloseAfter: 30s
|
||
rtspTransport: tcp # 家庭网络下 UDP 丢包严重
|
||
record: no
|
||
recordDeleteAfter: 7d
|
||
runOnOnline: curl -s -X POST http://control-plane:8080/hooks/online?path=$MTX_PATH
|
||
runOnOffline: curl -s -X POST http://control-plane:8080/hooks/offline?path=$MTX_PATH
|
||
|
||
paths:
|
||
"~^home-(\\d+)-cam(\\d+)$":
|
||
source: publisher
|
||
```
|
||
|
||
用一条正则 path 兜底，不要写 250 条静态配置。
|
||
|
||
> 注意：v1.19.x 的钩子命名为 runOnAvailable / runOnUnavailable / runOnOnline / runOnOffline，与旧版 runOnReady / runOnNotReady 不同。部署前核对所用版本的配置参考。
|
||
|
||
# 8. 容量与分片
|
||
|
||
## 8.1 带宽
|
||
|
||
| 项 | 估算 |
|
||
| --- | --- |
|
||
| 250 路子码流 640x360 @ 512 kbps | 约 125 Mbps 常态入向 |
|
||
| 250 路主码流 | 1-1.5 Gbps（不可行，必须用子码流做检测） |
|
||
|
||
## 8.2 算力
|
||
|
||
- 抽帧到 5 fps：250 x 5 = 1250 帧/秒解码
|
||
- CPU 软解不可行，需 NVDEC 或边缘解码
|
||
- 用 gortsplib 在 Go 侧做帧级丢弃（只保留关键帧/按抽帧间隔），比起用 ffmpeg 子进程可省约 70% 解码开销
|
||
|
||
## 8.3 分片
|
||
|
||
- 单 mediamtx 实例建议承载 60-80 路，250 路分 3-4 个实例
|
||
- 分片键用家庭 ID，映射存在 stream_bindings.mtx_instance
|
||
- 不要单实例硬扛：进程挂掉影响面过大，且默认 writeQueueSize: 512 下 250 路的内存与 GC 压力不小
|
||
|
||
# 9. 感知面：Savant 推理流水线
|
||
|
||
> 本节取代第 2 节表格中「感知面 = 自研推理服务」的占位描述。
|
||
|
||
## 9.1 为什么用框架而非完全自研
|
||
|
||
开源社区没有「批量摄像头摔倒检测」的成品（算法是差异化，不会有人开源），但有成熟的**多路视频分析流水线框架**。算法是自己的，工程化用现成的。
|
||
|
||
选定 **Savant**（insight-platform/Savant），基于 NVIDIA DeepStream 的高层框架，声明式 YAML + Python 插件函数。三个决定性理由：
|
||
|
||
1. **故障隔离** — 原生 DeepStream 中数据流与 pipeline 紧耦合，任一源崩溃则整个 pipeline 崩溃，重启加载模型要数秒且期间丢数据。Savant 的 adapter 通过 ZeroMQ 与框架通信，adapter 挂掉不影响 pipeline。200 户家庭网络掉线是常态，**这是 250 路规模的生死线**。
|
||
2. **可配置降级策略** — 可设为实时模式（算力不足时主动丢数据）或高吞吐模式（保证处理全部数据）。本系统选**实时模式**，丢帧优于积压崩溃。
|
||
3. **Replay（按需与非线性处理）** — REST 控制的录制/回放/转推服务，直接对应阶段二的雷达触发式二级确认。
|
||
|
||
同一套代码可跑在 Jetson（Orin Nano/NX/AGX）和数据中心 GPU 上，与本方案的边缘/中心混合部署契合。
|
||
|
||
**代价**：必须 NVIDIA 硬件（Turing/Ampere/Ada/Hopper/Blackwell 或 Jetson），与 DeepStream 版本强绑定（需查对照表），学习曲线陡，无企业支持。
|
||
|
||
**备选**：Pipeless（Rust，不绑 NVIDIA，支持 ONNX Runtime/OpenVINO/TensorRT，HTTP 动态增删流）——若硬件选型变更或规模缩小时启用。
|
||
|
||
## 9.2 模型选型与许可警告
|
||
|
||
> ⚠️ **Ultralytics YOLO 是 AGPL-3.0**。YOLOv8/v11 系列仓库默认对所有用户采用 AGPL-3.0；要集成进商业产品和服务而不遵守其开源要求，必须购买 Enterprise License。本项目是面向付费用户的网络服务，落在 AGPL 第 13 条覆盖范围内，严格执行则需开源整个服务端。**必须在 M3 前做出决定：买授权，或换模型。**
|
||
|
||
推荐替代：**RTMPose / RTMO**（MMPose 项目，Apache-2.0）
|
||
|
||
- RTMPose-m：COCO 75.8% AP，GTX 1660 Ti + TensorRT 下 430+ FPS，Intel i7-11700 CPU + ONNXRuntime 下 90+ FPS
|
||
- 支持 ONNXRuntime、TensorRT、ncnn、OpenVINO、RKNN 多种部署后端（通过 MMDeploy）
|
||
- 关键点定义同为 COCO 17 点，**现有判定算法基本不用改**
|
||
- 430 FPS 的单卡吞吐意味着第 8 节估算的 1250 fps 需求可用 2-3 张中端卡满足
|
||
|
||
## 9.3 Pipeline 架构
|
||
|
||
```
|
||
边缘推流 → mediamtx（250 路汇聚，按需拉流）
|
||
↓ RTSP
|
||
Savant RTSP source adapter（多路复用 + 故障隔离）
|
||
↓ ZeroMQ / Protobuf
|
||
Buffer Adapter（磁盘持久化缓冲，抗突发）
|
||
↓
|
||
Savant module
|
||
├─ RTMPose / TensorRT（姿态关键点）
|
||
└─ Python 插件：时序窗口 + 跌倒判定（**自研部分**）
|
||
↓ ZeroMQ / Protobuf
|
||
Go 控制面（告警、去重、防抖、通知）
|
||
```
|
||
|
||
需要自己写的只有中间那个 Python 插件，前后两段是现成的。
|
||
|
||
## 9.4 与 Go 控制面的对接契约
|
||
|
||
一条 pipeline 是自给自足的服务，通过高性能流式 API 与外界通信，视频和元数据统一使用 Protocol Buffers 协议。
|
||
|
||
| 需求 | 通道 | 语言无关 |
|
||
| --- | --- | --- |
|
||
| 接收检测结果 | 直接订阅 sink 的 ZeroMQ 端点，解 protobuf | ✅ |
|
||
| 动态增删流 | 动态挂载/卸载 source 与 sink，无需重载 pipeline | ✅ |
|
||
| 回放/回捞 | Replay 服务的 REST 接口 | ✅ |
|
||
| 程序化灌数据/调试 | Client SDK（**仅 Python**，集成 OpenTelemetry） | ❌ |
|
||
|
||
**设计约束：优先走 ZeroMQ 和 REST 两条语言无关通道，Go 服务不得依赖 Python 中间层。** Client SDK 仅用于算法调试和测试。
|
||
|
||
因为两边都是 API 驱动，**第 6 节的对账器可以同时驱动 mediamtx 和 Savant**：开通 = 建 path + 挂 source；停用 = kick + 卸 source。逻辑写在同一个 reconciler 里。
|
||
|
||
## 9.5 关键配置决策
|
||
|
||
**必须开启 Buffer Adapter**。它实现了 adapter 与 module 之间的持久化事务性磁盘缓冲，用于支撑资源消耗不可预测的 pipeline、抗住流量突发，并把自身条目数和大小导出到 Prometheus。
|
||
|
||
> 本场景天然有突发：夜里安静无事，早上起床时段几十户同时有活动。**一开始就加上，别等出问题再补。**
|
||
|
||
**AO-RTSP Sink 仅用于调试**。它把处理后、带元数据标注的视频通过 RTSP 和 LL-HLS 播出去，用来直观确认某一路的处理效果。
|
||
|
||
> ⚠️ **硬件限制**：GeForce 系列显卡同时硬件编码的流数上限为 **3**。若给多路挂 AO-RTSP 可视化，消费级卡直接卡在 3 路，需 Quadro/Tesla/L4 类专业卡。**不要做成常态功能。**
|
||
|
||
**开发期开 Development Server**：支持改代码动态重载、不重启 pipeline，还能从 IDE 远程开发跑在 Jetson 或服务器上的代码。原生 DeepStream 改一行要重启加载模型等几十秒，这个工具能省大量时间。
|
||
|
||
## 9.6 可观测
|
||
|
||
Savant 没有管理界面（与 mediamtx 同构），但可观测完整：
|
||
|
||
- **Prometheus + Grafana**：pipeline 和 buffer adapter 导出运行指标，开发者可声明自定义指标与系统指标一起导出。**把每路的人体检出率、跌倒候选数、推理延迟声明成自定义指标** → Grafana 上就是现成运营看板
|
||
- **OpenTelemetry → Jaeger**：排查单帧处理延迟
|
||
- mediamtx 也出 Prometheus 指标，**一个 Grafana 全收**，前期不用写一行前端代码
|
||
|
||
## 9.7 算法分层
|
||
|
||
| 层 | 内容 | 位置 |
|
||
| --- | --- | --- |
|
||
| 姿态提取 | RTMPose，COCO 17 关键点 | Savant 推理单元 |
|
||
| 单帧启发式 | 包围框宽高比、重心高度、躯干角度 | Python 插件（现有算法） |
|
||
| 时序判定 | 30 帧滑窗，静态位置 + 动态速度特征 | Python 插件（待建） |
|
||
| 事件后处理 | 去重、防抖、多源融合 | Go 控制面 |
|
||
|
||
参考实现：
|
||
|
||
- `GajuuzZ/Human-Falling-Detect-Tracks` — ST-GCN 对每个人轨迹的每 30 帧预测动作，支持站立/行走/坐下/躺下/起身/坐下动作/跌倒共 7 类。**七分类而非二分类是降误报的关键**
|
||
- `kelsonbatista/fall-detection-ai-project` — YOLO-pose 逐帧抽 128 维特征（静态位置 + 动态速度），30 帧窗口喂 LSTM。注意 GPL-3.0
|
||
|
||
**负面经验**：`Y-B-Class-Projects/Human-Fall-Detection` 用约 500 张网络图片训 LSTM 完全学不会，最后退回 if-else 规则。**小数据量下时序模型学不动，先解决数据再上模型。**
|
||
|
||
## 9.8 本节风险
|
||
|
||
| 风险 | 缓解 |
|
||
| --- | --- |
|
||
| Ultralytics AGPL-3.0 污染商业代码 | M3 前决策：买授权或换 RTMPose |
|
||
| 公开数据集与真实场景脱节（Le2i/UR Fall 均为演员摆拍的表演性跌倒，真实老人常为缓慢滑落、部分遮挡） | M3 首要产出是**真实误报案例库**，不是模型指标 |
|
||
| Savant 学习曲线陡 | M1 阶段先用 5 路跑通一条 pipeline，测出单路真实吞吐再反推卡数 |
|
||
| 绑定 NVIDIA + DeepStream 版本 | 预留 Pipeless 作为备选；推理代码与框架解耦 |
|
||
| 常态全量推理成本 | **Savant 不降低算力需求**，只解决「怎么高效跑 250 路」。雷达一级触发仍是唯一的数量级优化，与 Replay 配套使用 |
|
||
|
||
**无雷达时的过渡方案**：参考 Frigate 的「先用运动侦测过滤、有变化才跑推理」思路，与雷达触发是同一逻辑。
|
||
|
||
# 10. 预警信息管理系统
|
||
|
||
> 接住第 9 节的输出：检测出来之后怎么办。**本节描述的是产品本身，不是辅助设施。**
|
||
|
||
## 10.1 两类告警必须彻底分开
|
||
|
||
| | 运维告警 | 业务预警 |
|
||
| --- | --- | --- |
|
||
| 触发源 | 设备离线、binding 未收敛、GPU 过载、缓冲积压 | 跌倒判定 |
|
||
| 收件人 | 运维团队 | 家属、护理员、呼叫中心 |
|
||
| 延迟容忍 | 分钟级 | **秒级** |
|
||
| 漏报后果 | 服务降级 | 人身伤害 + 法律责任 |
|
||
| 方案 | Prometheus + Alertmanager（现成） | **自研状态机 + 复用投递通道** |
|
||
|
||
运维那侧接 Alertmanager 就完事，一两天工作量，本节不再展开。**两套系统不得共用投递通道和值班配置**，避免运维噪声淡化业务预警。
|
||
|
||
## 10.2 告警生命周期状态机
|
||
|
||
```
|
||
[触发] ─→ [投递中] ─→ [已送达] ─→ [已确认 ack] ─→ [处置中] ─→ [关闭]
|
||
│ │ │ │
|
||
│ │ └─超时未 ack─→ [升级] ─→ 下一级投递 │
|
||
│ └─投递失败─→ [升级] │
|
||
└─防抖命中─→ [抑制] [标记误报] ←─┘
|
||
```
|
||
|
||
**没有 ack 环节的告警系统等于没有。** 发出去和被人看到是两回事，整个设计围绕「确认或升级」这一对概念展开。
|
||
|
||
## 10.3 分级升级链
|
||
|
||
```
|
||
家属 App 推送
|
||
│ 30s 无 ack
|
||
▼
|
||
家属短信 + 语音呼叫
|
||
│ 60s 无 ack
|
||
▼
|
||
备用联系人（邻居/物业/护理员）
|
||
│ 90s 无 ack
|
||
▼
|
||
呼叫中心人工介入
|
||
```
|
||
|
||
每户的联系人链、时段策略（白天找子女、夜间找同住者）、优先级都要可配。升级超时值需支持按户覆盖——独居老人和有同住家属的超时策略应该不同。
|
||
|
||
## 10.4 数据模型
|
||
|
||
```sql
|
||
CREATE TABLE alerts (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
household_id BIGINT NOT NULL REFERENCES households(id),
|
||
device_id BIGINT REFERENCES devices(id),
|
||
kind TEXT NOT NULL, -- 'fall' | 'no_motion' | 'device_offline_business'
|
||
confidence REAL,
|
||
triggered_at TIMESTAMPTZ NOT NULL,
|
||
state TEXT NOT NULL, -- triggered/delivering/delivered/acked/handling/closed/suppressed
|
||
acked_by BIGINT,
|
||
acked_at TIMESTAMPTZ,
|
||
closed_at TIMESTAMPTZ,
|
||
outcome TEXT, -- true_positive / false_positive / unknown
|
||
evidence_uri TEXT, -- 回捞的视频片段 + 姿态序列
|
||
escalation_level INT NOT NULL DEFAULT 0
|
||
);
|
||
|
||
CREATE TABLE contact_chains (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
household_id BIGINT NOT NULL REFERENCES households(id),
|
||
level INT NOT NULL, -- 0,1,2,3
|
||
contact_name TEXT NOT NULL,
|
||
channels JSONB NOT NULL, -- [{type:'push',token:...},{type:'sms',no:...}]
|
||
active_hours TEXT, -- '08:00-22:00' 或 NULL 表示全天
|
||
timeout_sec INT NOT NULL DEFAULT 30,
|
||
UNIQUE (household_id, level)
|
||
);
|
||
|
||
CREATE TABLE alert_deliveries (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
alert_id BIGINT NOT NULL REFERENCES alerts(id),
|
||
level INT NOT NULL,
|
||
channel TEXT NOT NULL, -- push / sms / voice / webhook
|
||
provider TEXT NOT NULL, -- 便于多供应商冗余
|
||
sent_at TIMESTAMPTZ,
|
||
receipt_at TIMESTAMPTZ, -- 回执：NULL = 未确认送达
|
||
failed_reason TEXT
|
||
);
|
||
|
||
CREATE INDEX ON alerts (state) WHERE state NOT IN ('closed','suppressed');
|
||
```
|
||
|
||
关键设计：**投递是独立实体而非 alerts 的字段**。一次告警会产生多条投递记录（多级×多通道），每条各自有回执状态。
|
||
|
||
## 10.5 投递回执：三个不同的事实
|
||
|
||
| 事实 | 含义 | 字段 |
|
||
| --- | --- | --- |
|
||
| 发出去了 | 调用了上游 API | `sent_at` |
|
||
| 送达了 | 上游回执确认到达终端 | `receipt_at` |
|
||
| 被看到了 | 用户主动 ack | `alerts.acked_at` |
|
||
|
||
**没有回执就当失败并升级**，不要乐观假设。推送可能被系统杀掉、短信可能延迟、电话可能占线。
|
||
|
||
## 10.6 通道选型与冗余
|
||
|
||
**必须至少两条独立路径，且电话通道要能绕过互联网。** 推送依赖 APNs/FCM，短信依赖运营商，任何单一通道都可能整体故障。
|
||
|
||
| 层 | 选型 | 说明 |
|
||
| --- | --- | --- |
|
||
| 状态机、升级链、ack、审计 | **自研**（Go） | 业务定制度高，通用工具都要大改 |
|
||
| 多通道投递 | Novu / Apprise / ntfy，或直接对接云厂商 | 只解决「怎么发」 |
|
||
| 短信 + 语音呼叫 | 云厂商（双供应商） | `provider` 字段就是为切换准备的 |
|
||
|
||
> ⚠️ **不要用 Grafana OnCall**。OSS 版已于 2026-03-24 归档，仓库只读，仅修 CVSS 7.0+ 漏洞。更关键的是移动推送、短信和电话在归档当日停止工作（那些通道依赖 Grafana Cloud 中转）。调度和升级链还能跑，但**送不出去的告警系统等于没有**。
|
||
|
||
若阶段二引入 ThingsBoard（接雷达时），其告警子系统 + 规则链可覆盖状态机的一大半，届时自研部分可收缩到只做升级链和电话对接。
|
||
|
||
## 10.7 去重与防抖
|
||
|
||
| 规则 | 参数 | 理由 |
|
||
| --- | --- | --- |
|
||
| 同设备冷却期 | 5min 内不重复告警 | 避免同一事件多次触发 |
|
||
| 同家庭聚合 | 多设备同时触发合并为一条 | 客厅两个机位拍到同一次跌倒 |
|
||
| 已处置抑制 | 已 ack 的告警期间不再新建 | 护理员已到现场 |
|
||
| 维护窗口 | 住户主动静默（如家庭聚会） | **需限时且到期自动恢复** |
|
||
|
||
静默功能必须强制限时（建议最长 4h）并在到期前提醒。永久静默是这类系统最常见的事故成因。
|
||
|
||
## 10.8 误报反馈闭环（产品飞轮）
|
||
|
||
家属点「误报」这个动作，要自动把 `evidence_uri` 对应的视频片段和姿态序列推进标注队列。
|
||
|
||
这条链路直接解决 9.8 节的数据集问题：公开数据集全是演员摆拍，而**真实误报案例是你最稀缺的训练数据**。没有这个闭环，模型不会随运营时间变好。
|
||
|
||
同理，`outcome = true_positive` 的样本是正例金矿。**从 M3 第一天就要存，不要等到想训模型时才发现没数据。**
|
||
|
||
## 10.9 审计与合规
|
||
|
||
每条告警的完整生命周期需**不可篡改地**留存：
|
||
|
||
- 什么时间触发、基于什么证据
|
||
- 向谁发过、走的什么通道、是否送达
|
||
- 谁在什么时间确认、处置结果
|
||
- 升级到第几级、每级耗时
|
||
|
||
一旦出事，「系统有没有报、几点报的、谁接的、多久响应」是法律问题而非技术问题。建议 `alerts` 和 `alert_deliveries` **只追加不修改**（状态变更写事件表），并独立备份。
|
||
|
||
另需确认的合规项（开工前法务确认）：视频证据的保存期限、家属查看权限范围、被监护者本人的知情同意。
|
||
|
||
## 10.10 SLA 目标（待 M3 实测校准）
|
||
|
||
| 指标 | 目标 |
|
||
| --- | --- |
|
||
| 跌倒发生 → 首次投递 | < 10s |
|
||
| 首次投递 → 送达回执 | < 5s（推送）/ < 30s（短信） |
|
||
| 全链路无人响应 → 呼叫中心 | < 3min |
|
||
| 告警丢失率 | 0（持久化后才确认触发） |
|
||
|
||
最后一行是硬约束：**告警先落库再投递**。进程崩溃后重启，未完成的升级链要能从数据库恢复继续——这跟第 6 节对账器的「水平触发」是同一个思路，启动时扫描所有未终态告警并接续处理。
|
||
|
||
# 11. EdgeX 升级路径（可选，阶段二）
|
||
|
||
当前阶段不引入 EdgeX。理由：它白送的能力（设备注册表、探活、命令抽象）约值一两周开发量，但代价是长期多背 4 个服务、跨服务追日志，且它假设设备在同一局域网、与 NAT 场景冲突。
|
||
|
||
## 何时值得切换
|
||
|
||
当确定要接入毫米波雷达、门磁、紧急按钮等异构设备时。EdgeX 的 device-mqtt / device-modbus / device-snmp 能复用同一套设备模型，这是它唯一压倒性的优势。
|
||
|
||
## 切换成本低的原因
|
||
|
||
ONVIF 调用那部分代码两边几乎一样（EdgeX 的 device-onvif-camera 内部就是用 IOTechSystems/onvif），对账器也不用改。
|
||
|
||
## 若切换，最小服务集
|
||
|
||
```
|
||
core-metadata 设备注册表
|
||
core-command 命令下发入口
|
||
device-onvif-camera ONVIF <-> REST
|
||
redis 消息总线
|
||
（consul 可用 -cp=none 省掉）
|
||
```
|
||
|
||
砍掉 core-data、app-service-*、security 全套。注意 discovery 在本场景基本不可用：netscan 对 200 个 /24 段是 5 万次探测，不现实；应使用预定义 deviceList 或 REST 批量录入，但保留 EnableStatusCheck / CheckStatusInterval 做探活。
|
||
|
||
另注意：EdgeX 3.x 起 API 路径是 /api/v3，网上大量 2.x 文档写的是 /api/v2。
|
||
|
||
# 12. 风险清单
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
| --- | --- | --- |
|
||
| 摄像头 ONVIF 实现差异 | 部分型号无法接入 | 采购前用真机验证，见演示方案文档 |
|
||
| 摄像头时钟漂移 | 事件时间戳全乱 | 开通时调 SetSystemDateAndTime，定期校时 |
|
||
| NAT 隧道不稳 | 控制面失联 | 控制面失联不影响视频推流（已解耦）；告警但不阻断 |
|
||
| path reload 踢流 | 用户看到卡顿 | 配置变更前比对哈希；变更集中在维护窗口 |
|
||
| H.265 兼容性 | 浏览器无法预览 | 摄像头统一设为 H.264 |
|
||
| 隐私合规 | 项目无法落地 | 尽早引入雷达做一级触发，减少视频常态采集 |
|
||
|
||
# 13. 里程碑
|
||
|
||
| 阶段 | 内容 | 出口标准 |
|
||
| --- | --- | --- |
|
||
| M0 | 摄像头兼容性验证 | 3-5 个候选型号跑通 GetProfiles / GetStreamUri / SetSystemDateAndTime |
|
||
| M1 | 单 exe 骨架 + mediamtx | 5 路摄像头自动建 path、探活、断线重建 |
|
||
| M2 | 对账器 + Postgres + 隧道 | 10 户试点，含开通/停用全流程 |
|
||
| M3 | 抽帧 worker + 推理接入 | 端到端跌倒告警跑通，拿到误报率基线 |
|
||
| M4 | 分片 + 灰度扩容 | 250 路稳定运行 |
|
||
| M5（阶段二） | 雷达接入 + 两级判定 | 误报率显著下降，视频常态采集下降 |
|