常见问题与排障指引

排查链路：设备 → EMQX/MQTT 连接 → dgsvr 认证 → gpscodecsvr 解码 → NATS device.up.status.connected → Java iot 消费。

• 先看 EMQX 客户端是否建立连接，再看 dgsvr 认证日志是否通过（accessAuth / loginAuth）。
• 确认 NATS 上线事件是否发出、Java 消费端 Queue Group 是否正常。
• 认证失败时检查产品协议、设备密钥与物模型配置；密钥敏感，日志只允许脱敏 ID。

排查链路：geosvr 轨迹入库 → risksvr / alertsvr 规则命中 → eventsvr 分发 → Java alarm 落记录 → notify 消息任务 → wssvr / APNs / FCM。

• 按环节逐段确认事件是否产生与消费，避免"规则命中"与"通知送达"混为一谈。
• 检查 alertsvr 规则索引缓存是否已刷新（规则变更后失效）。
• 检查 notify 消息任务状态与推送 Token 有效性。
• 确认订阅权益是否覆盖该设备的告警推送能力。

mvn -pl entrax-server -am -DskipTests package
java -jar entrax-server/target/entrax-server-exec.jar --spring.profiles.active=local
curl -fsS http://127.0.0.1:48080/actuator/health
curl -fsS http://127.0.0.1:48080/v3/api-docs

• 单体至少依赖 MySQL、Redis；IoT、支付、消息与定时任务可能还需 TDengine、RocketMQ、Kafka、RabbitMQ、NATS、XXL-JOB。
• local profile 默认 register-enabled: false，不注册为普通服务，但保留 Nacos discovery 以发现外部 gRPC。
• dev/test 会导入 Nacos java-entrax-server.yaml，排查配置时同时确认 profile、namespace、group、dataId 与加载日志。

• 确认 Nacos 服务发现正常：实例 metadata 是否携带 gRPC_port / gRPC_enabled。
• 检查跨语言调用是否透传 Trace-Id、User-ID & Tenant-ID、Region，缺失可能导致数据隔离判定拒绝。
• 核对 proto 契约版本与生成代码是否同步——契约不一致是最常见的静默失败原因。
• Java 侧 gRPC 端口 = HTTP 端口 + 1000；单体 49080、独立服务 49xxx，先核对实际监听端口。

• NATS 多副本消费必须指定 Queue Group，否则同一条消息被多个节点重复消费。
• 告警、订单状态等不可丢失消息使用 JetStream 持久化模式。
• 消费端业务处理保持幂等：同一事件重复到达不应产生重复业务记录（唯一约束 + 状态检查）。
• Outbox 消息由 Job 发布，先确认 Outbox 表是否有积压与失败重试日志。

• 区分 GPS 原始点与清洗轨迹：原始点保留证据（TDengine），轨迹用于业务展示。
• 确认 geosvr 已消费 NATS 并写入 TDengine；rawAsyncWriter 异常会导致轨迹缺失。
• 坐标纠偏（WGS84→GCJ02）在 go-share/utils/geo 完成；偏移过大时检查设备定位源与纠偏配置。
• 离线补传数据按设备时间戳排序入库，避免影响里程与行程计算。

• 端口规则：Java 业务模块 HTTP 从 48090 起递增，gRPC = HTTP + 1000（49xxx）；单体 48080 / 49080 / MCP 49202，网关 48081。
• Go RPC 服务：eventsvr 9098、iamsvr 9097、videosvr 9096；dgsvr/dmsvr 等为 58848 段内部端口，以 etc/*.yaml 为准。
• 排查配置时同时确认 profile、namespace、group、dataId 与配置加载日志，远程 Nacos 配置可能覆盖本地端口。
• 新增模块不得占用既有端口，端口规划以项目 Wiki 与 Nacos 快照为准。