设备配置

概述: 设备配置管理设备基本信息和系统级设置,包括设备名称、固件信息、NTP 时间同步、调试选项等。配置文件存储在 LittleFS 的 /config/device.json 中,支持通过 Web 界面或 API 修改,也可通过配置导入/导出功能批量备份和恢复。

功能说明

设备配置页面用于管理设备的基本信息和系统级设置，包括设备名称、固件信息、NTP时间同步、调试选项等。

设备配置页面

页面中的基础配置用于维护设备身份和时间同步；涉及外设新增、删除、编辑的现场保护项集中在“高级配置”中。

操作指南

1. 进入 Web 界面 → 设备配置
2. 修改需要的配置项
3. 点击 保存 应用更改
4. 部分配置修改后需重启设备生效

参数说明

配置项	说明	默认值
设备名称	设备显示名称，用于 MQTT 和 Web 标识	FastBee-Device
设备ID	设备唯一标识符（不可修改）	自动生成
NTP 服务器	时间同步服务器地址	ntp.aliyun.com
时区	时区偏移（小时）	8（UTC+8）
日志级别	系统日志输出级别	INFO
自动重启	内存不足时自动重启	启用
重启阈值	触发自动重启的最低内存（字节）	30000
开发环境功能	控制外设配置、外设执行、Modbus 子设备的新增/删除/编辑/映射入口	启用

高级配置：开发环境功能

设备配置的“高级配置”页提供“开发环境功能”开关，默认启用。禁用或重新启用时需要输入当前登录用户的登录密码，用于避免现场误操作。

禁用后：

• 外设配置中的新增、编辑、删除、启用/禁用按钮不可用。
• 外设执行中的新增、编辑、删除、启用/禁用按钮不可用；执行一次保留可用。
• Modbus RTU 子设备和采集任务的新增、删除、编辑、寄存器映射以及 Modbus RTU 配置保存不可用。
• 设备监控、传感器读取、Modbus 实时控制、网络配置和普通设备信息查看不受影响。

后端接口也会校验该状态。即使绕过 Web 页面直接调用外设、外设执行或 Modbus RTU 配置写接口，禁用开发环境时也会返回 403。

配置示例

修改设备名称

设备名称会作为 MQTT 客户端ID的一部分，同时显示在 Web 界面标题栏。

NTP 时间配置

设备联网后自动同步时间，用于 Cron 定时任务和日志时间戳。

常用 NTP 服务器：

• ntp.aliyun.com — 阿里云（国内推荐）
• pool.ntp.org — 全球 NTP 池
• time.windows.com — Windows 时间服务

故障排除

| 问题 | 可能原因 | 解决方案 | |------|---------|---------|| | 时间不正确 | NTP 同步失败 | 检查网络连通性和 NTP 服务器地址 | | 配置不保存 | Flash 写入失败 | 检查 LittleFS 文件系统空间 | | 重启循环 | 配置错误 | 使用 AP 模式恢复默认配置 |

---

配置导入导出完整指南

功能位置: Web 界面 → 设备配置 → 高级配置 → 配置导入/导出

支持的配置类型

类型	文件	说明
全部配置包	fastbee-config-*.json	包含多个配置文件的备份包
设备信息	device.json	设备 ID、名称、缓存时间、NTP 等基础信息
网络配置	network.json	STA/AP、静态 IP、mDNS、重连策略
外设配置	peripherals.json	本地 GPIO、UART、I2C、传感器、显示屏等外设
外设执行	periph_exec.json	本地自动化规则、触发条件、动作列表
通信协议	protocol.json	MQTT、Modbus RTU、子设备、映射任务
用户配置	users.json	完整版多用户配置；精简版通常会跳过
角色配置	roles.json	完整版角色权限配置；精简版通常会跳过

提示: 精简版开启 FASTBEE_ENABLE_CONFIG_TRANSFER=1，但关闭多用户、角色、文件管理和 OTA。导入时如果遇到精简版不支持的 users.json、roles.json，后端会按当前编译开关跳过或拒绝，避免破坏单管理员模式。

推荐使用方式

日常备份建议优先按类型导出，尤其是：

• 外设执行规则
• 外设配置
• 通信协议

这样恢复时只覆盖目标模块，风险更低，也更容易在不同设备之间迁移。

完整迁移设备时再选择"全部配置包"。导入全部配置包后建议重启设备，使外设初始化、协议启动和规则调度都从新配置干净加载。

为什么不再使用大文件内联导入

ESP32 Web 服务解析表单时会临时占用 RAM。较大的配置文件如果通过 /api/config/transfer/import 一次性内联上传，容易触发内存不足。

当前版本采用分块上传+流式解析，避免单次内存占用过大。

导入导出步骤

导出配置

1. 进入 设备配置 → 高级配置 → 配置导入/导出
2. 选择导出类型：
   • 全部配置包: 导出所有配置文件
   • 按类型导出: 选择特定配置类型（推荐）
3. 点击 导出，浏览器自动下载 JSON 文件
4. 保存为本地备份

导入配置

1. 进入 设备配置 → 高级配置 → 配置导入/导出
2. 选择导入类型：
   • 全部配置包: 导入完整备份
   • 按类型导入: 选择特定配置类型
3. 点击 选择文件，上传 JSON 文件
4. 系统验证配置格式
5. 点击 导入，配置写入 LittleFS
6. 重启设备使配置生效

配置迁移最佳实践

1. 迁移前备份: 导出当前设备配置
2. 按模块迁移: 优先迁移外设配置、执行规则、协议配置
3. 验证配置: 导入后检查外设是否正常初始化
4. 重启设备: 确保所有模块从新配置加载
5. 测试功能: 验证自动化规则、通信协议是否正常工作

故障排除

| 问题 | 可能原因 | 解决方案 | |------|---------|---------|| | 导入失败 | 配置格式错误 | 检查 JSON 格式是否正确 | | 导入后外设不工作 | 引脚冲突 | 检查引脚分配是否冲突 | | 规则不执行 | 触发器配置错误 | 检查触发器类型和参数 | | 精简版导入失败 | 包含不支持的配置 | 精简版跳过 users.json/roles.json |