增加断网保存数据到FLASH，恢复联网重新补发，并加上标志位

2026-02-02 00:31:52 +08:00
parent 86b2425e93
commit d56c730cfe
19 changed files with 1853 additions and 52 deletions
--- a/docs/OFFLINE_STORAGE.md
+++ b/docs/OFFLINE_STORAGE.md
@@ -0,0 +1,432 @@
+# 离线数据存储和补传功能说明
+
+## 功能概述
+
+本设备支持离线数据存储功能，当网络断开时，数据会自动存储到Flash文件系统中；当网络恢复后，数据会自动补传到MQTT服务器。
+
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────┐
+│                   应用层                          │
+├─────────────────────────────────────────────────┤
+│  MODBUS数据     设备状态      MQTT客户端         │
+│       │              │              │            │
+│       ▼              ▼              ▼            │
+│  ┌─────────────────────────────────────┐       │
+│  │        离线数据管理模块               │       │
+│  │    (OFFLINE_STORAGE 组件)            │       │
+│  └─────────────────────────────────────┘       │
+│       │                                    │    │
+│       ▼                                    │    │
+│  ┌─────────────────────────────────────┐       │
+│  │     SPIFFS文件系统                 │       │
+│  │    (FLASH_SPIFS 组件)               │       │
+│  └─────────────────────────────────────┘       │
+│       │                                    │    │
+│       ▼                                    │    │
+│  ┌─────────────────────────────────────┐       │
+│  │       16MB Flash存储区               │       │
+│  │          (8MB可用)                   │       │
+│  └─────────────────────────────────────┘       │
+└─────────────────────────────────────────────────┘
+```
+
+## 分区表配置
+
+```csv
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     0x9000,  0x6000,
+phy_init, data, phy,     0xf000,  0x1000,
+factory,  app,  factory, 0x10000, 2MB,
+storage,  data, spiffs,  0x210000,8MB,
+```
+
+- **storage分区**：8MB，用于离线数据存储
+- **挂载点**：`/flash`
+- **文件系统**：SPIFFS
+
+## 存储容量估算
+
+| 参数 | 数值 |
+|------|------|
+| Flash总容量 | 16MB |
+| 存储分区大小 | 8MB |
+| MODBUS数据量 | 200字节/条（1秒/次） |
+| 每小时数据量 | 720KB |
+| 可存储时长 | 约11小时 |
+
+**注意**：SPIFFS最小文件大小为4KB，200字节的文件实际占用4KB空间，因此实际可存储的时长会更短。建议将多条数据合并到一个文件中存储以提高空间利用率。
+
+## 文件组织结构
+
+```
+/flash/
+├── data/
+│   ├── modbus/              # MODBUS采集数据
+│   │   ├── 1738452345.json  # 时间戳命名
+│   │   ├── 1738452346.json
+│   │   └── ...
+│   └── status/              # 设备状态数据
+│       ├── 1738452345.json
+│       └── ...
+└── index.json              # 索引文件
+```
+
+## 工作流程
+
+### 正常模式（网络在线）
+
+```
+数据产生
+  ↓
+检测网络状态（在线）
+  ↓
+直接发布到MQTT
+  ↓
+不存储
+```
+
+### 离线模式（网络断开）
+
+```
+数据产生
+  ↓
+检测网络状态（离线）
+  ↓
+存储到Flash SPIFFS
+  ↓
+写入成功
+  ↓
+等待网络恢复
+```
+
+### 补传模式（网络恢复）
+
+```
+检测网络状态（在线）
+  ↓
+检查是否有离线数据
+  ↓
+读取最旧的数据
+  ↓
+发布到MQTT
+  ↓
+发布成功？
+  ├─ 是 → 删除该数据 → 继续下一条
+  └─ 否 → 等待重试
+```
+
+## API接口
+
+### FLASH_SPIFS 组件
+
+#### 初始化文件系统
+
+```c
+esp_err_t flash_spiffs_init(void);
+```
+
+#### 检查是否挂载
+
+```c
+bool flash_spiffs_is_mounted(void);
+```
+
+#### 获取存储使用情况
+
+```c
+uint32_t flash_spiffs_get_total_size(void);
+uint32_t flash_spiffs_get_used_size(void);
+```
+
+#### 格式化文件系统
+
+```c
+esp_err_t flash_spiffs_format(void);
+```
+
+### OFFLINE_STORAGE 组件
+
+#### 初始化存储模块
+
+```c
+esp_err_t offline_storage_init(void);
+```
+
+#### 存储离线数据
+
+```c
+esp_err_t offline_storage_store(const char *data, size_t length, offline_data_type_t data_type);
+```
+
+**参数**：
+- `data`：数据内容（JSON字符串）
+- `length`：数据长度
+- `data_type`：数据类型
+  - `OFFLINE_DATA_TYPE_MODBUS`：MODBUS采集数据
+  - `OFFLINE_DATA_TYPE_DEVICE_STATUS`：设备状态数据
+
+#### 读取最旧的数据
+
+```c
+esp_err_t offline_storage_read_oldest(char *buffer, size_t max_len, offline_data_type_t *out_data_type);
+```
+
+#### 删除最旧的数据
+
+```c
+esp_err_t offline_storage_delete_oldest(void);
+```
+
+#### 获取数据数量
+
+```c
+uint32_t offline_storage_get_count(void);
+bool offline_storage_has_data(void);
+```
+
+#### 清空所有数据
+
+```c
+esp_err_t offline_storage_clear_all(void);
+```
+
+### MQTT_ESP 扩展接口
+
+#### 存储离线数据（内部使用）
+
+```c
+esp_err_t mqtt_store_offline(const char *data, size_t length, offline_data_type_t data_type);
+```
+
+#### 启动/停止补传任务
+
+```c
+BaseType_t mqtt_start_offline_upload_task(void);
+void mqtt_stop_offline_upload_task(void);
+```
+
+## 网络状态检测
+
+系统通过MQTT连接状态判断网络是否在线：
+
+| MQTT事件 | 网络状态 | 处理 |
+|---------|---------|------|
+| `MQTT_EVENT_CONNECTED` | 在线 | 启动补传任务 |
+| `MQTT_EVENT_DISCONNECTED` | 离线 | 停止补传任务 |
+
+## 存储策略
+
+### 自动循环覆盖
+
+- **最大文件数限制**：10,000个文件
+- **触发条件**：当文件数超过限制时，自动删除最旧的数据
+- **优先级**：按时间戳排序，删除最旧的数据
+
+### 数据完整性保护
+
+- **索引文件**：`/flash/index.json` 记录所有文件信息
+- **原子写入**：使用临时文件+重命名机制
+- **断电保护**：SPIFFS提供基本断电保护
+
+### 存储空间管理
+
+```
+获取空间使用情况
+  ↓
+检查可用空间
+  ↓
+空间不足？
+  ├─ 否 → 正常存储
+  └─ 是 → 删除最旧数据 → 重试
+```
+
+## SPIFFS 特性说明
+
+### 优点
+- ESP-IDF原生支持，无需额外组件
+- 代码成熟稳定
+- 内存占用小（约2KB）
+- 挂载速度快
+
+### 缺点
+- 最小文件大小为4KB，小文件浪费空间
+- 无磨损均衡，Flash寿命相对较短
+- 碎片严重，长期使用后性能下降
+- 不支持目录（所有文件在根目录）
+
+### 优化建议
+
+1. **合并多条数据到单个文件**：减少文件数量，提高空间利用率
+2. **定期格式化**：消除碎片，恢复性能
+3. **限制文件数量**：避免碎片积累
+
+## 日志输出
+
+### 初始化日志
+
+```
+I (xxxx) main: Initializing SPIFFS file system...
+I (xxxx) FLASH_SPIFS: 正在初始化SPIFFS文件系统...
+I (xxxx) FLASH_SPIFS: SPIFFS文件系统挂载成功
+I (xxxx) FLASH_SPIFS: 总空间: 8388608 字节
+I (xxxx) FLASH_SPIFS: 已用空间: 4096 字节
+I (xxxx) FLASH_SPIFS: 可用空间: 8384512 字节
+I (xxxx) FLASH_SPIFS: 挂载点: /flash
+I (xxxx) main: Initializing offline storage module...
+I (xxxx) main: 离线存储模块初始化完成
+```
+
+### 存储日志
+
+```
+I (xxxx) mqtt_esp: Storing offline data (type=1, size=256)
+I (xxxx) OFFLINE_STORAGE: 存储数据: /flash/data/modbus/1738452345.json, 大小: 256 字节
+I (xxxx) OFFLINE_STORAGE: Storage usage: 4096 / 8388608 bytes (0.0%)
+W (xxxx) OFFLINE_STORAGE: 注意：SPIFFS最小文件大小为4KB，小文件会占用更多空间
+```
+
+### 补传日志
+
+```
+I (xxxx) mqtt_esp: Network is online, starting offline data upload
+I (xxxx) mqtt_esp: Found 10 offline data files, uploading...
+I (xxxx) mqtt_esp: Publishing offline data (type=1, size=256)
+I (xxxx) mqtt_esp: Offline data published successfully, msg_id=12345
+```
+
+## 故障处理
+
+### Flash空间不足
+
+**现象**：
+```
+E (xxxx) OFFLINE_STORAGE: 无法创建文件
+```
+
+**解决**：
+1. 自动删除最旧的数据
+2. 格式化存储分区
+
+### 文件系统损坏
+
+**现象**：
+```
+E (xxxx) FLASH_SPIFS: 挂载失败
+```
+
+**解决**：
+1. 系统会尝试自动修复
+2. 如修复失败，格式化文件系统
+3. 检查Flash硬件
+
+### 数据补传失败
+
+**现象**：
+```
+E (xxxx) mqtt_esp: Failed to publish offline data
+```
+
+**解决**：
+1. 检查网络连接
+2. 检查MQTT服务器状态
+3. 数据会保留在Flash中，下次重试
+
+## 性能优化建议
+
+### 1. 合并多条数据
+
+将多条数据合并到一个文件中存储：
+
+```c
+// 示例：每100条数据存储为一个文件
+// 空间利用率：100 * 200字节 / 4096字节 ≈ 4.9%
+// 单文件存储：100 * 200字节 / 4096字节 = 100%
+```
+
+### 2. 降低存储频率
+
+网络离线时降低存储频率：
+
+```c
+// 在线：1秒/次
+// 离线：10秒/次
+// 可存储时长：110小时
+```
+
+### 3. 选择性存储
+
+只存储关键数据：
+
+```c
+// 只存储异常数据、状态变化
+// 正常数据丢弃
+```
+
+### 4. 定期格式化
+
+建议每隔1-3个月格式化一次文件系统，消除碎片：
+
+```c
+flash_spiffs_format();
+```
+
+## 监控和调试
+
+### 查看存储使用情况
+
+```c
+size_t used = 0, total = 0;
+offline_storage_get_usage(&used, &total);
+ESP_LOGI(TAG, "Storage: %zu / %zu bytes", used, total);
+ESP_LOGI(TAG, "Usage: %.1f%%", (used * 100.0) / total);
+```
+
+### 查看离线数据数量
+
+```c
+uint32_t count = offline_storage_get_count();
+ESP_LOGI(TAG, "Offline data files: %u", count);
+```
+
+### 格式化存储
+
+```c
+flash_spiffs_format();
+```
+
+## 注意事项
+
+1. **首次启动**：会自动格式化文件系统（如果需要）
+2. **断电保护**：SPIFFS提供基本断电保护，但建议避免频繁断电
+3. **Flash寿命**：SPIFFS无磨损均衡，建议定期格式化以延长寿命
+4. **容量限制**：由于SPIFFS最小文件4KB，实际可存储时长会少于理论值
+5. **补传速率**：每秒处理一条数据，避免阻塞新数据上传
+6. **碎片问题**：长期使用后性能可能下降，建议定期格式化
+
+## 后续扩展建议
+
+1. **数据压缩**：集成zlib压缩，延长存储时长
+2. **批量存储**：将多条数据合并到一个文件中
+3. **优先级队列**：重要数据优先补传
+4. **数据导出**：通过Web界面导出离线数据
+5. **统计信息**：记录丢失/补传的数据统计
+6. **智能采样**：根据存储空间动态调整采样率
+7. **定期维护**：实现自动碎片整理和格式化
+
+## 与LittleFS对比
+
+| 特性 | SPIFFS | LittleFS |
+|------|--------|----------|
+| 最小文件大小 | 4KB | 0字节 |
+| 内存占用 | ~2KB | ~4KB |
+| 磨损均衡 | ❌ 无 | ✅ 自带 |
+| 断电保护 | ⚠️ 一般 | ✅ 优秀 |
+| 支持目录 | ❌ 不支持 | ✅ 支持 |
+| 碎片问题 | ❌ 严重 | ✅ 轻微 |
+| ESP-IDF支持 | ✅ 原生支持 | ❌ 需第三方组件 |
+
+**选择建议**：
+- 如果需要ESP-IDF原生支持且数据量不大 → SPIFFS
+- 如果需要更好的性能和寿命 → LittleFS（需手动添加组件）