监控运维¶

本文引用的文件 - main.c - webui_server.c - wifi_manager.c - eth_manager.c - config.h - rest_api.h - led_indicator.h - index.html - devices.html

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考虑
故障排查指南
结论
附录

简介¶

本文件面向ESP32-S3 BLE网关的监控与运维，围绕系统状态监控指标、性能数据采集、健康检查机制、日志策略与远程传输、LED状态指示、故障诊断与维护提醒、Web界面监控与历史分析、远程管理接口与自动化、告警配置、巡检清单、性能调优与容量规划、备份恢复与应急响应等维度进行系统化文档化，帮助运维人员实现稳定高效的运行保障。

项目结构¶

本项目采用组件化设计，主程序负责启动顺序与全局状态，网络子系统（WiFi/以太网）负责连接管理，WebUI与REST API提供可视化与远程管理能力，LED指示模块提供本地状态反馈。关键硬件配置集中在全局配置头文件中，便于统一管理和跨组件共享。

graph TB
A["主程序<br/>main.c"] --> B["LED指示模块<br/>led_indicator.h"]
A --> C["配置管理<br/>config.h"]
A --> D["网络管理<br/>eth_manager.c / wifi_manager.c"]
A --> E["WebUI服务器<br/>webui_server.c"]
A --> F["REST API接口<br/>rest_api.h"]
E --> F
E --> G["静态资源<br/>data/*.html"]

图表来源 - main.c - webui_server.c - wifi_manager.c - eth_manager.c - config.h - rest_api.h - led_indicator.h - index.html - devices.html

章节来源 - main.c - config.h

核心组件¶

主程序与启动流程：负责系统初始化、NVS、事件循环、启动模式判断（以太网优先/WiFi优先/仅WiFi）、服务启动与周期性状态打印。
网络管理：以太网（CH390D SPI）与WiFi双栈支持，事件驱动的状态机与重连机制，提供连接状态查询与回调。
WebUI与REST API：基于HTTP服务器提供静态页面与REST接口，支持系统状态、设备列表等查询与控制。
LED指示模块：三色LED（系统/网络/BLE）状态映射，用于本地快速诊断。
配置中心：集中定义硬件引脚、网络参数、任务优先级、缓冲区大小等，便于统一维护。

章节来源 - main.c - wifi_manager.c - eth_manager.c - webui_server.c - led_indicator.h - config.h

架构总览¶

系统采用“主程序协调 + 多组件协作”的架构。主程序根据配置与启动条件选择网络模式，随后初始化各子系统并进入监控循环；网络层提供连接状态与IP信息；WebUI通过REST API暴露系统状态与设备管理；LED作为本地健康指示器。

graph TB
subgraph "应用层"
M["主程序<br/>app_main()"]
WUI["WebUI服务器"]
API["REST API"]
end
subgraph "网络层"
ETH["以太网管理"]
WIFI["WiFi管理"]
end
subgraph "硬件抽象"
LED["LED指示模块"]
CFG["全局配置"]
end
M --> ETH
M --> WIFI
M --> WUI
M --> LED
WUI --> API
M --> CFG
WIFI --> CFG
ETH --> CFG

图表来源 - main.c - webui_server.c - wifi_manager.c - eth_manager.c - led_indicator.h - config.h

详细组件分析¶

主程序与启动流程¶

初始化顺序：LED → NVS → 事件循环 → 打印系统信息 → 检查复位按键 → 加载配置 → 初始化网络栈 → WiFi配置引导 → 启动服务 → 创建按钮任务 → 进入监控循环。
启动模式判定：依据配置决定优先使用以太网或WiFi；若WiFi有凭据则尝试连接，失败则进入配置引导；无凭据则直接进入配置引导。
周期性监控：每30秒打印堆内存、网络连接状态、BLE设备数量，便于远程观察。

sequenceDiagram
participant APP as "主程序"
participant LED as "LED指示模块"
participant NVS as "NVS存储"
participant NET as "网络栈"
participant WIFI as "WiFi管理"
participant ETH as "以太网管理"
participant SVC as "服务启动"
APP->>LED : 初始化LED
APP->>NVS : 初始化NVS
APP->>NET : 初始化网络栈
APP->>APP : 检查复位按键
APP->>APP : 加载配置
alt 以太网优先
APP->>ETH : 初始化以太网
APP->>WIFI : 初始化WiFi
APP->>NET : 启动网络管理
APP->>SVC : 启动WebUI/REST/MQTT
else WiFi有凭据
APP->>WIFI : 连接已保存WiFi
alt 连接成功
APP->>NET : 启动网络管理
APP->>SVC : 启动服务
else 连接失败
APP->>WIFI : 启动配置引导
end
else 无凭据
APP->>WIFI : 启动配置引导
end
APP->>APP : 创建按钮任务
APP->>APP : 进入监控循环(30s)

图表来源 - main.c

章节来源 - main.c

网络管理（WiFi）¶

事件驱动：WIFI_EVENT/IP_EVENT两类事件处理连接建立、断开、重连与IP获得/丢失。
状态机：DISCONNECTED/CONNECTING/AP_MODE/CONNECTED四种状态，配合事件组同步。
回调机制：可注册回调函数在状态变化时通知上层。
扫描与连接：支持主动扫描AP、连接指定AP、断开、启动/停止AP模式。

flowchart TD
S["开始"] --> INIT["初始化WiFi管理"]
INIT --> CONNECT["连接到AP"]
CONNECT --> EVT{"事件触发"}
EVT --> |STA_START| START["启动STA并请求连接"]
EVT --> |CONNECTED| GOTIP["等待IP分配"]
EVT --> |DISCONNECTED| RETRY{"重试次数 < 最大值?"}
RETRY --> |是| RECONNECT["重新连接"]
RETRY --> |否| FAIL["标记失败并回调"]
GOTIP --> |获得IP| READY["状态=CONNECTED"]
GOTIP --> |失去IP| LOST["状态=CONNECTING"]
READY --> END["结束"]
LOST --> EVT
FAIL --> END

图表来源 - wifi_manager.c

章节来源 - wifi_manager.c

网络管理（以太网）¶

CH390D SPI控制器：配置SPI总线、CS/INT/RST引脚，安装MAC/PHY驱动，绑定到默认网络接口。
事件驱动：ETHERNET_EVENT/IP_EVENT处理链路状态与IP变更。
状态查询：支持获取当前IP、网关、掩码、速率、双工模式等。

sequenceDiagram
participant APP as "主程序"
participant ETH as "以太网管理"
participant MAC as "CH390 MAC"
participant PHY as "CH390 PHY"
participant NET as "网络接口"
APP->>ETH : 初始化
ETH->>MAC : 创建MAC
ETH->>PHY : 创建PHY
ETH->>ETH : 安装驱动并获取MAC地址
ETH->>NET : 绑定到网络接口
ETH->>ETH : 注册事件处理器
APP->>ETH : 启动以太网
ETH-->>APP : 连接状态/IP更新

图表来源 - eth_manager.c

章节来源 - eth_manager.c

WebUI与REST API¶

WebUI服务器：挂载SPIFFS分区，注册REST API处理器与静态文件处理器，监听端口对外提供服务。
静态资源：首页与设备页通过REST接口动态加载数据，实现实时状态展示与交互。
接口职责：REST API由上层模块注册，WebUI负责前端展示与用户交互。

sequenceDiagram
participant Browser as "浏览器"
participant HTTP as "HTTP服务器"
participant REST as "REST API"
participant DATA as "数据源"
Browser->>HTTP : GET /
HTTP->>HTTP : 解析URI并匹配静态文件
HTTP-->>Browser : 返回HTML/CSS/JS
Browser->>HTTP : GET /api/status
HTTP->>REST : 调用状态接口
REST->>DATA : 查询系统/网络/BLE状态
DATA-->>REST : 返回状态数据
REST-->>HTTP : JSON响应
HTTP-->>Browser : 渲染状态面板

图表来源 - webui_server.c - index.html - devices.html - rest_api.h

章节来源 - webui_server.c - index.html - devices.html - rest_api.h

LED状态指示系统¶

引脚与索引：系统定义三色LED引脚与索引（网络/蓝牙/系统），支持统一设置与单灯闪烁。
状态枚举：OFF/ON/慢闪/快闪/单次闪烁，用于表达不同运行阶段与异常状态。
使用场景：启动阶段快速闪烁表示初始化中；连接后常亮；异常时快闪；复位/引导模式下多灯联动提示。

classDiagram
class LED指示模块 {
+初始化()
+反初始化()
+设置(索引, 状态)
+全部设置(状态)
+单次闪烁(索引, 时长)
+获取(索引) 状态
}
class 状态枚举 {
+OFF
+ON
+慢闪
+快闪
+单次闪烁
}
LED指示模块 --> 状态枚举 : "使用"

图表来源 - led_indicator.h - config.h

章节来源 - led_indicator.h - config.h

依赖关系分析¶

主程序依赖网络、WebUI、LED与配置模块；网络模块依赖ESP-IDF的事件与网络接口；WebUI依赖HTTP服务器与REST接口；LED依赖GPIO；配置集中于头文件供全工程共享。
组件内聚高、耦合低，通过明确的接口与回调实现松耦合。

graph LR
MAIN["主程序"] --> CFG["配置头文件"]
MAIN --> LED["LED指示模块"]
MAIN --> NET["网络管理"]
NET --> WIFI["WiFi管理"]
NET --> ETH["以太网管理"]
MAIN --> WUI["WebUI服务器"]
WUI --> API["REST API接口"]
WUI --> HTML["静态页面"]

图表来源 - main.c - config.h - led_indicator.h - wifi_manager.c - eth_manager.c - webui_server.c - rest_api.h - index.html - devices.html

章节来源 - main.c - config.h