资源占用与功能裁剪
本文用于决定"哪些功能要编进固件，哪些功能应关闭"。构建段落、环境列表和宏定义位置见 构建配置；本页只保留资源预算、裁剪策略和交付前检查清单，避免重复维护 platformio.ini 的完整说明。
2026-10-04按当前开发代码核对内存保护和资源口径；新增TLS保护、功能观察与分池接口仍待统一测试和部署，参见当前验收状态。历史数值只说明当时特定固件与负载，不能作为本候选的内存实测。
ESP32 内存背景
| 资源 | ESP32 | ESP32-S3 | ESP32-C3 | ESP32-C6 |
|---|---|---|---|---|
| 内部 SRAM | 芯片规格与可分配DRAM分别核对 | 芯片规格与可分配DRAM分别核对 | 芯片规格与可分配DRAM分别核对 | 芯片规格与可分配DRAM分别核对 |
| 可用堆（启动后） | 按实际固件/配置测量 | 按实际固件/配置测量 | 按实际固件/配置测量 | 按实际固件/配置测量 |
| PSRAM | 4-8MB 可选 | 2-8MB 可选 | 无 | 无 |
| 正式环境Flash | 4/8MB | 8/16MB | 4MB | 4/8MB |
关键约束：
- WiFi、lwIP、FreeRTOS、TLS 握手等仍需要内部 DRAM，不能完全依赖 PSRAM。
- PSRAM 适合 HTTP/JSON 缓冲区和较大临时对象，不适合实时性高或硬件要求内部 DRAM 的结构。
- ESP32-C3/C6 的 4MB 无 PSRAM 环境使用对应 F4R0 出厂环境；未接硬件的显示、网络和高级协议模块应在运行时关闭。
- 长期运行时最大连续堆比总空闲堆更重要；总空闲 35KB 但最大连续块只有 8KB 时，大对象仍可能分配失败。
DRAM 消耗源实测分解（esp32-F4R0）
以 2026-08 实测固件（无 PSRAM）为例，排查“空闲 DRAM 为何下降”时可直接对照：
静态占用（data+bss，链接期确定）≈ 89.3KB，主要构成：
| 消耗源 | 占用 | 说明 |
|---|---|---|
| FastBee StaticSlabPool 三个池（256×32 / 192×32 / 64×64） | ≈18.5KB | HTTP/Web 预分配 slab，换取运行期零碎片 |
| WiFi/BT 协议栈静态内存（libnet80211/libpp/libbt 等） | ≈12KB | 芯片库固定占用，不可裁 |
| LoggerSystem 单例 + MQTT 发布池 + WiFi 扫描缓冲 | ≈6.2KB | 各约 2KB |
| lwIP/mDNS/FreeRTOS/U8g2 等框架静态 | 其余 | dns_table、mdns 任务栈等 |
运行期动态大头（启动后逐步占用）：MQTT（尤其 MQTTS：TLS 缓冲可达 35KB）、lwIP TCP 缓冲（已调优至 2×MSS/3×MSS，见下文）、AsyncTCP 连接块、JSON 配置解析峰值。
典型案例：free8 从 22.8KB 跌到 7.8KB 的原因链：
- MQTT 建连占 12-15KB lwIP 缓冲（叠加 TLS 时更多）
- 旧固件传感器并发读反复触发崩溃复位，启动期内存叠加碎片
- 碎片化：总空闲尚可但最大连续块 <6KB 时静态文件门控拒接，体感雪崩
修复（单总线互斥锁 + 限流退避 + MQTT 让位）后，STA 稳态实测：free8≈25-27KB、blk8≈11.7KB、frag≈49%、min free≈42.8KB（INTERNAL 口径），Web 8/8 资源正常。排查内存下降时先看 [METRICS] 行的 min 字段确定历史最低点，再对照上表定位是 MQTT/TLS 还是碎片问题。
内存优化策略
PSRAM 分配阈值
启动代码通过 heap_caps_malloc_extmem_enable(256) 设置默认分配的PSRAM偏好。它不改变显式内部/DMA能力分配，不保证所有TLS或JSON对象都位于PSRAM，也不能以PSRAM总空闲量替代内部DRAM水位。路由作用域可临时调整偏好；实际位置和峰值仍须测量。
保护基准集中在 include/core/MemoryBudget.h；HealthMonitor还会应用芯片/PSRAM档位、最大块、启动宽限和恢复迟滞，以下不是全部设备通用的最终等级判断：
| 常量 | 值 | 说明 |
|---|---|---|
GUARD_WARN_DRAM_FREE | 30720 | 默认WARN空闲基准，classic/C3无PSRAM档位使用20480 |
GUARD_SEVERE_DRAM_FREE | 24576 | 默认SEVERE空闲基准，classic/C3无PSRAM档位使用12288 |
GUARD_CRITICAL_DRAM_FREE | 16384 | 工具层默认值；HealthMonitor实际使用动态criticalThreshold |
MQTT_CMD_QUEUE_MAX_BYTES | 4096 | 位于MQTTClient.h，MQTT命令队列的累计消息字节上限 |
运行期分配闸门（低内存时跳过本次操作而非 OOM 重启，阈值统一收拢在 MemoryBudget.h）：
| 常量 | 值 | 作用点 |
|---|---|---|
MQTT_RECEIVE_MIN_DRAM | 12000 | MQTT 入站消息低于此值直接丢弃 |
TCP_RX_MIN_DRAM | 12000 | TCP 收包低于此值 drain 丢弃入站 |
TCP_RX_MAX_FRAME | 2048 | TCP 单轮读取上限（剩余下轮再读） |
PERIPH_EXEC_MIN_DRAM | 15000 | 外设执行动作链低于此值跳过剩余动作 |
MODBUS_POLL_MIN_DRAM | 12000 | Modbus 轮询低于此值跳过 |
ACTION_TICKER_MIN_DRAM | 4096 | BLINK/BREATHE ticker 分配前水位预检 |
CELLULAR_BEGIN_MIN_DRAM | 8192 | 4G 适配器创建 TinyGSM 对象族前预检 |
运行期分配三件套
新增可被 MQTT 指令/Web/定时器触发的堆分配时，必须遵循：① 水位预检（MemoryBudget::dram8Free()（内部8-bit能力） 对比 MemoryBudget 闸门）→ ② new (std::nothrow) → ③ 判空降级（跳过本次动作/优雅失败退避，绝不解引用空指针）。抛出型 new 在 OOM 时会直接 abort 整机重启，绕过全部降级保护，启动期同样需要处理分配失败，不能以一次性初始化为由忽略错误。TCP 收包禁止使用无界 readString()（O(n²) 追加 churn + 无上限累积），必须走 readTcpBounded() 限长读。WiFi 扫描的成功与失败路径都必须调用 WiFi.scanDelete() 释放驱动内结果。回归守护：test/test_stability_fixes.cpp。
HealthMonitor 四级保护
HealthMonitor根据内部8-bit空闲量、最大连续块、碎片率和芯片档位实施四级保护。网络与TLS仍有必须使用内部DRAM的分配，即使部分大缓冲可放PSRAM，也不能忽略内部压力。
| 级别 | 条件 | 行为 |
|---|---|---|
| NORMAL | 综合判断恢复到正常，满足恢复迟滞 | 按准入和用户配置尝试恢复；排队不等于对象已就绪 |
| WARN | 空闲/连续块/碎片综合告警 | 降低日志量、尝试有针对性的资源回收 |
| SEVERE | 当前档位的空闲/最大块/碎片条件越界 | 暂停MQTTS且保留安全协议；停Modbus、暂停PeriphExec及可选外设 |
| CRITICAL | 达到危急保护条件 | 持续压力可暂停MQTT并安排受控重启；具体路径和启动保护分别判断 |
PSRAM 动态阈值
CRITICAL 阈值根据 PSRAM 容量自动调整：无 PSRAM 8KB、4MB PSRAM 10KB、8MB PSRAM 12KB。阈值在首次检测时计算一次，运行时不变。
内存自动恢复机制
当 DRAM 持续下降进入 SEVERE 或 CRITICAL 时，固件自动执行分级恢复，并优先为 Web 核心保留资源。极低内存下请求仍可能返回 503、超时或触发受控重启，因此验收必须同时检查 Web 可达性、重启计数和恢复后的内存趋势。
分级恢复策略
| 触发时机 | 恢复动作 | 持久性 |
|---|---|---|
| SEVERE | 暂停MQTTS、Modbus、执行Worker/定时器及可选外设 | 保留用户scheme/port/enabled，不自动使用明文 |
| EMERGENCY（DRAM < 4096字节） | 立即执行回收并暂停MQTT；持续5s且越过启动保护时可安排重启 | 当前候选不持久修改MQTT配置；释放量没有保证 |
| criticalThreshold下持续30s | 本次启动暂停MQTT | 不写入enabled=false，恢复后仍须满足准入 |
| criticalThreshold下持续90s | 在启动120s保护窗以外安排受控重启 | 不能保证重启后故障或内存压力消失 |
| NORMAL 恢复 | 尝试重建服务，等待实际对象就绪；失败保持暂停并退避 | 旧版已持久禁用的配置仍需用户明确保存启用 |
防砖保护
| 机制 | 说明 |
|---|---|
| Web 核心优先 | 降级时先关闭 SSE 和非关键服务，为 Web 核心预留资源；极低内存时仍允许返回 503 或受控重启 |
| 重启循环保护 | 启动 < 120s 内不执行 90s 重启，防止"启动→CRITICAL→重启"死循环 |
| 紧急释放兜底 | DRAM < 4096字节时不等30s计时，立即请求暂停MQTT和相关可选服务；仍须观察释放结果 |
| 用户配置保全 | 新保护不改变协议、端口、enabled和凭据；临时暂停不改为永久禁用 |
| 历史降级兼容 | 原始磁盘标记保留；只有完整有效的原TLS协议/端口证据才允许安全恢复，缺证据拒绝启动 |
串口日志格式
代码中的恢复日志使用[MEMRECOVER]前缀。以下仅为当前代码的消息文本，不是本轮设备运行记录，也不承诺固定释放字节数：
[MEMRECOVER] MQTTS paused; scheme, port and enabled preserved
[MEMRECOVER] TLS recovery pending; configuration preserved, no plaintext fallback
[MEMRECOVER] MQTT paused for critical memory; enabled and credentials preserved恢复状态 API
/api/system/metrics直接返回指标JSON，memguard含恢复状态；下面为字段示意。/api/health和别名/api/system/health使用success/data包装及memoryDegradation驼峰字段，两者不能混用，详见健康监控。
{
"memguard": {
"level": 2,
"level_name": "SEVERE",
"mqtts_downgraded": false,
"mqtts_paused": true,
"mqtts_protection": "pause_without_plaintext_fallback",
"mqtt_stopped": false,
"mqtt_disabled": false,
"modbus_stopped": true,
"periph_exec_paused": true,
"critical_duration_s": 0
}
}内存池管理
- StringBufferPool：模板缓冲池
StringBufferPool<BufSize, PoolCount>，用于 Modbus 等重复缓冲区场景，避免频繁 new/delete 导致碎片。 - Modbus 缓冲池：PSRAM 设备 8 个槽位，无 PSRAM 设备 4 个槽位，条件编译控制。
- MQTT 命令队列：总字节数跟踪
_cmdQueueTotalBytes，超过 4096 字节时丢弃新命令，防止队列无限增长。
PSRAM JSON 分配器
FastBee::makeJsonDocument(8192)仅在编译启用FASTBEE_USE_PSRAM、检测到PSRAM且空闲量严格大于8192字节时选择PSRAM分配器；否则使用默认ArduinoJson分配器。8192是选择门槛，不是文档容量上限或持续保留量。选定PSRAM分配器后，后续分配只请求SPIRAM能力，失败时不会自动切到内部堆。该方式可减少文档动态存储对内部堆的占用，但不保证消除其它String/传输缓冲的内部内存峰值；须检查分配或解析失败，并以分池实测确认。
lwIP TCP 缓冲调优
以下TCP数值为旧调优记录，不是当前有效SDK配置：当前 platformio.ini 未声明该 board_build.cmake_extra_args 注入，不能以此表证明缓冲已变化。每连接DRAM成本须核对实际SDK/库配置并测量：
| 芯片 | TCP_SND_BUF / TCP_WND | 每连接合计 | 说明 |
|---|---|---|---|
| classic / C3 / C6 | 2872 B（2×MSS） | ~5.8 KB | 原默认 5744/5760 B，4 连接场景合计省 ~11.5 KB |
| ESP32-S3 | 4308 B（3×MSS） | ~8.6 KB | 带 PSRAM 内存宽裕，仅温和下调 |
连接数预算与耗尽恢复见TCP 连接预算。
延迟初始化（错峰启动）
网络依赖型功能（modbus、ruleScript、commandScript、i2cSensors、rfid、irRemote、ledScreen）的内存分配与 WiFi 启动期重叠会抬高启动 DRAM 峰值。固件通过 RuntimeFeatureManager 的 requiresNetwork 标记在网络就绪前门控这些功能，网络收敛后统一解锁并自动重试被跳过的 eager 外设（retryDeferredPeripherals()），不等于互联网已连接或实例已就绪。当前固件只实现 Modbus 主站，详见功能配置。
MQTTS(TLS) 内存影响
MQTTS可使用WiFiClientSecure或实际蜂窝TLS后端。TLS对象、网络控制块、记录缓冲和握手峰值须分别测量，不能把固定的20～40KB当作所有目标的已测占用或释放收益。当前行为包括：
- WiFiClientSecure按需分配；受控退役/回收路径释放，不能把单次断开等同于对象必定已删除。
- 无 PSRAM 设备 mqtts 连接失败后进入慢速退避，避免反复消耗
- 查询对象分配状态不触发TLS握手；分配失败或不可信的外部明文Client不能用于mqtts。TLS暂停/恢复保留安全协议，具体见MQTT配置。
功能开关方法
功能开关通过 platformio.ini 的 build_flags 设置：
build_flags =
-DFASTBEE_ENABLE_XXX=1 ; 启用
-DFASTBEE_ENABLE_XXX=0 ; 禁用默认值定义在 include/core/FeatureFlags.h，platformio.ini 中的值会覆盖默认值。九个发布环境统一引用 [unified_flags]，并在具体 [env:*] 中覆盖芯片、Flash、PSRAM 和网络模块差异。
四层控制架构
功能实际启用条件为 已编译 AND 用户启用 AND 依赖就绪 AND 预算通过 AND 初始化成功 AND 未被运行时降级：
| 层 | 载体 | 作用 |
|---|---|---|
| 编译时 | FASTBEE_ENABLE_* 宏（FeatureFlags.h / platformio.ini） | 决定功能是否编入固件；宏为 0 时代码完全不编译 |
| 运行时 | /config/features.json（RuntimeFeatureManager 管理） | 首次启动自动生成；可在 Web "功能配置"页面按模块启用/禁用，保存后重启生效；支持父子依赖级联（如关闭 lcd 自动关闭 lcd_gb2312） |
| 启动预算 | include/core/FeatureBudget.h（checkFeatureBudgets()） | 启动时逐项校验 DRAM 预算，不足的功能自动降级为 no-memory 不初始化 |
| 动态降级 | HealthMonitor + RuntimeFeatureManager | 持续内存压力下临时停用高成本功能；不改写用户配置，内存恢复后按策略恢复 |
相关 API（FeatureRouteHandler）：
| 端点 | 方法 | 说明 |
|---|---|---|
/api/features/status | GET | 返回全部功能的编译状态、用户开关、激活状态、资源估算和依赖关系 |
/api/features/config | POST | 仅保存 features.json，不重启 |
/api/features/apply | POST | 保存配置并延时重启生效 |
/api/features/estimate | POST | 预估应用某组开关后的 Flash/RAM 占用 |
请求体格式（config/apply/estimate 通用）：{"features": {"lcd": {"enabled": false}, "irRemote": {"enabled": true}}}。
统一出厂环境
platformio.ini 提供 9 个发布环境：ESP32 的 F4R0/F8R0/F8R8、C3-F4R0、C6-F4R0/F8R0、S3-F8R0/F8R8/F16R8。它们共享基础功能集，但不是全部模块无差别编译：esp32-F4R0、esp32c3-F4R0、esp32c6-F4R0 和 esp32c6-F8R0 明确不编译 4G 与以太网；4MB 环境还关闭 OTA。其余能力再由用户配置、启动预算和运行时降级共同决定是否激活。
启动内存预算校验
固件启动时会逐项校验已启用功能的内存预算（checkFeatureBudgets()，预算表集中在 include/core/FeatureBudget.h）：
- 串口输出
[BUDGET] <feature> ok/denied: free8=XXKB >= need=XXKB；预算不足的功能自动降级为不初始化（状态no-memory），避免启用重模块后启动即 OOM。 /api/system/status的features字段返回各功能运行时状态（active/disabled/no-memory），可用于部署后确认功能是否真正启用。- 新增重内存功能时应在 FeatureBudget 表登记预算，并补充 native 测试守卫（
test_memory_budget.cpp/test_profile_consistency.cpp）。
优先裁剪顺序
| 优先级 | 模块 | 建议 |
|---|---|---|
| 1 | BLE | unified_flags 默认关闭；正式环境关闭BLE；源码有条件编译的配网/API路径，需要时手动覆盖 FASTBEE_ENABLE_BLE=1 并补齐依赖 |
| 2 | 4G / 以太网 | C3、C6 和 ESP32-F4R0 等受限环境在编译期关闭；其余环境即使已编译，未接硬件时也应在功能配置页关闭 |
| 3 | OTA / 定制文件 API / 文件日志 / 用户管理 | 交付版按维护需求开启；无 PSRAM 的 4MB 环境已显式关闭 OTA（单 app 分区无法双槽升级） |
| 4 | LCD/OLED、NeoPixel、LED 点阵、RFID、红外、I2C 高级传感器、GB2312 中文字库 | 未接模块建议在 Web 功能配置页运行时关闭（也可编译期覆盖为 0）；中文字库单个占 ~107KB Flash，4MB 预算紧张时优先裁剪 |
| 5 | 规则脚本 / 命令脚本 | 统一编入；不需要时可在功能配置页关闭；低内存环境优先用固定动作 |
TCP 客户端、HTTP 客户端和 CoAP 协议模块已从代码库移除（保留 MQTT 与 Modbus RTU），不再参与裁剪决策。
Web 资源预算
Web 静态资源通过 scripts/gzip-www.js 生成 staging（.pio/fs-staging/run-*/）后上传 LittleFS。当前发布产物统一使用完整 Web 资源，功能页是否可用由固件编译开关和 RuntimeFeatureManager 决定。不通过 Web 资源集区分产品版本；只按目标能力和配置状态显示相应功能。
| 资源集 | 适用范围 | 说明 |
|---|---|---|
| unified | 所有发布环境 | 完整 Web 页面随文件系统上传，页面通过能力接口和运行时状态决定显示与操作 |
| custom | 自定义构建 | 可自行裁剪页面，但必须同步验证 API、能力接口和 LittleFS 容量 |
自定义 Web 裁剪时应同步清理 device-control.js/-view.js/-modbus.js 等设备大屏 bundle，避免旧构建残留进镜像；发布环境由脚本统一生成 staging。
设备控制页面与设备DRAM的区别
设备控制页面（FASTBEE_ENABLE_DEVICE_CONTROL）的JS解压、执行和DOM位于访问页面的浏览器。设备负责流式提供静态资源和处理API，请求及响应有瞬时DRAM成本；不能把浏览器DOM估值记为固件常驻内存。
当前功能目录将deviceControl列为无独立运行实例的静态资源，常驻RAM估算为0；这不代表页面请求不耗内存。无PSRAM也不是该页面必然拒绝的条件，应检查实际编译能力、用户开关、准入和API响应。完整并发请求、延迟及内存峰值须实测，参见功能配置。
模块资源预算
以下为估算值，用于选型和裁剪决策；实际占用以当前编译输出和运行时 /api/system/info 为准。
外设与显示
| 开关宏 | RAM | Flash | 预设 | 说明 |
|---|---|---|---|---|
FASTBEE_ENABLE_LCD | ~1.2KB | ~20KB | 统一默认启用 | OLED/LCD，依赖 U8g2 |
FASTBEE_ENABLE_NEOPIXEL | 当前估算99×灯数+512字节，待实测 | 待同配置差值构建 | 默认启用 | 包含RGB/RMT发送缓存预算，默认最多64颗；见NeoPixel |
FASTBEE_ENABLE_LED_SCREEN | 动态分配 | ~10KB | 统一默认启用 | WS2812B 点阵屏 |
FASTBEE_ENABLE_I2C_SENSORS | ~500B | ~15KB | 统一默认启用 | BMP280、MPU6050、SHT31、BH1750、AHT20 等 |
FASTBEE_ENABLE_RFID | ~200B | ~12KB | 统一默认启用 | MFRC522 |
FASTBEE_ENABLE_IR_REMOTE | ~300B | ~8KB | 统一默认启用，S3 F8R8环境覆盖禁用 | 不能外推所有S3；按环境库组合核对 |
FASTBEE_ENABLE_LCD_GB2312 | - | ~107KB (wqy12) / ~141KB (wqy15) | 统一默认启用 | OLED GB2312 中文字库；禁用时回退 ASCII 字体，4MB 预算紧张时优先裁剪 |
FASTBEE_ENABLE_DEVICE_CONTROL | 无独立常驻实例；API峰值待实测 | 以当前Web发布清单为准 | 编译能力与用户开关分别检查 | 浏览器页面；DOM不占设备DRAM，不能因无PSRAM直接认定不可用 |
FASTBEE_ENABLE_SENSOR_DRIVER | ~200B | ~8KB | 默认启用 | DHT、DS18B20 等基础传感器 |
FASTBEE_ENABLE_SEVEN_SEGMENT | ~32B/实例 | ~3KB | 默认启用 | TM1637 数码管 |
FASTBEE_ENABLE_DS1302 | ~100B | ~2KB | 正式基线编入，运行时关闭 | 有 NTP 时通常不必启用 |
FASTBEE_ENABLE_LCD1602 | ~100B | ~3KB | 正式基线编入，运行时关闭 | LCD1602/LCD2004 I2C 字符屏 |
网络与协议
| 开关宏 | RAM | Flash | 预设 | 说明 |
|---|---|---|---|---|
FASTBEE_ENABLE_MQTT | ~4-8KB | ~15KB | 默认启用 | 平台通信核心能力；mqtts 额外需 ~20-40KB（TLS） |
FASTBEE_ENABLE_MODBUS | ~3-5KB | ~20KB | 统一默认启用 | 工业现场常用 |
FASTBEE_ENABLE_ETHERNET | ~8KB | ~8KB | 按环境编译，运行时默认关闭 | 受限环境未编译；其他环境用于 W5500，未接硬件时保持关闭 |
FASTBEE_ENABLE_CELLULAR | ~10-15KB | ~15KB | 按环境编译，运行时默认关闭 | 受限环境未编译；其他环境用于 EC801E 4G，RAM 占用高 |
FASTBEE_ENABLE_BLE | ~20-30KB | ~80KB | 默认关闭 | 正式环境关闭BLE；源码有条件配网路径；启用前需补齐依赖和验证 |
FASTBEE_ENABLE_MDNS | ~2KB | ~5KB | 默认启用 | 禁用后不能用 fastbee.local |
FASTBEE_ENABLE_DNS | ~1KB | ~3KB | 默认启用 | AP 配网页面常用 |
FASTBEE_ENABLE_AP_MODE | ~1-2KB | ~2KB | 默认启用 | 禁用后首次配网能力受影响 |
系统与 Web
| 开关宏 | RAM | Flash | 预设 | 说明 |
|---|---|---|---|---|
FASTBEE_ENABLE_WEB_SERVER | ~20-30KB | ~25KB | 默认启用 | Web 控制台和 REST API 核心 |
FASTBEE_ENABLE_PERIPH_EXEC | ~2-4KB | ~8KB | 默认启用 | 定时、事件、平台触发等自动化规则 |
FASTBEE_ENABLE_RULE_SCRIPT | ~4-8KB | ~8KB | 统一默认启用 | 规则脚本引擎 |
FASTBEE_ENABLE_COMMAND_SCRIPT | ~1-2KB | ~3KB | 统一默认启用 | 命令脚本 |
FASTBEE_ENABLE_OTA | 峰值待实测 | 差值待同配置构建测量 | 跟随双 app 分区与实际能力 | 4MB单应用环境关闭；PSRAM不是所有OTA环境的必要条件，内部DRAM仍须达门槛 |
FASTBEE_ENABLE_OTA_FS | 不作为已实现功能计量 | 不承诺独立收益 | 旧宏保留兼容 | 当前没有文件系统OTA writer；开发候选的有效otaFs.compiled=false，不影响固件OTA父项 |
FASTBEE_ENABLE_STORAGE_CACHE | ~2-4KB | ~1KB | 默认关闭 | 大配置文件会绕过缓存，避免峰值翻倍 |
FASTBEE_ENABLE_FILE_LOGGING | ~500B | ~3KB | 统一默认启用 | 持续写 Flash 会影响寿命 |
FASTBEE_ENABLE_USER_ADMIN | ~500B | ~5KB | 统一默认启用 | 多用户管理 |
FASTBEE_ENABLE_FILE_MANAGER | ~500B | ~3KB | 默认关闭 | 定制诊断工具使用的文件 API（无发布版 Web 页面） |
FASTBEE_ENABLE_HEALTH_MONITOR | ~200B | ~4KB | 默认启用 | 不建议关闭；四级堆保护策略 |
FASTBEE_ENABLE_LOGGER | ~300B | ~6KB | 默认启用 | 可调小 FASTBEE_LOG_BUFFER_SIZE |
性能调优参数
| 参数 | 建议 | 说明 |
|---|---|---|
FASTBEE_USE_PSRAM / BOARD_HAS_PSRAM | 只在真实带 PSRAM 的环境开启 | 配合 heap_caps_malloc_extmem_enable(256) 将较大 HTTP/JSON 分配优先放到 PSRAM |
FASTBEE_JSON_DOC_SIZE | 低内存环境可从 4096/8192 下调 | 减少 JSON 文档峰值，但不能小到影响配置解析 |
CONFIG_ASYNC_TCP_MAX_CONNECTIONS | C3/C6 保守，S3+PSRAM 可提高 | 每个连接会消耗内部 DRAM 和 lwIP PCB |
ARDUINO_LOOP_STACK_SIZE | 同时核对强覆盖函数 | 当前main.cpp实际loop栈24KiB，Worker最低栈无PSRAM8KiB/有PSRAM12KiB；宏不代表实际栈 |
FASTBEE_STRIP_INFO_LOGS | 生产建议 1 | 编译期剥离 INFO 日志字符串，节省 Flash |
FASTBEE_DEBUG_LOG / CORE_DEBUG_LEVEL | 生产保持低级别 | 调试日志会增加 Flash 和运行时输出压力 |
典型配置方案
ESP32-C3/C6 4MB 低预算裁剪（esp32c3-F4R0 / esp32c6-F4R0）
统一固件已默认关闭 OTA；如需进一步压低 Flash（app 预算 <82%），可在 env 段追加覆盖，关闭确定不用的模块；若不使用灯带，也关闭 NeoPixel：
-DFASTBEE_ENABLE_MODBUS=0
-DFASTBEE_ENABLE_OTA=0
-DFASTBEE_ENABLE_RULE_SCRIPT=0
-DFASTBEE_ENABLE_COMMAND_SCRIPT=0
-DFASTBEE_ENABLE_LCD=0
-DFASTBEE_ENABLE_NEOPIXEL=0
-DFASTBEE_ENABLE_I2C_SENSORS=0
-DFASTBEE_STRIP_INFO_LOGS=1
-DFASTBEE_LOG_BUFFER_SIZE=128注意：无PSRAM的C3/C6须按实际TLS后端、内部DRAM和最大连续块判断MQTTS准入。内存不足或连接失败时保留mqtts协议、端口、凭据和enabled配置，暂停并退避，不自动改为明文。优先裁剪无用功能或重新评估硬件预算；如需改变通信方案，须由用户明确评估网络安全要求后手动配置，不作为故障恢复默认动作。
ESP32 4MB 低预算裁剪（esp32-F4R0）
目标是 WiFi + MQTT + Modbus + 基础外设。统一预设已关闭 4G、以太网、BLE 和 OTA（env 显式覆盖）；若 Flash 预算紧张（实测接近 82%），优先从大件入手：
-DFASTBEE_ENABLE_OTA=0
-DFASTBEE_ENABLE_ETHERNET=0
-DFASTBEE_ENABLE_CELLULAR=0
-DFASTBEE_ENABLE_LCD_GB2312=0 ; 中文字库 ~107KB，裁剪首选注意：经典ESP32无PSRAM时，MQTTS是否可用须以实际准入、握手和资源测量为准。失败时暂停、保留TLS配置并退避，不以降低传输保护换取自动恢复。用户可在明确核对安全要求后手动重新评估硬件、负载或通信方案。RFID/红外/I2C传感器不用时在功能配置页关闭；编译期裁剪见构建配置。
带 PSRAM 环境（esp32-F8R8 / esp32s3-F8R8 / esp32s3-F16R8）
统一预设已启用 PSRAM 和 OTA；未接 4G、以太网时保持默认关闭（可在功能配置页按需启用），BLE不在正式环境中启用，定制路径需单独验证。
-DFASTBEE_USE_PSRAM=1
-DBOARD_HAS_PSRAM
-DFASTBEE_ENABLE_BLE=0提示：带 PSRAM 的设备更适合 mqtts。固件会优先把符合条件的较大 TLS 分配放入 PSRAM，但 WiFi、lwIP 和部分 TLS 数据仍占用内部 DRAM；是否可用应以 MQTTS 准入检查和实际连接状态为准。
资源上限参考
| 参数 | esp32c3/c6-F4R0 | esp32-F4R0 | esp32s3 系列（PSRAM） |
|---|---|---|---|
| 最大外设数 | 16 | 24 | 32 |
| 推荐执行规则数 | 12 | 16 | 32 |
| 传感器缓存条目 | 16 | 24 | 32 |
| TCP 并发预算 | 4 | 6 | 8 |
| SSE 连接预算 | 1 | 1 | 2 |
| HTTP 连接预算 | 3 | 5 | 6 |
| TCP 耗尽阈值 | 10 | 12 | 14 |
| MQTT 命令队列上限 | 4096B | 4096B | 4096B |
| Modbus 缓冲池 | 4 槽 | 4 槽 | 8 槽（PSRAM） |
配置检查清单
- 确认硬件实际连接了哪些外设模块。
- 确认需要的联网方式：WiFi、以太网或 4G。
- 确认协议需求：MQTT 通常保留，Modbus 按需开启（TCP/HTTP/CoAP 客户端已移除）。
- 4MB正式环境关闭OTA；无PSRAM不是OTA的统一禁止条件（需双 app 分区；无 PSRAM 的 4MB 环境已在 env 段显式关闭）。
- 有 PSRAM 的环境才启用
FASTBEE_USE_PSRAM=1和BOARD_HAS_PSRAM。 - 未连接的外设、网络模块和管理功能默认关闭。
- 需要 BLE 时同步确认依赖、源码入口、Web/API 能力、配网流程和资源验证；当前设备端默认使用 WiFi AP/Web 配网。
- unified 全量固件交付前，通过 Web 功能配置页面确认实际硬件用不到的模块已关闭；运行期开关不缩小已构建固件。关闭后的RAM变化须等待实例完成退出或所需重启，再按同条件测量；Flash差异须在符合候选功能要求的构建中通过map/bin核实，不能将页面估算当作实际Flash回收。
- 修改后使用带锁的
npm run test:firmware -- <环境名>等入口，检查实际BIN容量、map及RAM/Flash，不仅查看程序统计值。 - 获准现场验收后按资源实测与物理验收记录保存原始响应：内部DRAM取
/api/system/status的data.memory.dram8Free/dram8Largest（B），分池内存取完整/api/system/info?full=1的data.memory.capabilityPools，运行资源取/api/peripherals/resources的data.runtime。裸/api/system/info默认精简，显式full仍可能因内存保护降级；缺失字段保留未知，不能用总heap、PSRAM余量或0替代。 - 无 PSRAM 设备如需加密通信，评估是否改用外部 TLS 代理或 VPN，而非设备端 mqtts。