8.4 嵌入部署实录
8.4 嵌入部署实录：链接、线程、升级与排错
本节摘要：部署 SQLite 没有"装服务"这一步，却有四个服务端没有的决策点：怎么链接引擎（amalgamation 还是系统库）、怎么配线程模式、怎么管连接与升级、出问题按什么顺序排。本节是一份可直接执行的部署清单，每个决策点给出依据与默认答案。
决策一：链接方式——自带引擎还是用系统的
SQLite 以 amalgamation 形态分发：整个引擎约 25 万行 C 合成单文件（sqlite3.c 加 sqlite3.h），编译进你的工程即可。两种路线的对照：
| 维度 | 自带 amalgamation | 依赖系统库（libsqlite3） |
|---|---|---|
| 版本控制 | 完全自定，升级随发版走 | 跟随操作系统，不可控 |
| 编译选项 | 可裁剪（禁用不需要的模块省体积） | 发行版的默认配置 |
| 升级成本 | 换一个源文件重新编译 | 无需动应用，但特性冻结 |
| 兼容性测试 | 自己负责 | 发行版背书 |
生产实践的多数答案：移动端与桌面应用自带（要控制版本与特性集），服务器侧工具脚本用系统库（省事，特性足够）。自带时两个编译开关值得认识：SQLITE_ENABLE_FTS5（全文检索，5.3 节的主角默认不编入）与 SQLITE_THREADSAFE（线程模式，下面展开）。升级策略与版本核对一行代码：
printf("runtime=%s, headers=%s\n", sqlite3_libversion(), SQLITE_VERSION); /* 两个值不一致说明链接到了旧库——部署检查项之一 */
决策二：线程模式与连接管理
三个线程模式，默认 SERIALIZED（全库一把大锁，任何时刻一个线程碰一个连接）：
sqlite3_config(SQLITE_CONFIG_SINGLETHREAD); /* 编译期全局：完全无线程保护 */ sqlite3_config(SQLITE_CONFIG_MULTITHREAD); /* MT：连接可跨线程，但同一连接同时只用一个线程 */ sqlite3_config(SQLITE_CONFIG_SERIALIZED); /* 默认：随便跨，性能换安全 */
工程上最稳的姿势不是调模式，而是连接归属纪律：写连接全局唯一（配合 WAL 的单写者），只读连接按线程或按请求创建（创建成本接近零，第 1 章讲过）；跨线程共享连接句柄一律禁止。这套纪律把线程模式的选择降级为细节——SERIALIZED 的锁开销在"一连接一线程"的用法下几乎为零。对照 MySQL 与 PostgreSQL：它们的连接是网络资源，池化是刚需；SQLite 的连接是进程内对象，随用随开反而更干净——两条连接管理哲学完全相反，把服务端习惯直接搬过来（全局池化共享连接）是 SQLite 应用多线程 bug 的头号来源。
决策三：部署清单与迁移预案
上线前的检查清单，按故障代价排序：
- 三件套意识：主文件加 -wal 加 -shm 是一个整体；备份、迁移、杀进程都要按整体对待（第 8.1 节的教训）。
- 初始化 PRAGMA 集中管理：journal_mode、synchronous、busy_timeout、cache_size、foreign_keys 五件套写在唯一的初始化路径里，杜绝"某个模块忘了开 WAL"。
- 版本迁移走版本号：库内放一张 schema_version 表，启动时对比代码期望版本，逐版本执行迁移脚本；迁移包在事务里，失败自动回滚。
- 磁盘空间水位：WAL 模式下写峰值时 WAL 临时膨胀，磁盘满会导致 SQLITE_FULL——部署时为数据目录预留两倍于预期的空间，并监控水位。
- 运行期断言：用
sqlite3_config(SQLITE_CONFIG_LOG)挂日志回调，把引擎内部告警（自动重编译、检查点被拖延）落到应用日志，故障时是第一手证据。
⚠️ 最隐蔽的部署坑：把数据库文件放在用户目录外的系统路径（如程序安装目录），正常用户无写权限，首启动建库失败；或放在会被系统清理工具扫描的临时目录，数据莫名消失。库文件的位置要么在用户数据目录，要么在明确的配置项里。
决策四：故障排查的固定顺序
出问题按这个顺序走，九成能在第四步内定位：
1. 版本核对：sqlite3_libversion 与预期一致？链接的是哪个库？ 2. 三件套检查：主文件、wal、shm 是否同目录、权限是否一致、wal 是否异常巨大？ 3. 健康检查：integrity_check、freelist_count（第 8.2 节的组合） 4. 配置核对：五件套 PRAGMA 的当前值与预期是否一致？ 5. 并发画像：谁在持有写事务？长读事务在哪？（BUSY 与 WAL 膨胀的双源） 6. 计划核对：慢查询的 EXPLAIN QUERY PLAN 是否与上线前一致？统计是否过期？
这六步覆盖了本册出现过的全部故障模式：版本错配、WAL 孤儿、损坏与碎片、配置漂移、长事务、计划劣化。把它贴在团队 wiki 上，比任何一次性的救火文档都管用。
常见问题速答
**多个进程能同时打开同一个库吗？**能，这正是文件锁存在的意义——同一台机器上的多个进程各开各的连接，SQLite 用文件锁协调它们。前提纪律不变：WAL 模式（否则读写互斥得厉害）、同机本地图盘（网络盘锁语义不可靠）、busy_timeout 必设。真正的红线是"跨机器"：两台机器的进程通过网络文件系统共享同一个库文件，锁协议在多数网络文件系统上不成立，官方明确视为不支持场景——需要多机共享时，请用服务端数据库或做应用层的主从分片。
**升级 SQLite 版本要注意什么？**SQLite 的兼容性口碑极好：同主版本系列内升级零风险；跨主版本（3.x 内的小版本升级）保持了官方"文件格式长期稳定"的承诺，新版本读旧文件永远兼容，旧版本读新文件在"未使用新特性"的前提下也兼容。工程上注意两点：amalgamation 随应用升级后跑一遍完整性校验与核心用例回归；依赖系统库的部署要写明最低版本要求（新 SQL 特性如窗口函数依赖 3.25+），版本断言在启动日志里（本节的检查项）。
本节要点回顾
- 链接方式按可控性选：移动桌面自带 amalgamation，服务器脚本用系统库；版本断言写进启动日志。
- 连接纪律优于线程模式调参：单写连接加按线程只读连接，禁止跨线程共享句柄。
- 部署五清单：三件套整体观、PRAGMA 集中化、版本化迁移、磁盘水位、引擎日志回调。
- 排错六步固定顺序：版本、三件套、健康、配置、并发、计划——全册机制在此收拢成动作。
全册到此收束。附录给出 PRAGMA 速查与三库决策卡，作为日常工作的桌面参考。