部署、烧录与测试

本文把 FastBee-Arduino 从在线烧录、源码构建、打包发布到真实设备验证的关键命令放在一处，适合开发调试、现场部署、发布打包和量产前核对。第一次体验可直接看 快速开始，浏览器烧录可直接打开 在线烧录工具。

参考来源：源码仓库 FastBee-Arduino 和当前设备端发布脚本说明。

流程总览

固件与环境选择

先按硬件选择 PlatformIO 环境，避免固件与 Flash/PSRAM 不匹配。

环境	档位	芯片	Flash / PSRAM	适用场景
esp32c3-F4R0	Lite	ESP32-C3	4MB / 无	低成本 WiFi/MQTT 节点
esp32c6-F4R0	Lite	ESP32-C6	4MB / 无	WiFi 6 低成本节点
esp32-F4R0	Standard	ESP32	4MB / 无	普通 ESP32 开发板
esp32s3-F8R0	Standard+OTA	ESP32-S3	8MB / 无	S3 8MB 模组，保留 OTA
esp32-F8R4	Full	ESP32	8MB / 4MB	ESP32-WROVER 或带 PSRAM 模块
esp32s3-F8R4	Full	ESP32-S3	8MB / 4MB	ESP32-S3 N8R4
esp32s3-F16R8	Full	ESP32-S3	16MB / 8MB	完整功能、长稳和发布推荐

文件名中的 F 表示 Flash 容量，R 表示 PSRAM 容量。功能差异详见 版本对比指南，构建开关详见 构建配置。

在线烧录

普通体验和现场快速恢复优先使用 在线烧录工具。内置固件是合并镜像，包含 bootloader、分区表、应用固件和 LittleFS Web 文件系统，烧录地址固定为 0x0。

1. 使用 Chrome 或 Edge 打开在线烧录工具。
2. 连接 ESP32 开发板并选择串口。
3. 选择与芯片、Flash、PSRAM 匹配的内置固件。
4. 地址保持 0x0，点击烧录并等待自动复位。

合并固件已经包含所有分区，无需再分别烧录其他文件。默认外设和执行规则都是安全模板，首次接线请先确认引脚和供电。

如果烧录后页面异常，先确认固件档位与硬件一致；切换分区表或旧配置异常时可先擦除整片 Flash 再重新烧录。

从源码部署

开发调试推荐使用统一部署脚本。脚本会先检查环境，若 data/www/*.gz 不存在则自动调用 node scripts/gzip-www.js 生成 Web 资源，再构建并上传当前环境对应的 LittleFS Web 文件系统和固件。脚本支持 Windows、Linux 和 macOS（后两者需安装 PowerShell Core）。

# Windows
cd D:\project\gitee\FastBee-Arduino
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32-F4R0 -Port COM6

# Linux / macOS（需安装 pwsh）
pwsh -File scripts/deploy.ps1 -Env esp32-F4R0 -Port /dev/ttyUSB0

常用部署命令：

# ESP32 标准版
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32-F4R0 -Port COM6

# ESP32-S3 16MB + 8MB PSRAM 全功能版
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6

# 只构建，不烧录
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -BuildOnly

# 部署后打开串口监视器
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -Monitor

# 显示完整编译输出，用于排查编译失败
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -FullOutput

分开部署时使用：

# 只更新 LittleFS Web 文件系统
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -SkipFirmware

# 只更新应用固件
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F16R8 -Port COM6 -SkipFs

deploy.ps1 适合日常使用。需要直接调用 PlatformIO 时，可使用以下兜底命令：

# 编译
pio run -e esp32s3-F16R8

# 上传应用固件
pio run -e esp32s3-F16R8 -t upload --upload-port COM6

# 上传 LittleFS
pio run -e esp32s3-F16R8 -t uploadfs --upload-port COM6

# 串口监视
pio device monitor --port COM6 --baud 115200

打包发布产物

准备交付或量产烧录包时，生成所有环境的发布产物：

powershell -ExecutionPolicy Bypass -File scripts\build-all-artifacts.ps1 -CleanOutput

重点检查输出目录：

dist/business/firmware/all-latest/
├── fastbee-esp32-F4R0.bin
├── fastbee-esp32-F8R4.bin
├── fastbee-esp32c3-F4R0.bin
├── fastbee-esp32c6-F4R0.bin
├── fastbee-esp32s3-F8R0.bin
├── fastbee-esp32s3-F8R4.bin
├── fastbee-esp32s3-F16R8.bin
└── manifest.json

这些 .bin 是合并固件，适合在线烧录工具、flash-release.ps1、esptool.py 或量产烧录工具使用。发布前必须核对 manifest.json 中的环境、文件大小和 SHA-256。

直接烧录发布包

已生成发布包后，可以跳过本地编译，直接写入合并固件：

# 推荐封装脚本，会按 Env 找到 dist/business/firmware/all-latest 中的合并固件
powershell -ExecutionPolicy Bypass -File scripts\flash-release.ps1 -Env esp32s3-F16R8 -Port COM6

# 预览命令，不实际烧录
powershell -ExecutionPolicy Bypass -File scripts\flash-release.ps1 -Env esp32s3-F16R8 -Port COM6 -DryRun

也可以直接使用 esptool.py：

# 可选：切换分区表或旧配置异常时先擦除
esptool.py --chip auto --port COM6 erase_flash

# 从 0x0 写入合并固件
esptool.py --chip auto --port COM6 --baud 921600 write_flash -z 0x0 dist\firmware\all-latest\fastbee-esp32s3-F16R8.bin

首次访问与部署验证

设备首次启动或 WiFi 未配置时会进入 AP 模式。

项目	默认值
WiFi 热点	fastbee-ap
浏览器地址	http://192.168.4.1 或 http://fastbee.local
用户名	admin
密码	admin123

烧录完成后按以下顺序验证：

1. 登录 Web 控制台，确认仪表盘能显示运行时间、Heap、Flash 和网络状态。
2. 在网络配置页配置 WiFi、以太网或 4G，并确认重新上线。
3. 配置 MQTT 或 Modbus，确认协议状态正常。
4. 添加一个实际接线的外设，先禁用保存，再单项启用验证。
5. 新增一条简单外设执行规则，先手动执行，再启用自动触发。
6. 导出配置、保留截图、串口日志和发布包 manifest.json。

部署后仪表盘检查

默认外设模板和执行规则都应保持出厂禁用。现场接线确认前不要启用继电器、电机、Modbus 写入、系统重启或 OTA 等强动作。

测试分层

测试分层从低成本到高真实性逐层推进；日常开发优先跑底层，发布验收必须覆盖真机和长稳层。

层级	命令入口	覆盖内容	何时执行
静态检查	scripts\test-all.ps1 -Checks static	UTF-8、测试注册、API 矩阵、构建矩阵、文档链接、默认配置安全性、i18n、Web 静态资源、Git 空白检查	每次提交前
native 单元测试	scripts\test-all.ps1 -Checks native	host 侧 C++ 单元测试（含 CommandBus、ErrorHandler、OTA、RuleScript、Batch/SSE、PeriphExec）	修改核心逻辑/API/配置解析时
全版本编译	scripts\test-all.ps1 -Checks build	7 个发布环境：ESP32、ESP32-C3、ESP32-C6、ESP32-S3 的 Lite/Standard/Full 档位	每次影响固件或编译开关时
发布产物	scripts\test-all.ps1 -Checks artifacts	合并固件、LittleFS、manifest.json	准备发布或交付烧录包时
设备冒烟	scripts\test-all.ps1 -Checks device-smoke	登录、系统、版本能力、网络、设备配置、协议、MQTT、外设、外设执行、日志/文件/OTA/用户角色等 API	烧录真实设备后
设备稳定性	scripts\test-all.ps1 -Checks device-soak	多轮 API 循环、版本能力、低内存保护、认证稳定性和响应耗时	关键改动后和发布前
浏览器快速	scripts\test-all.ps1 -Checks browser-quick	~62 个 @quick 标记核心用例：登录/仪表盘/网络/MQTT/外设/规则	日常开发和固件冒烟
浏览器完整	scripts\test-all.ps1 -Checks browser	273 个全量 Playwright 用例：所有页面交互和边界场景	发布前完整回归

版本矩阵

PlatformIO 环境	芯片/硬件	版本档位	必跑检查
esp32c3-F4R0	ESP32-C3 4MB Flash	lite	static、build、lite 设备冒烟
esp32c6-F4R0	ESP32-C6 4MB Flash	lite	static、build、lite 设备冒烟
esp32-F4R0	ESP32 4MB Flash	standard	static、native、build、standard 设备冒烟
esp32s3-F8R0	ESP32-S3 8MB Flash	standard	static、native、build、standard 设备冒烟
esp32-F8R4	ESP32 8MB Flash + 4MB PSRAM	full	static、build、full 设备冒烟
esp32s3-F8R4	ESP32-S3 8MB Flash + 4MB PSRAM	full	static、build、full 设备冒烟
esp32s3-F16R8	ESP32-S3 16MB Flash + 8MB PSRAM	full	static、native、build、artifacts、full 设备冒烟和稳定性测试

4MB 环境使用 fastbee.csv 且不支持 OTA；8MB 环境使用 fastbee-8MB.csv 并提供 OTA 双分区；16MB 环境使用 fastbee-16MB.csv，适合 Full 长稳和文件/日志功能。

常用测试命令

所有测试的统一入口是 scripts\test-all.ps1，通过 -Checks 指定检查项，支持多项组合。

# 快速提交前检查（静态 + 构建）
powershell -ExecutionPolicy Bypass -Command ".\scripts\test-all.ps1 -Checks static,build"

# 完整本地矩阵，不访问真实设备
powershell -ExecutionPolicy Bypass -Command ".\scripts\test-all.ps1 -Checks static,native,build,artifacts"

# 真实设备 API 冒烟测试
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks device-smoke -BaseUrl http://192.168.5.116 -DeviceProfile full

# 真实设备长期稳定性测试，输出 CSV 到 .pio/test-results
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks device-soak -BaseUrl http://192.168.5.116 -DeviceProfile full -SoakRounds 100

# 快速浏览器测试（日常开发推荐）
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks browser-quick -BaseUrl http://192.168.5.116 -DeviceProfile full

# 完整浏览器测试（发布前回归）
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks browser -BaseUrl http://192.168.5.116 -DeviceProfile full

# 一次跑多项检查
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks static,build,device-smoke,browser-quick -BaseUrl http://192.168.5.116 -DeviceProfile full

-Checks 可选值

值	说明	是否需要设备参数
static	静态检查：UTF-8、测试注册、API 矩阵、构建矩阵、文档链接、默认配置安全性、i18n、Web 静态资源、Git 空白	否
native	Host 侧 C++ 单元测试（CommandBus、ErrorHandler、OTA、RuleScript、Batch/SSE、PeriphExec）	否
build	7 个发布环境全版本编译（ESP32/C3/C6/S3 的 Lite/Standard/Full）	否
artifacts	生成合并固件、LittleFS、manifest.json 发布产物	否
device-smoke	设备 API 冒烟：登录、系统、能力、网络、设备、协议、MQTT、外设、日志/文件/OTA/用户	是
device-soak	设备长稳：多轮 API 循环、低内存保护、认证稳定性、响应耗时	是
browser-quick	62 个 @quick 标记核心用例：登录/仪表盘/网络/MQTT/外设/规则	是
browser	273 个全量 Playwright 用例：所有页面交互和边界场景	是
all	运行全部检查项（等同于上面所有值）	是

-BaseUrl 和 -DeviceProfile 在访问真实设备的检查项（device-smoke、device-soak、browser-quick、browser）中必须传入，否则会因无法连接设备而报错。

常用参数

参数	默认值	说明
-Checks	static,native,build	要执行的检查项，支持多项
-BaseUrl	http://192.168.4.1	设备 Web 地址（AP 或 STA）
-DeviceProfile	full	设备能力档位：lite/standard/full
-Username / -Password	admin / admin123	Web 登录凭据
-SoakRounds	10	长稳测试循环次数
-Environments	全部 7 个	指定要编译的 PlatformIO 环境
-ContinueOnError	false	某项失败后继续执行后续检查
-DeviceSerial	空	浏览器测试时指定串口（用于设备预检）
-BrowserHeaded	false	浏览器测试显示窗口（调试用）
-ReportDir	.pio\test-results	长稳 CSV 报告输出目录
-RequireNetworkConnected	false	冒烟测试要求设备已联网
-RequireMqttConnected	false	冒烟测试要求 MQTT 已连接

如果本地 Windows 环境缺少 gcc/g++，native 会失败。这不是固件编译失败，需要先安装 MinGW/MSYS2 或在 CI/Linux 环境执行 native 测试。

-DeviceProfile 必须与固件档位匹配：Lite、Standard、Full 的 API 能力不同，档位写错会把正常的裁剪接口误判为失败。

浏览器自动化测试

浏览器测试使用 Playwright 自动操作设备 Web 控制台，覆盖登录、仪表盘、网络/设备/MQTT 配置、外设管理、规则脚本、日志/文件/用户等页面交互场景。

快速 vs 完整测试

模式	配置文件	用例数	预估时间	适用场景
快速 (browser-quick)	playwright.quick.config.ts	62	~22 分钟	开发阶段快速验证、CI 快速回归、固件冒烟
完整 (browser)	playwright.config.ts	273	30-37 分钟	发布前完整验收、深度回归测试

快速测试通过 @quick 标签从每个 spec 文件中筛选核心用例，覆盖认证、仪表盘、网络配置、设备信息、MQTT 通信、外设 CRUD、规则脚本、日志/文件/用户管理等关键路径。

Playwright 直连运行

不经过 test-all.ps1，直接调用 Playwright 可以获得更细粒度的控制：

cd test\browser
$env:DEVICE_IP = "192.168.5.116"

# 运行快速 / 完整测试
npx playwright test -c playwright.quick.config.ts        # 快速
npx playwright test                                       # 完整

# 运行指定测试
npx playwright test -g "AUTH-001"                        # 按名称过滤
npx playwright test -g "@quick" --project=smoke           # 组合过滤

# 查看 HTML 报告
npx playwright show-report reports\quick-html             # 快速测试
npx playwright show-report reports\html                   # 完整测试

测试时间对比报告

运行快速测试后，执行对比脚本查看与上次完整测试的时间差异：

node scripts\compare-test-timing.js

输出包含总时间、每文件耗时分解、Top 10 最慢用例和加速倍数。

@quick 标签维护

核心测试用例标题中包含 @quick 标签，quick 配置通过 --grep @quick 过滤：

test('AUTH-001: 正确凭证登录 @quick', async ({ page }) => { ... });

新增测试时，判断是否加入快速集：

• 覆盖核心用户路径（登录、配置保存、协议连接）→ 加 @quick
• 边界值、异常场景、详细表单字段验证 → 仅完整测试

进度显示

两种模式都使用 list reporter 实时显示每个测试的通过/失败状态和耗时。快速测试无重试（retries: 0），失败立即报告，适合快速定位问题。

设备冒烟覆盖

设备 API 测试共用 scripts\device-api-test-matrix.json。执行冒烟测试时，失败项应立刻记录首个失败接口，首个失败通常最接近根因。

类别	检查项
认证	登录、Bearer Token 优先级、多会话登录
系统	/api/health、/api/system/health、/api/system/info、/api/system/status、/api/system/web-runtime、/api/system/capabilities
系统指标	/api/system/metrics、heap、memguard、运行时指标
网络	/api/network/status、/api/network/config、连接状态、IP、联网类型、AP/STA 配置
设备	/api/device/config、/api/device/info、/api/device/time
通信	MQTT 状态、MQTT 配置、协议紧凑配置、Standard/Full 的 Modbus 状态
外设	外设列表、外设类型、参数缺失错误、执行规则、执行控件、触发器、静态/动态事件、事件分类、批量 API
版本能力	lite、standard、full 的 capability 开关语义
全功能版	文件系统、根目录文件列表、日志、OTA、RuleScript、用户、角色、权限
版本边界	Lite/Standard 下 Modbus 或 Full-only 接口应返回合理不可用状态

新增或调整 API 时，先更新 device-api-test-matrix.json，再执行 smoke/soak，确保裁剪行为和状态码都符合预期。

三版本稳定性验收底线

Lite、Standard、Full 的功能范围可以不同，但长期运行底线必须一致。发布前至少确认：

验收项	Lite	Standard	Full
上电自动启动	必须通过	必须通过	必须通过
WiFi/AP 配网可用	必须通过	必须通过	必须通过
网络恢复后自动重连	必须通过	必须通过	必须通过
MQTT 恢复后自动重连	必须通过	必须通过	必须通过
配置异常保护	必须通过	必须通过	必须通过
看门狗/健康监控	必须通过	必须通过	必须通过
关键日志或故障码	基础覆盖	完整覆盖	完整覆盖
OTA	不要求	可选	必须通过
远程配置	基础 API	常用配置	完整配置与文件能力
长稳测试	至少 72 小时	至少 72 小时，建议 7 天	至少 7 天

冒烟测试清单

冒烟测试用于判断当前固件是否具备继续功能测试和交付验证的条件。任一必测项失败，都不应进入长稳测试。

编号	测试项	Lite	Standard	Full	通过标准
SMK-01	全版本编译	必测	必测	必测	对应 PlatformIO 环境无编译错误
SMK-02	固件烧录	必测	必测	必测	串口烧录完成，设备自动重启
SMK-03	上电启动	必测	必测	必测	串口出现启动日志，无异常重启
SMK-04	文件系统挂载	必测	必测	必测	/config/*.json 可读取，默认配置有效
SMK-05	AP/STA 网络	必测	必测	必测	AP 可访问，STA 配网后有 IP
SMK-06	Web/API 健康检查	必测	必测	必测	/api/health 或 /api/system/health 返回正常
SMK-07	版本能力识别	必测	必测	必测	/api/system/capabilities 与固件档位一致
SMK-08	MQTT 连接	必测	必测	必测	MQTT 状态为 connected，平台可见在线
SMK-09	数据上报一条	必测	必测	必测	平台收到属性或事件数据
SMK-10	命令下发一条	建议	必测	必测	设备执行命令并返回结果
SMK-11	重启恢复	必测	必测	必测	重启后自动恢复网络、协议和配置
SMK-12	Modbus 状态	不测	必测	必测	配置启用后状态与轮询结果正常
SMK-13	OTA 状态入口	不测	可选	必测	/api/ota/status 返回状态，能力开关符合预期
SMK-14	日志/文件/用户角色	不测	可选	必测	Full-only 接口可用，非 Full 返回合理状态

推荐命令（统一入口详见 常用测试命令）：

# 静态 + 构建检查
powershell -ExecutionPolicy Bypass -Command ".\scripts\test-all.ps1 -Checks static,build"

# 设备冒烟（要求网络和 MQTT 已连接）
powershell -ExecutionPolicy Bypass -File scripts\test-all.ps1 -Checks device-smoke -BaseUrl http://192.168.5.116 -DeviceProfile full -RequireNetworkConnected -RequireMqttConnected

功能测试用例矩阵

功能测试按模块验证完整业务行为。新增外设、协议、接口或版本裁剪开关时，应同步补充用例。

编号	模块	用例	Lite	Standard	Full	预期结果
FUN-01	启动初始化	首次启动、默认配置、AP 配网入口	必测	必测	必测	默认配置可加载，AP/Web/API 可访问
FUN-02	网络配置	WiFi SSID/密码保存与重连	必测	必测	必测	保存后重启仍能联网
FUN-03	网络配置	静态 IP/DHCP 切换	可选	必测	必测	状态页显示正确 IP 和模式
FUN-04	设备配置	设备名、时区、基础参数修改	必测	必测	必测	参数校验、保存和重启恢复正常
FUN-05	MQTT	连接、订阅、发布、遗嘱消息	必测	必测	必测	平台在线状态和消息流正确
FUN-06	数据采集	GPIO/ADC/基础传感器读取	必测	必测	必测	数据格式正确，无异常阻塞
FUN-07	外设执行	定时触发、事件触发、平台触发	建议	必测	必测	条件判断和动作执行符合配置
FUN-08	Modbus	从站扫描、寄存器轮询、控制指令	不测	必测	必测	轮询稳定，异常从站不阻塞主循环
FUN-09	Web/API	登录、Bearer Token、多会话	必测	必测	必测	权限与会话状态符合预期
FUN-10	文件/日志	日志查看、文件列表、配置导入导出	不测	可选	必测	Full 版本可用，低内存时可降级
FUN-11	用户角色	用户、角色、权限边界	不测	可选	必测	未授权访问被拒绝
FUN-12	RuleScript	脚本保存、执行、异常脚本处理	不测	可选	必测	失败不影响主循环
FUN-13	OTA	固件上传、URL 升级、状态查询	不测	可选	必测	升级成功后版本正确
FUN-14	远程配置	增量配置、非法字段、重启生效	基础	必测	必测	非法配置不覆盖旧配置
FUN-15	边界值	空配置、超长字段、非法 JSON	必测	必测	必测	返回错误码，不崩溃
FUN-16	资源保护	低内存、并发 API、SSE 降级	必测	必测	必测	返回合理状态，系统继续运行

发布前清单

1. 执行 scripts\test-all.ps1 -Checks static,native,build,artifacts。
2. 分别烧录目标芯片，并确认 deploy.ps1 的 -Env 与芯片版本一致。
3. 执行 node scripts\validate-config-defaults.js --staging-root .pio\fs-staging --latest-only。
4. 确认默认 peripherals.json 外设模板和 periph_exec.json 规则没有出厂启用。
5. 对每个实际交付版本执行一次设备冒烟测试（-Checks device-smoke）。
6. 执行快速浏览器测试（-Checks browser-quick），确认核心页面交互正常。
7. 对 esp32s3-F16R8 或包含日志/文件/用户角色的版本执行至少 100 轮 soak。
8. 检查 /api/system/info 的 heap、maxAlloc、PSRAM 和功能档位是否符合预期。
9. 检查 Web 页面：登录、网络设置、通信协议、外设配置、外设执行、日志、文件、用户、角色、RuleScript。
10. 生成发布产物并核对 dist\firmware\all-latest\manifest.json。

断网重连测试

断网重连测试重点验证无人值守现场的自动恢复能力。所有版本都必须执行，Full 版本还要覆盖以太网或 4G 等已启用网络方式。

编号	场景	操作步骤	通过标准
NET-01	启动前无网络	断开路由器或输入不可用 SSID 后上电	设备保持 AP/Web 可访问，不死机，不频繁重启
NET-02	运行中断开 WiFi	设备在线后关闭路由器 5 分钟	日志记录断线，主循环继续运行，MQTT 不阻塞
NET-03	网络恢复	恢复路由器或信号	设备自动获取 IP，MQTT 自动重连，平台重新在线
NET-04	MQTT 服务不可达	停止 broker 或阻断端口	设备进入退避重连，不影响本地 Web 和外设执行
NET-05	DNS 解析失败	配置错误域名或阻断 DNS	返回连接失败状态，恢复 DNS 后自动连接
NET-06	弱网/高延迟	增加丢包或限速	请求超时可恢复，无内存持续下降
NET-07	网络类型切换	WiFi/以太网/4G 按配置切换	/api/network/status 与 MQTT Client 类型一致

验收指标：网络恢复后 3 分钟内自动上线；断网期间不进入无限重启；MQTT 重连后至少完成一次属性或状态上报；heapFree 和 heapMaxAlloc 不持续恶化。

掉电恢复测试

掉电恢复测试用于验证配置保护、文件系统一致性和升级失败保护。执行掉电测试前先备份现场配置。

编号	场景	操作步骤	通过标准
PWR-01	普通运行中掉电	设备稳定在线后直接断电，再上电	配置不丢失，设备自动恢复在线
PWR-02	数据上报中掉电	连续上报时断电	重启后主循环、MQTT 和外设状态正常
PWR-03	配置保存中掉电	修改网络/设备/协议配置时断电	旧配置或新配置至少有一个可用，不出现损坏 JSON
PWR-04	文件系统更新中掉电	导入配置或更新 LittleFS 时断电	文件系统可挂载，异常文件可重新写入
PWR-05	OTA 上传中掉电	Full 版本升级上传中断电	重启后旧固件仍可启动或进入可恢复状态
PWR-06	OTA 校验失败	上传错误包或错误 SHA-256	升级中止，返回 ERR_OTA_VERIFY_FAILED 或等价状态
PWR-07	高频重启	连续上电/断电 10 次	无配置丢失、无启动卡死、无异常 Flash 写入

长稳测试报告模板

长稳测试建议每个版本单独出报告。Lite 至少 72 小时；Standard 至少 72 小时，建议 7 天；Full 至少 7 天。报告要保留趋势判断：最小 heapFree、最小 heapMaxAlloc、失败率和首次失败前后的接口耗时。

项目名称：FastBee-Arduino 嵌入式物联网软件系统
测试类型：长稳测试
测试版本：
版本档位：Lite / Standard / Full
PlatformIO 环境：
硬件型号：
Flash/PSRAM：
固件 SHA-256：
LittleFS SHA-256：
测试地点/网络环境：
平台/Broker 地址：
测试开始时间：
测试结束时间：
累计运行时长：

关键指标：
- 异常重启次数：
- 网络断线次数：
- 自动恢复次数：
- MQTT 断线次数：
- 数据上报总数：
- 数据上报成功率：
- 命令下发总数：
- 命令响应成功率：
- 最小 heapFree：
- 最小 heapMaxAlloc：
- Full 版本 psramTotal/psramFree：
- 低内存保护触发次数：
- OTA 状态检查次数：
- 故障码统计：

结论：
- 通过 / 不通过：
- 遗留问题：
- 发布建议：

推荐稳定性指标：

指标	Lite	Standard	Full
连续运行	>= 72 小时	>= 72 小时，建议 7 天	>= 7 天
异常重启	0 次	0 次	0 次
网络恢复	100% 自动恢复	100% 自动恢复	100% 自动恢复
数据上报成功率	>= 99%	>= 99%	>= 99%
命令响应成功率	>= 98%	>= 99%	>= 99%
内存趋势	不持续下降	不持续下降	heap/PSRAM 均不持续下降

---

常见问题

找不到串口

确认 USB 线支持数据传输，安装 CH340、CP210x 等串口驱动，并关闭 Arduino IDE、PlatformIO Monitor 或其他占用串口的软件。

一直等待同步

部分开发板自动下载电路不稳定。按住 BOOT 后开始烧录，看到写入日志后松开；失败后按 EN / RST 重启再试。

上传后 Web 控制台打不开

优先确认是否上传了 LittleFS。只用 pio run -t upload 会更新应用固件，但不会更新 Web 文件系统；日常部署建议用 deploy.ps1 或先 uploadfs 再 upload。

Full 固件运行不稳定

检查实际硬件是否带 PSRAM，并在 /api/system/info 或启动日志中确认 psramTotal > 0。Full 固件在无 PSRAM 硬件上容易触发低内存保护。

发布包烧录后配置异常

切换不同分区表、不同 Flash 容量或从其它固件迁移时，先擦除整片 Flash，再烧录合并固件。擦除会清空网络、外设和规则配置，现场执行前必须备份。

-DeviceProfile 不匹配

-DeviceProfile 必须匹配固件档位，否则 full-only API 会被误判。浏览器登录问题优先用 smoke 测 Bearer Token，避免陈旧 Cookie 干扰。

native 测试编译失败

Windows 环境缺少 gcc/g++ 时 native 会报编译错误，这不是固件问题。安装 MinGW/MSYS2 或在 CI/Linux 环境执行 native 测试即可。

浏览器测试超时失败

优先检查设备 IP 是否正确（-BaseUrl）、设备是否在线（ping 或访问 Web 页面）。globalSetup 预检会输出设备可达性警告。网络配置变更后设备可能临时不可达，测试内置了 cleanup 恢复逻辑。

浏览器测试结果不一致

同一用例偶尔通过偶尔失败时，检查是否有其它进程占用设备串口或 Web 端口。降低 TEST_DELAY_MS（如 300）可加速但可能增加不稳定性；增大到 800 可提高稳定性。完整测试有自动重试（retries: 2），快速测试无重试（retries: 0）。

soak 测试内存指标持续下降

heapFree 或 heapMaxAlloc 持续下降通常是内存泄漏。先确认固件版本是否已包含 MQTTS 内存优化（memguard 降级机制），再检查 /api/system/metrics 中的 heapMinFree 历史最小值。Full 版本还需关注 psramFree 趋势。