企业官网建设流程全解析

做单片机存数据这件事我前后折腾了快十年，前八年基本都在"凑合"。参数要掉电不丢，就在 Flash 某个固定地址上硬写一个结构体；日志要留几条，就自己划一块区域做环形覆盖；设备序列号、校准系数、运行小时数各写各的，散落在不同的扇区里，谁也管不着谁。直到去年接了一个要长期记录环境数据的项目，样机跑了三个月，参数区读出来全是 0xFF，日志指针也回绕到了不该去的地方——那一刻我才认真去 GitHub 上找现成的轮子。后来锁定的那个开源库叫FlashDB，2.4k Star 上下，嵌入式圈子里做数据落盘的人基本绕不开它。它不是什么黑魔法，但把"存数据"这件事里我一直用裸代码硬扛的脏活——磨损均衡、掉电原子性、容量管理、版本兼容——全都封装到了一层薄薄的 API 后面。

这篇东西不打算写成 API 手册。我想说的是：为什么过去那套"凑合写法"迟早会出事、一个正经的嵌入式存储库到底帮你挡掉了哪些坑、把它移植到 STM32 或国产 32 位单片机上要动哪几个地方、以及我实测中真正踩过的几个坑。不管你现在用的是 51、STC、STM32 还是 RISC-V 的片子，只要涉及"设备断电之后数据还得在"，这里面的思路都能直接用。

1. 那些年我们凑合过的存数据方案，问题都出在哪一环

先把老账翻一遍。不是为了怀旧，是因为不搞清楚这些方案到底哪里漏，你用上了新库也还是会写出错的用法。下面这三种写法，我敢说做单片机的人至少中过一种。

1.1 固定地址直接写：路径最短，命也最短

最经典的写法是这样：在链接脚本或者某块预留区域里挑一个地址，#define PARAM_ADDR 0x0800F000，然后要存参数的时候：

HAL_FLASH_Unlock(); /* 先擦除整页 */ FLASH_EraseInitTypeDef erase = { .TypeErase = FLASH_TYPEERASE_PAGES, .PageAddress = PARAM_ADDR, .NbPages = 1 }; uint32_t err_page; HAL_FLASHEx_Erase(&erase, &err_page); /* 再写入 */ HAL_FLASH_Program(FLASH_TYPEPROGRAM_WORD, PARAM_ADDR, (uint64_t)word); HAL_FLASH_Lock();

这段代码本身没写错，问题在于它的物理代价。片内 Flash 的擦除单位是页或扇区，不是字节。你想改一个标志位，代价是擦掉整个扇区。所以这条路径的擦写次数是 1:1 的——写一次，擦一次。拿 STM32F1 的片内 Flash 来说，官方手册给的擦写寿命是 1 万次量级。1 万次听起来很多，换算一下就不乐观了：设备每 10 分钟保存一次运行状态，就是 10000 × 10 分钟 ≈ 69 天。也就是说，这台设备的参数区寿命连三个月都撑不到，而且它坏得毫无征兆，某一天上电就变成了全0xFF。

还有一个更隐蔽的问题：结构体直写。很多人喜欢定义一个struct直接往 Flash 里丢：

typedef struct { uint8_t magic; float kp; uint32_t run_hours; char sn[16]; } sys_param_t;

看着挺整齐对吧。但sizeof(sys_param_t)会因为编译器不同、对齐策略不同而变成 28 或者 32，字段之间还可能塞进填充字节。换一次编译器版本、改一个打包选项，读出来的数据就整体错位了。这种 bug 在实验室里永远复现不了，只会出现在量产的某一批设备上。

1.2 双区备份加魔术字：解决了掉电，没解决磨损

被上面那个坑教育过之后，稍微讲究一点的写法就出来了：A/B 两个扇区交替写，每块数据前面加一个魔术字和 CRC 校验。读的时候先读 A，CRC 不过就读 B，谁新用谁。

这套方案在掉电原子性上确实管用——擦 A 的时候 B 还在，写 A 写到一半掉电，B 还在。逻辑闭环了，思路是对的。

但它的账本一点没变好。A/B 轮换只是把擦写次数稀释了一倍，每次保存还是要擦一整个扇区。还是那台每 10 分钟保存一次的设备，寿命从 69 天变成 138 天。而且这套代码的维护成本会随着需求长大：今天加个新参数，明天改个结构体版本，后天要求"能回滚到上一版配置"，你那几百行手写逻辑就开始互相打架了。我见过最惨的一个项目，参数版本演进到第 7 版，代码里全是if (ver == 3) {...} else if (ver == 5) {...}，最后没人敢动。

1.3 手搓环形日志：指针和 CRC 全自己扛

日志类的需求更麻烦。传感器每隔几分钟采一条数据，要存下来，要能按时间段查，空间满了要自动淘汰最老的。

于是就有了自己写的环形缓冲：一个头指针、一个尾指针、每条记录带时间戳和长度、写满了绕回去覆盖。写的时候还得小心不能跨扇区边界——跨了就得处理"一条记录一半在扇区尾、一半在扇区头"的情况。再往后，需求变成"查最近 24 小时的数据""把过期数据删掉""统计一共有多少条"，你就会发现自己在手写一个数据库的查询层。

这类代码最要命的地方是故障暴露得特别慢。指针错位一个字节，可能要连续跑三十天才表现出来，而那时候设备已经装在客户现场了。

2. 一个 2.4k Star 的库，替我挡掉了哪四件事

FlashDB 的定位很明确：面向单片机的超轻量级嵌入式数据库，整个库编译进去非常小，跑在几十 KB Flash、几 KB RAM 的片子上没压力。它把存储拆成两条独立的线——KV 数据库和时序数据库（TSDB）——这个拆分是我觉得设计上最聪明的地方。

2.1 参数和记录是两种东西，别用一套代码硬撑

很多人的直觉是"反正都是往 Flash 里写数据，一套接口就够了"。不对。参数和记录在访问模式上完全是两回事：

• 参数类数据（校准系数、设备序列号、Wi-Fi 配置、运行小时数）：写入频率极低，读取频率高，用键值随机访问，最看重一致性——读到半截数据等于设备跑飞。
• 记录类数据（传感器采样、异常日志、事件流水）：写入频率高，只追加不修改，按时间顺序读写，空间满了要能滚动淘汰。

FlashDB 对应给了两套 API 和两套存储结构。KV 那边是fdb_kv_set/fdb_kv_get这种字符串键的接口，支持字符串、定长数值和任意二进制 blob；TSDB 那边是fdb_tsl_append追加、fdb_tsl_iter_by_time按时间区间遍历、fdb_tsl_query_count统计条数。你不用再为"查询最近一天的数据"这种需求去手写遍历逻辑。

2.2 磨损均衡和掉电保护，其实藏在"不擦除"这三个字里

这是 FlashDB 和我之前手搓方案最本质的区别，值得单独说清楚。

手搓方案的逻辑是"原地改写"：数据放在扇区的固定位置，改了就把这个扇区擦掉重写。

FlashDB 用的是"日志式追加"：新数据永远是往当前空闲的位置追加一条记录，不擦除。每条记录自带状态标记和 CRC，状态从PRE_WRITE变成WRITE才算真正生效。只有当一个扇区的空间被追加的记录填满之后，才会触发一次空间回收，把还有效的记录搬走，再擦掉整个扇区。

这带来两个直接好处：

第一，掉电安全。写一条记录的过程是先写数据、再把状态改成WRITE。如果在这中间断电，上电后扫描时发现一条记录状态是PRE_WRITE或者 CRC 校验不过，直接丢弃。要么完整写入，要么完全不存在，没有中间态。这就是所谓的原子性，而且是靠数据结构设计出来的，不依赖任何硬件特性。

第二，磨损被摊平了。一次擦除动作对应的是整个扇区的空间被写满，而不是一次写入。这还是那台每 10 分钟保存一次的设备，我们来算笔账：

2048 万次，按每小时保存一条算，是两万三千多年。数字悬殊到这个程度，本质原因就是"擦除"这个昂贵动作被记录条数给摊薄了。

2.3 几种常见落盘方案的边界对比

光说 FlashDB 好没意义，得看它在整个选项里处在什么位置。下面这张表是我自己在几个项目里对比后的结论，参数是经验值，不同片子会有出入：

看到那张表里"文件系统掉电安全弱"可能会有人不服。这是实话：通用文件系统是为块设备和缓存的写入模型设计的，它假设写入是成批的、可缓存的，掉电时容易在 FAT 表和目录项之间产生不一致。用它来做"每秒都可能有写入、随时可能断电"的现场数据落盘，是选错工具了。

3. 从零把它跑起来：移植到 STM32 上要动的几个地方

理论讲完，说实操。这一节按我实际做过一遍的顺序来，每一步都标出容易翻车的位置。

3.1 依赖准备：绕不开的 FAL 抽象层

FlashDB 默认跑在一层叫FAL（Flash Abstraction Layer）的抽象层上。这层的存在意义是：让你的数据库代码不关心底下是片内 Flash、SPI Nor Flash 还是别的什么，只要按分区表配好就行。这个设计是对的，但也意味着你要多理解一层结构，很多人第一次移植就是卡在这一步。

目录大致是这么组织的：

FlashDB/ fdb_cfg.h <- 你自己写的配置文件 src/ fdb.c fdb_kvdb.c fdb_tsdb.c fdb_utils.c FAL/ inc/fal.h inc/fal_cfg.h src/fal.c src/fal_flash.c src/fal_part.c samples/port/fal_flash_stm32f2_port.c <- 参考移植文件

fdb_cfg.h里几个开关必须先确认：

#define FDB_USING_KVDB #define FDB_USING_TSDB #define FDB_USING_FAL_MODE /* 用 FAL 作为底层驱动 */ #define FDB_WRITE_GRAN 8 /* 写粒度，按你的物理 Flash 填 */ #define FDB_ERASE_GRAN 4096 /* 擦除粒度，按你的物理 Flash 填 */

FDB_WRITE_GRAN这个参数很多人随手填 1，这是个典型的坑。它的含义是"一次最小写入单位是多少位"，片内 Flash 通常是 32 位或 64 位，也就是填 4 或 8。填错了不会立刻报错，但会在跑一段时间之后出现莫名其妙的记录损坏。填之前请翻你片子的数据手册，别猜。

FDB_DEBUG这类调试开关，实验室里开着方便看日志，量产固件里一定要关掉，它会在每次操作时输出大量字符串，Flash 占用和运行开销都不小。

3.2 底层三个接口：read / write / erase

FAL 层要求你实现最底层的三个动作，参考fal_flash_stm32f2_port.c改写即可。核心是一个fal_flash_dev结构体：

struct fal_flash_dev stm32_onchip_flash = { .name = "onchip_flash", .addr = 0x08000000, .len = 256 * 1024, .blk_size = 2048, /* 擦除块大小 */ .ops = { init, read, write, erase }, .write_gran = 32 /* 写粒度，单位 bit，这里 32bit = 4 字节 */ };

三个函数里，write和erase是重点。片内 Flash 的写入要求目标区域已经被擦干净（全1），并且写入地址按写粒度对齐；擦除必须整块擦。移植的时候不要偷懒直接调 HAL 而不做参数检查，我建议在write里加一段：

static int flash_write(long offset, const uint8_t *buf, size_t size) { /* 地址必须按写粒度对齐 */ if (offset % 4 != 0 || size % 4 != 0) { return -1; } /* 目标区域必须是已擦除状态，否则 HAL 会返回错误 */ for (size_t i = 0; i < size; i += 4) { if (*(volatile uint32_t *)(FLASH_BASE + offset + i) != 0xFFFFFFFF) { /* 这里返回错误，别硬写 */ return -1; } } /* 再调 HAL_FLASH_Program ... */ }

这段检查看着多余，但它能在调试阶段把"忘了先擦除"这类错误直接暴露出来，而不是等到运行几个月后发现数据坏了。写驱动的原则就一条：宁可返回错误，也不要让硬件处在未定义状态。

3.3 分区表：起始地址必须按擦除粒度对齐

分区表在fal_cfg.h里定义，一个典型的划分：

#define FAL_PART_TABLE \ { \ {FAL_PART_MAGIC_WORD, "kvdb", "onchip_flash", 0 * 1024, 64 * 1024, 0},\ {FAL_PART_MAGIC_WORD, "tsdb", "onchip_flash", 64 * 1024, 128 * 1024, 0},\ }

这里有个特别容易被忽略的坑：STM32F4 系列的片内 Flash 扇区大小是不等的——前面几个扇区是 16 KB，中间跳到 64 KB，后面是 128 KB。如果你按"每 16 KB 一个扇区"的直觉去划分区，起始地址落在了一个 64 KB 扇区的中间，那么对这个分区的擦除会把前一个分区的数据一起带走。表现出来就是"KV 能写进去，但一擦 TSDB，KV 就读不出来了"。

规避方法很土但有效：拿片子的参考手册，把每个扇区的起止地址抄在纸上，分区边界只落在扇区边界上，而且分区长度用扇区长度标注一下。我是直接在配置文件里写注释，比如/* 64KB，对应 F4 的 Sector 4 */，下次改分区的时候一眼就知道能不能动。

3.4 最小闭环：先让 KV 和 TSDB 各跑通一次

移植完成之后别急着往业务代码里塞，先写个最小验证。KV 部分：

fdb_kvdb_t kvdb; void storage_init(void) { fal_init(); fdb_err_t err = fdb_kvdb_init(kvdb, "env", "kvdb", NULL, NULL); if (err != FDB_NO_ERR) { /* 初始化失败一定要处理，比如点亮故障灯 */ fault_led_on(); return; } /* 写入两个不同形态的值 */ fdb_kv_set(kvdb, "boot_count", "1"); sys_cfg_t cfg = { .kp = 1.25f, .ki = 0.03f }; struct fdb_blob blob; fdb_blob_make(&blob, &cfg, sizeof(cfg)); fdb_kv_set_blob(kvdb, "sys_cfg", &blob); }

注意fdb_blob_make这一步：存取结构体、数组这类二进制数据，必须用 blob 接口，不能当字符串处理。原因是 FlashDB 内部对字符串和 blob 的存储策略不同——字符串会额外处理结尾符，blob 是原样存原始字节。我见过有人把结构体当字符串set进去，读出来在某个字节处被截断，查了两天才发现问题。

TSDB 部分需要一个时间戳回调：

static uint32_t get_timestamp(void) { return (uint32_t)(xTaskGetTickCount() / configTICK_RATE_HZ); } fdb_tsdb_t tsdb; void log_init(void) { fdb_tsdb_init(tsdb, "log", "tsdb", get_timestamp, NULL, NULL); sensor_rec_t rec = { .temp = 25.3f, .humi = 60 }; struct fdb_blob blob; fdb_blob_make(&blob, &rec, sizeof(rec)); fdb_tsl_append(tsdb, &blob); }

遍历查询的时候，回调函数的返回值语义要特别注意：

static bool query_cb(fdb_tsl_t tsl, void *arg) { sensor_rec_t rec; struct fdb_blob blob; fdb_blob_make(&blob, &rec, sizeof(rec)); fdb_tsl_to_blob(tsl, &blob); /* 处理 rec */ return false; /* 返回 false 表示继续遍历，返回 true 表示终止 */ } /* 查询最近一小时 */ uint32_t now = get_timestamp(); fdb_tsl_iter_by_time(tsdb, now - 3600, now, query_cb, NULL);

注意：这个回调的返回值是"返回 false 继续、返回 true 停止"，和不少人直觉里的写法是反的。头一回用的时候很容易记反，结果只处理了一条数据就退出遍历，还以为是查询条件写错了。

fdb_tsl_append之后还有一个原子提交的动作你不需要手动调，库里已经处理好了。但如果你想减少掉电窗口，可以在批量写入之后调用一次fdb_tsdb_control(tsdb, FDB_TSDB_CTRL_SET_SEC_SIZE, ...)之类的控制接口调整行为——具体可用参数以你手上版本的fdb.h为准。

4. 实测踩过的四个坑，以及每个坑的排查链路

这一节是我最想写的地方。上面那些是"应该怎么做"，下面这些是"我实际怎么翻车的"。

4.1 扇区大小与分区配置不一致：能写进去，读出来是乱码

第一次移植的时候，我参考的是一个 F1 的配置，FDB_ERASE_GRAN填了 2048，但手上这块 F4 的扇区最小是 16 KB。现象很诡异：初始化成功，fdb_kv_set返回也没报错，甚至重启之后第一次fdb_kv_get还能读出来。但连续写几次之后，读出来的内容开始出现部分乱码。

排查过程是这样的：先确认底层 write/erase 是否真的操作到了我期望的地址——用一个简单的测试函数，往分区首地址写一个已知的 pattern，然后手工 dump 出来看，是对的。再确认 KV 层写入的数据是否真的落到了该落的位置——打印出记录头和状态标记，发现状态是WRITE，CRC 也对。那问题只能出在"库认为的扇区"和"物理扇区"不一致上。

结论就是FDB_ERASE_GRAN与实际 Flash 的擦除粒度对不上。库按 2048 字节算扇区，回收时只擦了 2048 字节，但硬件实际是整块 16 KB 擦除，导致相邻记录被一起抹掉，读出来自然是乱的。改对参数之后问题消失。

这里给一条经验：配置阶段宁愿多花半小时对着数据手册核参数，也别指望运行时能自动补救。这类参数错配不会立刻报错，它会在你放松警惕之后才发作。

4.2 掉电测试怎么做才算数

磨损和原子性这种东西，不测是看不出来的。但"掉电测试"很多人的做法是错的——直接拔电源，测十次，没坏，就认为过关了。

这几乎测不出问题。原因在于写入窗口非常短，你随机拔十次，大概率一次都没落在写入的那几毫秒里。

我的做法是用一个受控电源，在写入操作正在执行时切断供电。具体实现是在写数据之前拉高一个 GPIO，写完拉低，然后用示波器或者逻辑分析仪看这个 GPIO，手动在它高电平期间断电。重复至少几十次，每次上电都做一次完整的数据校验。

更工程化的做法是写一段自动化代码，让设备在"写入中断电"这件事上做循环。比如用一颗 IO 控制一颗 MOS 管给整板供电，MCU 上电后立刻执行一次写入，随机延迟若干微秒后主动断电，如此循环几百次。跑完之后统计有多少次出现了校验失败。合格的标准是：每次上电读到的数据要么是完整的旧值，要么是完整的新值，绝不能出现第三种情况。

我按这个方法跑了 500 次随机断电，FlashDB 那一侧没有出现过一次数据损坏；同一个测试下，我之前手写的那版双区方案出现了 3 次读到"半新半旧"的情况。这个对比是我彻底换掉旧方案的直接原因。

4.3 分区写满之后会怎样，容量该怎么估

日志类数据是会写满的。写满之后的默认行为是滚动淘汰最老的记录，但你要提前知道容量有多少，否则设备在客户现场跑两个月之后突然发现历史数据只剩最近三小时，那是要出事的。

KV 和 TSDB 的容量估算公式不一样：

KV 场景，每条记录的开销 = 键名长度 + 数据长度 + 文件头（约 20 到 30 字节）。所以：

可容纳的键数量 ≈ 分区大小 / 平均单条记录占用

TSDB 场景，每条记录开销 = 时间戳 4 字节 + 数据长度 + 记录头。假设分区 128 KB，一条传感器记录 16 字节，加上开销按 32 字节算，那么大约能存 4096 条。如果每 5 分钟采一条，覆盖时间就是 4096 × 5 分钟 ≈ 14 天。

这个数字在立项的时候就该算出来，然后反推分区该切多大。我见过一个项目因为分区只给了 16 KB，日志覆盖时间不到一天，最后只能把采样周期从 1 分钟改成 10 分钟，业务上直接不达标。

4.4 中断和主循环同时碰数据库

最后一个坑是并发。KV 数据库的写入不是原子的内存操作，它涉及多次 Flash 访问。如果你在主循环里fdb_kv_set，中断服务函数里又读同一个键，就可能读到中间态。

FlashDB 提供了可选的锁机制，在fdb_kvdb_init的最后一个参数里传一个加解锁回调进去。但对绝大多数项目，我更推荐简单粗暴的做法：把数据库的所有访问都收敛到一个任务或者一个上下文里，用队列传请求。这样锁都不用加，心智负担最小。

如果你用的是 RTOS，那就更简单——建一个存储任务，其他任务通过消息队列发请求，存储任务顺序执行。这比到处加锁、还要小心死锁要可靠得多。裸机项目没有任务概念，那就退而求其次，在访问数据库前关中断，访问完开中断。但要注意关中断的时间窗口，TSDB 遍历几千条记录的时候长时间关中断是会丢串口数据的，遍历这种操作一定要放到中断外做。

5. 什么时候该用它，什么时候别硬上

用了两年多，我对它的适用边界摸得比较清楚了。这几个判断标准可以直接拿去用。

5.1 每秒几十次的高频写入，它也不是银弹

日志式追加虽然比原地改写省擦除，但每次写仍然是一次真实的 Flash 编程操作。片内 Flash 单次编程的耗时在几十微秒到几毫秒之间，而且频繁的编程会占用 CPU 和外设总线。如果你要每秒写入几十次，片内 Flash 会被拖得非常吃力，而且擦除配额消耗得也快。

这种场景有三个选择：改用外挂的 FRAM 或者 MRAM（写入快、寿命几乎无限，缺点是贵）、在 RAM 里做缓冲攒够一批再批量落盘、或者降低采样频率改用滑动平均。我的默认选择是第二种——RAM 里放一个几百字节的缓冲，攒够 32 条或者每 30 秒批量提交一次，写入吞吐立刻降下来，掉电最多丢最近 30 秒的数据。这个取舍必须和业务方明确说清楚，别自己拍脑袋决定。

5.2 需要 PC 端直接读写的，还是老实上文件系统

FlashDB 的分区结构是为设备自己读设计的，PC 端插上之后不认识。如果你的需求是"设备插到电脑上，电脑能直接看到一个可移动磁盘，里面的文件能复制出来"，那它的分层结构不适合，应该走文件系统。

但反过来，如果只是"设备通过串口或者蓝牙把数据传出来，上位机解析"，那 FlashDB 更合适——它按记录存，读取的时候一条一条出，天然适合流式传输，不用处理 FAT 表、目录项、文件碎片这一堆东西。

5.3 我实测的几组数据

下面这组数字来自一块 STM32F4 板子，片内 Flash 作为存储介质，KV 分区 64 KB、TSDB 分区 128 KB，运行在 168 MHz 主频下。不同片子、不同编译优化等级会有出入，仅供参考量级：

最后一项值得单独提醒：空间回收的耗时是波动的，最坏情况下要搬运整个分区的有效记录。如果你的系统对实时性有硬要求，别让回收动作在时间敏感的任务里触发。我的做法是把 TSDB 的遍历和潜在回收动作都放进一个低优先级任务，靠空闲时间去消化。

真要说这套东西给我最大的改变是什么，不是省了几百行代码，而是它让我在写业务逻辑的时候不用再分心去考虑存储层会不会崩。以前每加一个参数，我要想这个参数多大、放哪个地址、要不要重新划分区、版本升级怎么兼容；现在这些都是fdb_kv_set一句话的事，剩下的交给库。这种"把不擅长的事交给专门做这件事的代码"的思维转变，比学会一个库本身要值钱得多。

如果你现在手上还压着一堆自己手搓的存储代码，我的建议是先别急着全换。挑一个最痛的地方——比如参数区——先把它挪过来，跑通、跑稳、看着它在掉电测试里不出错，你自然就有底气把剩下的也搬过去。