📚 课程目录第3章离线可用设计原则

3、离线可用设计原则：断网场景分析、降级策略、本地优先架构、数据一致性与最终一致性

ESP32 作为物联网边缘节点，常被部署在 Wi-Fi 信号不稳定、运营商网络故障、甚至完全隔离的工业现场。如果系统设计时默认“在线可用”，一旦断网，设备要么空转、要么死机、要么丢失关键数据。离线可用设计不是“断网后还能开机”这种表面功夫，而是要在网络不可用时，系统依然能完成核心业务闭环，并在网络恢复后自动完成数据同步。本章从断网场景分析出发，逐步拆解降级策略、本地优先架构，以及数据一致性与最终一致性的落地方法。

3.1 断网场景分析：从“有没有网”到“网络质量如何”

很多开发者对断网的理解只有“Wi-Fi 断开”这一种状态，但实际工程中，断网场景远比想象中复杂。ESP32 可能遇到 Wi-Fi 信号弱但未断开、路由器重启、DNS 解析失败、云端服务器 5xx、MQTT 连接被重置、运营商网络拥塞等多种“半断网”状态。如果只检测 Wi-Fi 连接状态，系统会在“看似在线、实际不可用”的假象中做出错误决策。

断网场景分析的核心是建立网络可用性分级模型。建议从三个维度评估：物理链路（Wi-Fi 是否关联）、网络层（能否获取 IP、能否 ping 通网关）、应用层（MQTT/HTTP 是否握手成功、云端是否响应）。只有三层全部通过，才认为“完全在线”；否则进入降级流程。

断网类型	典型表现	检测方法	降级触发条件
瞬时抖动	Wi-Fi 信号短暂丢失，1-3 秒恢复	Wi-Fi 事件回调 + 快速重连	连续 3 次重连失败
链路断开	Wi-Fi 关联丢失，无法扫描到 AP	Wi-Fi 状态机检测	10 秒内未恢复关联
网络不可达	Wi-Fi 正常，但 ping 网关超时	ICMP 探测或 TCP 连接测试	连续 5 次探测失败
服务端故障	网络通，但云端 API 返回 5xx	HTTP 状态码 / MQTT ACK 超时	连续 3 次请求无有效响应

实战中，建议在 ESP32 上实现一个网络健康度检测任务，每 10 秒执行一次。检测逻辑不复杂：先检查 Wi-Fi 连接状态，再尝试 TCP 连接云端域名（端口 80 或 443），最后发送一个轻量级心跳（如 MQTT PingReq）。根据检测结果维护一个状态变量 net_state，取值范围为 ONLINE、DEGRADED、OFFLINE。业务逻辑只读取这个状态变量，不直接操作网络 API，这样能避免各模块重复检测、状态不一致的问题。

风险提示：不要在主循环中用 delay() 阻塞检测网络。ESP32 的 Wi-Fi 驱动是事件驱动的，阻塞会导致事件回调无法执行，反而让断网检测更迟钝。建议使用 FreeRTOS 任务或定时器驱动检测逻辑。

3.2 降级策略：不是“功能全关”，而是“分级响应”

降级策略的核心思想是：断网时，系统仍然要完成最重要的业务目标，只是以降低体验或减少功能为代价。对于 ESP32 设备，降级通常分为三个等级：

L1 在线模式：全功能运行，数据实时上报，远程控制实时响应。
L2 降级模式：本地控制逻辑继续运行，传感器数据写入本地存储，云端交互暂停，但保留重连尝试。
L3 应急模式：仅保留安全相关功能（如过温保护、紧急停机），其他业务全部暂停，降低功耗以延长续航。

降级策略的设计要点是明确每个功能模块的降级行为。例如，一个智能温控器：温度采集模块在 L2 模式继续工作；远程调温接口在 L2 模式返回“设备离线”提示；本地按键调温在 L2 模式仍然有效；在 L3 模式，只有温度超过 60°C 时触发继电器断开，其他功能全部休眠。

  降级策略判断流程：
  读取 net_state 状态变量。
若为 ONLINE，执行正常业务逻辑。
若为 DEGRADED，关闭非核心云端交互，启动本地缓存。
若为 OFFLINE 超过 30 秒，进入 L3 应急模式，只保留安全监控任务。
每次状态变化时，记录事件日志到本地 Flash。

降级策略的常见误区是“一刀切”——断网就停止所有功能。这在某些场景下是合理的（如纯云端计算设备），但对大多数物联网设备来说，本地控制能力才是核心价值。正确的做法是：先列出所有功能清单，标注每个功能的“在线依赖度”和“业务重要性”，然后根据这两个维度决定降级顺序。

3.3 本地优先架构：数据先落盘，逻辑先跑通

本地优先架构（Local-First Architecture）是离线可用设计的核心实现手段。它的基本原则是：所有关键数据和操作首先在本地完成，云端同步作为异步补充。对于 ESP32 来说，这意味着三件事：

本地存储：使用 NVS（非易失存储）保存配置参数，使用 SPIFFS 或 LittleFS 保存日志和传感器历史数据。
本地计算：阈值判断、数据滤波、PID 控制等逻辑不依赖云端返回，直接在设备端执行。
本地决策：设备根据本地数据和预设规则做出控制决策，而不是等待云端指令。

以 ESP32 环境监测站为例，传统架构是“传感器→ESP32→云端→判断→返回指令”，断网后整个链路瘫痪。本地优先架构改为“传感器→ESP32→本地判断→执行动作”，同时将数据写入本地日志文件；网络恢复后，再把日志文件分批上传。这样即使断网一周，设备依然能完成数据采集和超限报警。

// 本地优先架构的日志写入示例（LittleFS）
void log_sensor_data(float temp, float hum) {
    File logFile = LittleFS.open("/data/sensor.csv", FILE_APPEND);
    if (logFile) {
        logFile.printf("%lu,%.2f,%.2f\n", millis(), temp, hum);
        logFile.close();
    }
}

// 网络恢复后补传
void upload_pending_logs() {
    File logFile = LittleFS.open("/data/sensor.csv", FILE_READ);
    if (!logFile) return;
    while (logFile.available()) {
        String line = logFile.readStringUntil('\n');
        if (mqtt_publish("sensor/data", line.c_str())) {
            // 上传成功，记录偏移量
        } else {
            break; // 网络又断了，停止上传
        }
    }
    logFile.close();
}

本地优先架构的难点在于存储空间管理。ESP32 的 Flash 通常只有 4MB~16MB，日志文件不能无限增长。建议实现环形覆盖策略：当日志文件超过设定大小（如 512KB）时，删除最旧的数据块。同时，日志写入要采用“批量提交”方式，避免频繁擦写 Flash 导致寿命衰减。

经验建议：NVS 适合保存小体积配置（如设备 ID、校准参数），不适合保存日志。日志类数据优先使用 LittleFS，因为它支持文件追加写入，且磨损均衡做得更好。如果日志量很大，可以考虑外接 SD 卡或 SPI Flash 芯片。

3.4 数据一致性与最终一致性：从“强一致”到“最终一致”

在分布式系统中，数据一致性是一个经典难题。对于 ESP32 设备，我们通常不追求强一致性（即云端和设备数据时刻完全相同），而是采用最终一致性模型：允许设备在断网期间产生与云端不一致的数据，但保证在网络恢复后，经过补传和对账，数据最终达到一致状态。

最终一致性需要解决三个问题：数据版本管理、冲突检测、冲突解决。数据版本管理最简单的方式是给每条记录加时间戳和递增序号。冲突检测发生在补传时：如果云端发现某条记录的时间戳比本地新，说明存在冲突。冲突解决策略有三种：

时间戳优先：以最后写入的数据为准，适合传感器数据（新数据覆盖旧数据）。
设备优先：以设备端数据为准，适合控制指令（设备实际执行结果更可信）。
合并策略：将两条记录合并为一条，适合需要保留历史轨迹的场景。

场景	推荐策略	原因
温湿度历史数据	时间戳优先	传感器数据是时序数据，新值覆盖旧值合理
设备配置参数	设备优先	设备本地配置是用户最近修改的，云端可能过期
报警事件记录	合并策略	每条报警都是独立事件，不能互相覆盖

在 ESP32 上实现最终一致性，需要设计一个补传队列。当设备处于离线状态时，所有需要上报的数据先写入本地队列（可以是 LittleFS 文件或 NVS 中的环形缓冲区）。网络恢复后，补传任务按顺序读取队列，逐条发送到云端。发送成功后，从队列中删除该记录；发送失败则保留，等待下次重试。补传任务要设置超时和重试次数限制，避免某条坏数据阻塞整个队列。

注意：补传不是简单的“把文件发完”。要考虑云端接口的幂等性——如果一条数据发送成功但 ACK 丢失，设备会重发，云端需要能识别重复数据并去重。建议在每条记录中包含全局唯一 ID（如设备 MAC + 时间戳 + 序号），云端根据 ID 去重。

3.5 案例拆解：智能灌溉控制器的离线可用改造

某农业大棚部署了 20 台 ESP32 智能灌溉控制器，每台控制器连接土壤湿度传感器和电磁阀。原始设计是：传感器数据 → ESP32 → Wi-Fi → 云端服务器 → 云端判断是否浇水 → 返回指令 → ESP32 执行。实际运行中，大棚内 Wi-Fi 信号受金属架构遮挡，经常出现 5~10 分钟的断网。断网期间，设备无法获取浇水指令，导致部分区域土壤过干。

改造目标：断网期间设备能根据本地湿度阈值自动浇水，网络恢复后补传所有传感器数据和浇水记录。

关键参数：土壤湿度阈值设为 30%（低于则浇水），每次浇水时长 10 秒，传感器采样间隔 5 分钟，本地日志容量 512KB（约可存储 7 天数据）。

实施步骤：

在 ESP32 上实现网络健康度检测任务，每 10 秒检测一次，状态变量 net_state 供全局读取。
将浇水判断逻辑从云端迁移到本地：读取湿度传感器 → 与阈值比较 → 控制电磁阀。云端只负责远程修改阈值和查看历史数据。
使用 LittleFS 创建日志文件 /data/irrigation.csv，每次采样和浇水都追加记录。
实现补传任务：网络恢复后，按行读取日志文件，通过 MQTT 发布到云端主题 farm/irrigation/history。发布成功后记录文件偏移量，下次从偏移量继续。
设置日志文件最大 512KB，超过后删除最旧的 20% 数据。

结果对比：改造前，断网期间设备完全失控，平均每天有 3 次浇水延误；改造后，断网期间设备自动浇水成功率达到 100%，网络恢复后 2 分钟内完成所有补传数据。云端数据与本地记录对账后，误差为 0 条。

代价与风险：本地自动浇水依赖湿度传感器准确性，如果传感器漂移，可能导致误浇水。因此增加了“连续 3 次采样均低于阈值才浇水”的防误判逻辑。另外，补传期间如果网络再次中断，已发送但未确认的数据会重复发送，云端需要按设备 ID + 时间戳去重。

复盘经验：离线可用设计不是“加一个缓存”那么简单，而是要从业务逻辑层面重新划分“哪些功能必须在线、哪些功能可以离线”。对于灌溉控制器，浇水决策是核心功能，必须本地化；而远程查看历史数据是次要功能，可以等待网络恢复。

3.6 常见误区与总结

离线可用设计中有几个高频误区，值得特别提醒：

误区一：只检测 Wi-Fi 连接状态。Wi-Fi 关联不代表网络可用，必须检测到云端服务的连通性。
误区二：降级策略过于简单。“断网就停止所有功能”或“断网就无限重连”都是极端做法。应该分级降级，并设置合理的重连退避策略。
误区三：本地日志无限增长。ESP32 Flash 空间有限，必须设计日志轮转和清理机制。
误区四：补传不考虑幂等性。网络抖动可能导致重复发送，云端必须能识别重复数据。
误区五：忽略时间同步。断网期间设备时钟可能漂移，补传时时间戳不准确会导致数据对账混乱。建议使用 RTC 模块或 GPS 校时，断网时至少保持相对时间。

总结来说，离线可用设计的核心是“本地优先、云端补充”。断网场景分析帮助我们识别网络状态，降级策略让我们知道不同状态下该做什么，本地优先架构保证核心业务不中断，最终一致性确保数据不丢失。这四者环环相扣，缺一不可。在实际项目中，建议先画出业务功能清单，标注每个功能的在线依赖度和重要性，再设计对应的降级路径和数据同步方案。这样设计出来的系统，才能真正应对复杂的网络环境。