常见问题（FAQ）
部署与启动
启动微服务时报 MQTT 连接失败？
依次检查：
- EMQX 容器是否运行：
docker ps | grep unihh-emqx； - 1883 端口是否可通：
telnet localhost 1883； - 各服务
application.yml中的 MQTT 账号密码是否为unihh/unihh（或与你修改后的一致）； - EMQX Dashboard（
http://localhost:18083）查看是否有客户端连接记录。
服务启动顺序有要求吗？
建议按 gateway → admin → data → 驱动 的顺序启动。驱动在 admin 之前启动也可正常注册（admin 上线后会重新同步注册信息），但依赖 MySQL 与 EMQX 必须先就绪。
Docker Compose 启动后服务一直重启？
最常见原因是 MySQL 尚未通过健康检查：unihh-admin 依赖 unihh-mysql 的 service_healthy 条件，MySQL 首次启动要执行 db/unihh_iot.sql 全量导表，可能需要 1~2 分钟。按顺序排查：
docker compose ps确认unihh-mysql是否已变为 healthy；docker compose logs unihh-mysql查看导表是否报错；docker compose logs unihh-admin若报连接数据库失败，等待 MySQL 就绪后服务会自动恢复（restart: always）。
本机端口被占用（3306 / 1883 / 28000 等）怎么办？
修改 docker-compose.yml 中对应服务 ports 的左侧宿主机端口（右侧容器端口不可改），例如将 "3306:3306" 改为 "13306:3306"，并同步修改各服务连接串中引用的端口。EMQX 的 1883 总线端口被占用时，所有驱动与微服务的 EMQX_SERVER_URI 需一并调整。
如何彻底重置 Docker 环境？
docker compose down -v # 停止并删除容器与 mysql_data 数据卷
docker compose up -d # 重新启动，MySQL 将重新执行初始化脚本
注意：down -v 会删除全部业务数据，执行前先备份（见部署与运维）。
最低配置跑得动吗？
可以。核心服务推荐 -Xmx128m、驱动 -Xmx64m（见部署与运维），2GB 内存的树莓派即可承载"EMQX + 三服务 + 单驱动"的最小系统。
驱动与采集
驱动显示离线，如何排查？
- 到驱动管理点击通道心跳自检，根据 RTT 结果区分网络问题与进程问题；
- 确认驱动进程存活、端口监听正常；
- 查看驱动日志的 MQTT 报错；
- 心跳看门狗为 15 秒超时，短暂网络抖动会自动恢复，无需人工干预。
点位一直显示异常（Quality=0）？
品质异常表示链路通但读数失败，常见原因按概率排序：
- 物理寄存器地址填写错误（如 Modbus 功能码区段与地址偏移不匹配）；
- 数据类型与实际寄存器长度不符（如用 INT 读 DOUBLE 空间）；
- 多字节字节序配置错误（可参考驱动内
IndustrialEndianUtils的说明）； - 设备侧拒绝读取（权限、部分寄存器不可读）。
采集数值与现场仪表对不上？
数值有规律偏差是量程换算问题：核对点位的缩放系数（Scale）与零点偏置（Offset），工程值 = 原始值 × Scale + Offset。数值完全乱跳则优先排查字节序。
如何降低采集对 RS485 总线的占用？
- 增大设备基础数采周期；
- 变化平缓的点位将采样模式设为
COV（值变化上报）替代周期采样； - 精简点位绑定，只挂真正需要的测点；
- 反控与采集由通道锁自动排队，无需额外配置。
反向控制
反控指令下发失败？
- 确认点位读写模式为 RW（只读点位不允许反写）；
- 到日志审计查看下发参数快照与失败原因；
- 确认设备在线且同通道读取正常；
- 检查驱动通道心跳自检结果。
反控会不会和采集冲突（粘包/错帧）？
不会。平台在驱动层对每个设备通道加了公平互斥锁（getChannelLock），采集轮询与反写指令自动排队串行执行，这正是平台针对半双工总线的设计目标。
数据与存储
实时值存在哪里？
Redis 实时快照（前端实时刷新直接读取）+ 时序库落盘。存储引擎通过 StorageEngineRouter 策略路由，详见部署与运维。
不部署 TDengine 可以吗？
可以。仅执行 db/unihh_iot.sql 即可运行，历史数据将使用其它已配置引擎或 MySQL 承载。需要高频时序分析时再启用 TDengine。
账号与安全
默认密码有哪些？
| 入口 | 账号 | 默认密码 |
|---|---|---|
| 平台管理端 | admin | unihhiot |
| EMQX Dashboard | admin | public |
| MQTT 总线 | unihh | unihh |
生产部署后务必全部修改。
忘记 admin 密码怎么办？
由其他管理员在【系统管理 → 用户管理】重置；若只有一个账号，可直接更新数据库 sys_user 表中该账号的密码字段（bcrypt 加密），或暂时以相同 bcrypt 串复制其它账号的密码。
其它
如何接入新协议？
参考驱动开发指南，继承 AbstractDriverPlugin 实现三个方法即可。欢迎向仓库提交新驱动 PR。
遇到文档未覆盖的问题？
在 GitHub 仓库提交 Issue，描述现场协议、设备型号与日志片段，维护者会尽快跟进。