设备端与网关
本页区分 ESP32 设备端固件 与 工业网关。两者都可连接云平台，但硬件资源、配置方式和当前能力边界不同；详细操作以各自专题文档为准。
1. ESP32 设备端
1.1. ESP32 设备端与工业网关分别适合什么场景？
ESP32 固件适合让单个传感器、开关或控制器通过 WiFi 等方式直连云平台；工业网关部署在 x86、ARM 或树莓派等网关上，用于汇聚 RS485、PLC、电表等现场设备后统一上行。
两者可以使用平台物模型和主题规范，但不能用平台侧排查步骤替代设备端串口、引脚和固件日志。参见 ESP32 设备端文档 和 工业网关概览。
1.2. 烧录失败、COM 口被占用或 ESP32-C3 启动停留在下载模式怎么办？
先关闭占用该串口的串口监视器或其他烧录客户端，并确认数据线和 USB 枚举正常。ESP32-C3 停留在下载模式时，按故障指南核对复位时序，必要时物理重插 USB。
不要终止不属于自己的任务，也不要删除构建锁来强行绕过占用。详见 设备端常见故障排查。
1.3. ESP32-C6 串口静默或外设初始化 panic 与引脚配置有关吗？
可能有关。C6 的部分引脚用于 UART0 控制台，错误分配会导致串口日志消失；超出芯片可用 GPIO 范围或占用封装内 Flash/PSRAM 引脚，还可能在初始化时触发 panic。
按芯片保留引脚和外设配置逐项核对，不要只检查应用程序日志。详见 设备端常见故障排查。
1.4. 烧录后页面错乱、登录空白或资源异常怎么办？
常见原因是固件与 Web 文件系统资源不匹配，或使用了不属于当前构建的历史资源。先核对固件/Web 摘要和接口兼容性，再按发布流程选择应用或仅 Web 更新。
不要默认全量擦除烧录，也不要直接使用来源不明的 data/www 历史文件。详见 设备端常见故障排查。
1.5. WiFi 凭据正确但设备仍只在 AP 热点可达怎么办？
可能是 STA 连接失败后自动回退 AP，也可能是实际加载的网络配置与预期不同。先读串口启动日志，区分配置加载、NVS 回退和 STA 连接失败，再通过可用管理入口核对 SSID 与认证配置。
不要因为怀疑旧配置就直接擦除整个 NVS 分区；需要离线恢复时先备份身份和原镜像。详见 网络模式切换 和 故障排查。
1.6. .local 域名无法访问、解析慢或 4G 模式无法远程访问怎么办？
现场优先使用 IP 直连。Windows 的 mDNS 依赖 Bonjour 等组件，可能出现解析慢或间歇失败；多台设备还要确认实际域名和冲突情况。
4G 模式下 mDNS 不作为远程访问入口，物联网 SIM 通常也是 NAT 内网地址。可连接设备 AP 后通过 192.168.4.1 管理。详见 mDNS 与设备发现。
1.7. MQTT 配置显示“已保存”是否代表已经连接？
不代表。保存只写入配置，还需要在设备状态或 /api/mqtt/status 确认 connected，并验证平台消息收发。
未连接时检查 DNS、服务器/端口、账号密码、Client ID、TLS 开关和系统时间。详见 设备端通信协议。
1.8. 设备端 MQTT QoS 和 Modbus 主/从站能力有哪些边界？
当前设备端 PubSubClient 发布实际使用 QoS 0，页面中的发布 qos=1 配置不构成 QoS 1 送达保证；订阅与遗嘱 QoS 需分别判断。
Modbus 从站响应默认关闭，当前固件默认提供主站能力，不要把本机按从站设备配置。详见 设备端通信协议。
1.9. 设备端 OTA 返回 501/503、上传中断或升级后 API 返回 401 怎么办？
- 501：检查当前分区是否真有 OTA 槽；4MB 正式环境不具备应用双槽 OTA，不能为消除错误随意改布局。
- 503：可能是内存门控，关闭其他页面/连接后按
Retry-After重试。 - 上传中断：核对升级终态、设备身份、固件版本/摘要和重启原因，不能只凭恢复探活判断成功。
- 升级后 401：重启会清空内存会话，重新登录即可。
详见 设备端 OTA 与故障排查。
1.10. 外设无响应、规则不执行或接口因内存压力返回 503 怎么办？
外设先检查供电、引脚、类型和启用状态；规则再检查触发器来源、目标外设和动作类型是否匹配，先用“执行一次”验证再启用。
内存压力返回 503 时减少并发请求并等待重试，长期出现则检查高内存功能、长连接和堆趋势。详见 设备端快速开始 和 故障排查。
2. 工业网关
2.1. 没有真实工业设备能否开发调试？
可以使用 x86 开发机、Stub 驱动、模拟后端或 Modbus 模拟器验证配置和流程。模拟环境适合开发调试，但不能替代真实串口、电气链路、设备协议和长期稳定性验收。
2.2. 网关 Web 无法打开、静态资源缺失或 MQTT 保存后未生效怎么办？
Web 先确认实际 HTTP 端口、进程监听、工作目录和静态资源路径，不要把未实现的 HTTPS 端口当成默认入口。MQTT 再按 Broker 地址可达性、认证/TLS、配置解密和运行日志排查。
保存配置不等于所有字段都会自动重连；需要在受控窗口按当前运维文档验证或重启。详见 工业网关运维。
2.3. 网关没有采集值、无法写入或驱动被自动隔离怎么办？
先确认当前版本的开发预览基线：官方运维文档明确指出，应用尚未把配置驱动注册到 TagEngine，形成真实采集闭环前的全局阻塞，配置正确也不能绕过该问题。所用版本未修复此阻塞时，不要把 Modbus 配置或模拟结果当作可交付的真实采集能力。
已确认该阻塞修复后，再检查驱动、设备和 Tag 是否使用运行时字段，Modbus 地址是否采用零基 registerAddr，以及是否使用真实驱动而非 Stub 结果。串口链路还要检查 RS485 A/B、终端电阻、波特率、从站地址和总线负载；驱动隔离时查看健康状态和连续错误计数，修复底层通信后再观察自动恢复。详见 工业网关运维。
2.4. 网关报警未触发或在阈值附近频繁抖动怎么办？
未触发时检查规则是否启用、Tag 是否持续更新、阈值和比较条件是否合理。阈值附近频繁抖动时，可按业务需要配置 deadband，避免数值在触发点附近反复改变报警状态。
详见 工业网关运维。
2.5. 网关断网补报、配置重连、OTA、恢复出厂和反向控制都已完整可用吗？
不能这样假设。当前运维文档明确列出了尚未完整接通的能力：活动上报链路未完整使用 SQLite 离线缓存补报，部分配置保存不自动重连，恢复出厂、OTA 和生产反向控制也存在未完成边界。
实施时应以当前版本实际验证结果为准，不要把设计目标当作交付能力。详见 工业网关运维的能力边界。
2.6. 网关调试 API 和生产运维接口有哪些安全边界？
调试读取/写入、系统重启和诊断接口可能产生真实设备负载或系统影响，不应暴露给不可信用户或网络。生产环境要限制 Token、网络来源和角色权限，并先修复或隔离存在风险的调试入口。
不要在公开 FAQ 中直接复制高风险调用示例；具体边界见 工业网关运维。