1673 lines
49 KiB
Markdown
1673 lines
49 KiB
Markdown
# 智能锁新实时系统方案
|
||
|
||
本文档面向一个“全新项目”的设计，但明确采用 `starcloud` 作为共享业务能力云平台，`starlock` 作为其租户化应用层入口，不重复建设通用业务能力。
|
||
|
||
## 1. 目标与约束
|
||
|
||
### 1.1 已知现状
|
||
|
||
- `starcloud`：共享云平台，向下游业务应用提供可复用 API 与业务能力。
|
||
- `starlock`：PHP 业务后台，负责 APP 用户注册、登录、权限、家庭/门锁归属和其它业务规则。
|
||
- `app-starlock`：Flutter APP。
|
||
- `starchart-sls1 - 0304`：现有中央通信层，承担注册、发现、转发、对讲相关职责。
|
||
- 目标方向：
|
||
- 发现服务迁移到 Apache BifroMQ
|
||
- 音视频不再默认全部走中心服务器转发，但保留中心转发兜底
|
||
- 按网络质量动态选择 WebRTC P2P 或 `ZLMediaKit` 转发
|
||
- 在 P2P 不稳定时，可切回中心服务器转发或 ZLMediaKit 转发
|
||
|
||
### 1.2 新方案目标
|
||
|
||
新项目应满足以下目标：
|
||
|
||
1. `starcloud` 作为共享业务能力主平台，承载可复用的业务 API。
|
||
2. `starlock` 作为面向 APP 的租户化业务入口和编排层。
|
||
3. 实时控制面与媒体面彻底分离。
|
||
4. 设备发现、在线状态、会话信令交给 Apache BifroMQ。
|
||
5. 音视频链路不固定单一路径，而是按网络质量动态选路：中好网络优先 P2P，弱网优先 `ZLMediaKit` 转发，`TURN` 作为 RTC 路径补位。
|
||
6. AI 通过旁路式能力接入，不破坏主对讲链路。
|
||
|
||
### 1.3 设计原则
|
||
|
||
- `starcloud` 负责可复用业务能力与共享策略，
|
||
`starlock` 负责租户化编排和对外 API 聚合。
|
||
- 新实时系统只做连接、会话编排、信令分发和媒体接入。
|
||
- App 与设备获取到的是短期会话权限，不直接暴露业务后台内部权限模型。
|
||
- AI 接入必须解耦于主通话状态机。
|
||
- 所有大流量音视频传输采用网络自适应策略：中好网络优先标准 RTC P2P，弱网由 `ZLMediaKit` 作为优先实现方案。
|
||
|
||
## 2. 角色划分
|
||
|
||
### 2.1 `starcloud` 共享能力职责
|
||
|
||
`starcloud` 继续承担：
|
||
|
||
- 可复用用户/权限策略能力
|
||
- 设备与家庭关系的共享模型能力
|
||
- 通用套餐、计费、审计、风控能力
|
||
- 标准化业务 API（供 `starlock` 等下游应用调用）
|
||
- 可复用的业务规则引擎与跨租户能力演进
|
||
|
||
### 2.2 `starlock` 租户应用层职责
|
||
|
||
`starlock` 继续承担：
|
||
|
||
- 面向 `app-starlock` 的统一业务入口
|
||
- 结合租户/渠道配置编排 `starcloud` 共享能力
|
||
- 聚合会话、通知、AI 与设备业务流程
|
||
- 面向 APP 的主业务 API 与体验层策略
|
||
- 仅保留强租户定制逻辑，不重复实现通用业务能力
|
||
|
||
### 2.3 新实时系统承担职责
|
||
|
||
新项目承担：
|
||
|
||
- 设备在线状态管理
|
||
- 设备能力声明与发现
|
||
- 实时会话创建与编排
|
||
- WebRTC signaling
|
||
- WebRTC 媒体接入
|
||
- TURN/STUN 基础设施
|
||
- 中心媒体转发兜底
|
||
- `ZLMediaKit` 转发接入
|
||
- AI 会话桥接
|
||
- 调试日志、会话追踪、弱状态缓存
|
||
|
||
## 3. 总体架构图
|
||
|
||
说明：如果你当前 Markdown 查看器不支持 Mermaid，请直接看 `3.0.1` 与 `3.0.2` 的纯文本结构图。
|
||
|
||
### 3.0.1 纯文本结构图（精简版）
|
||
|
||
```text
|
||
app-starlock
|
||
-> starlock (租户应用层)
|
||
-> starcloud (共享业务能力 API)
|
||
-> session-orchestrator (独立服务)
|
||
-> Apache BifroMQ (发现/在线/信令)
|
||
-> 媒体选路: P2P / TURN / ZLMediaKit / relay
|
||
<-> Lock/Gateway (对讲设备)
|
||
-> ai-gateway -> xiaozhi_server (AI旁路)
|
||
```
|
||
|
||
### 3.0.2 纯文本结构图（详细版）
|
||
|
||
```text
|
||
[Client]
|
||
app-starlock
|
||
Lock/Gateway
|
||
|
||
[Business]
|
||
starlock (租户应用层，面向APP)
|
||
- 聚合业务 API
|
||
- 编排实时会话
|
||
- 调用共享能力
|
||
starcloud (共享业务云平台)
|
||
- 用户/权限/套餐/审计等通用能力
|
||
|
||
[Session & Control]
|
||
session-orchestrator (phase1+, 独立服务形态)
|
||
device-bootstrap
|
||
Apache BifroMQ
|
||
MQTT event worker
|
||
realtime-store
|
||
|
||
[Media]
|
||
优先策略(自适应):
|
||
1) 中好网络 -> WebRTC P2P
|
||
2) RTC补位 -> TURN
|
||
3) 弱网优先 -> ZLMediaKit
|
||
4) 最终兜底 -> media-relay
|
||
|
||
[AI]
|
||
ai-gateway -> xiaozhi_server
|
||
```
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Client
|
||
APP[app-starlock\nFlutter App]
|
||
LOCK[Lock / Gateway\n门锁或网关]
|
||
end
|
||
|
||
subgraph Business
|
||
STARCLOUD[starcloud\n共享业务云平台]
|
||
STARLOCK[starlock\n租户应用层]
|
||
PUSHSVC[Push / Callback\n推送与业务通知]
|
||
end
|
||
|
||
subgraph Realtime
|
||
ORCH[session-orchestrator\n会话编排服务]
|
||
BIFROMQ[Apache BifroMQ\n发现/在线/信令]
|
||
TURN[coturn\nSTUN/TURN]
|
||
RELAY[media-relay\n中心音视频转发]
|
||
ZLM[ZLMediaKit\n标准流媒体转发]
|
||
TRACE[realtime-store\n会话状态/日志缓存]
|
||
end
|
||
|
||
subgraph AI
|
||
AIGW[ai-gateway\nAI桥接层]
|
||
XIAOZHI[xiaozhi_server\nAI实时服务]
|
||
end
|
||
|
||
APP -->|HTTPS| STARLOCK
|
||
STARLOCK -->|共享业务 API| STARCLOUD
|
||
LOCK -->|HTTPS / bootstrap| STARLOCK
|
||
|
||
STARLOCK -->|内部 API| ORCH
|
||
STARLOCK --> PUSHSVC
|
||
|
||
APP <-->|MQTT over WSS| BIFROMQ
|
||
LOCK <-->|MQTT / MQTT over TLS| BIFROMQ
|
||
|
||
APP <-->|WebRTC P2P / TURN| LOCK
|
||
APP -. fallback .-> TURN
|
||
LOCK -. fallback .-> TURN
|
||
APP -. relay fallback .-> RELAY
|
||
LOCK -. relay fallback .-> RELAY
|
||
APP -. optional relay .-> ZLM
|
||
LOCK -. optional relay .-> ZLM
|
||
|
||
ORCH --> BIFROMQ
|
||
ORCH --> RELAY
|
||
ORCH --> ZLM
|
||
ORCH --> TRACE
|
||
STARLOCK --> TRACE
|
||
|
||
LOCK -. AI side channel .-> AIGW
|
||
APP -. AI assisted mode .-> AIGW
|
||
AIGW --> XIAOZHI
|
||
AIGW --> STARLOCK
|
||
```
|
||
|
||
### 3.1 架构解读
|
||
|
||
- `starcloud` 是跨项目可复用业务能力平台，`starlock` 是租户化编排入口。
|
||
- `session-orchestrator` 是会话状态机中心，但不保存完整业务模型。
|
||
- `Apache BifroMQ` 只承接设备发现、在线状态和 signaling，不承接大媒体流。
|
||
- `coturn` 是 WebRTC 的第一层兜底中继。
|
||
- `media-relay` 是中心服务器音视频转发能力层，作为 P2P/TURN 失败后的工程兜底。
|
||
- `ZLMediaKit` 可以直接承担这层能力，实现 WebRTC 失败后的中心转发，因此通常不需要再长期维护一套独立自研 relay。
|
||
- `ai-gateway` 把 AI 从实时媒体层中解耦出来。
|
||
|
||
### 3.2 基于现有项目的迁移版架构图
|
||
|
||
下面这张图不是“完全脱离现状的理想图”，而是基于你当前项目角色关系做的迁移版架构图。
|
||
|
||
对应关系如下：
|
||
|
||
- 现有 `scd` 的“注册/发现/心跳”职责，迁移到 `Apache BifroMQ + device bootstrap + session-orchestrator`
|
||
- 现有 `scrd` 的“媒体中继/NAT 穿透”职责，迁移到 `WebRTC P2P + coturn + 中心媒体转发兜底`
|
||
- 现有 `rpcd` 不再承担实时转发中心角色，只保留必要的业务桥接，长期建议并入 `starlock` 内部服务调用
|
||
- 现有 `event_listener` 继续保留在事件上报链路，但不再参与主媒体链路
|
||
- 新增 `media-relay` 能力层，优先采用 `ZLMediaKit` 落地
|
||
- 新增 `ai-gateway + xiaozhi_server` 作为 AI 能力面
|
||
|
||
当前项目约束补充：`WiFi锁` 默认就是“网关锁形态”，因此可直接承接 `网关设备` 角色。
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph AppSide[APP侧]
|
||
APP[app-starlock\nFlutter APP]
|
||
end
|
||
|
||
subgraph BizSide[业务后台]
|
||
STARCLOUD[starcloud\n共享业务云平台]
|
||
STARLOCK[starlock\n租户应用层]
|
||
CALLBACK[推送/回调/业务通知]
|
||
end
|
||
|
||
subgraph RealtimeCloud[新实时云]
|
||
BOOT[device-bootstrap\n设备接入与临时凭证]
|
||
BIFROMQ[Apache BifroMQ\n发现/在线/信令]
|
||
ORCH[session-orchestrator\n会话编排]
|
||
TURN[coturn\nTURN/STUN]
|
||
RELAY[media-relay\n中心音视频转发]
|
||
ZLM[ZLMediaKit\n流媒体转发]
|
||
EVT[event-listener\n事件监听/媒体落库]
|
||
end
|
||
|
||
subgraph AIPlane[AI能力]
|
||
AIGW[ai-gateway]
|
||
XIAOZHI[xiaozhi_server]
|
||
end
|
||
|
||
subgraph DeviceSide[智能锁设备侧]
|
||
GW[WiFi网关锁\nWebRTC/AI优先承载]
|
||
BLE[蓝牙锁]
|
||
end
|
||
|
||
APP -->|HTTPS业务API| STARLOCK
|
||
STARLOCK -->|共享业务 API| STARCLOUD
|
||
STARLOCK -->|内部调用| BOOT
|
||
STARLOCK -->|内部调用| ORCH
|
||
STARLOCK --> CALLBACK
|
||
|
||
GW -->|设备认证/换取MQTT凭证| BOOT
|
||
|
||
APP <-->|MQTT over WSS| BIFROMQ
|
||
GW <-->|MQTT/TLS| BIFROMQ
|
||
|
||
ORCH --> BIFROMQ
|
||
BOOT --> BIFROMQ
|
||
|
||
APP <-->|WebRTC P2P / ZLM 自适应| GW
|
||
APP -. P2P失败走TURN .-> TURN
|
||
GW -. P2P失败走TURN .-> TURN
|
||
APP -. TURN仍失败走中心转发 .-> RELAY
|
||
GW -. TURN仍失败走中心转发 .-> RELAY
|
||
APP -. 可选切到ZLM .-> ZLM
|
||
GW -. 可选切到ZLM .-> ZLM
|
||
|
||
GW -->|事件上报| EVT
|
||
GW -. 蓝牙透传 .-> BLE
|
||
EVT -->|HTTP回调| STARLOCK
|
||
|
||
GW -. AI音频旁路 .-> AIGW
|
||
APP -. AI辅助模式 .-> AIGW
|
||
AIGW --> XIAOZHI
|
||
AIGW --> STARLOCK
|
||
```
|
||
|
||
### 3.3 这张迁移图怎么理解
|
||
|
||
- 对你当前项目，`WiFi锁` 就是 `网关设备` 形态，可直接承接 WebRTC、双讲、AI 音频旁路能力。
|
||
- 图中已合并为单节点 `WiFi网关锁`，避免角色重复表达。
|
||
- `Apache BifroMQ` 取代了原先 `scd` 的发现中心角色，但不再承接媒体搬运。
|
||
- `TURN` 是 RTC 路径的补位能力，但不是所有场景的首选。
|
||
- `media-relay` 继续保留中心服务器音视频转发能力，便于兼容旧设备和极端网络环境。
|
||
- `ZLMediaKit` 可以作为更标准的中心转发实现，在弱网场景下可优先于 P2P 成为首选媒体路径。
|
||
- `event_listener` 继续服务事件回调、图片/视频处理、业务通知，不进入主实时链路。
|
||
- `starlock` 仍然是外部唯一可信业务入口，APP 不直接向 `session-orchestrator` 暴露业务接口。
|
||
|
||
### 3.4 第一阶段落地架构图（`session-orchestrator` 独立）
|
||
|
||
按当前决策，第一阶段就独立部署 `session-orchestrator`，不再采用内嵌 `starlock` 的过渡形态。
|
||
|
||
这样做的目的：
|
||
|
||
- 从一开始就把业务编排与实时状态机解耦
|
||
- 统一会话控制协议，替代历史 UDP 协议分散控制
|
||
- 提前建立可扩容、可观测、可回放的会话控制平面
|
||
- 后续只做横向扩容，不再经历二次拆分改造
|
||
|
||
对应第一阶段架构图如下：
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph AppSide[APP侧]
|
||
APP[app-starlock\nFlutter APP]
|
||
end
|
||
|
||
subgraph BizSide[业务后台]
|
||
STARCLOUD[starcloud\n共享业务云平台]
|
||
STARLOCK[starlock\n租户应用层]
|
||
CALLBACK[推送/业务通知]
|
||
end
|
||
|
||
subgraph RealtimeInfra[实时基础设施]
|
||
ORCH[session-orchestrator\n独立会话控制服务]
|
||
BOOT[device-bootstrap\n设备接入与临时凭证]
|
||
BIFROMQ[Apache BifroMQ\n发现/在线/信令/事件总线]
|
||
TURN[coturn\nTURN/STUN]
|
||
RELAY[media-relay\n中心音视频转发]
|
||
ZLM[ZLMediaKit\n流媒体转发]
|
||
EVT[MQTT event worker\n原event-listener演进]
|
||
end
|
||
|
||
subgraph AIPlane[AI能力]
|
||
AIGW[ai-gateway]
|
||
XIAOZHI[xiaozhi_server]
|
||
end
|
||
|
||
subgraph DeviceSide[智能锁设备侧]
|
||
GW[WiFi网关锁\nWebRTC/AI优先承载]
|
||
BLE[蓝牙锁]
|
||
end
|
||
|
||
APP -->|HTTPS业务API| STARLOCK
|
||
STARLOCK -->|共享业务 API| STARCLOUD
|
||
STARLOCK -->|内部调用| ORCH
|
||
STARLOCK --> CALLBACK
|
||
|
||
GW -->|认证/换取MQTT凭证| BOOT
|
||
STARLOCK -->|内部调用| BOOT
|
||
|
||
APP <-->|MQTT over WSS| BIFROMQ
|
||
GW <-->|MQTT/TLS| BIFROMQ
|
||
|
||
ORCH --> BIFROMQ
|
||
ORCH --> RELAY
|
||
ORCH --> ZLM
|
||
|
||
APP <-->|WebRTC P2P / ZLM 自适应| GW
|
||
APP -. P2P失败走TURN .-> TURN
|
||
GW -. P2P失败走TURN .-> TURN
|
||
APP -. TURN失败走中心转发 .-> RELAY
|
||
GW -. TURN失败走中心转发 .-> RELAY
|
||
APP -. 可选切ZLM .-> ZLM
|
||
GW -. 可选切ZLM .-> ZLM
|
||
|
||
GW -->|事件上报| BIFROMQ
|
||
BIFROMQ --> EVT
|
||
EVT -->|HTTP回调/业务处理| STARLOCK
|
||
|
||
GW -. 蓝牙透传 .-> BLE
|
||
|
||
GW -. AI音频旁路 .-> AIGW
|
||
APP -. AI辅助模式 .-> AIGW
|
||
AIGW --> XIAOZHI
|
||
AIGW --> STARLOCK
|
||
```
|
||
|
||
### 3.5 第一阶段图的关键变化
|
||
|
||
与前面的“目标态迁移图”相比，第一阶段版本有三个关键变化：
|
||
|
||
1. 第一阶段即独立部署 `session-orchestrator`
|
||
2. `starlock` 只做业务授权与编排，不承载会话状态机
|
||
3. `event_listener` 不再作为协议接收器，而是变成 `MQTT event worker`
|
||
|
||
### 3.6 第一阶段图的实际含义
|
||
|
||
- `starlock` 负责业务授权与会话编排入口，实时状态流转由 `session-orchestrator` 统一管理。
|
||
- MQTT 上只跑发现、在线、signaling 和事件通知，不跑大媒体流。
|
||
- 主媒体链路采用自适应策略：中好网络优先 `WebRTC P2P`，弱网优先 `ZLMediaKit`，`TURN` 负责 RTC 路径补位，中心转发能力持续保留。
|
||
- `Apache BifroMQ -> MQTT event worker -> starlock` 负责事件消费、回调、媒体后处理等异步任务。
|
||
- 后续如果会话量上来，优先扩容 `session-orchestrator` 实例与会话存储层，不再做架构拆分。
|
||
|
||
### 3.6.1 `session-orchestrator` 如何控制视频会话（详细）
|
||
|
||
你们之前“通过 UDP 协议字段通知 APP 和锁端开始/结束”的模式，本质是点对点控制，状态一致性和故障收敛依赖端侧实现，云端很难统一治理。
|
||
|
||
新方案里，`session-orchestrator` 用“会话状态机 + 控制指令 + ACK/超时机制”统一控制视频会话。
|
||
|
||
核心机制如下：
|
||
|
||
1. 建会话：`starlock` 完成权限校验后调用 `session-orchestrator` 创建会话，返回 `sessionId`、topic、短期 token、媒体策略。
|
||
2. 发起呼叫：`session-orchestrator` 下发 `invite` 控制事件，设备侧回 `ringing/accept/reject`。
|
||
3. 信令协商：APP/设备仅在约定 topic 交换 `offer/answer/candidate`，`session-orchestrator` 只做状态编排与超时控制，不搬运大媒体流。
|
||
4. 建链判定：`session-orchestrator` 收集两端链路质量上报（RTT、丢包、抖动、可用带宽、candidate 类型），进入 `connecting -> connected`。
|
||
5. 动态选路：当指标降级，发 `switch-route` 控制指令，从 `p2p` 切 `turn` 或 `zlmediakit`；若仍失败，再切 `relay`。
|
||
6. 结束会话：任一端发送 `hangup` 或超时触发 `terminate`，`session-orchestrator` 统一写入终态并清理 token/资源。
|
||
|
||
推荐状态机：
|
||
|
||
- `pending` -> `ringing` -> `accepted` -> `connecting` -> `connected`
|
||
- 通话中可进入：`degraded` -> `switching_route` -> `recovered`
|
||
- 结束态：`ended` / `rejected` / `timeout` / `failed`
|
||
|
||
和旧 UDP 控制的关系：
|
||
|
||
- 旧模型：端到端 UDP 协议字段直接表达“开始/结束”，中心侧难追踪完整会话。
|
||
- 新模型：开始/结束只是状态机中的两个事件，所有控制动作都有 `sessionId`、事件序号、ACK、超时重试与最终态落库。
|
||
- 结果：可审计、可回放、可补偿，且便于联调和问题追踪。
|
||
|
||
### 3.7 现状与第一阶段对照图
|
||
|
||
这张图适合给团队评审时使用，左边是你们当前主要链路，右边是第一阶段目标链路。
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph NOW[当前架构]
|
||
APP1[app-starlock]
|
||
STAR1[starlock]
|
||
SCD[scd\n注册/发现/心跳]
|
||
SCRD[scrd\n媒体转发/NAT]
|
||
RPCD[rpcd\n业务桥接]
|
||
EVT1[event_listener]
|
||
DEV1[锁/网关设备]
|
||
|
||
APP1 --> STAR1
|
||
STAR1 --> RPCD
|
||
DEV1 --> SCD
|
||
APP1 --> SCD
|
||
APP1 --> SCRD
|
||
DEV1 --> SCRD
|
||
DEV1 --> EVT1
|
||
EVT1 --> STAR1
|
||
end
|
||
|
||
subgraph PHASE1[第一阶段架构]
|
||
APP2[app-starlock]
|
||
STAR2[starlock]
|
||
ORCH2[session-orchestrator]
|
||
BOOT2[device-bootstrap]
|
||
BIFROMQ2[Apache BifroMQ]
|
||
TURN2[coturn]
|
||
RELAY2[media-relay]
|
||
ZLM2[ZLMediaKit]
|
||
EVTW[MQTT event worker]
|
||
AIGW2[ai-gateway]
|
||
XIAO2[xiaozhi_server]
|
||
DEV2[锁/网关设备]
|
||
|
||
APP2 --> STAR2
|
||
STAR2 --> ORCH2
|
||
STAR2 --> BOOT2
|
||
ORCH2 --> BIFROMQ2
|
||
APP2 --> BIFROMQ2
|
||
DEV2 --> BOOT2
|
||
DEV2 --> BIFROMQ2
|
||
APP2 --> TURN2
|
||
DEV2 --> TURN2
|
||
APP2 --> RELAY2
|
||
DEV2 --> RELAY2
|
||
APP2 --> ZLM2
|
||
DEV2 --> ZLM2
|
||
BIFROMQ2 --> EVTW
|
||
EVTW --> STAR2
|
||
ORCH2 --> RELAY2
|
||
ORCH2 --> ZLM2
|
||
DEV2 -. AI旁路 .-> AIGW2
|
||
AIGW2 --> XIAO2
|
||
AIGW2 --> STAR2
|
||
end
|
||
```
|
||
|
||
### 3.8 `xiaozhi_server` 的 MQTT 网关策略（已定）
|
||
|
||
策略已定：主方案不使用 `xiaozhi-mqtt` 网关。
|
||
|
||
- 智能锁主链路只使用 `Apache BifroMQ`
|
||
- AI 面只使用 `ai-gateway <-> xiaozhi_server` 的 HTTP/WebSocket 会话
|
||
- 不引入第二套 MQTT broker，不保留双 broker 共存方案
|
||
|
||
### 3.9 改进后的推荐方案
|
||
|
||
推荐做法是：
|
||
|
||
- 智能锁主实时链路只保留一套 MQTT 基础设施，即 `Apache BifroMQ`
|
||
- `xiaozhi_server` 只保留在 AI 能力面，负责 ASR、TTS、Agent、知识库、工具调用
|
||
- 明确禁用 `xiaozhi-mqtt` 网关，不在任何环境接入智能锁主链路
|
||
|
||
对应理解是：
|
||
|
||
- 锁、APP、网关设备的发现、在线、signaling、事件总线，都走 `Apache BifroMQ`
|
||
- WebRTC signaling 仍然走 `Apache BifroMQ`
|
||
- 音视频主链路走 `WebRTC + coturn`，P2P/TURN 失败后切到中心媒体转发或 `ZLMediaKit`
|
||
- `xiaozhi_server` 只通过 `ai-gateway` 接入，不直接成为锁侧 MQTT broker
|
||
|
||
这样改完以后，`xiaozhi_server` 不会和 `Apache BifroMQ` 在主方案中发生正面冲突。
|
||
|
||
### 3.10 执行规范（禁用 `xiaozhi-mqtt`）
|
||
|
||
为避免双 broker 风险，执行层按以下规范落地：
|
||
|
||
1. 仅部署并对外开放 `Apache BifroMQ` 的 MQTT 接入。
|
||
2. 不部署 `xiaozhi-mqtt-gateway`，或在配置中明确关闭其对外监听。
|
||
3. 智能锁、APP、网关设备统一接入 `Apache BifroMQ`。
|
||
4. AI 功能统一走 `ai-gateway <-> xiaozhi_server` 的 HTTP/WebSocket，不走 MQTT。
|
||
5. 运维检查项中增加“第二 MQTT broker 禁入”巡检规则。
|
||
|
||
### 3.11 最终建议
|
||
|
||
对你这个智能锁项目，最稳的版本是：
|
||
|
||
- `Apache BifroMQ` 是唯一主 MQTT 平台
|
||
- `starcloud` 是共享业务能力平台，`starlock` 是租户应用层入口
|
||
- `xiaozhi_server` 是 AI 引擎，不是主消息总线
|
||
- 不启用 `xiaozhi-mqtt`，避免双 broker 架构复杂度
|
||
|
||
### 3.12 按你项目落地的真实接线图，Broker 改为 Apache BifroMQ
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph ClientSide[用户侧]
|
||
APP[app-starlock]
|
||
end
|
||
|
||
subgraph BizSide[业务与控制面]
|
||
STARCLOUD[starcloud]
|
||
STARLOCK[starlock]
|
||
BOOT[device-bootstrap]
|
||
ORCH[session state machine]
|
||
EVTW[MQTT event worker]
|
||
end
|
||
|
||
subgraph BrokerSide[消息面]
|
||
BIFROMQ[Apache BifroMQ]
|
||
end
|
||
|
||
subgraph MediaSide[实时媒体]
|
||
TURN[coturn]
|
||
RELAY[media-relay]
|
||
ZLM[ZLMediaKit]
|
||
end
|
||
|
||
subgraph DeviceSide[设备侧]
|
||
GW[WiFi网关锁]
|
||
BLE[蓝牙锁]
|
||
end
|
||
|
||
subgraph AIPlane[AI能力面]
|
||
AIGW[ai-gateway]
|
||
XIAOZHI[xiaozhi_server]
|
||
end
|
||
|
||
APP -->|HTTPS 业务 API| STARLOCK
|
||
STARLOCK -->|共享业务 API| STARCLOUD
|
||
STARLOCK -->|内部调用| BOOT
|
||
STARLOCK -->|内部调用| ORCH
|
||
STARLOCK -->|事件消费/回调| EVTW
|
||
|
||
GW -->|认证/换 MQTT 凭证| BOOT
|
||
|
||
APP <-->|MQTT over WSS| BIFROMQ
|
||
GW <-->|MQTT over TLS| BIFROMQ
|
||
|
||
ORCH -->|signaling/session control| BIFROMQ
|
||
EVTW <-->|订阅事件| BIFROMQ
|
||
|
||
APP <-->|WebRTC P2P / ZLM 自适应| GW
|
||
APP -. TURN fallback .-> TURN
|
||
GW -. TURN fallback .-> TURN
|
||
APP -. relay fallback .-> RELAY
|
||
GW -. relay fallback .-> RELAY
|
||
APP -. optional ZLM relay .-> ZLM
|
||
GW -. optional ZLM relay .-> ZLM
|
||
GW -. 蓝牙透传 .-> BLE
|
||
|
||
GW -. AI 音频旁路 .-> AIGW
|
||
APP -. AI 辅助模式 .-> AIGW
|
||
AIGW --> XIAOZHI
|
||
AIGW --> STARLOCK
|
||
```
|
||
|
||
这张图对应的边界是：
|
||
|
||
- `Apache BifroMQ` 只承接在线、发现、signaling、事件通知，不承接大媒体流。
|
||
- 主音视频链路按网络质量自适应选择：中好网络优先 `WebRTC + coturn`，弱网优先 `ZLMediaKit`。
|
||
- `media-relay` 承接 P2P/TURN 不可用时的中心音视频转发。
|
||
- `ZLMediaKit` 提供标准化流媒体转发方案，可作为中心转发实现之一。
|
||
- `starcloud` 提供可复用业务能力，`starlock` 负责租户化编排与 APP 入口。
|
||
- `xiaozhi_server` 只在 `ai-gateway` 后面提供 ASR、TTS、Agent、知识库、工具调用。
|
||
- 用户、权限、套餐、审计等可复用能力优先沉淀在 `starcloud`，`starlock` 负责租户侧业务编排与体验层策略。
|
||
|
||
### 3.13 精简业务图（管理/评审）
|
||
|
||
这张图只保留关键角色和主链路，适合评审会快速对齐。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
APP[app-starlock]
|
||
STARLOCK[starlock\n租户应用层]
|
||
STARCLOUD[starcloud\n共享业务能力]
|
||
SESSION[session-orchestrator]
|
||
MQ[Apache BifroMQ]
|
||
MEDIA[ZLMediaKit / TURN / relay]
|
||
DEV[Lock/Gateway]
|
||
AI[ai-gateway + xiaozhi]
|
||
|
||
APP -->|业务 API| STARLOCK
|
||
STARLOCK -->|共享业务 API| STARCLOUD
|
||
STARLOCK -->|会话编排| SESSION
|
||
SESSION --> MQ
|
||
APP <-->|信令| MQ
|
||
DEV <-->|信令| MQ
|
||
APP <-->|音视频自适应| DEV
|
||
APP -. 弱网优先 .-> MEDIA
|
||
DEV -. 弱网优先 .-> MEDIA
|
||
APP -. AI模式 .-> AI
|
||
DEV -. AI旁路 .-> AI
|
||
```
|
||
|
||
### 3.14 详细业务图（研发/实现）
|
||
|
||
这张图包含业务层、会话层、媒体层、事件回调与 AI 旁路，适合研发实现和联调。
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Client[客户端与设备]
|
||
APP[app-starlock]
|
||
GW[Gateway/Lock]
|
||
end
|
||
|
||
subgraph Biz[业务层]
|
||
STARLOCK[starlock\n租户应用层]
|
||
STARCLOUD[starcloud\n共享业务API]
|
||
PUSH[push/callback]
|
||
end
|
||
|
||
subgraph SessionPlane[会话与控制面]
|
||
SESSION[session-orchestrator]
|
||
BOOT[device-bootstrap]
|
||
MQ[Apache BifroMQ]
|
||
EVT[MQTT event worker]
|
||
TRACE[realtime-store]
|
||
end
|
||
|
||
subgraph MediaPlane[媒体面]
|
||
P2P[WebRTC P2P]
|
||
TURN[coturn]
|
||
ZLM[ZLMediaKit]
|
||
RELAY[media-relay]
|
||
end
|
||
|
||
subgraph AIPlane[AI面]
|
||
AIGW[ai-gateway]
|
||
XZ[xiaozhi_server]
|
||
end
|
||
|
||
APP -->|HTTPS 业务请求| STARLOCK
|
||
STARLOCK -->|共享能力调用| STARCLOUD
|
||
STARLOCK -->|创建会话| SESSION
|
||
STARLOCK --> PUSH
|
||
|
||
GW -->|设备认证| BOOT
|
||
STARLOCK -->|内部调用| BOOT
|
||
|
||
SESSION -->|会话信令编排| MQ
|
||
APP <-->|MQTT/WSS| MQ
|
||
GW <-->|MQTT/TLS| MQ
|
||
|
||
APP -->|网络探测上报| SESSION
|
||
GW -->|链路质量上报| SESSION
|
||
SESSION -->|中好网络| P2P
|
||
SESSION -->|RTC补位| TURN
|
||
SESSION -->|弱网优先| ZLM
|
||
SESSION -->|最终兜底| RELAY
|
||
|
||
APP <-->|媒体| P2P
|
||
GW <-->|媒体| P2P
|
||
APP -. fallback .-> TURN
|
||
GW -. fallback .-> TURN
|
||
APP -. weak network .-> ZLM
|
||
GW -. weak network .-> ZLM
|
||
APP -. emergency fallback .-> RELAY
|
||
GW -. emergency fallback .-> RELAY
|
||
|
||
GW -->|事件上报| MQ
|
||
MQ --> EVT
|
||
EVT -->|业务回调| STARLOCK
|
||
SESSION --> TRACE
|
||
|
||
GW -. AI音频旁路 .-> AIGW
|
||
APP -. AI辅助模式 .-> AIGW
|
||
AIGW --> XZ
|
||
AIGW --> STARLOCK
|
||
```
|
||
|
||
## 4. 控制面与媒体面分层
|
||
|
||
### 4.1 控制面
|
||
|
||
控制面使用：
|
||
|
||
- HTTPS
|
||
- MQTT
|
||
|
||
控制面承载：
|
||
|
||
- 登录与鉴权
|
||
- 设备绑定与发现
|
||
- 会话创建
|
||
- 呼叫控制
|
||
- 开锁命令
|
||
- 在线状态
|
||
- 事件通知
|
||
|
||
### 4.2 媒体面
|
||
|
||
媒体面使用：
|
||
|
||
- WebRTC
|
||
|
||
媒体面承载：
|
||
|
||
- 视频上行
|
||
- 双向音频
|
||
- DataChannel 辅助消息
|
||
- 录制或云存的旁路扩展
|
||
- P2P/TURN 失败后的中心媒体转发
|
||
- 基于 `ZLMediaKit` 的流转发
|
||
|
||
### 4.3 AI 面
|
||
|
||
AI 面使用：
|
||
|
||
- `ai-gateway` 与 `xiaozhi_server` 的 WebSocket/HTTP 会话
|
||
- 不使用 `xiaozhi` 原生 MQTT+UDP 网关能力，避免引入第二套 MQTT 基础设施
|
||
|
||
AI 面承载：
|
||
|
||
- 语音转文本
|
||
- TTS
|
||
- 意图识别
|
||
- 工具调用
|
||
- 智能应答
|
||
- AI 辅助摘要/关键词提取
|
||
|
||
## 5. 核心时序图
|
||
|
||
### 5.1 设备上线与发现
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Lock as Lock/Gateway
|
||
participant Starlock as starlock
|
||
participant BifroMQ as Apache BifroMQ
|
||
participant App as APP
|
||
|
||
Lock->>Starlock: 设备认证/获取 MQTT 临时凭证
|
||
Starlock-->>Lock: mqtt username/password 或 JWT
|
||
Lock->>BifroMQ: 建立 MQTT 连接
|
||
Lock->>BifroMQ: 发布 retained presence=online
|
||
Lock->>BifroMQ: 发布 retained capabilities
|
||
|
||
App->>Starlock: 获取门锁列表与权限
|
||
App->>Starlock: 申请查看设备在线态
|
||
App->>BifroMQ: 订阅锁相关 presence/status topic
|
||
BifroMQ-->>App: 推送设备在线与能力信息
|
||
```
|
||
|
||
### 5.2 App 发起对讲，媒体路径自适应
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant App as APP
|
||
participant Starlock as starlock
|
||
participant Orch as session-orchestrator
|
||
participant BifroMQ as Apache BifroMQ
|
||
participant Lock as Lock/Gateway
|
||
participant TURN as coturn
|
||
participant Relay as media-relay
|
||
participant ZLM as ZLMediaKit
|
||
|
||
App->>Starlock: 发起视频/对讲请求
|
||
Starlock->>Starlock: 校验用户对该锁的权限
|
||
Starlock->>Orch: 创建 realtime session
|
||
Orch-->>Starlock: sessionId + signaling topics + rtc config + token
|
||
Starlock-->>App: 返回 session 启动信息
|
||
|
||
Starlock->>BifroMQ: 通知目标锁有呼叫请求
|
||
BifroMQ-->>Lock: 推送 incoming call
|
||
|
||
App->>BifroMQ: 发布 offer
|
||
BifroMQ-->>Lock: 转发 offer
|
||
Lock->>BifroMQ: 发布 answer
|
||
BifroMQ-->>App: 转发 answer
|
||
|
||
App->>BifroMQ: 发布 ICE candidate
|
||
Lock->>BifroMQ: 发布 ICE candidate
|
||
|
||
Orch->>Orch: 根据 RTT/丢包/NAT/终端能力选择媒体路径
|
||
alt 网络良好，优先 P2P
|
||
App-->>Lock: WebRTC P2P 建链
|
||
else RTC 可用但 P2P 不理想
|
||
App-->>TURN: 使用 TURN 中继
|
||
Lock-->>TURN: 使用 TURN 中继
|
||
else 弱网或高丢包，优先中心转发
|
||
Orch->>ZLM: 创建 ZLMediaKit 转发会话
|
||
App->>ZLM: 拉流/推流
|
||
Lock->>ZLM: 推流/拉流
|
||
else P2P/TURN/ZLM 都受限
|
||
Orch->>Relay: 创建中心媒体转发会话
|
||
App->>Relay: 接入中心音视频转发
|
||
Lock->>Relay: 接入中心音视频转发
|
||
end
|
||
|
||
App->>BifroMQ: 会话控制消息 accept/hangup
|
||
Lock->>BifroMQ: 会话状态更新
|
||
Orch->>Orch: 聚合状态并记录 trace
|
||
```
|
||
|
||
### 5.2.1 弱网判定与自动切换规则
|
||
|
||
为了让“弱网优先 `ZLMediaKit`”可执行，建议 `session-orchestrator` 在建链前和通话中都持续评估以下指标：
|
||
|
||
- RTT：连续 3 个采样窗口平均 RTT `> 250ms`
|
||
- 丢包率：上行或下行连续 3 个窗口丢包率 `> 8%`
|
||
- 抖动：连续 3 个窗口抖动 `> 30ms`
|
||
- 实际可用上行带宽：低于当前音视频档位最低要求的 `1.3x` 安全阈值
|
||
- NAT/连通性：ICE 在限定时间内无法形成稳定 candidate pair，或只剩高成本 relay 路径
|
||
|
||
建议默认策略如下：
|
||
|
||
1. 建链前网络探测显示 RTT、丢包、抖动都健康时，优先 `WebRTC P2P`。
|
||
2. 建链前就已经出现高丢包、复杂 NAT、运营商弱网或企业网限制时，直接优先 `ZLMediaKit`。
|
||
3. P2P 已建成但连续 `5-10s` 质量低于阈值时，先尝试降码率、降分辨率、关闭非关键视频层。
|
||
4. 降档后仍连续 `10-15s` 不达标时，从 P2P/TURN 自动切到 `ZLMediaKit`。
|
||
5. 只有在 `ZLMediaKit` 也不可用，或该设备型号暂不支持对应接入方式时，才退回通用 `media-relay` 兜底。
|
||
|
||
建议把这些阈值做成可配置项，而不是写死在代码里；不同设备型号、码率档位、音频优先级和运营商环境下，实际阈值会有差异。
|
||
|
||
### 5.3 AI 旁路模式
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Lock as Lock/Gateway
|
||
participant App as APP
|
||
participant Starlock as starlock
|
||
participant Orch as session-orchestrator
|
||
participant AIGW as ai-gateway
|
||
participant Xiao as xiaozhi_server
|
||
|
||
App->>Starlock: 请求开启 AI 模式
|
||
Starlock->>Starlock: 校验 AI 权限/套餐/设备能力
|
||
Starlock->>Orch: 为当前会话启用 AI sidecar
|
||
Orch->>AIGW: 创建 ai session
|
||
AIGW->>Xiao: 建立 AI 对话会话
|
||
|
||
Lock->>AIGW: 推送音频副本或独立音频流
|
||
AIGW->>Xiao: 转发音频
|
||
Xiao-->>AIGW: ASR / 意图 / TTS / 工具调用结果
|
||
|
||
alt AI 辅助模式
|
||
AIGW-->>Starlock: 摘要/关键词/告警事件
|
||
else AI 应答模式
|
||
AIGW-->>Lock: TTS 音频或文本应答
|
||
AIGW-->>App: AI 状态与结果
|
||
end
|
||
```
|
||
|
||
## 6. 服务清单与职责设计
|
||
|
||
### 6.1 `starlock`
|
||
|
||
角色：租户应用层业务入口。
|
||
|
||
关键职责：
|
||
|
||
- 对外提供 APP 业务 API
|
||
- 编排 `starcloud` 共享业务能力
|
||
- 管理租户/渠道差异化配置
|
||
- 生成实时会话请求
|
||
- 向 APP 返回会话入口信息
|
||
|
||
不负责：
|
||
|
||
- 长连接连接保持
|
||
- WebRTC signaling 分发
|
||
- 大媒体转发
|
||
- 重复实现本应沉淀到 `starcloud` 的通用业务能力
|
||
|
||
### 6.1.1 `starcloud`
|
||
|
||
角色：共享业务能力云平台。
|
||
|
||
关键职责：
|
||
|
||
- 对下游应用（包括 `starlock`）输出可复用业务 API
|
||
- 沉淀用户、权限、套餐、审计等通用能力
|
||
- 承载跨项目可复用的业务规则与模型
|
||
- 减少同类项目重复开发，提升统一治理能力
|
||
|
||
### 6.2 `session-orchestrator`
|
||
|
||
角色：实时会话编排中心。
|
||
|
||
关键职责：
|
||
|
||
- 创建 `sessionId`
|
||
- 生成 signaling topic
|
||
- 生成短期 session token
|
||
- 聚合会话状态：`pending`、`ringing`、`accepted`、`connected`、`ended`
|
||
- 管理媒体兜底策略：`p2p`、`turn`、`relay`、`zlmediakit`
|
||
- 根据网络质量阈值执行媒体路径切换
|
||
- 管理 AI sidecar 生命周期
|
||
- 写会话 trace、诊断日志
|
||
|
||
不负责：
|
||
|
||
- 用户权限判断
|
||
- 业务订单/套餐判断
|
||
- 持久化完整业务模型
|
||
|
||
#### 为什么需要它
|
||
|
||
`session-orchestrator` 这个名字容易让人误以为它是一个很重的“中央调度服务”，其实不是。
|
||
|
||
它本质上只是一个“实时会话状态机”，作用是把下面几类逻辑从 `starlock` 的普通业务接口里剥出来：
|
||
|
||
- 创建一次实时会话
|
||
- 给这次会话分配 `sessionId`
|
||
- 给 APP 和设备生成本次会话可用的 signaling topic
|
||
- 生成短期 session token / TURN 凭证
|
||
- 在需要时切换中心媒体转发或 `ZLMediaKit` 流转发
|
||
- 维护这次会话的状态变化：响铃、接听、连接成功、挂断、异常结束
|
||
|
||
换句话说，它不决定“这个人有没有权限打这个锁”；这类权限决策通常由 `starlock` 发起并结合 `starcloud` 共享能力完成。它只负责“既然已经允许打了，那这通会话怎么被安全地建起来并结束”。
|
||
|
||
#### 为什么必须独立服务
|
||
|
||
按当前决策，`session-orchestrator` 必须从第一阶段独立部署，理由是：
|
||
|
||
- 视频会话控制与业务 API 解耦，避免 `starlock` 发布节奏被实时链路牵制
|
||
- 统一替代历史 UDP 分散控制，形成中心化状态机治理
|
||
- 路由切换策略（`p2p/turn/zlmediakit/relay`）可独立演进
|
||
- 会话可观测性（trace、失败原因、切路记录）可统一沉淀
|
||
|
||
落地约束：
|
||
|
||
1. `starlock` 只负责权限校验、业务编排、对外 API。
|
||
2. `session-orchestrator` 负责会话状态机、控制命令、超时收敛、媒体路径决策。
|
||
3. APP/设备只认会话级 topic 与短期 token，不直接依赖业务后台内部状态。
|
||
|
||
#### 会话控制协议建议（替代旧 UDP 开始/结束协议）
|
||
|
||
建议把“开始/结束”从 UDP 专用协议，升级为统一会话控制事件：
|
||
|
||
- `sessions/{sessionId}/control`：`invite`、`ringing`、`accept`、`reject`、`hangup`、`switch-route`、`terminate`
|
||
- `sessions/{sessionId}/status`：`pending`、`connecting`、`connected`、`degraded`、`switching_route`、`ended`、`failed`
|
||
|
||
每条控制事件都带：
|
||
|
||
- `sessionId`
|
||
- `eventId`（单调递增）
|
||
- `from`（app/device/orchestrator）
|
||
- `ts`
|
||
- `ackTimeoutMs`
|
||
|
||
处理规则：
|
||
|
||
1. 未 ACK 的控制事件按策略重发。
|
||
2. 超过最大重试进入 `timeout` 或 `failed`。
|
||
3. 任一终态都由 `session-orchestrator` 写最终状态并触发资源清理。
|
||
|
||
#### 归属结论与简化实现（提炼版）
|
||
|
||
归属结论：
|
||
|
||
- `session-orchestrator` 属于云端实时基础设施层，不属于 APP 端，也不属于设备端。
|
||
- 它是被 `starlock` 调用的独立服务。
|
||
- `starlock` 负责业务授权与编排，`session-orchestrator` 负责视频会话控制与状态机收敛。
|
||
|
||
技术建议：
|
||
|
||
- 首选 Go 实现独立服务（更适合高并发会话状态控制）。
|
||
|
||
|
||
简单实现方法（MVP）：
|
||
|
||
1. 先独立部署 `session-orchestrator`，并配套 `Redis`（热状态/重试队列）与 `MySQL`（会话记录/审计）。
|
||
2. 先开三个内部接口：创建会话、结束会话、开启 AI sidecar，`starlock` 只通过这三个接口编排实时流程。
|
||
3. APP/设备统一使用会话级 topic：`sessions/{sessionId}/control` 与 `sessions/{sessionId}/status`，不再用旧 UDP 协议字段直接控制开始/结束。
|
||
4. 按固定状态机落地：`pending -> ringing -> accepted -> connecting -> connected -> ended/failed`，并实现 ACK 超时重试。
|
||
5. 媒体选路先做最小闭环：`p2p -> turn -> zlmediakit -> relay`，由 `session-orchestrator` 统一下发 `switch-route`。
|
||
6. 灰度迁移旧方案：先镜像上报、再双栈并行、最后下线旧 UDP 开始/结束控制。
|
||
|
||
### 6.3 `Apache BifroMQ`
|
||
|
||
角色：发现、在线、信令总线。
|
||
|
||
关键职责：
|
||
|
||
- 设备 presence
|
||
- retained capabilities
|
||
- signaling 消息传递
|
||
- 控制类 topic 分发
|
||
- ACL 与连接鉴权
|
||
|
||
不负责：
|
||
|
||
- 大媒体流
|
||
- 复杂业务校验
|
||
|
||
### 6.4 `coturn`
|
||
|
||
角色：RTC 网络兜底。
|
||
|
||
关键职责：
|
||
|
||
- STUN
|
||
- TURN relay
|
||
- 临时凭证校验
|
||
|
||
### 6.4.1 `media-relay`
|
||
|
||
角色：中心服务器音视频转发兜底。
|
||
|
||
关键职责：
|
||
|
||
- 在 P2P/TURN 都不可用时承接音视频转发
|
||
- 兼容旧设备或弱网场景
|
||
- 为录制、审计、媒体后处理保留中心接入点
|
||
- 作为一个能力层存在，不要求必须单独做成自研服务
|
||
|
||
### 6.4.2 `ZLMediaKit`
|
||
|
||
角色：中心媒体转发能力的优先实现方案。
|
||
|
||
关键职责：
|
||
|
||
- 提供比自定义 relay 更标准的媒体转发实现
|
||
- 支持 WebRTC、推流、拉流、转协议和中心媒体接入
|
||
- 可直接承接 `media-relay` 这层能力，逐步替代自研转发逻辑
|
||
- 在弱网、高抖动、高丢包场景下，可作为比 P2P 更稳的优先媒体方案
|
||
|
||
#### 结合 WebRTC 怎么理解
|
||
|
||
- 中好网络时，首选仍然是 App 与设备直接做 WebRTC P2P。
|
||
- 弱网、高丢包、复杂 NAT 或需要录制审计时，可以直接优先 `ZLMediaKit`。
|
||
- 如果仍希望保持 RTC 直连能力，可让 `coturn` 作为 RTC 路径补位。
|
||
- 当 `ZLMediaKit` 也受限或需要特殊兼容时，再切到更通用的中心转发能力。
|
||
- 这时中心转发不一定再单独做一套自研 `media-relay` 服务，可以直接由 `ZLMediaKit` 承担。
|
||
|
||
#### 弱网下哪个更适合作为首选
|
||
|
||
- 如果目标是“弱网下更稳”，通常优先 `ZLMediaKit` 转发，而不是 WebRTC P2P。
|
||
- 原因是 P2P 更依赖两端实时网络质量、NAT 情况和上行稳定性；弱网下抖动、重传、带宽突降会更明显暴露出来。
|
||
- `ZLMediaKit` 走中心接入点，更容易做统一的拥塞控制、转协议、录制和链路治理，所以在弱网场景更适合作为首选方案。
|
||
- 只有在网络质量较好、希望最低时延和最低中心带宽成本时，才应把 WebRTC P2P 放到第一位。
|
||
|
||
|
||
- 如果你的意思是“完全不要中心转发能力”，不建议。
|
||
- 原因是 WebRTC P2P 和 TURN 仍然会遇到设备兼容性、弱网、企业网限制、录制审计、协议桥接等场景，这些场景仍需要中心接入点。
|
||
- 更合理的做法是：保留中心转发这层能力，但把实现尽量收敛到 `ZLMediaKit`，不要长期维护两套并行转发系统。
|
||
|
||
### 6.5 `ai-gateway`
|
||
|
||
角色：AI 桥接层。
|
||
|
||
关键职责：
|
||
|
||
- 为设备或会话创建 AI session
|
||
- 对接 `xiaozhi_server`
|
||
- 在 AI 模式和业务模式之间做协议适配
|
||
- 把 AI 结果回送 `starlock`、APP 或设备
|
||
|
||
不负责：
|
||
|
||
- 用户体系
|
||
- 主对讲状态机
|
||
|
||
### 6.6 `event-listener` 是否还能保留
|
||
|
||
这个问题要拆成两类：
|
||
|
||
#### 类别一：实时通知分发
|
||
|
||
这部分很多是可以用 MQTT 做的。
|
||
|
||
例如：
|
||
|
||
- 设备上线/下线通知
|
||
- 门锁状态变化通知
|
||
- 振铃通知
|
||
- 会话状态变化通知
|
||
- AI 摘要完成通知
|
||
|
||
这类消息天然适合通过 MQTT 分发，因为它们是轻量消息、低延迟、面向订阅者的实时通知。
|
||
|
||
#### 类别二：业务事件消费与回调
|
||
|
||
这部分不建议只靠 MQTT 替代。
|
||
|
||
例如：
|
||
|
||
- 设备上报开锁记录
|
||
- 报警事件
|
||
- 图片/视频文件处理
|
||
- 回调 `starlock` 或其它 HTTP 接口
|
||
- 做重试、幂等、失败补偿、落库
|
||
|
||
这些更像“异步业务任务”，而不只是“通知”。如果只用 MQTT 裸消费，后面你很容易遇到这些问题：
|
||
|
||
- 消费失败后的补偿不清楚
|
||
- 回调重试策略分散
|
||
- 消息被订阅了，但业务并没有真正处理成功
|
||
- 文件处理、转码、上传对象存储这类任务不适合留在纯通知链路里
|
||
|
||
所以更合理的做法是：
|
||
|
||
- 用 MQTT 承担“事件通知总线”
|
||
- 保留一个事件消费器来做“业务处理和回调”
|
||
|
||
这个消费器仍然可以继续叫 `event-listener`，但它的角色要重新定义。
|
||
|
||
#### 推荐的新定义
|
||
|
||
建议把 `event-listener` 改成：
|
||
|
||
- 订阅 MQTT 事件主题
|
||
- 负责把事件写入业务处理流水
|
||
- 负责做 HTTP 回调、对象存储、媒体后处理、重试和幂等
|
||
|
||
也就是说，它不再是老架构里“星图协议事件接收器”，而是“MQTT 事件消费器 + 业务回调 worker”。
|
||
|
||
这个改法是最平滑的，因为：
|
||
|
||
- 设备侧事件入口可以改成 MQTT
|
||
- 你们现有很多事件处理逻辑还能保留
|
||
- `starlock` 不需要直接订阅所有低层设备消息
|
||
|
||
## 6.7 对你当前项目的更实际建议
|
||
|
||
结合你现在的系统，我建议这样落：
|
||
|
||
### 第一阶段
|
||
|
||
- 独立部署 `session-orchestrator` 服务
|
||
- `starlock` 专注业务授权与编排，实时会话状态机由 `session-orchestrator` 承担
|
||
- 新增通用业务能力优先落在 `starcloud`，再由 `starlock` 编排调用
|
||
- 用 Apache BifroMQ 做 presence + signaling
|
||
- 保留现有中心服务器音视频转发作为兜底
|
||
- 直接把 `ZLMediaKit` 作为中心转发优先实现，逐步下线自研 relay
|
||
- 保留一个 `event-listener` worker，改为订阅 MQTT 事件并做业务回调
|
||
|
||
### 第二阶段
|
||
|
||
- 根据会话量扩容 `session-orchestrator`（多实例 + 会话分片/一致性哈希）
|
||
- 如果事件量很大，再把 `event-listener` 拆成多类 worker：
|
||
- 业务回调 worker
|
||
- 媒体处理 worker
|
||
- AI 结果消费 worker
|
||
|
||
### 一句话判断
|
||
|
||
- `session-orchestrator` 从第一阶段就独立部署，“实时会话状态机”不内嵌到 `starlock`
|
||
- `event-listener` 的通知入口可以迁到 MQTT，但“业务处理与回调”仍然建议保留专门消费者，不要只靠 MQTT 本身完成
|
||
|
||
## 7. 设备形态建议
|
||
|
||
### 7.1 推荐的设备侧分层
|
||
|
||
对你当前项目，`WiFi锁` 默认按网关锁能力建设，可直接承接高能力终端职责。
|
||
|
||
如果后续扩展到多设备形态（低功耗锁体 + 高能力网关），再按下面方式分层：
|
||
|
||
- 锁体 MCU：负责电机、门磁、电池、基础控制协议
|
||
- 网关/猫眼/门口机/Linux SoC：负责摄像头、麦克风、编码、WebRTC、AI 侧接入
|
||
|
||
### 7.2 不建议的做法
|
||
|
||
当前项目因为 `WiFi锁` 已是网关锁形态，本节主要用于后续低功耗设备线扩展时参考。
|
||
|
||
不建议把完整 WebRTC 栈强行压到能力非常有限的锁体 MCU 上，除非你已经确认：
|
||
|
||
- 编码能力足够
|
||
- 网络和 TLS 栈足够稳定
|
||
- 长连接状态机可维护
|
||
- 双讲回声、抖动和弱网体验可接受
|
||
|
||
如果只是探索方向，可以参考 `libpeer-main` 作为设备侧 C WebRTC 库候选，但量产方案仍应优先基于更成熟的端侧平台或网关代理。
|
||
|
||
## 8. 接口草案
|
||
|
||
以下接口草案按“APP -> starlock -> realtime services”关系设计。
|
||
|
||
### 8.1 APP 调 `starlock`
|
||
|
||
#### 创建会话
|
||
|
||
`POST /api/realtime/sessions`
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"deviceId": "lock_123456",
|
||
"sessionType": "talk",
|
||
"mediaPolicy": {
|
||
"strategy": "adaptive",
|
||
"preferP2PWhenGoodNetwork": true,
|
||
"preferZlmWhenWeakNetwork": true,
|
||
"autoSwitch": true
|
||
},
|
||
"media": {
|
||
"audio": true,
|
||
"video": true,
|
||
"dataChannel": true
|
||
},
|
||
"aiMode": "disabled"
|
||
}
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "sess_01HT...",
|
||
"role": "caller",
|
||
"mqtt": {
|
||
"brokerUrl": "wss://mq.example.com:8084/mqtt",
|
||
"clientId": "app_user_1001_sess_01HT",
|
||
"username": "app_user_1001",
|
||
"password": "temp-password",
|
||
"topics": {
|
||
"signalPublish": "sessions/sess_01HT/signal/app",
|
||
"signalSubscribe": "sessions/sess_01HT/signal/device",
|
||
"control": "sessions/sess_01HT/control"
|
||
}
|
||
},
|
||
"rtc": {
|
||
"iceServers": [
|
||
{
|
||
"urls": ["stun:turn.example.com:3478"]
|
||
},
|
||
{
|
||
"urls": ["turn:turn.example.com:3478?transport=udp"],
|
||
"username": "turn-user",
|
||
"credential": "turn-pass"
|
||
}
|
||
]
|
||
},
|
||
"mediaRoute": {
|
||
"selected": "p2p",
|
||
"candidates": ["p2p", "turn", "zlmediakit", "relay"],
|
||
"switchPolicy": {
|
||
"rttMs": 250,
|
||
"packetLossRate": 0.08,
|
||
"jitterMs": 30,
|
||
"degradeDurationSec": 10
|
||
}
|
||
},
|
||
"sessionToken": "jwt-or-paseto"
|
||
}
|
||
```
|
||
|
||
#### 结束会话
|
||
|
||
`POST /api/realtime/sessions/{sessionId}/terminate`
|
||
|
||
#### 查询会话详情
|
||
|
||
`GET /api/realtime/sessions/{sessionId}`
|
||
|
||
#### 开启 AI 模式
|
||
|
||
`POST /api/realtime/sessions/{sessionId}/ai`
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"mode": "assistant",
|
||
"voiceProfile": "default",
|
||
"intentScope": ["intercom", "unlock", "qa"]
|
||
}
|
||
```
|
||
|
||
### 8.2 `starlock` 调 `session-orchestrator`
|
||
|
||
#### 创建内部会话
|
||
|
||
`POST /internal/realtime/sessions`
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "sess_01HT...",
|
||
"tenantId": 1,
|
||
"userId": 1001,
|
||
"deviceId": "lock_123456",
|
||
"sessionType": "talk",
|
||
"mediaPolicy": {
|
||
"audio": true,
|
||
"video": true,
|
||
"p2pPreferred": true,
|
||
"turnFallback": true,
|
||
"zlmPreferredWhenWeakNetwork": true,
|
||
"autoSwitch": true,
|
||
"thresholds": {
|
||
"rttMs": 250,
|
||
"packetLossRate": 0.08,
|
||
"jitterMs": 30,
|
||
"degradeDurationSec": 10
|
||
}
|
||
},
|
||
"authContext": {
|
||
"familyId": 2002,
|
||
"permissionSnapshot": ["device.talk", "device.view"]
|
||
}
|
||
}
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "sess_01HT...",
|
||
"mqttTopics": {
|
||
"deviceSignal": "sessions/sess_01HT/signal/device",
|
||
"appSignal": "sessions/sess_01HT/signal/app",
|
||
"control": "sessions/sess_01HT/control"
|
||
},
|
||
"sessionToken": "signed-token",
|
||
"mediaRoute": {
|
||
"selected": "p2p",
|
||
"fallbackOrder": ["turn", "zlmediakit", "relay"]
|
||
},
|
||
"turnCredential": {
|
||
"username": "turn-u",
|
||
"credential": "turn-c",
|
||
"ttl": 300
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 上报业务结束态
|
||
|
||
`POST /internal/realtime/sessions/{sessionId}/finalize`
|
||
|
||
#### 开启 AI sidecar
|
||
|
||
`POST /internal/realtime/sessions/{sessionId}/ai-sidecar`
|
||
|
||
### 8.3 设备 bootstrap 接口
|
||
|
||
设备不应长期写死 MQTT 密钥，建议通过 `starlock` 或设备接入子服务换取短期凭证。
|
||
|
||
`POST /internal/device/bootstrap`
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"deviceId": "lock_123456",
|
||
"firmwareVersion": "2.3.1",
|
||
"nonce": "abc123",
|
||
"signature": "device-signature"
|
||
}
|
||
```
|
||
|
||
### 8.4 `starlock` 调 `starcloud` 共享业务 API
|
||
|
||
#### 权限快照与策略校验
|
||
|
||
`POST /internal/starcloud/policy/evaluate`
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"tenantId": 1,
|
||
"userId": 1001,
|
||
"deviceId": "lock_123456",
|
||
"action": "device.talk",
|
||
"context": {
|
||
"familyId": 2002,
|
||
"channel": "app-starlock"
|
||
}
|
||
}
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"allow": true,
|
||
"policyVersion": "pcv_20260422_01",
|
||
"permissionSnapshot": ["device.talk", "device.view"],
|
||
"reason": "matched-tenant-policy"
|
||
}
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"mqtt": {
|
||
"clientId": "lock_123456",
|
||
"username": "lock_123456",
|
||
"password": "temporary-secret",
|
||
"expireAt": 1713700000
|
||
},
|
||
"topics": {
|
||
"presence": "locks/lock_123456/presence",
|
||
"capabilities": "locks/lock_123456/capabilities",
|
||
"commands": "locks/lock_123456/commands",
|
||
"signal": "locks/lock_123456/signals"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 9. Apache BifroMQ Topic 设计
|
||
|
||
### 9.1 设备级 topic
|
||
|
||
- `locks/{deviceId}/presence`
|
||
- `locks/{deviceId}/capabilities`
|
||
- `locks/{deviceId}/status`
|
||
- `locks/{deviceId}/commands`
|
||
- `locks/{deviceId}/events`
|
||
- `locks/{deviceId}/signals`
|
||
|
||
#### 用途说明
|
||
|
||
- `presence`：在线/离线，建议 retained + LWT
|
||
- `capabilities`：设备支持的编码、AI、摄像头、麦克风等能力，建议 retained
|
||
- `status`：电量、网络质量、门状态、当前是否忙
|
||
- `commands`：来自后台或 APP 的设备控制命令
|
||
- `events`：设备产生的业务事件
|
||
- `signals`：设备级呼叫通知或预唤起 signaling
|
||
|
||
### 9.2 会话级 topic
|
||
|
||
- `sessions/{sessionId}/signal/app`
|
||
- `sessions/{sessionId}/signal/device`
|
||
- `sessions/{sessionId}/control`
|
||
- `sessions/{sessionId}/status`
|
||
- `sessions/{sessionId}/ai-events`
|
||
|
||
### 9.3 消息类型建议
|
||
|
||
`signal/*` 统一使用以下类型：
|
||
|
||
- `offer`
|
||
- `answer`
|
||
- `candidate`
|
||
- `restart-ice`
|
||
|
||
`control` 使用：
|
||
|
||
- `ringing`
|
||
- `accept`
|
||
- `reject`
|
||
- `hangup`
|
||
- `mute`
|
||
- `unmute`
|
||
- `pause-video`
|
||
- `resume-video`
|
||
|
||
`status` 使用：
|
||
|
||
- `pending`
|
||
- `connecting`
|
||
- `connected`
|
||
- `reconnecting`
|
||
- `ended`
|
||
- `error`
|
||
|
||
### 9.4 ACL 建议
|
||
|
||
APP 在某个会话中只允许：
|
||
|
||
- 发布：`sessions/{sessionId}/signal/app`
|
||
- 订阅：`sessions/{sessionId}/signal/device`
|
||
- 发布/订阅：`sessions/{sessionId}/control`、`sessions/{sessionId}/status`
|
||
|
||
设备在某个会话中只允许：
|
||
|
||
- 发布：`sessions/{sessionId}/signal/device`
|
||
- 订阅：`sessions/{sessionId}/signal/app`
|
||
- 发布/订阅：`sessions/{sessionId}/control`、`sessions/{sessionId}/status`
|
||
|
||
这样可以避免跨会话串话和 topic 污染。
|
||
|
||
## 10. Session Token 设计
|
||
|
||
### 10.1 设计目标
|
||
|
||
session token 只表达“某个主体在某个短会话里的实时权限”，不重复承载完整业务模型。
|
||
|
||
### 10.2 推荐字段
|
||
|
||
推荐使用 JWT 或 PASETO，字段如下：
|
||
|
||
```json
|
||
{
|
||
"iss": "starlock",
|
||
"aud": "realtime",
|
||
"sub": "user:1001",
|
||
"sid": "sess_01HT...",
|
||
"did": "lock_123456",
|
||
"role": "caller",
|
||
"scp": ["signal", "rtc", "ai:disabled"],
|
||
"tenant": 1,
|
||
"family": 2002,
|
||
"exp": 1713700300,
|
||
"nbf": 1713700000,
|
||
"jti": "uuid"
|
||
}
|
||
```
|
||
|
||
### 10.3 说明
|
||
|
||
- `sid`：绑定单个会话
|
||
- `did`：绑定单个设备
|
||
- `role`：`caller`、`callee`、`observer`、`ai-sidecar`
|
||
- `scp`：实时权限范围，如 `signal`、`rtc`、`ai`、`record`
|
||
- 过期时间建议 5 到 10 分钟
|
||
|
||
### 10.4 验证位置
|
||
|
||
- `session-orchestrator` 验证 token
|
||
- MQTT ACL 网关可基于 token 生成动态权限
|
||
- TURN 凭证由 `session-orchestrator` 基于 session token 派生
|
||
- `ai-gateway` 验证是否允许 AI 接入
|
||
|
||
## 11. 数据模型建议
|
||
|
||
### 11.1 `starlock` 保存
|
||
|
||
- `users`
|
||
- `families`
|
||
- `locks`
|
||
- `family_lock_members`
|
||
- `device_permissions`
|
||
- `realtime_session_records`
|
||
- `ai_usage_records`
|
||
|
||
### 11.2 新实时项目保存
|
||
|
||
- `device_presence_snapshot`
|
||
- `device_capability_snapshot`
|
||
- `realtime_session_state`
|
||
- `realtime_session_trace`
|
||
- `signaling_audit_log`
|
||
- `ai_session_state`
|
||
|
||
### 11.3 数据归属原则
|
||
|
||
- 用户与业务归属只认 `starlock`
|
||
- 新实时项目只保存运行时弱状态和诊断数据
|
||
- 异常恢复时可允许丢失部分弱状态，但不能影响业务主数据
|
||
|
||
## 12. AI 接入策略
|
||
|
||
### 12.1 三种模式
|
||
|
||
#### 模式一：`human_to_human`
|
||
|
||
纯 APP 与设备对讲。
|
||
|
||
#### 模式二：`human_assisted`
|
||
|
||
AI 作为旁路助手，提供：
|
||
|
||
- 转写
|
||
- 摘要
|
||
- 关键词告警
|
||
- 指令识别
|
||
|
||
#### 模式三：`human_to_ai`
|
||
|
||
用户直接与设备上的 AI 交互，设备通过 `ai-gateway` 接入 `xiaozhi_server`。
|
||
|
||
### 12.2 推荐优先级
|
||
|
||
上线顺序建议是：
|
||
|
||
1. 先做人对人对讲
|
||
2. 再做 AI 辅助
|
||
3. 最后做设备直连 AI 应答
|
||
|
||
### 12.3 为什么 AI 必须旁路化
|
||
|
||
因为 AI 是高延迟、可失败、可替换的能力。如果把它直接嵌入主通话状态机：
|
||
|
||
- AI 延迟会拖慢接听体验
|
||
- AI 故障会中断主通话
|
||
- 后续替换 `xiaozhi_server` 成本高
|
||
|
||
## 13. 演进路径
|
||
|
||
### Phase 1：发现与在线迁移
|
||
|
||
目标：把设备发现、在线状态、基础 signaling 从 `scd` 拆到 Apache BifroMQ。
|
||
|
||
交付：
|
||
|
||
- 设备 bootstrap
|
||
- MQTT 连接鉴权
|
||
- presence / capability / status topic
|
||
- APP 通过 `starlock` 获取设备在线态
|
||
|
||
### Phase 2：WebRTC 对讲上线
|
||
|
||
目标：让音视频主链路切到 WebRTC。
|
||
|
||
交付：
|
||
|
||
- APP 端 WebRTC
|
||
- 设备或网关端 WebRTC
|
||
- TURN 兜底
|
||
- 中心媒体转发兜底
|
||
- `ZLMediaKit` 转发方案打通
|
||
- signaling 全链路打通
|
||
|
||
### Phase 3：AI 辅助模式上线
|
||
|
||
目标：接入 `xiaozhi_server`，但不侵入主媒体链路。
|
||
|
||
交付：
|
||
|
||
- ai-gateway
|
||
- AI sidecar
|
||
- 转写/摘要/命令识别
|
||
|
||
### Phase 4：旧通信层逐步退役
|
||
|
||
目标：减少对 `starchart-sls1` 中发现和媒体 relay 能力的依赖。
|
||
|
||
保留项可按实际评估：
|
||
|
||
- 某些设备尚未迁移时的兼容 relay
|
||
- 某些 RPC 查询能力
|
||
- 事件回调历史逻辑
|
||
|
||
## 14. 风险与决策点
|
||
|
||
### 14.1 最大技术风险
|
||
|
||
- 设备端是否真有能力稳定跑 WebRTC
|
||
- 音频 codec 选型是否统一
|
||
- 双讲回声与弱网体验是否可接受
|
||
- TURN 成本与带宽预算
|
||
|
||
### 14.2 关键决策点
|
||
|
||
已经定下：
|
||
|
||
1. WebRTC 终端跑在锁体、网关
|
||
2. 音频 codec 兼容 G711 桥接
|
||
3. 会话信令完全走 MQTT
|
||
4. AI 能提供的功能都用上
|
||
|
||
## 15. 推荐结论
|
||
|
||
最终推荐方案如下：
|
||
|
||
- `starcloud`：共享业务能力主平台
|
||
- `starlock`：租户化应用层与 APP 业务入口
|
||
- `Apache BifroMQ`：发现、在线、会话 signaling
|
||
- `session-orchestrator`：实时会话编排中心
|
||
- `coturn`：RTC 第一层兜底
|
||
- `media-relay` 能力层，由 `ZLMediaKit` 优先实现：P2P/TURN 失败后的中心转发兜底
|
||
- `ai-gateway + xiaozhi_server`：AI 能力面
|
||
- 设备侧优先由网关/高能力终端承担 WebRTC 与 AI，而不是全部压到低功耗锁体
|
||
|
||
这套方案能把你现在的“中央通信系统”拆成可演进的分层结构，同时把通用业务能力沉淀到 `starcloud`，由 `starlock` 聚焦租户化编排与应用体验层。 |