简介：这份资源面向在 Qt 环境下开发桌面数据库应用的开发者，聚焦 SQLiteCipher 加密数据库的集成与多库协同操作。内容涵盖加密连接的建立、AES-256 密钥配置、多数据库连接管理，以及通过 ATTACH DATABASE 实现跨库查询的完整实例，适合已具备一定 Qt 与 SQL 基础、需要处理敏感数据存储的中高级开发者参考。压缩包共 101 个文件，约 35.85MB，包含 27 个 dll 运行库、21 个 qm 翻译文件、4 个 db 示例数据库、4 个 cpp 源码与 2 个 h 头文件，另有 vcxproj、sln、pro 等工程配置及 exe 可执行文件，覆盖从源码到运行环境的完整链路。目前已有 595 人学习下载。读者可据此快速搭建加密数据库实验环境，理解 QSqlDatabase 多连接与跨库查询的写法，并借鉴工程组织方式与依赖配置，减少集成 SQLiteCipher 时的试错成本。

1. Qt 里给 SQLite 上锁：SqliteCipher 加密与多库附着到底解决什么问题

很多做 Qt 桌面端的同行都遇到过这种需求：软件装到客户机器上，本地 SQLite 数据库文件被人用 DB Browser for SQLite 直接打开，表结构、业务数据一览无余。SQLite 本身不带加密，标准QSqlDatabase打开的就是明文文件。要在 Qt 里给 SQLite 加密，常见做法是换成带加密能力的驱动，SqliteCipher 就是其中被用得比较多的一种——它在 SQLite 源码基础上加了 AES 加密，通过PRAGMA key设置密钥，整个库文件（包括页、索引、WAL）都是密文。与此同时，一个稍微像样的业务系统往往不止一个库：主库放业务表，日志库单独放，历史归档再拆一个。Qt 的QSqlDatabase支持addDatabase加不同连接名，再用ATTACH DATABASE把多个库挂到同一个连接上做跨库 JOIN。这篇就把这两件事串起来讲：怎么在 Qt 里用 SqliteCipher 打开加密库、怎么同时打开多个库、怎么附着做跨库查询，以及那些不踩一次根本不知道的坑。适合正在做 Qt 本地存储、又对数据安全有要求的开发者，新手能照着跑通，熟手能对参数边界心里有数。

2. SqliteCipher 在 Qt 里的接入方式与驱动选型

2.1 为什么标准 QSQLITE 驱动加密不了

Qt 自带的QSQLITE驱动链接的是官方 SQLite 源码，官方版本从设计上就没有加密层。你就算在连接后执行PRAGMA key='xxx'，标准 SQLite 也只会把它当成一个未知 pragma 忽略掉，文件依旧是明文。这是很多人第一次翻车的地方：代码写了PRAGMA key，用 DB Browser 一开，数据全在，还以为是自己密钥写错了。

要真正加密，必须让 Qt 链接一个「改过的 SQLite」。SqliteCipher 就是这样一个分支，它在 SQLite 的 pager 层做了页级 AES 加密，对外仍然暴露标准 SQLite C API，所以 Qt 的驱动层几乎不用改，只要把编译出来的 sqlite3 库替换掉即可。理解这一点很关键：加密发生在 SQLite 引擎内部，不是 Qt 层做的，Qt 只是调用方。

2.2 两种接入路径：替换驱动 vs 自编译插件

实际落地有两条路，选哪条取决于你的构建环境。

第一条是替换 Qt 的 SQLite 驱动。Qt 的 SQLite 驱动是一个插件（Windows 下是qsqlite.dll，Linux 下是libqsqlite.so），它静态链接了 sqlite3 的 amalgamation。你把 SqliteCipher 的sqlite3.c/sqlite3.h替换进 Qt 源码的qtbase/src/3rdparty/sqlite/，重新编译这个插件，产出的驱动就带加密能力了。这条路干净，业务代码完全不用动，QSqlDatabase::addDatabase("QSQLITE")照常用。

第二条是自己写一个 Qt SQL 驱动插件，直接链接 SqliteCipher 编译出的库。适合你不想动 Qt 源码、或者用的是预编译 Qt 的情况。代价是要自己实现QSqlDriver那一套接口，工作量大，一般不推荐，除非有特殊定制。

我一般走第一条。下面给一个最小可复现的编译流程（以 Linux 为例，Windows 用对应的 MSVC 命令即可）：

# 1. 拿到 SqliteCipher 的 amalgamation（sqlite3.c / sqlite3.h） # 放到 Qt 源码对应目录，覆盖原文件 cp sqlite3.c $QTSRC/qtbase/src/3rdparty/sqlite/sqlite3.c cp sqlite3.h $QTSRC/qtbase/src/3rdparty/sqlite/sqlite3.h # 2. 只重新编译 sqlite 插件，不用全量重编 Qt cd $QTSRC/qtbase/src/plugins/sqldrivers/sqlite qmake make -j4 # 3. 产物替换到运行时的 sqldrivers 目录 # Linux: libqsqlite.so Windows: qsqlite.dll cp libqsqlite.so $QT_INSTALL/plugins/sqldrivers/

逻辑说明：第 1 步是把加密版 SQLite 源码塞进 Qt 的第三方目录，Qt 编译驱动时会自动把它编进去。第 2 步只编 sqlite 这一个插件，几分钟就完事，不用等整个 Qt。第 3 步把新驱动放到 Qt 运行时能找到的sqldrivers目录，程序启动时加载的就是加密版。

参数说明：$QTSRC是你的 Qt 源码根目录，$QT_INSTALL是 Qt 安装目录（qmake -query QT_INSTALL_PLUGINS能查到）。注意驱动版本要和 Qt 版本严格对应，5.15 的驱动别拿去给 6.x 用，ABI 对不上会直接崩。

2.3 验证驱动是否真的带加密

编完别急着写业务，先验证。最直接的办法是建一个带密钥的库，然后用标准工具去开，看能不能读出数据。

#include <QSqlDatabase> #include <QSqlQuery> #include <QSqlError> #include <QDebug> int main() { QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE", "verify"); db.setDatabaseName("enc_test.db"); if (!db.open()) { qDebug() << "open failed:" << db.lastError().text(); return -1; } QSqlQuery q(db); // 关键：open 之后、任何其他操作之前，先设密钥 if (!q.exec("PRAGMA key = 'my_secret_key_123'")) { qDebug() << "set key failed:" << q.lastError().text(); return -1; } // 触发一次真实读写，确认密钥生效 q.exec("CREATE TABLE t(id INTEGER PRIMARY KEY, v TEXT)"); q.exec("INSERT INTO t(v) VALUES('hello')"); q.exec("SELECT count(*) FROM t"); if (q.next()) qDebug() << "rows:" << q.value(0).toInt(); db.close(); return 0; }

逻辑说明：PRAGMA key必须在open()之后、任何建表/查询之前执行，顺序错了密钥就不生效。执行完建表插入后，用 DB Browser for SQLite 打开enc_test.db，如果提示「file is not a database」或者全是乱码，说明加密生效了；如果能正常看到t表和hello，说明你的驱动还是明文版，回去检查驱动替换那步。

参数说明：密钥字符串建议用足够长度、带随机性的内容，别用123456这种。SqliteCipher 默认用 AES-256，密钥长度不够会被内部 KDF 补齐，但熵太低等于没加密。

3. 打开多个数据库与 ATTACH 跨库查询的落地写法

3.1 多库的两种组织方式：多连接 vs 单连接多 ATTACH

Qt 里同时用多个库，有两种思路，别混用。

第一种是多个QSqlDatabase连接，每个库一个连接名。适合库之间完全独立、不需要 JOIN 的场景，比如主库和日志库各写各的。缺点是跨库查询做不了，因为 SQLite 的 JOIN 只能在同一连接内。

第二种是单连接 +ATTACH DATABASE。一个连接打开主库，再把其他库 attach 进来，之后就能main.tableA JOIN log.tableB这样跨库查。这是做跨库查询的唯一正路。

我一般这么分：需要跨库 JOIN 的，用 ATTACH；纯粹隔离、互不相关的，用多连接。下面重点讲 ATTACH，因为这是标题里「附着数据库跨库查询」的核心。

3.2 ATTACH 的完整代码与别名规则

#include <QSqlDatabase> #include <QSqlQuery> #include <QSqlError> #include <QDebug> bool setupMultiDb() { QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE", "main_conn"); db.setDatabaseName("main.db"); if (!db.open()) { qDebug() << "open main failed:" << db.lastError().text(); return false; } QSqlQuery q(db); // 主库密钥 if (!q.exec("PRAGMA key = 'main_key_abc'")) { qDebug() << "main key failed:" << q.lastError().text(); return false; } // 附着日志库，别名 logdb；被附着的库同样要设密钥 if (!q.exec("ATTACH DATABASE 'log.db' AS logdb KEY 'log_key_xyz'")) { qDebug() << "attach failed:" << q.lastError().text(); return false; } // 跨库查询：主库订单表 JOIN 日志库操作记录表 if (!q.exec("SELECT o.id, o.amount, l.op_time " "FROM main.orders o " "JOIN logdb.op_log l ON l.order_id = o.id " "WHERE o.amount > 100")) { qDebug() << "cross query failed:" << q.lastError().text(); return false; } while (q.next()) { qDebug() << q.value(0).toInt() << q.value(1).toDouble() << q.value(2).toString(); } return true; }

逻辑说明：ATTACH DATABASE 'file' AS alias KEY 'key'这一句同时完成了附着和设密钥。别名logdb之后就是跨库查询里的库前缀。注意主库用main前缀（SQLite 默认主库别名就是main），被附着的库用你起的别名。JOIN 时两边都要带库前缀，否则 SQLite 不知道去哪个库找表。

参数说明：KEY子句是 SqliteCipher 扩展的语法，标准 SQLite 的ATTACH没有KEY。如果你的驱动没编进加密能力，这句会报语法错误——这也是判断驱动是否生效的一个旁证。别名不要用main、temp这些保留名，会冲突。

3.3 跨库查询的性能边界与索引

跨库 JOIN 在 SQLite 里本质是把两个库的文件都打开，查询计划器统一优化。它没有分布式查询那套网络开销，但有两个现实约束。

一是索引必须建在各自的库里。logdb.op_log的order_id上要单独建索引，主库的orders.id是主键自带索引。跨库 JOIN 时，SQLite 会分别用各自库的索引，不会因为你 attach 了就自动帮你建。

二是事务跨库要小心。SQLite 的ATTACH之后，一个事务可以同时写多个库，但前提是这些库在同一个连接、且没有其他连接持有写锁。多线程下如果两个线程分别操作主库和日志库，很容易撞锁。常见做法是：跨库写操作串行化，或者干脆把跨库写拆成「先写主库、再写日志库」两步，各自独立事务。

-- 在日志库里单独建索引，跨库 JOIN 才快 CREATE INDEX IF NOT EXISTS idx_oplog_order ON op_log(order_id); -- 跨库查询前先看执行计划，确认走了索引 EXPLAIN QUERY PLAN SELECT o.id FROM main.orders o JOIN logdb.op_log l ON l.order_id = o.id;

逻辑说明：EXPLAIN QUERY PLAN会告诉你 SQLite 打算怎么执行这条跨库查询。如果输出里出现SCAN而不是SEARCH ... USING INDEX，说明索引没生效，十万条数据级别的表就会明显卡。参数说明：索引建在被 JOIN 的那一列上，order_id是关联键，必须建。

4. 加密库的密钥管理、迁移与避坑排查

4.1 密钥不能硬编码，那放哪

PRAGMA key的密钥如果直接写死在代码里，等于没加密——逆向一下字符串就拿到了。常见做法是：密钥由用户口令派生（PBKDF2 之类），或者存在系统凭据管理器里，程序启动时取出来。Qt 里可以用QSettings存加密后的密钥，但QSettings本身不加密，只能算混淆。更稳的是结合平台凭据 API，或者让用户每次启动输入口令。

这里有个血泪经验：密钥一旦丢失，SqliteCipher 的库是无法恢复的，没有后门。所以密钥备份策略要和数据库备份一起考虑，别只备份了.db文件，密钥没备份，等于备份了一堆废纸。

4.2 明文库迁移到加密库

已经上线的明文库要转加密，不能直接改PRAGMA key，那样只会让文件损坏。正确做法是用sqlcipher_export或者 ATTACH 导出。

-- 打开明文库，attach 一个加密库，把数据导过去 ATTACH DATABASE 'enc_new.db' AS enc KEY 'new_key'; SELECT sqlcipher_export('enc'); DETACH DATABASE enc;

逻辑说明：sqlcipher_export是 SqliteCipher 提供的函数，把当前连接的主库内容整体导出到指定别名库。导完新库就是加密的，旧明文库确认无误后再删。参数说明：导出前确保没有未提交事务，导出过程中别让其他连接写主库。

4.3 避坑排查：五个真实踩过的坑

现象一：PRAGMA key执行成功，但 DB Browser 能直接打开。原因：驱动还是标准 SQLite，PRAGMA key被当未知语句忽略了。 解决：按 2.2 重新编译并替换qsqlite驱动，用 2.3 的方法验证。

现象二：ATTACH ... KEY报语法错误。原因：驱动不带 SqliteCipher 扩展，标准 SQLite 不认KEY子句。 解决：同上，确认驱动版本；或者改用先 attach 再对附着库单独PRAGMA的写法（部分版本支持）。

现象三：跨库查询报no such table: logdb.op_log。原因：attach 的别名写错，或者被附着的库路径不对（相对路径基准是进程工作目录，不是主库目录）。 解决：attach 用绝对路径，别名和查询里保持一致，先PRAGMA database_list看当前挂了哪些库。

现象四：多线程下偶发database is locked。原因：多个连接同时写同一个库，SQLite 写锁是库级的。 解决：写操作集中到一个连接串行执行，或开启 WAL 模式提升并发读；跨库写拆成独立事务。

现象五：程序换台机器后打不开加密库。原因：密钥派生依赖了机器相关的东西（比如机器码），换机后派生结果变了。 解决：密钥派生不要绑定硬件，用用户口令 + 固定 salt，salt 存在库文件旁边单独管理。

5. 进阶：用事务和 WAL 把多库读写压到稳定

跨库场景真正难的不是「能不能查」，而是「并发写稳不稳」。我一般会做三件事。

第一，主库开 WAL。WAL 模式下读不阻塞写、写不阻塞读，多库场景下读多写少的业务提升明显。

PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL;

synchronous = NORMAL在 WAL 下是安全性和性能的平衡点，比FULL快不少，掉电最多丢最后一个事务，多数桌面业务能接受。

第二，跨库写用显式事务包起来，并且控制顺序。SQLite 在 attach 多库时，一个事务内可以写多个库，但锁的获取顺序会影响死锁概率。固定「先主库、后日志库」的顺序，能避免两个连接交叉持锁。

QSqlQuery q(db); db.transaction(); q.exec("INSERT INTO main.orders(id, amount) VALUES(1, 200)"); q.exec("INSERT INTO logdb.op_log(order_id, op_time) VALUES(1, datetime('now'))"); if (!db.commit()) { db.rollback(); qDebug() << "commit failed:" << db.lastError().text(); }

第三，验证。别只看代码跑通，要压一下。十万条数据量级下，跨库 JOIN 带索引通常在几十毫秒内；如果超过一秒，先看EXPLAIN QUERY PLAN是不是全表扫描，再看是不是没开 WAL 导致读写互相等。我自己习惯在提交前跑一遍PRAGMA integrity_check，确认加密库没被写坏——这个习惯帮我拦下过两次因为密钥设错导致的静默损坏。加密库一旦密钥对不上，SQLite 不会立刻报错，而是当成空库或损坏库，等你发现时数据已经写乱了。所以每次改密钥逻辑，先拿测试库验证，别直接上生产。希望帮到你。

本文还有配套的精品资源，点击获取