OCTO 是一款开源企业级 IM 客户端（OCTO iOS Client），而它的消息、会话、群成员等海量数据都落在本地 SQLite 数据库中。本文带你完整看懂 OCTO iOS 的数据库工程：基于 FMDB 的存储封装、按时间戳命名的 SQL 迁移策略，以及"检测到数据库损坏 → 一键重建 → 自动重启"的恢复机制，全程无需修改一行代码即可复用到自己的项目。

1. 为什么消息数据库是 IM 的"生命线"

📌 对企业 IM 来说，本地数据库存的是：

• 消息流水：每条聊天记录的落库与查询（核心表message）
• 会话与群信息：频道、成员、置顶、免打扰等状态
• 未读与回执：未读队列、已读上报队列（如unread_ack_queue）
• 配置数据：账号级别的偏好与缓存

一旦数据库文件损坏（断电写入、加密密钥不匹配、存储空间异常），轻则消息列表空白，重则整个应用不可用。OCTO 针对这一点做了三层防护：可靠的存储封装 → 可追溯的迁移体系 → 一键恢复兜底。

2. FMDB 存储底座：每个账号一个加密库

OCTO 的 IM SDK 用 FMDB 作为 SQLite 访问层，核心封装在 WKDB.h：

关键设计有三个 👇

1. 按账号隔离：switchDB:uid会把库路径拼成{dbPrefix}{uid}.db（见 WKDB.m），换账号就是换库文件，互不污染。
2. 库级加密：打开库时用 uid 派生密钥执行setKeyWithData:，即使数据库文件被拷走也无法直接读取。
3. 写缓存失效广播：切库完成会发出WKDBDidSwitchNotification，提醒所有持有"DB 派生缓存"的类清缓存，避免拿 A 账号的结论去判 B 账号的库。

3. FMDB 迁移策略：时间戳 SQL 文件 + 事务回滚

OCTO 没有手写if version < N之类的升级代码，而是内置了一套迁移管理器 WKDBMigrationManager.h，规则非常直观：

• 迁移脚本统一放在 Assets/Migrations/ 目录
• 文件名格式为[版本时间戳]_[描述].sql，例如 201911270513.sql（建频道表）
• 管理器用schema_migrations表记录"已应用版本"，启动时自动只执行pendingVersions
• 每次迁移在单个事务中执行，任一步失败整体回滚，不会留下半成品表结构

这套机制的实际效果：从 2019 年第一个版本到 2026 年，OCTO 已经沉淀了31 个迁移文件（例如 202605281200.sql 新增了未读回执队列表）。老用户升级 App 时，switchDB:末尾会自动调用migrateDatabase补跑脚本，无需人工干预。

💡 新手可直接借鉴的迁移写法：建表 +CREATE UNIQUE INDEX IF NOT EXISTS+AFTER UPDATE触发器维护updated_at，全部写在一个.sql文件里即可。

4. 健康检查：数据库损坏是如何被发现的

加密库有一个隐蔽故障：文件格式与加密方式不兼容时，开库会直接失败。OCTO 在 WKDB.m 里做了"开库健康检查"：

1. 每次switchDB:打开库后，先执行SELECT count(*) FROM sqlite_master试读元数据
2. 查询失败即判定"不健康"，在主线程发出WKIMDBHealthCheckFailedNotification通知（携带imDBPath和uid）
3. AppDelegate.m 在启动时监听该通知，弹出"立即修复 / 稍后再说"的确认弹窗

也就是说，损坏不会静默吞掉，而是第一时间暴露给用户。

5. 一键数据库恢复机制：四步重建，进度可视

用户点击"立即修复"后，进入 WKDBRepairViewController.m——一个带旋转扳手动画、进度条和步骤文案的修复页。真正的重活在 WKDBRecoveryManager.m 中，流程拆解如下：

几个工程细节值得学习 🔧：

• 主线程调用、后台执行：performRecovery只在主线程改状态位，文件删除和重建全部丢到 GCD 后台队列，UI 丝滑不卡顿
• WAL/SHM 一起删：SQLite 的预写日志文件残留是"删库重建"常见的坑，这里一并清理
• 防重入：isRecovering标志位防止用户连续点击触发二次删除
• 失败兜底：任一步出错即回传NSError，页面提示"请尝试卸载并重新安装应用"
• 重启闭环：修复完成后显示"重启应用"按钮，点击后exit(0)冷启动，历史消息自动从服务器重新同步

6. 小结：这套方案能直接抄什么

✅ 给普通用户/维护者：数据库损坏时 OCTO 会主动提示并一键修复，历史消息重启后从服务端恢复，不用重装丢记录。

✅ 给开发者：Migrations/时间戳 SQL 目录 +schema_migrations版本表 + 事务回滚，是 IM 类应用数据库升级的稳妥范式；"开库试读 + 通知 + 重建 + 重启"四件套，是本地数据损坏场景的低成本兜底方案。

关键文件索引

• 存储核心：WKDB.m
• 迁移管理器：WKDBMigrationManager.h
• 迁移脚本：Assets/Migrations/
• 恢复逻辑：WKDBRecoveryManager.m
• 修复界面：WKDBRepairViewController.m
• 配置库：WKKitDB.h