下面这份是**基于你提供的“智能锁新实时系统方案”整理的模块开发周期、技术栈、难点和注意事项**。我按**第一阶段独立部署 `session-orchestrator`** 的方案来拆分。 > 预估��提： > - `starcloud`、`starlock`、`app-starlock`、现有设备端已有基础能力。 > - 新项目重点是实时控制面、BifroMQ、WebRTC/TURN/ZLMediaKit、事件链路、AI 旁路。 > - 团队配置按：后端 2 人、APP 1 人、设备端 1 人、运维 1 人、测试 1 人估算。 > - 如果设备端 WebRTC 能力要从零做，周期要明显增加。 --- # 一、整体开发阶段建议 ## 阶段划分 | 阶段 | 目标 | 周期预估 | |---|---|---| | 阶段 0：方案细化与协议设计 | 确定 topic、状态机、API、媒体选路策略 | 1 - 2 周 | | 阶段 1：实时控制面 MVP | 完成 `session-orchestrator`、`device-bootstrap`、BifroMQ 基础接入 | 3 - 5 周 | | 阶段 2：WebRTC / TURN / ZLM 媒体链路 | 完成 P2P、TURN、ZLMediaKit 基础切换 | 4 - 8 周 | | 阶段 3：APP 与设备端联调 | APP、WiFi 锁、后台完整跑通呼叫、接听、挂断、切路 | 4 - 6 周 | | 阶段 4：事件、日志、可观测、弱网优化 | 完成事件消费、质量上报、链路追踪、告警 | 2 - 4 周 | | 阶段 5：AI 旁路接入 | 接入 `ai-gateway`、`xiaozhi_server` | 2 - 4 周 | | 阶段 6：灰度上线与稳定性优化 | 压测、弱网测试、灰度、回滚方案 | 2 - 4 周 | ## 总周期预估 | 范围 | 周期 | |---|---| | 最小可用版本 MVP | 8 - 12 周 | | 可灰度上线版本 | 12 - 16 周 | | 含 AI、完整动态选路、完整可观测版本 | 16 - 24 周 | --- # 二、模块开发周期、技术栈、难点与注意事项 ## 1. `starlock` 租户应用层改造 ### 模块定位 `starlock` 是 APP 的统一业务入口，负责： - APP 登录鉴权 - 家庭 / 门锁归属判断 - 调用 `starcloud` 共享能力 - 调用 `session-orchestrator` 创建实时会话 - 下发短期会话权限 - 处理事件回调和业务通知 ### 开发周期 **2 - 4 周** 如果现有 PHP 代码结构清晰，只做 API 编排，约 2 周。 如果需要整理权限、设备归属、租户模型，可能 4 周以上。 ### 技术栈 | 类型 | 技术 | |---|---| | 后端语言 | PHP | | 框架 | Laravel / ThinkPHP / Yii / 原有框架，按现状 | | API | RESTful API | | 认证 | JWT / Session / OAuth2 内部 token | | 数据库 | MySQL / PostgreSQL | | 缓存 | Redis | | 内部调用 | HTTP / gRPC，可先 HTTP | | 日志 | Monolog / ELK / Loki | ### 主要开发内容 - 新增“创建视频会话”接口 - 调用 `session-orchestrator` 创建 `sessionId` - 根据用户、家庭、门锁关系做权限校验 - 返回 APP 所需短期 token、MQTT topic、媒体策略 - 处理 `MQTT event worker` 回调 - 处理 AI 会话状态回调 - 保留对 `starcloud` 的共享能力调用 ### 难点 1. **权限边界** - APP 用户是否有权访问某把锁 - 家庭成员、租户、渠道、套餐规则是否影响通话权限 2. **短期会话权限设计** - APP 不能直接拿长期业务 token 去访问实时系统 - 需要生成短期、单会话、可过期的 token 3. **业务状态与实时状态解耦** - `starlock` 不应该维护完整通话状��机 - 它只关心会话结果、事件回调和业务通知 4. **兼容旧链路** - 旧 UDP 控制、旧 `scd/scrd/rpcd` 可能仍有设备在用 - 需要新旧能力并存一段时间 ### 注意事项 - `starlock` 不要直接搬运 WebRTC signaling。 - APP 不应直接访问 `session-orchestrator` 的内部管理接口。 - 所有会话创建都必须经过设备归属和家庭权限校验。 - 短期 token 要绑定： - `userId` - `deviceId` - `sessionId` - 过期时间 - 权限范围 - 事件回调要做幂等处理，防止重复消费。 - 所有敏感操作要写审计日志。 --- ## 2. `starcloud` 共享业务能力对接 ### 模块定位 `starcloud` 是共享业务平台，主要提供： - 用户 / 权限策略 - 家庭 / 设备关系 - 套餐 / 计费 - 审计 / 风控 - 通用业务规则 ### 开发周期 **1 - 3 周** 如果现有 API 完备，只需对接和字段适配，约 1 周。 如果需要补充共享能力 API，则需要 2 - 3 周。 ### 技术栈 | 类型 | 技术 | |---|---| | 后端 | 现有 `starcloud` 技术栈 | | API | REST / RPC | | 鉴权 | 内部服务 token / AK-SK / OAuth2 | | 数据库 | 现有数据库 | | 缓存 | Redis | | 审计 | 日志服务 / 审计表 | ### 主要开发内容 - 提供设备归属查询能力 - 提供用户权限策略查询能力 - 提供套��能力判断 - 提供风控和审计接口 - 给 `starlock` 提供标准化业务 API ### 难点 - 多租户和跨项目能力边界容易混乱 - 共享模型与 `starlock` 定制逻辑可能重复 - 权限策略需要兼容现有用户体系 ### 注意事项 - `starcloud` 不直接参与实时会话状态机。 - `starcloud` 只输出通用业务判断，不关心 WebRTC、BifroMQ、ZLM 细节。 - 通用能力和租户定制能力要分清。 - 不要把实时系统的 topic、signaling、media route 等细节侵入 `starcloud`。 --- ## 3. `session-orchestrator` 会话编排服务 ### 模块定位 这是新实时系统的核心模块，负责： - 创建会话 - 管理会话状态机 - 下发控制指令 - 处理 ACK / 超时 / 重试 - 编排 signaling topic - 控制媒体选路 - 记录会话状态和质量数据 ### 开发周期 **4 - 8 周** MVP 版本 4 周左右。 完整支持状态机、切路、追踪、重试、幂等，建议预留 6 - 8 周。 ### 技术栈 推荐技术栈： | 类型 | 推荐 | |---|---| | 后端语言 | Go / Java / Node.js | | 推荐优先级 | Go 或 Java 更适合长连接、并发和状态机 | | Web 框架 | Go Fiber / Gin，Java Spring Boot | | 内部 API | REST / gRPC | | MQTT Client | Eclipse Paho / gmqtt / HiveMQ Client | | 状态缓存 | Redis | | 持久化 | MySQL / PostgreSQL | | 消息序列 | Redis Stream / Kafka，可���续引入 | | 日志追踪 | OpenTelemetry | | 指标 | Prometheus | | 配置 | YAML / ENV / Nacos / Consul | ### 主要开发内容 - `CreateSession` - `InviteDevice` - `AcceptSession` - `RejectSession` - `StartSignaling` - `ReportQuality` - `SwitchRoute` - `Hangup` - `Timeout` - `Terminate` - 会话状态机 - MQTT topic 分配 - 短期 token 校验 - ACK / seq / retry - 会话日志落库 - 媒体策略下发 ### 推荐状态机 ```text pending -> ringing -> accepted -> connecting -> connected -> degraded -> switching_route -> recovered -> ended 异常结束： -> rejected -> timeout -> failed ``` ### 难点 1. **状态一致性** - APP、设备、云端三方状态容易不一致。 - 必须通过状态机和事件序列统一收敛。 2. **ACK 与超时控制** - `invite` 发出后，设备可能离线、延迟、重复 ACK。 - 所有控制指令要有 `seq`、`ack`、`timeout`。 3. **动态选路** - 什么时候从 P2P 切 TURN？ - 什么时候从 TURN 切 ZLM？ - 切路过程中如何不中断或少中断？ 4. **幂等性** - APP 重试创建会话 - 设备重复上报 accept - MQTT 重复投递 - 都必须能安全处理 5. **分布式扩容** - 多个 `session-orchestrator` 实例时，会话归属、锁、状态更新要处理好。 ### 注意事项 - 会话 ID 必须全局唯一。 - 所有指令都要带： - `sessionId` - `eventId` - `seq` - `timestamp` - `expireAt` - `from` - `to` - 状态变更必须有合法状态迁移校验。 - 会话状态建议短期放 Redis，终态落 MySQL。 - 不建议在 MQTT retained message 中保存敏感 signaling。 - `session-orchestrator` 不搬运大媒体流。 - `session-orchestrator` 应只管控制面，不直接承载视频数据。 --- ## 4. `device-bootstrap` 设备接入服务 ### 模块定位 设备首次或周期性接入时，通过该服务获取： - 设备认证 - MQTT 连接参数 - 短期 MQTT 凭证 - 设备 topic 权限 - 设备能力配置 - 固件能力声明 ### 开发周期 **2 - 4 周** 如果设备认证机制已存在，2 周左右。 如果需要重新设计设备证书、密钥、签名，3 - 4 周。 ### 技术栈 | 类型 | 技术 | |---|---| | 后端语言 | Go / Java / PHP 均可 | | API | HTTPS | | 鉴权 | 设备证书 / 设备密钥 / HMAC 签名 | | 存储 | MySQL | | 缓存 | Redis | | MQTT 权限 | BifroMQ Auth Provider / 自定义鉴权 | ### 主要开发内容 - 设备身份校验 - 颁发 MQTT username/password/token - 生成设备 topic ACL - 返回 BifroMQ 连接地址 - 返回心跳周期 - 返回设备配置 - 支持设备能力声明： - 是否支持 WebRTC - 是否支持 ZLM - 是否支持 AI 音频旁路 - 是否支持 BLE 透传 ### 难点 - 设备端时间不准导致签名过期判断失败 - 设备密钥泄露风险 - MQTT ACL 粒度设计 - 新旧设备兼容 ### 注意事项 - 不要给设备长期固定 MQTT 密码。 - MQTT 凭证建议短期有效，可刷新。 - topic 权限必须最小化。 - 设备只能发布和订阅自己的 topic。 - 设备 capability 要版本化，方便后续灰度。 --- ## 5. Apache BifroMQ 模块 ### 模块定位 BifroMQ 承担： - 设备在线状态 - 发现 - MQTT signaling - 事件总线 - APP 与设备信令通道 ### 开发周期 **2 - 4 周** 部署和基础联调 1 - 2 周。 完整 ACL、认证、监控、压测，建议 3 - 4 周。 ### 技术栈 | 类型 | 技术 | |---|---| | MQTT Broker | Apache BifroMQ | | 协议 | MQTT 3.1.1 / MQTT 5 | | APP 连接 | MQTT over WSS | | 设备连接 | MQTT over TLS | | 鉴权 | 自定义 Auth Provider | | 监控 | Prometheus / Grafana | | 日志 | Loki / ELK | ### Topic 设计建议 ```text tenant/{tenantId}/device/{deviceId}/status tenant/{tenantId}/device/{deviceId}/event tenant/{tenantId}/session/{sessionId}/signal/app tenant/{tenantId}/session/{sessionId}/signal/device tenant/{tenantId}/session/{sessionId}/control tenant/{tenantId}/session/{sessionId}/quality ``` ### 难点 1. **topic 权限控制** - APP 只能访问自己本次会话相关 topic。 - 设备只能访问自己所属 topic。 2. **在线状态判断** - MQTT connected 不等于设备业务可用。 - 需要结合心跳、lastWill、设备能力状态。 3. **QoS 选择** - signaling 可用 QoS 1。 - 质量上报可用 QoS 0。 - 控制指令建议 QoS 1 + 应用层 ACK。 4. **消息顺序** - MQTT 不能替代完整状态机。 - 状态一致性仍应由 `session-orchestrator` 控制。 ### 注意事项 - 不要通过 MQTT 传大视频流。 - 不要把长期敏感 token 放在 topic 或 payload 里。 - topic 命名要预留租户维度。 - MQTT payload 要版本化。 - retained message 谨慎使用，尤其是 signaling 类消息。 - LWT 遗嘱消息要设计好，用于设备离线通知。 --- ## 6. APP 端 `app-starlock` 改造 ### 模块定位 APP 需要支持： - 调用 `starlock` 创建会话 - 连接 BifroMQ - 订阅 session topic - WebRTC offer/answer/candidate - 媒体链路质量上报 - 动态切路响应 - 弱网提示 - AI 辅助入口 ### 开发周期 **4 - 8 周** 如果现有 Flutter 已有实时对讲能力，约 4 - 5 周。 如果 WebRTC 从零接入，建议 6 - 8 周。 ### 技术栈 | 类型 | 技术 | |---|---| | APP 框架 | Flutter | | WebRTC | flutter_webrtc | | MQTT | mqtt_client / 其他 Flutter MQTT SDK | | 网络 | Dio | | 状态管理 | Riverpod / Bloc / Provider | | 本地存储 | shared_preferences / hive | | 日志 | Sentry / 自建日志上报 | | 推送 | FCM / APNs / 厂商推送 | ### 主要开发内容 - 会话创建 API - MQTT over WSS 连接 - WebRTC PeerConnection - ICE candidate 处理 - offer/answer 交换 - TURN 配置 - ZLM 播放 / 推流能力接入 - route switch 指令处理 - 通话 UI 状态机 - 通话质量上报 - 异常提示和重连 ### 难点 1. **Flutter WebRTC 稳定性** - Android 和 iOS 行为不同。 - 后台、锁屏、权限、音频路由复杂。 2. **弱网处理** - 网络切换 WiFi/4G - ICE reconnect - MQTT 断线重连 - 媒体重连 3. **状态同步** - APP UI 状态必须跟云端会话状态保持一致。 - 不能只靠本地 WebRTC 状态判断。 4. **音频权限和回声消除** - 双向语音容易出现回声、啸叫、音量问题。 ### 注意事项 - APP 不要保存长期 MQTT 密钥。 - APP 进入后台时要处理 MQTT 和 WebRTC 生命周期。 - 会话失败要区分： - 设备离线 - 权限不足 - signaling 超时 - ICE 失败 - ZLM 失败 - 所有通话状态变化都要上报。 - iOS 需要特别注意后台音视频权限和推送唤醒策略。 - Android 需要注意不同厂商后台保活限制。 --- ## 7. WiFi 网关锁 / 设备端改造 ### 模块定位 WiFi 锁作为网关设备，需要支持： - HTTPS bootstrap - MQTT/TLS 连接 - 在线状态上报 - 会话 invite/accept/reject/hangup - WebRTC 采集、编码、推流 - TURN / ZLM / relay 切换 - AI 音频旁路 - BLE 锁透传 ### 开发周期 **6 - 12 周** 如果设备端已有音视频 SDK 和 WebRTC 能力，6 - 8 周。 如果从零接入 WebRTC，尤其是嵌入式平台，可能 12 周以上。 ### 技术栈 | 类型 | 技术 | |---|---| | 语言 | C / C++ | | MQTT | Eclipse Paho Embedded / mosquitto client / 自研 | | TLS | mbedTLS / OpenSSL | | WebRTC | libwebrtc / Pion 设备适配 / vendor SDK | | 编码 | H.264 / H.265 / AAC / Opus | | 媒体 | GStreamer / FFmpeg / 设备厂商 SDK | | 存储 | Flash / 本地配置 | | 日志 | 本地环形日志 + 云端上报 | ### 主要开发内容 - bootstrap 接入 - MQTT topic 订阅和发布 - 设备能力声明 - 接收 `invite` - 发送 `ringing/accept/reject` - signaling 处理 - WebRTC 建链 - TURN 支持 - ZLM 推流或 WebRTC 接入 - 质量指标采集 - route switch 响应 - 会话结束清理 - AI ��频旁路转发 ### 难点 1. **设备性能限制** - CPU、内存、编码能力有限。 - WebRTC 对资源要求高。 2. **嵌入式 WebRTC 集成难** - ICE、DTLS、SRTP、NAT 穿透复杂。 - SDK 移植成本高。 3. **音视频编码兼容** - APP、ZLM、WebRTC 对 codec 支持要统一。 - H.264 profile、packetization mode 要注意。 4. **切路过程中资源释放** - P2P 切 ZLM 时要释放旧连接。 - 防止摄像头、麦克风、编码器被占用。 5. **断网恢复** - 设备重连后要恢复 MQTT 状态。 - 旧会话要能被云端清理。 ### 注意事项 - 设备端必须实现控制指令 ACK。 - 设备端所有消息要带 `sessionId` 和 `seq`。 - 设备端不能信任任意 MQTT 消息，必须校验 token 或签名。 - 摄像头、麦克风只能被一个会话独占，除非明确支持多路。 - 本地日志非常重要，否则现场问题很难定位。 - 如果设备端 WebRTC 难度过高，可以第一阶段优先走 ZLMediaKit 或厂商 SDK，再逐步补 P2P。 --- ## 8. WebRTC / TURN 媒体链路模块 ### 模块定位 负责 APP 与设备之间的实时音视频链路： - 优先 P2P - P2P 不通走 TURN - 弱网时可切 ZLM - 最终兜底走中心转发 ### 开发周期 **4 - 8 周** APP、设备、服务端三方联调复杂，建议至少预留 1 个月。 ### 技术栈 | 类型 | 技术 | |---|---| | WebRTC | libwebrtc / flutter_webrtc | | STUN/TURN | coturn | | 加密 | DTLS-SRTP | | NAT 穿透 | ICE | | 编码 | H.264 / Opus | | 质量监控 | getStats / 自定义质量上报 | ### 主要开发内容 - ICE server 配置 - offer/answer - candidate 收集和交换 - TURN credential - 质量上报 - P2P / TURN 判定 - ICE restart - 通话异常恢复 ### 难点 - NAT 类型复杂 - 对称 NAT 下 P2P 失败率高 - TURN 成本高，带宽压力大 - ICE 状态和业务状态不完全一致 - 移动网络切换容易断流 ### 注意事项 - TURN 账号必须短期有效。 - TURN 带宽成本要评估。 - 不要把 TURN 当成无限免费兜底。 - WebRTC 质量指标要持续上报： - RTT - packet loss - jitter - bitrate - candidate type - frame drop - 首版可以先实现“失败后重建到 ZLM”，不要一开始追求无感切换。 --- ## 9. `ZLMediaKit` 中心转发模块 ### 模块定位 ZLMediaKit 用于： - 弱网优先转发 - P2P/TURN 失败后的媒体兜底 - 标准化流媒体接入 - 后续录像、截图、事件视频处理 ### 开发周期 **3 - 6 周** 基础部署和推拉流 1 - 2 周。 与 APP、设备、鉴权、会话状态打通，约 3 - 6 周。 ### 技术栈 | 类型 | 技术 | |---|---| | 流媒体服务 | ZLMediaKit | | 协议 | WebRTC / RTSP / RTMP / HLS / HTTP-FLV | | 编码 | H.264 / AAC / Opus | | 鉴权 | ZLM hook + 业务鉴权 | | 部署 | Docker / systemd | | 负载均衡 | Nginx / SLB | | 监控 | Prometheus exporter / 日志采集 | ### 主要开发内容 - ZLM 部署 - 推流地址生成 - 播放地址生成 - Hook 鉴权 - 流开始 / 结束事件回调 - 与 `session-orchestrator` 对接 - APP 播放适配 - 设备推流适配 - 异常断流重试 ### 难点 1. **协议选择** - 设备推什么协议？ - APP 拉什么协议？ - 是否都走 WebRTC？ 2. **延迟控制** - HLS 延迟高，不适合实时对讲。 - WebRTC / RTMP / HTTP-FLV 要按实际需求选。 3. **双向语音** - 只看视频容易，双向对讲更复杂。 - 要确认 ZLM 在当前方案中如何承载上行音频。 4. **鉴权和防盗链** - 推流 / 播放 URL 必须短期有效。 - 不能裸露固定流地址。 ### 注意事项 - 弱网优先 ZLM 是合理的，但要明确“实时对讲”的延迟指标。 - 首版建议只做一套主协议，避免 RTMP、RTSP、WebRTC、FLV 全部都上。 - ZLM 的 hook 回调要和 `session-orchestrator` 状态机打通。 - 流 ID 要绑定 `sessionId`。 - 推流和播放权限必须过期。 - 要有自动清理僵尸流机制。 --- ## 10. `media-relay` 中心转发兜底模块 ### 模块定位 `media-relay` 是最终兜底。 但你文档里已经明确：**优先采用 ZLMediaKit 落地，通常不需要长期维护自研 relay。** ### 开发周期 | 方案 | 周期 | |---|---| | 不自研，直接用 ZLMediaKit 承担 | 0 - 1 周设计适配 | | 轻量封装 ZLM relay API | 2 - 3 周 | | 自研完整音视频 relay | 8 - 16 周，不建议第一阶段做 | ### 技术栈 如果不自研： | 类型 | 技术 | |---|---| | Relay 实现 | ZLMediaKit | | 控制层 | `session-orchestrator` | | 鉴权 | ZLM hook | | 监控 | Prometheus / 日志 | 如果自研： | 类型 | 技术 | |---|---| | 语言 | C++ / Go | | 媒体协议 | RTP / SRTP / WebRTC | | 编码处理 | FFmpeg / GStreamer | | NAT | ICE / TURN | | 难度 | 高 | ### 难点 - 自研媒体转发成本极高 - 音视频同步、抖动缓冲、拥塞控制都复杂 - 稳定性和性能验证成本高 ### 注意事项 - 第一阶段不建议自研 `media-relay`。 - 先让 `media-relay` 成为逻辑模块，由 ZLMediaKit 实现。 - 后续只有在 ZLM 无法满足业务需求时再考虑自研。 --- ## 11. `MQTT event worker` / 原 `event_listener` 演进 ### 模块定位 负责消费设备事件和实时事件： - 门锁事件 - 设备上下线 - 通话事件 - 媒体事件 - AI 事件 - 图片 / 视频后处理 - 回调 `starlock` ### 开发周期 **2 - 4 周** ### 技术栈 | 类型 | 技术 | |---|---| | 后端语言 | Go / Java / PHP Worker / Node.js | | 消息来源 | BifroMQ MQTT | | 队列 | Redis Stream / Kafka / RabbitMQ，可选 | | 存储 | MySQL / Redis | | 回调 | HTTP | | 重试 | 延迟队列 / 定时任务 | ### 主要开发内容 - MQTT 事件订阅 - 事件解析 - 事件幂等 - 回调 `starlock` - 失败重试 - 死信队列 - 事件日志落库 - 媒体后处理触发 ### 难点 - MQTT 事件可能重复 - 设备事件顺序可能乱 - 回调失败后要重试 - 事件消费不能阻塞主实时链路 ### 注意事项 - 每个事件必须有唯一 `eventId`。 - 回调 `starlock` 要支持幂等。 - 不要在 worker 中做耗时媒体处理，应该异步化。 - 事件处理失败要可追踪、可重放。 - 事件 schema 要版本化。 --- ## 12. `realtime-store` 实时状态与日志缓存 ### 模块定位 用于保存： - 会��临时状态 - 会话质量指标 - signaling 摘要 - route 切换记录 - 调试日志 - 会话终态 ### 开发周期 **1 - 3 周** ### 技术栈 | 类型 | 技术 | |---|---| | 热状态 | Redis | | 持久化 | MySQL / PostgreSQL | | 日志 | Loki / Elasticsearch | | 指标 | Prometheus | | 链路追踪 | OpenTelemetry | ### 数据建议 #### Redis ```text session:{sessionId}:state session:{sessionId}:participants session:{sessionId}:route session:{sessionId}:quality device:{deviceId}:online device:{deviceId}:capability ``` #### MySQL - `realtime_session` - `realtime_session_event` - `realtime_quality_report` - `realtime_route_switch` - `device_online_log` ### 难点 - 热状态和持久化状态一致性 - 会话结束后的资源清理 - 日志量较大 - 敏感数据脱敏 ### 注意事项 - Redis key 必须设置 TTL。 - signaling 内容不建议完整长期保存，只保存必要摘要。 - 质量数据可以采样，不要无限写入。 - 终态必须落库，便于审计和问题排查。 - 需要按 `sessionId` 能快速查完整链路。 --- ## 13. `ai-gateway` 与 `xiaozhi_server` AI 旁路模块 ### 模块定位 AI 不进入主通话状态机，而是旁路能力： - 设备音频旁路到 AI - APP AI 辅助模式 - AI 结果回传 `starlock` - 不影响主对讲链路 ### 开发周期 **2 - 4 周** 如果只是接入已有 `xiaozhi_server`，2 周左右。 如果需要实时音频流、唤醒词、语音识别、语音合成，4 周以上。 ### 技术栈 | 类型 | 技术 | |---|---| | 网关语言 | Go / Python / Node.js | | AI 服务 | xiaozhi_server | | 音频协议 | WebSocket / RTP / HTTP streaming | | 编码 | PCM / Opus / AAC | | 鉴权 | 短期 token | | 回调 | HTTP 到 `starlock` | ### 主要开发内容 - AI 会话创建 - 音频旁路接入 - AI 服务转发 - AI 结果回调 - 会话结束清理 - AI 异常不影响主通话 ### 难点 - 音频格式转换 - 实时性要求 - AI 服务异常隔离 - 主通话和 AI 旁路资源竞争 - 隐私和权限控制 ### 注意事项 - AI 不要阻塞主对讲链路。 - AI 失败不能导致视频通话失败。 - AI 音频采集要经过用户授权。 - AI 数据要做隐私合规处理。 - AI 事件要独立状态机，不能混入主通话状态机。 --- ## 14. 运维部署与基础设施模块 ### 模块定位 负责部署： - BifroMQ - `session-orchestrator` - `device-bootstrap` - coturn - ZLMediaKit - MQTT event worker - Redis - MySQL - 日志、监控、告警 ### 开发周期 **3 - 6 周** MVP Docker Compose 1 - 2 周。 生产高可用部署 4 - 6 周。 ### 技术栈 | 类型 | 技术 | |---|---| | 容器 | Docker | | 编排 | Docker Compose / Kubernetes | | 网关 | Nginx / Ingress | | 证书 | Let's Encrypt / 企业证书 | | 监控 | Prometheus + Grafana | | 日志 | Loki / ELK | | 追踪 | Jaeger / Tempo | | CI/CD | GitLab CI / GitHub Actions | | 配置 | ENV / Secret / ConfigMap | ### 难点 - BifroMQ 集群部署 - TURN 公网 IP 和端口规划 - ZLM 带宽和并发压力 - 日志量控制 - 多服务之间配置复杂 - 灰度和回滚 ### 注意事项 - coturn 必须部署在公网可达节点。 - TURN UDP 端口范围要提前开放。 - ZLM 和 TURN 带宽要按峰值计算。 - 所有服务要有健康检查。 - 生产环境密钥不能写在配置文件仓库中。 - 日志要设置保留周期，避免磁盘被打满。 - 要准备一键回滚方案。 --- # 三、模块优先级建议 ## P0：第一阶段必须完成 | 模块 | 说明 | |---|---| | `starlock` 会话入口 | APP 创建会话必须依赖 | | `session-orchestrator` | 新实时系统核心 | | `device-bootstrap` | 设备拿 MQTT 凭证 | | BifroMQ | 发现、在线、信令 | | APP MQTT + WebRTC 基础 | APP 端通话能力 | | 设备 MQTT + WebRTC/ZLM 基础 | 设备端通话能力 | | coturn | P2P 失败补位 | | ZLMediaKit 基础转发 | 弱网和失败兜底 | | `MQTT event worker` | 事件回调 | | 基础监控日志 | 联调和上线必需 | ## P1：灰度上线前建议完成 | 模块 | 说明 | |---|---| | 完整 ACK / 超时 / 重试 | 提升状态一致性 | | 质量指标上报 | 支撑动态选路 | | 动态 route switch | P2P / TURN / ZLM 切换 | | 会话追踪 | 定位问题 | | ZLM hook 鉴权 | 防止盗流 | | TURN 临时凭证 | 安全必需 | | 异常恢复 | 网络切换、断线重连 | | 压测和弱网测试 | 上线前必需 | ## P2：后续增强 | 模块 | 说明 | |---|---| | AI 旁路 | 不影响主链路，可后置 | | 自研 media-relay | 如 ZLM 不满足再考虑 | | 高级网络评分模型 | 根据数据逐步优化 | | 多区域接入 | 用户量上来后再做 | | 完整录像 / 云存储 | 按业务套餐推进 | --- # 四、关键技术难点总结 ## 1. 控制面和媒体面解耦 难点不是画架构，而是实现时防止耦合： - `session-orchestrator` 不能直接处理视频流 - BifroMQ 不能传大媒体 - `starlock` 不能变成实时状态机 - ZLM 不能承载业务权限判断 正确边界是： ```text starlock：业务权限 session-orchestrator：会话状态机 BifroMQ：信令和事件通道 WebRTC/ZLM/TURN：媒体链路 event worker：异步事件处理 ``` --- ## 2. 会话状态一致性 这是整个方案最大的工程难点之一。 必须解决： - APP 发起了但设备没收到 - 设备 accept 了但 APP 已取消 - MQTT 重连导致重复消息 - WebRTC 连上但云端状态还是 connecting - P2P 断了但双方状态不一致 - 会话结束后资源没释放 建议所有状态变化都通过 `session-orchestrator` 收敛。 --- ## 3. 媒体动态选路 动态选路不要一开始做得太复杂。 建议第一版策略： ```text 默认尝试 P2P -> ICE 失败或超时，切 TURN -> TURN 仍失败，切 ZLMediaKit -> ZLMediaKit 失败，提示通话失败或走旧 relay ``` 弱网优化版再做： ```text 根据 RTT、丢包、jitter、candidate type、带宽评估是否提前切 ZLM ``` --- ## 4. 设备端复杂度 设备端是高风险点。 尤其要确认： - 芯片性能是否支撑 WebRTC - 是否有硬编 H.264 - 是否支持 Opus / AAC - 是否支持 TLS - 是否支持 MQTT 长连接 - 摄像头和麦克风资源是否可同时给 WebRTC 和 AI - 固件 OTA 是否方便灰度 如果设备 WebRTC 成本过高，建议： ```text 第一阶段：设备 -> ZLMediaKit，APP -> ZLMediaKit 第二阶段：中高端设备支持 WebRTC P2P ``` --- ## 5. BifroMQ 权限和 topic 设计 MQTT topic 一旦上线后修改成本较高。 建议提前确定： - topic 命名规范 - tenant 隔离 - device 隔离 - session 隔离 - QoS 策略 - retained 使用策略 - LWT 设备离线策略 - ACL 权限模型 --- # 五、上线前必须注意的点 ## 1. 安全 必须做好： - MQTT TLS - MQTT ACL - 短期 token - TURN 临时账号 - ZLM 播放 / 推流鉴权 - APP 不能直接访问��部服务 - 设备密钥不能明文泄露 - 日志脱敏 --- ## 2. 可观测性 至少要能按 `sessionId` 查到： - 谁发起 - 哪个设备 - 哪个 APP - 设备是否在线 - invite 是否送达 - accept 是否收到 - offer/answer 是否完成 - ICE 是否成功 - 使用了 P2P / TURN / ZLM / relay 哪条链路 - 失败原因是什么 - 最终状态是什么 否则后期排查会非常痛苦。 --- ## 3. 弱网和异常测试 必须覆盖： - APP 4G / WiFi 切换 - 设备断网重连 - MQTT 断线重连 - TURN 不可用 - ZLM 不可用 - BifroMQ 重启 - `session-orchestrator` 重启 - APP 杀进程 - 设备重复上线 - 双端同时挂断 - 多个 APP 同时呼叫同一把锁 --- ## 4. 资源和成本 需要重点评估： | 资源 | 风险 | |---|---| | TURN | 带宽成本高 | | ZLMediaKit | 中心转发带宽和 CPU 压力 | | BifroMQ | 长连接数量 | | Redis | 会话状态和 TTL 清理 | | 日志系统 | signaling 和质量上报可能量很大 | | MySQL | 会话事件写入频率 | --- # 六、推荐的第一阶段 MVP 范围 第一阶段不要一次性做太满，建议 MVP 范围如下： ## 必做 - `starlock` 创建会话 API - `session-orchestrator` 独立服务 - BifroMQ 接入 - APP MQTT over WSS - 设备 MQTT/TLS - 基础 invite / accept / reject / hangup - WebRTC P2P 基础链路 - coturn 兜底 - ZLMediaKit 兜底链路 - 基础质量上报 - 基础会话日志 - 事件 worker 回调 `starlock` ## 暂缓 - AI 深度集成 - 自研 media-relay - 复杂无感切路 - 多区域部署 - 高级网络评分模型 - 全量录像和云存储 - 复杂套餐计费联动 --- # 七、建议的里程碑排期 ## 第 1 - 2 周：协议和架构落地 - 确定 API 文档 - ��定 MQTT topic - 确定状态机 - 确定 route 策略 - 确定设备 capability schema - 搭建 BifroMQ、coturn、ZLM 测试环境 ## 第 3 - 6 周：控制面 MVP - `session-orchestrator` - `device-bootstrap` - `starlock` 会话入口 - APP MQTT - 设备 MQTT - invite / accept / hangup 跑通 ## 第 7 - 10 周：媒体链路 MVP - WebRTC P2P - TURN - ZLM 推拉流 - APP 与设备完整通话 - 失败后切换到 ZLM ## 第 11 - 14 周：稳定性和可观测 - ACK / retry / timeout 完善 - 质量上报 - 会话追踪 - 事件 worker - 日志和监控 - 弱网测试 ## 第 15 - 16 周：灰度上线 - 小范围设备灰度 - 问题收集 - 性能压测 - 回滚方案 - 运维文档 --- # 八、最终建议 这个架构方向是合理的，关键是第一阶段要控制范围。 我建议优先落地这条主链路： ```text APP -> starlock -> session-orchestrator -> BifroMQ signaling -> 设备 -> WebRTC P2P / TURN -> 失败后 ZLMediaKit ``` 同时把 AI、自研 relay、高级动态选路放到第二阶段。 最需要重点投入的模块是： 1. `session-orchestrator` 状态机 2. BifroMQ topic / ACL / token 设计 3. APP 与设备端 WebRTC 联调 4. ZLMediaKit 弱网兜底 5. 会话日志与问题追踪 如果这 5 个点做好，后续 AI、录像、套餐、计费、多区域扩容都可以逐步叠加。