SQLite 生产实战 2026：把单文件数据库用进真实线上服务

2026 年，一个越来越明显的趋势是：中小型服务正在从"默认上 Postgres"转向"先问一句，真的需要网络数据库吗"。SQLite 把整个数据库装进一个文件、随应用一起部署、零配置零运维，读性能吊打绝大多数网络数据库（省掉的就是那一次网络往返）。Fly.io 与不少基础设施团队的实践反复证明：在合适的场景里，SQLite 完全可以承载真实的生产负载。但它不是"开箱即用的免费午餐"——并发模型、持久化参数、备份策略，每一项都需要你主动做对。这篇文章把这些"必须做对的事"一次讲全。

---

一、先破偏见：SQLite 到底强在哪

SQLite 的三个被低估的优势：

① 零网络往返
   读写直接走函数调用，没有连接建立、没有序列化
   协议开销。单机场景下，简单查询比走网络的
   数据库快一个数量级——因为"快"来自省略。

② 运维极简
   一个文件就是全部：备份 = 拷贝文件，
   迁移 = 拷贝文件，开发/测试/生产完全同构。
   没有连接池调优、没有主从复制、没有慢查询
   管理后台。

③ 可靠性极佳
   数十年打磨的存储引擎，测试覆盖率在业界
   排得上号；崩溃恢复由 WAL 机制保证，
   断电不损坏。"嵌入式数据库不可靠"是老黄历。

2026 年的新变量还有两个：本地优先（local-first）产品形态的兴起——数据在用户设备上，SQLite 是天然载体；边缘部署——各种嵌入式分发方案把 SQLite 推到了离用户更近的位置。这些趋势都在持续扩大它的适用边界。

---

二、场景判断：什么时候该用，什么时候别用

诚实的场景判断比技术选型更重要：

适合 SQLite 的场景：

  ✓ 读多写少的多数中小型应用（内容站、API 后端、
    内部工具、中小 SaaS 的早期）
  ✓ 单机部署 + 可接受垂直扩展
  ✓ 本地优先/桌面/移动应用的内嵌存储
  ✓ 边缘节点、IoT、需要离线工作的系统
  ✓ 每秒写入不超过个位数峰值的典型业务负载
    （WAL 模式下的实际吞吐远超直觉）

不适合的场景：

  ✗ 多机同时写同一个库（SQLite 是单写者模型）
  ✗ 海量并发写入（写锁是全局的）
  ✗ 需要服务端丰富扩展生态（逻辑复制、
    行级安全、存储过程生态）
  ✗ 数据必须集中共享的多实例集群架构
    （除非引入分发层的专用方案）

一个实用的迁移视角：**从 SQLite 起步，业务涨到写瓶颈再迁 Postgres，是比"一开始就上重武器"更健康的路径。**原因是 SQLite 的 SQL 方言与主流 ORM 兼容性好，迁移成本可控；而反过来"先重后轻"几乎不会发生。关键在于从第一天就用 ORM/迁移工具管理 schema，别把过程式 SQL 写散。

---

三、并发模型：单写多读与 WAL 模式

SQLite 生产化的第一课是并发模型。默认的回滚日志模式（delete journal）在写入时阻塞读取，这在 Web 服务里不可接受。解法就是开启 WAL（Write-Ahead Logging）：

WAL 模式的核心变化：

  传统回滚日志：写 → 先把旧数据拷走 → 覆盖 →
               写入期间读写互斥
  WAL：写 → 追加进 -wal 文件 → 读不阻塞写、写不阻塞读
               → 读者读最后一个已提交快照（MVCC 语义）
               → checkpoint 时才把 WAL 合并回主库

  并发语义总结：
    写与写：仍然互斥（同一时刻只有一个写事务）
    读与读：并行
    读与写：并行（读者看到一致性快照）

单写多读的约束决定了一个架构决策：**应用的写路径要串行化。**好在这在应用层很容易——单个写队列、或干脆让写操作走一条专用的轻量通道。读路径则可以放心放开：

/**
 * SQLite 连接管理：读写分离 + 写串行化
 * WAL 模式下读可并发，写必须排队
 */
import Database from "better-sqlite3";

/** 创建生产级连接配置 */
export function createDb(path: string) {
  const db = new Database(path);

  // WAL：读不阻塞写（生产环境必开）
  db.pragma("journal_mode = WAL");
  // 完全持久化：牺牲少量写性能换断电安全（生产环境必配）
  db.pragma("synchronous = FULL");
  // 外键约束默认关闭！显式打开，别让"外键失效"埋雷
  db.pragma("foreign_keys = ON");
  // 写锁等待上限：繁忙时等待而非立刻报错
  db.pragma("busy_timeout = 5000");

  return db;
}

/**
 * 写任务队列：把并发写串行化，规避 SQLITE_BUSY
 * @param db 单一写连接
 */
export function createWriteQueue(db: DatabaseType) {
  let chain: Promise<unknown> = Promise.resolve();

  /**
   * 将写任务追加到串行链上依次执行
   * @param task 写事务
   * @returns 任务结果
   */
  return function enqueueWrite<T>(task: () => T): Promise<T> {
    const next = chain.then(() => task());
    // 链上吞掉错误，避免一次失败卡死后续任务
    chain = next.catch(() => undefined);
    return next as Promise<T>;
  };
}

连接数策略与 networked 数据库相反：SQLite 偏爱少量长连接。典型形态是"一个写连接 + 若干读连接"（或用 WAL 模式下支持多读的单连接），千万不要像用 Postgres 那样开几十个连接——每个连接都会抢同一把写锁，busy 报错反而增多。

---

四、PRAGMA 清单：每一项都该知道为什么

SQLite 的默认配置面向"嵌入式设备兼容"，不是服务端负载。上线前的必配项：

生产环境 PRAGMA 清单：

  journal_mode = WAL       读并发的前提，一次设置永久生效
  synchronous = FULL       每次提交都落盘；配合 WAL 可保证
                           断电不丢已提交事务（默认 NORMAL
                           在断电时可能丢最近事务）
  foreign_keys = ON        外键约束默认关闭，必须显式开启
  busy_timeout = 5000      遇到锁等待最多等 5 秒再报错，
                           而不是立刻抛 SQLITE_BUSY
  cache_size = -64000      页缓存提到约 64MB（按内存预算调）
  wal_autocheckpoint       WAL 自动合并阈值，默认已合理；
                           写入高峰可观察 -wal 文件大小
  temp_store = MEMORY      临时表放内存，减少磁盘抖动

其中 synchronous 的取舍值得单独说：FULL 与 NORMAL 在 WAL 下的差距是"每次提交 fsync"与"只在 checkpoint 时 fsync"。**对收钱的业务用 FULL；对日志类、可再生数据可以用 NORMAL 换吞吐。**这是一个明确的持久化语义选择，不是默认值能替你做的。

---

五、事务与持久化：把边界画清楚

SQLite 的事务语义是"整个库一个写者"，这反而让事务设计变得简单，但有几个生产要点：

/**
 * 典型的生产写事务：批量写入打包成单事务
 * 关键认知：N 条语句分别提交 = N 次落盘；
 * 打包成一个事务提交 = 1 次落盘，吞吐差百倍不止
 */
const insertUsers = db.transaction((users: NewUser[]) => {
  const stmt = db.prepare(
    "INSERT INTO users (email, name, created_at) VALUES (?, ?, ?)",
  );
  for (const u of users) {
    stmt.run(u.email, u.name, u.createdAt);   // 同一事务内执行
  }
});

/**
 * 生成批量数据时的标准姿势：
 * 包一层事务，把 fsync 次数从 N 压到 1
 */
function bulkInsert(users: NewUser[]) {
  insertUsers(users);
}

事务实践要点：

  ① 批量写必须包事务：导入、迁移、任务批处理，
     否则每次提交都是一次真实落盘。
  ② 长事务会推迟 checkpoint：让 WAL 无限膨胀，
     占满磁盘。避免在事务里做网络调用等慢操作。
  ③ 独占写者意味着"写延迟可预测"：
     没有锁等待分析这种事，写性能瓶颈只可能是
     磁盘本身。
  ④ busy 错误的正确处理：重试（带退避），
     而不是把 busy_timeout 调到无限大。

---

六、备份：单文件不等于不会丢

"数据库就一个文件，备份还不简单？"——不简单。直接拷贝一个正在写入的 SQLite 文件，可能拷到撕裂状态。正确的备份策略：

三层备份方案：

① 流式实时备份（生产标配）：Litestream
   独立进程持续把 WAL 增量推到对象存储（S3 等），
   恢复粒度可到秒级。这是 SQLite 上生产的
   事实标准方案，配置极简。

② 快照备份：VACUUM INTO 或 backup API
   生成一致性快照文件，再交给任何文件备份系统。
   适合低频全量 + 简单架构。

③ 恢复演练：备份的价值取决于恢复是否被演练过
   定期从备份恢复到测试环境，验证完整性
   （PRAGMA integrity_check）与恢复时长。

# Litestream 极简配置示例（/etc/litestream.yml）
dbs:
  - path: /var/lib/app/app.db
    replicas:
      - url: s3://your-bucket/backups/app.db
        retention: 720h          # 保留期
        sync-interval: 1s        # WAL 同步间隔（越短越接近零丢失）

另一个常被忽略的点：SQLite 的 durability 依赖文件系统的 fsync 语义。把库文件放在网络文件系统（NFS 类）上运行是官方明确不支持的用法——要么本地盘 + 流式备份外发，要么用专门的分发方案，别自己发明第三种。

---

七、迁移管理：让 schema 演进可回溯

单文件数据库更需要纪律性的迁移管理，因为"随手改表结构"太容易发生了：

迁移实践：

  □ 迁移文件版本化：按序号命名的 SQL 文件
    （0001_init.sql, 0002_add_index.sql ...），
    启动时自动应用未执行的迁移并记录版本表。
  □ 变更只增不改：加列、加索引用 ADD/CREATE；
    改列类型/删除列走"建新表 - 拷数据 - 改名"
    的标准流程（SQLite 支持有限，工具会代劳）。
  □ 大表变更放低峰：SQLite 的 DDL 多数要全表
    重建索引，写入高峰执行会拉长写锁时间。
  □ 迁移脚本本身放进事务（DDL 大多可回滚），
    失败即整体回退，不留半成品 schema。

ORM/迁移工具层面，主流方案（Drizzle、Atlas、Prisma 的 SQLite 支持等）都已成熟，选一个用起来比纠结哪个最好重要得多。

---

八、性能调优：方法与高频优化点

SQLite 的调优方法与任何数据库一致：先测量，再动手。

-- ① 看执行计划：确认查询走了预期索引
EXPLAIN QUERY PLAN
SELECT * FROM orders WHERE user_id = 42 ORDER BY created_at DESC;

-- 输出里出现 "SCAN orders" 即全表扫描，
-- 出现 "SEARCH orders USING INDEX ..." 才是索引命中。

-- ② 高频优化点一：复合索引覆盖排序
CREATE INDEX idx_orders_user_created
  ON orders (user_id, created_at DESC);
-- "WHERE user_id = ? ORDER BY created_at DESC"
-- 这类最常见列表查询，一个复合索引同时解决
-- 过滤与排序，避免 filesort 式的临时排序。

-- ③ 更新统计信息，让查询规划器做对选择
ANALYZE;

性能高频检查项：

  □ 全部高频查询 EXPLAIN 过，无全表扫描
  □ LIKE '%x%' 类查询改用 FTS5 全文索引
  □ 大 JSON 字段考虑用生成列建索引
  □ 页缓存与操作系统内存预算匹配
  □ 写入吞吐：批量事务化（见前文），
    必要时评估 synchronous 降级
  □ 定期 PRAGMA optimize;（或连接关闭时执行）
    让规划器持续自优化

FTS5 值得单独一提：SQLite 内建的全文本检索扩展，毫秒级配置即可获得分词与 BM25 排序，对中小应用足够替代"为搜索专门上一个外部服务"的冲动。

---

九、部署形态：单文件架构的工程红利

生产形态上，SQLite 释放的架构简化常常比性能更诱人：

单文件架构的典型形态：

  应用 + 数据库文件 同机同生命周期
    ├─ 部署 = 发布二进制/镜像 + 挂载一个数据卷
    ├─ 每日备份由 Litestream 持续外发对象存储
    ├─ 灾难恢复 = 新机器 + 恢复脚本 + 最近备份
    └─ 环境（开发/测试/生产）天然同构，
       测试库就是生产库的拷贝

  本地优先形态：
    数据库文件在用户设备，SQLite 嵌入应用内
    + 同步层（自研或专用方案）负责多端收敛
    → 离线可用、隐私默认、零后端数据库成本

边界也要划清楚：**当业务真的长到多机写入、水平分片、复杂权限模型的那天，迁去 Postgres。**把 SQLite 的生命周期定位为"从第一天到写瓶颈之前"，它就是最锋利的工具；指望它覆盖所有终局形态，才是用错。

---

十、落地清单

上线前
  □ WAL 模式 + synchronous 语义明确选定
  □ foreign_keys 显式开启，busy_timeout 配置
  □ 写路径串行化（写队列/单写连接），读连接按需并行
  □ 批量写入全部事务化
  □ 全部高频查询 EXPLAIN 验证索引

备份与运维
  □ Litestream（或等价方案）流式备份到对象存储
  □ 恢复流程写脚本，演练过完整恢复
  □ 迁移版本化，启动自动应用
  □ 监控指标：-wal 文件大小、写延迟、磁盘余量

持续运营
  □ 定期 PRAGMA optimize / integrity_check
  □ 写入增长趋势跟踪，预留迁移 Postgres 的触发线
  □ schema 变更评审，DDL 避开写入高峰

---

结语：简单是一种需要维护的能力

SQLite 上生产的真正门槛，从来不是功能不够，而是它把过去数据库服务器替你做的决定，还给了你：持久化强度、锁等待、备份时机、恢复流程——这些在网络数据库里由服务端"默认兜底"的事，在 SQLite 里需要你亲手配置与验证。

这正是它最迷人的地方：架构变简单了，责任却更清晰了。你用半天时间把 WAL、备份、迁移、索引这几件事做对，换来的是一个没有网络跳数、没有连接池玄学、备份就是流式推对象存储的数据库系统。**对绝大多数还没被写瓶颈逼到墙角的服务来说，这不是妥协，而是升级。**用好它，然后在你真的需要那门"重炮"的那天，再干脆地搬过去——届时你会发现，正因为 SQLite 逼你搞懂了持久化与并发的每一层，那次迁移也比想象中从容。