❓ 常见排错指南 (FAQ)

本文档整理了 MzMedia 在实际生产与研发部署过程中最常见的故障现象及排查手段。

---

1. 视频与流媒体常见问题

Q1: 摄像头在海康/大华后台配置后，平台显示注册成功，但点击播放提示超时或黑屏？

• 排查步骤：
  1. 检查 application.yaml 中的 sip.ip 与 media.ip，严禁配置为 127.0.0.1，必须配置为摄像头在局域网内或公网能直接路由访问的实际 IP 地址；
  2. 检查宿主机防火墙是否阻断了 ZLMediaKit 的动态 RTP 端口（默认 30000-30500）；
  3. 检查摄像机视频编码格式，部分老设备默认推复合流或 H.265，如果浏览器不支持硬解，可在平台点播设置中勾选转码为 H.264。
  4. 推荐在 💻 前端播放引擎集成 中使用在线模拟视窗对比 WebRTC 与 FLV 传输差异。

Q2: 摄像机在线，但是获取不到通道列表或目录为空？

• 排查步骤：
  1. 检查摄像机配置的 SIP 服务器 ID（国标 20 位）与平台配置是否完全一致；
  2. 检查大包分包：当设备下挂通道较多时，XML 报文可能超过单包 MTU 导致 UDP 丢包，建议在前端将该设备的 SIP 传输协议切换为 TCP 模式。

---

2. 物联网与工控通信常见问题

Q1: Modbus 读取到的数值为负数、极大极小值或与现场仪表显示不符？

• 排查步骤：
  1. 检查字节序 (Endianness) 设置：常规使用大端（ABCD），施耐德等常见字交换（CDAB），国产仪器仪表常见字节交换（BADC）；
  2. 检查寄存器起始地址基准：查看设备手册标注的是 0 开始（0-based）还是 1 开始（1-based），若存在 1 的偏移，需在配置中相应加减 1；
  3. 检查缩放系数 (Scale)：确认浮点数是否需要乘以 0.1 或 0.01 转换；
  4. 快捷排查：您可直接使用平台内置的 ⚡ Modbus 字节序在线换算器，输入现场抓包的十六进制字节，一秒验证数值排布。

Q2: 设备连接 MQTT Broker 频繁掉线？

• 排查步骤：
  1. 检查每个物理设备的 ClientID 是否全球唯一，禁止两台物理设备使用同一个 ClientID 连接，否则会发生互相踢线（KeepAlive 争抢）；
  2. 检查心跳间隔（KeepAlive），建议设置为 60 秒并开启客户端断线自动重连。

---

3. Spring AI 与 MCP 智能体常见问题

Q1: 启动时报错 ChatClient.Builder 重复注入或找不到 Bean？

• 排查步骤：
  • 项目设计了多模型动态工厂 Ai1LlmModelFactory。请确保 application.yaml 中配置了 spring.ai.chat.client.enabled: false，避免 Spring Boot 官方自动装配单一固定 Client 产生冲突。

Q2: 本地 stdio MCP 客户端启动失败或报找不到命令？

• 排查步骤：
  • 确认 MCP 配置中填写的命令行程序（如 python、node、uvx）已加入操作系统的系统环境变量 PATH 中；
  • 检查当前执行账户是否具备对应脚本文件与工作目录的读写执行权限。