简介FlashDB 是一款面向物联网与边缘计算场景的超轻量级嵌入式数据库专为资源受限的MCU产品提供高效可靠的数据存储方案。定位为可移植的数据库源码包适合嵌入式工程师、物联网开发者以及对Flash存储管理有需求的底层技术人员参考学习。包内共751个文件以C/H源码文件为主配合构建脚本、编译配置、Markdown说明文档以及少量原理图与项目工程文件压缩包约7.15MB结构紧凑且便于按需剪裁。内容预览显示已集成STM32F1/F4系列HAL库驱动可直接对接常见ARM Cortex-M平台帮助缩短开发周期。已有1028人学习浏览读者可从中获取完整源码、多平台工程模板以及基础使用示例便于快速移植并验证FlashDB在实际产品中的低占用、长寿命特性。1. FlashDB给物联网设备换一种更耐擦的存数方式FlashDB 这份资源包解决的是物联网设备上最头疼的两件事掉电丢参数以及 Flash 被频繁擦写提前报废。大家普遍以为嵌入式设备存少量数据用文件系统就够了但文件系统在 NOR Flash 上的行为并不理想——改一个小参数要重写整个扇区掉电还可能损坏目录结构。FlashDB 的思路完全不同它直接基于 Flash 物理特性实现键值存储KVDB和时序存储TSDB资源占用极低却能在 STM32F1/F4 这类 MCU 上稳定跑起来。资源包内附带了源码、示例工程和 HAL 适配层适合做边缘采集、参数校准、日志记录等场景的开发者。2. 从 Flash 物理特性看 FlashDB为什么要换个方式存数据2.1 Flash 的三个硬约束读快、写慢、擦除粒度大主控外挂的 Flash 芯片和机械硬盘的存储逻辑完全不一样设计存储方案前必须先接受它的三个硬约束。第一个约束是「写入之前必须擦除」你不能像改内存一样覆盖某个字节只能先把一整块擦成 0xFF再把新值写进去。第二个约束是「擦除粒度远大于写入粒度」一般 NOR Flash 按 256 字节的 page 写入但一次擦除至少是一个 4K 的 sector你想改 4 个字节物理上却要先擦 4096 字节差异接近一千倍。第三个约束是擦除次数有限NOR 主流规格在十万次左右NAND 在一百万次左右如果某个 sector 天天被擦写几个月就能到寿命上限。三个约束叠加起来结论很明确嵌入式存储不能照搬桌面的文件系统逻辑。文件系统要维护目录和元数据每次更新都要反复改写这些结构随机小写的写放大特别严重掉电时元数据正好写到一半整个文件系统可能就认不出来了。FlashDB 这类嵌入式数据库的思路是颠覆性的——它不建目录表而是把数据当作日志顺序追加旧记录通过垃圾回收统一清理。NOR 与 NAND 的典型参数可以作为选型参考很多物联网终端用的是小容量 NOR| 参数 | NOR Flash | NAND Flash | | 读速度 | 快可随机读 | 慢按页读 | | 写粒度 | 约 256B/page | 约 2KB/page | | 擦除粒度 | 4KB/sector | 128KB/block | | 擦除寿命 | 约 10 万次 | 约 100 万次 | | 常见容量 | 1MB 到 64MB | 128MB 以上 |基于这个对比小容量参数存储我一般选 NOR 加 FlashDB大容量文件存储才考虑 NAND 配文件系统。FlashDB 的 KVDB 在 NOR 上的表现尤其稳定因为它把随机小写改写成了顺序大块写正好规避掉 NOR 擦除粒度大的短板。2.2 顺序追加加垃圾回收FlashDB 耐擦写的核心策略FlashDB 的 KVDB 对某个 key 的更新不是把旧数据覆盖掉而是在当前块的末尾追加一条新记录旧记录原地保留但被标记为失效。等到一个 sector 写满后台触发垃圾回收GC把仍然有效的 key 复制到新的 sector然后整块擦除旧 sector。这个过程和 LSM-Tree 在磁盘上的思路一脉相承只是实现被压缩到极小的内存占用里。这样做有两个直接收益。第一物理擦除发生得很整齐每次 GC 都是一整块擦不像文件系统那样为了改一个 key 反复擦同一个 sector。第二宏观上看所有 sector 的磨损速率趋于一致不会出现某一个 sector 提前报废的「单点死亡」。我在 STM32 板子上观察过 GC 行为一个 16KB 分区持续写入时擦除次数是轮流增长的磨损均衡确实在工作不是玄学。需要注意GC 不是免费的。GC 启动时要把有效数据读出来、搬过去、再擦除旧块这个流程会引入一次明显的耗时尖峰。如果分区开得特别大比如 64KBGC 搬移耗时可能到几十毫秒如果你对写入时延有硬性要求分区大并不是好事。我一般把 KVDB 分区控制在 16KB 到 32KB 之间够用就好分区越大 GC 卡顿越明显。2.3 KVDB 内部布局魔数、状态轮转与 GC 触发时机理解 KVDB 的内部布局你才知道分区至少该开多大。KVDB 的每个分区内部按 sector 组织每个 sector 头部有一个状态字段记录它当前处于「空闲」「活跃」还是「待回收」。活跃 sector 写满后FlashDB 不会立刻擦而是先找下一个空闲 sector 继续写整个分区所有 sector 都写满后GC 才被触发选择一个待回收 sector把其中仍有效的 key 搬进当前活跃 sector再执行擦除。这个状态机直接决定了几个关键参数分区至少要有两个 sector 才能跑 GC推荐 4 个以上是为了留出缓冲余量GC 的触发时机不是由时间决定而是由空间决定。所以你观察到某次写入特别慢大概率就是那一刻空间刚好见底GC 被强制启动了。2.4 掉电安全与 CRC 校验FlashDB 敢说「不丢数据」的依据嵌入式设备最常见的故障就是掉电尤其是电池供电的物联网终端。FlashDB 的处理方式是在每条记录后面附带 CRC 校验同时每个 sector 初始化时写入魔数标记。正常写入时记录是完整落盘的如果掉电发生在写入途中Flash 上残留的是一条 CRC 校验不过的半截记录。重启后 FlashDB 扫描分区遇到 CRC 不匹配的记录直接丢弃然后定位到上一条完整记录作为有效值。这就是 KVDB 敢承诺掉电不丢的原因——它不是用了什么高级事务机制而是用「追加加校验加回滚」这个朴素方案把随机小写变成顺序写把数据撕裂问题交给校验去兜底。这一点在实际测试里可以复现反复随机断电几十次读出来的配置要么是新值要么是旧值从来没有出现过逻辑上不可能的中间值。TSDB 的掉电处理更简单因为时序数据本身是追加型掉电丢掉最后几条采样通常可以接受。FlashDB 把 TSDB 做成环形存储旧数据会被新数据覆盖这决定了它适合「近期数据」而不是「永久归档」。如果你要把采样数据长期保留要么定期导出到外部存储要么给 TSDB 分配足够大的分区。原理部分先看到这。搞清楚了「擦除粒度」「GC 搬移」「CRC 回滚」这三个机制下一章的移植步骤你就能看懂每一步在为什么服务。3. 把 FlashDB 移植到 STM32F4从文件清单到 KV 落盘3.1 资源包里到底有什么文件清单与用途先看清楚包里的文件再动手。资源包不是只有 FlashDB 源码还包含一套 STM32F1/F4 的 HAL 适配层文件这部分常被人忽略。文件清单和作用如下| 文件 | 类型 | 在移植中的作用 | | libarm_cortexM4l_math.a / libarm_cortexM4lf_math.a | 预编译数学库 | 提供 DSP 与浮点运算TSDB 做滤波或统计时用到 | | stm32f1xx_hal_i2c.c / stm32f4xx_hal_i2c.c / stm32f4xx_hal_fmpi2c.c | HAL 驱动 | I2C 外设连接传感器或外部存储 | | stm32f1xx_hal_tim.c / stm32f4xx_hal_tim.c | HAL 驱动 | 定时器为 TSDB 提供时间基准与采样节拍 | | flashdb.h / fdb_kvdb.c / fdb_tsdb.c / fdb_utils.c | 数据库源码 | 核心实现需加入工程编译 | | fal.c / fal_flash.c / fal_partition.c | 抽象层源码 | Flash 抽象层向上给 FlashDB 提供统一读写接口 |看到 I2C 和 TIM 的驱动文件不要困惑这不是跑数据库必须引入的而是这套资源包自带的示例工程依赖。FlashDB 本身只依赖 FAL 抽象层你只要把 FAL 的底层回调接到自己的 Flash 驱动上数据库就和具体芯片解耦了。移植的第一步是先把这些文件加进工程。Cortex-M4 的数学库两个都提供是因为工程有带浮点单元和不带浮点单元两个编译选项按你的 MCU 型号选一个不要两个都加进链接否则符号冲突会给你上一课。3.2 分区表怎么配FAL 配置决定数据的物理边界FAL 是这个方案的命门FlashDB 把「哪个地址范围归哪个数据库用」这件事全部交给 FAL 分区表。打开 fal_cfg.h核心就是 FAL_PART_TABLE 这个宏/* fal_cfg.h —— 分区表偏移和长度必须是物理擦除块的整数倍 */ #ifndef _FAL_CFG_H_ #define _FAL_CFG_H_ #define FAL_PART_TABLE_FLASH_DEV_NAME norflash0 #define FAL_PART_TABLE { \ {FAL_PART_MAGIC_WORD, app, norflash0, 0, 0x80000, 0}, \ {FAL_PART_MAGIC_WORD, kvdb, norflash0, 0x80000, 0x4000, 0}, \ {FAL_PART_MAGIC_WORD, tsdb, norflash0, 0x84000, 0x8000, 0}, \ } #endif分区表每一行的字段依次是魔数、分区名、所属 Flash 设备名、起始偏移、分区长度。上面这份配置把 512KB 之后的空间切了两块kvdb 占 16KBtsdb 占 32KB。注意所有偏移和长度都必须按物理擦除块对齐如果 Flash 的 sector 是 4KB那 0x4000、0x8000 都是合法值如果哪一行出现 0x5000 这种非整数倍长度初始化时会出各种奇怪问题。三个分区的职责很清楚app 放固件数据库不碰它kvdb 管配置掉电要保留16KB 能存几百条 KVtsdb 管采样数据环形覆盖需要比 kvdb 更大的空间来缓冲数据。我一般先把采样间隔和单条 blob 大小算清楚再决定 tsdb 的 0x8000 够不够。比如每秒采样一次、每条 8 字节32KB 约能存 4000 条不到一小时长时间采集就得加大分区或降低采样频率。注意改完 fal_cfg.h 要确认宏里的设备名和实际注册的 FAL 设备名完全一致大小写不一样都会初始化失败。3.3 初始化数据库句柄、名字、分区三者对齐工程里新建一个 flashdb_port.c初始化代码如下/* flashdb_port.c —— 初始化 FlashDB返回 0 表示成功 */ #include flashdb.h static fdb_kvdb_t kvdb; /* 配置文件句柄 */ static fdb_tsdb_t tsdb; /* 采样数据句柄 */ int app_flashdb_init(void) { fdb_err_t err; err fdb_kvdb_init(kvdb, app_cfg, kvdb, NULL, NULL); if (err ! FDB_NO_ERROR) { return -1; /* 初始化失败多半是分区名对不上 */ } err fdb_tsdb_init(tsdb, sensor, tsdb, NULL, NULL); if (err ! FDB_NO_ERROR) { return -2; } return 0; }初始化函数各参数是固定的对应关系第一个是句柄第二个是数据库逻辑名第三个必须和 fal_cfg.h 里的分区名一致。这里最容易翻车的是把第二个参数和第三个参数搞混——第二个「app_cfg」会作为标识写进 Flash第三个「kvdb」才是它使用的物理分区。初始化之后FlashDB 会自动扫描分区找到上次留下的标记和有效数据。首次上电分区是空白的它会自己完成格式化并写入初始化标记所以不需要额外做格式化动作。如果初始化返回错误码优先回头查 FAL 设备是否注册而不是怀疑数据库源码有问题。3.4 实际读写KV 覆盖写、默认值兜底、TSDB 追加配置类数据用 KVDB。写校准值、读校准值、带默认值兜底代码是这样的/* 保存校准值把 int16_t 包装成 blob 写入 key bias */ void save_bias(int16_t bias) { struct fdb_blob blob; fdb_blob_make(blob, bias, sizeof(bias)); fdb_kv_set_blob(kvdb, bias, blob); } /* 读取校准值key 不存在就返回 default_val */ int16_t load_bias(int16_t default_val) { int16_t bias default_val; struct fdb_blob blob; fdb_blob_make(blob, bias, sizeof(bias)); fdb_kv_get_blob(kvdb, bias, blob); return *(int16_t *)blob.buf; }fdb_blob_make 把内存块包装成一个 blob。set 时 blob 里是数据源get 时 blob 里的 buffer 是接收容器。注意 get 返回后要读取的是 blob.buf 指向的内存而不是 blob 结构体本身key 不存在时 get 不会改动 bufferdefault_val 自然被保留。这个兜底模式在出厂校准缺失时很实用。采样数据走 TSDB一次追加多个不同通道的 blob/* 追加一组采样电压和温度一次写入自动带时间戳 */ void ts_append_sample(uint16_t mv, int16_t temp) { struct fdb_blob blob[2]; fdb_blob_make(blob[0], mv, sizeof(mv)); fdb_blob_make(blob[1], temp, sizeof(temp)); fdb_tsdb_append(tsdb, blob, 2); }TSDB 同一时刻能追加多个 blob按数组顺序排列读取时按时间顺序回放。它和 KVDB 的语义差异决定了用法KVDB 关心「某个 key 当前的值」TSDB 关心「某个时间段的曲线」两类需求不要混用。混用的代价不是功能出错而是存储效率明显下降GC 会被无谓触发Flash 寿命白白消耗。3.5 裸机与 RTOS 下的集成差异裸机环境下 main 函数里先调 app_flashdb_init()之后任何代码路径里都能直接调 kv_set 或 tsdb_append前提是 Flash 写操作不被中断打断。如果写 Flash 时来了一个高优先级中断而中断服务程序里又访问了同一片 Flash 地址轻则读回错误数据重则卡死在硬件等待状态。所以裸机项目我一般关掉与 Flash 同 bank 的 DMA并在写 Flash 期间用临界区保护。RTOS 环境更要注意一点FlashDB 本身不提供线程安全多任务同时写同一个 kvdb 句柄会互相踩踏。常见做法是设置一个专管配置写入的任务其他任务通过消息队列把更新请求发给它读取操作相对安全可以随意但写操作一定要串行化。我见过有人直接在中断里调 kv_set结果 GC 一触发就死机后来改成消息队列才稳定。4. 避坑与常见问题FlashDB 移植中的 5 个真实踩坑记录移植 FlashDB 的坑大多数不在数据库本身而在它和 Flash 硬件特性的交界处。下面 5 个坑是在 STM32F1/F4 上调这套资源包时真实遇到过的每一条按「现象 → 原因 → 解决」展开你在自己的板子上遇到类似症状可以直接对号入座。4.1 现象初始化返回错误码程序进 while(1)第一次上电fdb_kvdb_init 返回非零错误码程序停在初始化代码串口看不到任何分区信息。原因FAL 的设备没有注册。FlashDB 通过 FAL 操作 Flashfal_cfg.h 里写了设备名 norflash0但底层没有把对应的 read/write/erase 回调挂到这个名字上所有读写操作等于调用空指针。解决先单独调 FAL。写一个测试函数直接调用 fal_partition_find(kvdb)再用 fal_partition_read 读回原始字节能正常读回来再初始化 FlashDB。这一步能过滤掉一半以上的移植问题跳过它就是在浪费时间。4.2 现象写入几十条后提示分区满但空间还剩一半连续 kv_set 都正常突然某一次返回「分区已满」错误查 FAL 剩余空间还有约一半。原因分区长度没有按物理 sector 对齐。比如 Flash 的 sector 是 4KB你给 kvdb 分了 0x500020KB最后一个 4KB 块对数据库来说不可用可用空间比预期少了一整块GC 计算容量时因此出现偏差。解决打开数据手册确认擦除粒度再把 fal_cfg.h 里所有分区长度改成该粒度的整数倍。4KB 粒度下推荐 0x4000、0x8000、0xC000 这类对齐值不要拍脑袋写个 0x5000 进去。4.3 现象随机断电后读出的是旧值但不是更早的那一版做掉电测试时读回的配置偶尔既不是最新值也不是出厂值而是某个中间版本的数据。原因blob 里混进了栈上的未初始化字节。局部结构体没完全赋值就丢给 fdb_blob_makeCRC 计算时和落盘时看到的内容不一致掉电后校验虽然通过了但读到的是语义上不完整的数据。解决写操作前把源数据用 memset 清零或者只把有效字段打包成 blob。不要图省事直接把整个结构体指针传给 fdb_blob_make除非你确认过结构体没有 padding 垃圾字节。4.4 现象在线调试单步时Flash 写入总是失败接上在线调试器单步跟到 kv_set 就返回错误再读 Flash 全是 0xFF。原因调试器的内存访问和 Flash 控制器的擦写操作并发执行把硬件状态机打乱了。Flash 擦写期间任何总线访问都可能中断操作这是在线调试的固有限制。解决写 Flash 的代码段不要单步进入。在 kv_set 外层打断点断点停下后再放行批量写入测试时关掉调试器的实时内存监视只保留串口日志输出问题立刻消失。4.5 现象GC 触发时系统卡顿实时任务掉线持续写入一段时间后某次 kv_set 或 tsdb_append 耗时特别长实测超过 50msRTOS 里的实时任务错过 deadline。原因GC 在搬移有效数据分区越大单次搬移的块越多这个耗时是物理性的不是调度配置能解决的。解决把 KVDB 分区控制在 4 到 8 个 sector。对实时性要求高的采样数据走 TSDBTSDB 的环形写不会频繁触发全量搬移GC 压力小得多。另外把采样写入放到低优先级任务里让高优先级任务不被 GC 拖住。5. 验证与进阶用老化测试摸清 FlashDB 的寿命边界5.1 KVDB 与 TSDB 的选型边界调通之后下一步是确认你的分区配置是否合理。选型边界一张表就能说清| 维度 | KVDB | TSDB | | 数据模型 | key-value 覆盖写 | 时间序列追加写 | | 典型场景 | 校准值、设备编号、OTA 标志 | 温度曲线、电压采样 | | 查询方式 | 按 key 读当前值 | 按时间范围回放 | | 空间回收 | GC 搬移有效 key | 环形覆盖旧数据 | | 分区建议 | 16KB 起步 | 32KB 起步 |判断规则很简单变量是「状态」用 KVDB变量是「过程」用 TSDB。设备编号、校准参数、开关状态都是状态传感器曲线、电耗记录、运行日志都是过程。混用不是不能跑但存储效率很差GC 会被无谓触发。5.2 连续写测试与寿命预估老化测试是验证寿命设计的最直接手段。写一段连续写脚本统计总耗时和写入字节数/* 老化测试连续写入 rounds 次统计总耗时与写入量 */ void wear_test(uint32_t rounds) { uint32_t i, tick HAL_GetTick(); for (i 0; i rounds; i) { fdb_kv_set(kvdb, cnt, i, sizeof(i)); } uint32_t cost HAL_GetTick() - tick; uint64_t bytes (uint64_t)rounds * (4 32); printf(write %llu bytes in %u ms\r\n, bytes, cost); }每条 KV 约 4 字节负载加 32 字节元数据开销把测试总字节数乘 2 估算写放大就能换算出擦除次数。16KB 分区、每天写入 13 万字节对应约每年 2900 次擦除NOR 十万次寿命足够跑三十年采样频率提高十倍就要加大分区或缩短数据保存周期。测试时打开 GC 触发日志观察耗时尖峰是否集中在搬移段若频繁覆盖多个 key 导致搬移量大、GC 耗时异常说明存储策略需要调整。从那以后我每次移植 FlashDB 都强制走一遍「分区对齐、裸调 FAL、初始化、老化测试」四步流程确认 GC 曲线正常才敢把固件发出去量产。这套验证流程希望帮到你尤其是第一次接触 FlashDB 的时候。本文还有配套的精品资源点击获取
