Wi-Fi AP配网失败后的恢复流程与验收测试

作者LIU, ZHUOHUI

Wi-Fi配网流程达到产品交付条件，意味着用户遇到密码错误、路由器缺席、配置中断和断电后，仍能恢复，而不需要重新刷机。应将配网设计成有时间边界、有明确结果、能保护凭据并能受控重返设置的状态机。向设备成功提交一次HTTP请求，只是流程中的一步。

本文讨论设备先提供配网热点，再接入客户路由器的流程，适用于Linux和MCU产品；具体API取决于所选驱动与SDK。全部时间示例和测试均为设计建议，不是产品实测声明。

设计界面前先定义成功条件

将四个里程碑分开：手机提交了候选配置；设备完成关联与认证；取得可用IP配置；访问了规定的应用服务。本地控制器的最终要求可能是能够在局域网被发现；云端产品则可能需要认证注册或健康检查交互。必须明确到哪个阶段才提交新配置。

不能把云服务故障当成Wi-Fi密码错误。如果Wi-Fi和DHCP成功，但后端服务不可用，应保留“网络已配置，服务不可用”的独立状态。由产品策略决定这种状态是否允许完成安装，而不是反复让用户填写密码。

写清支持的路由器频段、安全模式、SSID编码与长度、隐藏网络流程和企业网络要求。仅支持2.4 GHz的模组无法通过重试接入仅有5 GHz的网络。WPA-Enterprise、上游强制认证门户和受管理的企业网络，都需要明确支持方案或排除说明。

六阶段Wi-Fi配网状态机，包含候选配置、网络测试、原子提交和故障返回设置路径。
图1：恢复是配网状态机的一部分，成功条件与提交边界应明确。图中文字为英文。

将配置变更设计成事务

将上一次已知可用配置与正在测试的候选配置分开保存。每次尝试分配一个标识；相同标识的重复提交应返回同一次尝试的状态，而不是启动多个并行连接操作。新尝试应以受控方式取消或取代旧尝试。

平台支持时，先测试候选凭据，不立即覆盖持久保存的已知可用记录。达到约定成功条件后，再原子提交带版本的记录。保存完整性信息和结构版本，并定义提交过程中断电后的启动行为。静态加密需要合适的密钥存储设计，也不能代替经过认证的配网流程。

部分SDK管理器会在应用完成自身验证之前持久保存凭据。例如，ESP-IDF 5.2.6的Wi-Fi配网指南说明了基于已存凭据的配网状态检查，以及失败和重启行为。这属于特定版本的集成约束。应验证所选管理器的重置与重新配网API，并围绕它实现产品状态模型，不能假定“有凭据”等于“安装成功”。

保留有意触发的恢复入口

定义什么操作能重新进入配网：经过认证的命令、物理按键序列或安装工具。明确按住时长、LED反馈，以及意外短按是否会改变设置。网络重置通常应保留校准数据、设备身份和无关应用配置。恢复出厂设置应作为单独且提示明确的操作。

一种建议策略是开放十分钟配网窗口，为一次路由器连接尝试设置可配置截止时间，超时后允许重试或恢复旧配置。具体数值必须根据支持的路由器和安装流程确定。不能因为首次失败，就永久暴露不受限制的配网网络。

配网自动关闭时，手机需要明确获知结果。可以在仍可连接时轮询状态、在切换前显示成功凭证、使用LED状态，或在目标网络重新发现设备。TCP连接中断本身无法区分成功与设备崩溃。

考虑手机失去连接路径

手机可能优先使用移动数据、离开无互联网的Wi-Fi网络，或打开功能受限的强制门户浏览器。对支持的Android/iOS版本，分别在移动数据开启和关闭时测试。提供自动门户检测失败时仍能使用的本地URL或应用流程。必须离线工作的设置页，不应依赖互联网托管的脚本或字体。

AP与STA并存有具体无线平台限制。ESP32文档说明站点/AP模式共享工作信道，站点优先；接入其他信道上的路由器可能影响配网连接。可参考厂商的Wi-Fi驱动指南，随后按实际SDK和模组版本验证。Linux芯片同样需要驱动支持相应接口组合，不能根据单独演示过AP和STA，就推定AP+STA可用。

状态接口应能应对重新连接。尝试结果要独立于HTTP连接保存，返回尝试ID、阶段和不含敏感信息的原因码。确保过期浏览器页面不能覆盖较新的成功配置。

保护凭据传输与诊断信息

使用适合产品的单设备配网密钥或其他经过认证的注册设计。开放AP加上未认证的密码表单会暴露敏感配置入口。应同时考虑传输安全和设备身份验证；没有信任与发现机制的随机自签名证书，可能只会让安装人员习惯忽略安全警告。

不要照搬会打印Wi-Fi密码的示例日志。记录阶段、耗时、SDK断开原因、重试次数、固件版本和脱敏网络标识。限制诊断导出，并在不再需要时清除临时候选凭据。限制尝试次数和并发会话，明确两部手机同时配置同一设备时的控制权。

不同原因对应不同处理。认证被拒绝时，检查凭据或安全模式；找不到匹配AP时，检查频段、距离、隐藏SSID和扫描策略；DHCP超时指向地址服务或本地网络；TLS或注册失败属于应用链路，可能涉及时间、证书或账户策略。

让验收矩阵证明恢复能力

测试 预期恢复行为 保留证据
先提交错误密码，再提交正确密码 无需刷机或清除设备身份即可接受新尝试 尝试ID、失败原因和最终连接状态
连接时路由器消失 在规定时间内超时；可恢复旧配置或配网入口 阶段时间线、重试和资源计数
关联成功但阻断DHCP 地址分配故障与认证故障分别显示 Wi-Fi事件和DHCP抓包
网络正常但云端不可用 识别服务故障；按策略保留有效Wi-Fi配置 不含凭据的IP、DNS和应用状态
接收、测试、提交时分别断电 启动到有效旧配置、新配置或明确恢复模式 启动日志、记录版本和完整性检查
手机离开AP，第二部手机加入 保持尝试控制权，并能读取最新结果 客户端状态和并发请求行为
配网超时及物理网络重置 入口按时关闭；授权操作可重开且不丢失校准 无线扫描、按键/LED记录及设置对比

围绕状态转换重复注入故障，不要只在任意时刻断开。覆盖路由器换信道、弱信号和无线/应用并发负载。统计成功恢复次数与总尝试次数，记录全部失败，并测量到可用状态的耗时。不能只报告平均值；少量没有结束边界的尝试也可能主导售后成本。

提供精简的诊断协议

下面的状态文档是应用协议示例，不是SDK API。原因码与阶段名称应随手机应用共同维护版本：

{
  "schema": 1,
  "attempt_id": "setup-0042",
  "phase": "waiting_for_ip",
  "result": "pending",
  "elapsed_ms": 12400,
  "reason": null,
  "can_retry": false
}

尝试截止时间应使用单调时钟，避免校时意外延长或缩短重试。看门狗应识别工作线程卡死，而不是仅因外部路由器不在线就重启健康设备。连续失败尝试期间跟踪内存与套接字使用，找出一次成功演示无法暴露的泄漏。

约定完整的配网交付物

欧蓓特的设备联网服务可用于梳理设备、手机与路由器的集成范围。已交付的ESP32 Wi-Fi与蓝牙网关项目描述了AP/STA相关方向；其中独立的Mesh角色，不代表本文配网流程已实现或完成验证。

请提供模组与SDK版本、目标手机清单、支持的路由器和安全模式、当前故障日志，以及安装人员必须完成的流程。交付内容除了成功路径设置界面，还应包括状态定义、手机可见错误、凭据处理、重置语义和可重复的故障测试。

类似文章