常见问题与排查

页面打不开

确认启动输出的 Login URL、主机地址与端口。默认原生管理页为 8081，不是 API 的 8080。其他电脑无法访问时，检查路由、防火墙和监听地址。先运行 status，避免反复重启掩盖原始错误。

登录失败或 502

先确认数据库和后端已启动，再确认账号、密码及启用状态。页面能打开而 API 代理失败时，检查后端日志和代理目标。不要清空数据库来恢复初始账号。

网关离线

1. 用完整 EUI 找到网关记录。
2. 核对网关指向的服务器地址是否是当前主机地址。
3. MQTT：检查实际端口、监听地址、账号/TLS 和区域前缀。
4. UDP：确认已启用对应 Profile，检查其实际 UDP 端口和防火墙。
5. 看 MQTT stats 或 UDP 状态包是否到达服务器；仅 ping 成功不能证明 MQTT/UDP 链路畅通。
6. 核对最后在线时间；旧记录不代表刚收到新上报。

网关在线，终端没数据

先查网关实时帧：没有目标无线包时检查供电、区域、信道和终端发送；有无线包但没有终端 up 时查身份、会话密钥、MIC、帧计数和模版。自动登记还要核对目录和识别条件。不要先改服务器解析器。

上行有原始 data，没有业务字段

核对终端模版 codec、FPort、固件协议和字节顺序。用同一包测试解析，保留原始字节供比对。无 codec 和 codec 失败要分别处理。

下行已入队，设备没反应

核对 Class A 是否尚未上行、Class C 会话是否有效、网关是否可用、队列是否过期。再查 txack，检查频率/数据率/接收窗口，最后核对终端 FPort、协议字节与业务回执。不要因没有动作就重复发送高风险命令。

MQTT 连接成功但订阅为空

核对应用 ID、DevEUI、topic 层级和事件名；确认接入的是 Application MQTT 而不是网关管理入口。MQTT 正常订阅不会自动补齐所有历史数据；订阅后等待新的真实上行。

远程管理不可用

数据 MQTT 与管理 MQTT 分别检查。网关收到无线数据不保证远程命令主题和认证正确。核对网关管理地址、管理主题及版本；命令超时时先重新读取，不立即重复保存或重启。

创建按钮禁用、权限错误

核对用户角色、授权期限、资源额度以及必填字段。已被管理员隐藏的入口不属于该版本常规操作路径；需要后台能力时按 API 权限调用。

反馈问题时准备

提供版本、系统平台、复现步骤、发生时间、目标设备/网关标识、页面错误和脱敏日志。明确是“登记成功”“收到上行”“网关发送成功”还是“终端动作失败”，便于定位对应环节。