移动端日志收集方案里，Bugfender 扮演着把远端设备上的 log 实时甚至近实时送到 web 控制台的角色，让开发者不用连数据线就能看到用户侧发生了什么。但实际场景中，应用可能处于弱网、无网或频繁切换网络的状态，Bugfender 的远程日志一旦因为网络问题发送失败，SDK 自带的缓存队列在极端情况下也会溢出或丢失。为了保证关键诊断信息百分之百被上报，我们可以在本地引入 SQLite 作为持久化的“安全垫”，再配合 Bugfender 的远程通道构建一套先入本地库、后按策略上传的混合日志系统。下面以一个 Android 端的简化实现为主线展开讲解，iOS 端的思路完全一致，只需将数据库部分换成 FMDB 或 Core Data 即可。
为什么选择 SQLite 做本地日志缓冲
Bugfender SDK 本身已经提供了本地缓存，比如在初始化时可以设置 Bugfender.setForceEnabled(true) 让 SDK 在写入日志时即使没有网络也会缓存到设备本地，待网络恢复后自动发送。但这个“自动”行为对上层来说几乎是黑盒：你无法确切知道一条日志是否已经刷入磁盘、它会在什么时候被回收、缓存上限是多少。当我们需要对特定等级的日志做精确的持久化控制时，直接依赖 SDK 的缓存就不够了。
SQLite 作为移动端本地数据库，带来的好处非常直接。第一，持久化保证：只要事务提交成功，日志就写入了文件系统，App 被 kill 或重启都不会丢失。第二，结构化查询：我们可以给日志打上时间戳、级别、标签等字段，方便本地调试时用 SQL 过滤，甚至可以在诊断模式下导出整个 db 文件。第三，可控的上传策略：我们可以自行决定何时从 SQLite 中读取未上报的日志，批量提交给 Bugfender，并在成功回调后删除相应的记录，形成一条完整的“写入-上传-确认-删除”闭环。
当然，SQLite 的引入也会带来额外的 IO 开销和存储占用，所以设计时需要平衡写入频率与性能，以及制定合理的日志清理规约，防止数据库无限膨胀。
SQLite 日志表设计与线程安全写入
日志表结构并不复杂，但需要为后续的上传和清理做足准备。典型的表定义如下：
CREATE TABLE IF NOT EXISTS bugfender_log_buffer (
id INTEGER PRIMARY KEY AUTOINCREMENT,
tag TEXT,
message TEXT NOT NULL,
level INTEGER NOT NULL,
timestamp INTEGER NOT NULL,
uploaded INTEGER DEFAULT 0
);
CREATE INDEX IF NOT EXISTS idx_uploaded ON bugfender_log_buffer(uploaded, timestamp);
字段说明：tag 用来模拟 Bugfender 的标签行为；level 可以按数字映射，比如 0=Verbose，1=Debug，2=Info，3=Warning，4=Error；timestamp 存 epoch 毫秒值，方便排序；uploaded 是核心标志位，0 表示待上传，1 表示已上报成功可以清理。索引 idx_uploaded 能加速查询所有未上传日志并按时间排序。
在 Android 端，通常使用 Room 或者直接基于 SQLiteOpenHelper 封装。考虑到日志写入是一个高频操作，必须保证线程安全。简单做法是使用单线程的 HandlerThread 或者 Kotlin 协程的 Channel，把所有 insert 操作串行化，避免直接在主线程或者多个线程并发写入导致的 SQLiteDatabaseLockedException。下面是一个基于 HandlerThread 的日志写入封装示例：
public class LocalLogBuffer {
private HandlerThread logThread;
private Handler logHandler;
private SQLiteDatabase db;
public LocalLogBuffer(Context context) {
logThread = new HandlerThread("LocalLogThread");
logThread.start();
logHandler = new Handler(logThread.getLooper());
DBHelper helper = new DBHelper(context);
db = helper.getWritableDatabase();
}
public void log(String tag, String message, int level) {
logHandler.post(() -> {
ContentValues values = new ContentValues();
values.put("tag", tag);
values.put("message", message);
values.put("level", level);
values.put("timestamp", System.currentTimeMillis());
values.put("uploaded", 0);
db.insert("bugfender_log_buffer", null, values);
});
}
}
这样无论从哪个线程调用 localLogBuffer.log(...)，实际的数据库写入都在同一后台线程串行执行，既安全又不会卡 UI。如果你使用 Kotlin，还可以借助 Dispatchers.IO 和协程进一步简化，但本质思路相同。
将 SQLite 缓存日志同步到 Bugfender 远程服务
Bugfender 提供了多种发送日志的方法，比如 Bugfender.d(tag, text) 发送 debug 级别日志，Bugfender.e(tag, text) 发送 error 日志。我们要做的是读取 SQLite 中 uploaded=0 的记录，逐条或批量发送给 Bugfender，发送成功后把对应记录的 uploaded 更新为 1。
同步策略的核心在于“什么时候触发上传”和“每次上传多少条”。最实用的做法是结合网络状态监听与定时轮询。可以用 ConnectivityManager 注册网络回调，当网络变为可用时立即触发一次上传；同时再开一个 Handler 每隔 30 秒检视是否有未上报日志。上传逻辑建议分批进行，比如每次最多取 50 条，避免一次性处理过多数据导致主线程卡顿或占用太多网络资源。
下面是一个上传逻辑的伪代码实现：
private void syncPendingLogs() {
logHandler.post(() -> {
Cursor cursor = db.query("bugfender_log_buffer",
null, "uploaded=0", null, null, null, "timestamp ASC", "50");
try {
while (cursor.moveToNext()) {
long id = cursor.getLong(cursor.getColumnIndex("id"));
String tag = cursor.getString(cursor.getColumnIndex("tag"));
String message = cursor.getString(cursor.getColumnIndex("message"));
int level = cursor.getInt(cursor.getColumnIndex("level"));
// 根据 level 调用 Bugfender 对应方法
switch (level) {
case Log.VERBOSE: Bugfender.v(tag, message); break;
case Log.DEBUG: Bugfender.d(tag, message); break;
case Log.INFO: Bugfender.i(tag, message); break;
case Log.WARN: Bugfender.w(tag, message); break;
case Log.ERROR: Bugfender.e(tag, message); break;
}
// 标记为已发送
ContentValues values = new ContentValues();
values.put("uploaded", 1);
db.update("bugfender_log_buffer", values, "id=?", new String[]{String.valueOf(id)});
}
} finally {
cursor.close();
}
});
}
这里需要注意：Bugfender 本身有内部队列，我们在循环里连续调用 Bugfender.d 并不会阻塞很长时间，但如果日志量非常大，单次上传数量需要限制，否则可能导致 Bugfender 内部队列积累过快而触发丢弃机制。同时，我们标记 uploaded=1 的操作是紧随发送后执行的，但没有等 Bugfender 确认网络发送成功。这种做法在大部分场景下足够可靠，因为 Bugfender 会自行缓存并重试发送，如果我们需要更强的“已发送确认”，可以监听 Bugfender 的发送回调（如果 SDK 提供）或自建服务端接收通道，但那样复杂度会大幅上升。对多数应用来说，这样的“发送并标记”模式已经能保证日志几乎不丢失。
当同步完成后，可以定期清理已上传且时间超过一定期限的旧日志，例如保留最近 3 天的已上报记录，删掉更早的数据以控制数据库体积：
DELETE FROM bugfender_log_buffer WHERE uploaded=1 AND timestamp < ?;
清理操作放在一个后台周期任务中执行，比如每天凌晨，避免与高频写入同步争抢锁。
性能优化与边界场景处理
在日志量巨大的应用中（例如频繁打点），SQLite 写入可能成为瓶颈。优化方向包括：使用 WAL 模式提升并发读性能；将批量插入放在一个事务中减少磁盘同步次数（例如每收集 20 条日志统一提交一次）；以及控制日志消息的长度，避免将整个 JSON 包或调用栈直接塞入，可以只存关键信息并将完整追踪另外写入文件。
另一个容易忽视的点是 Crash 瞬间的日志落盘。通常 Bugfender 会在应用崩溃时尝试发送最后的日志，而我们的 SQLite 缓冲方案必须确保崩溃前的 log() 调用已经将数据刷入了数据库。对于基于 HandlerThread 的实现，如果 App 在主线程发生崩溃，后台线程可能还没来得及执行数据库写入。解决办法是：在 UncaughtExceptionHandler 中主动 flush 日志队列，或者将日志先写入一个无锁的内存队列，再由后台线程写入 SQLite。这样即使崩溃瞬间，我们也能在 finally 块里把内存队列中尚未持久化的日志快速写入数据库，最大限度减少丢失。
安全性方面，如果日志中可能包含用户隐私数据（如账户 ID、设备标识），建议对 SQLite 中的日志内容进行加密。可以使用 SQLCipher 或在应用层对 message 字段做 AES 加密后再入库，上报时在服务端解密。这能有效防止设备被 root 后日志泄露。
最后，这个混合架构并非要替代 Bugfender 的原生使用方式，而是在其之上构建了一条更可靠的旁路通道。当远程日志服务遇到网络或服务端异常时，SQLite 缓冲守护了本地数据的完整性；当网络恢复后，同步策略确保数据有序回传，让开发和运维团队永远不丢失线上关键线索。