Thunderbolt零知识同步架构完全指南：后端只存密文的端到端加密设计

Thunderbolt零知识同步架构完全指南：后端只存密文的端到端加密设计

【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderbolt

Thunderbolt是一款开源的自托管 AI 客户端，支持端到端加密的多设备同步。它的核心承诺是：启用零知识同步后，后端服务器只存储密文与包装密钥（wrapped keys），连管理员也无法读取你的聊天记录、模型配置和自动化任务。本文将带你用通俗的方式看懂这套密码学设计：内容密钥（Content Key）、ECDH + ML-KEM 混合信封、24 词恢复密钥，以及让服务器"自证清白"的金丝雀机制 🛡️。

一、零知识同步：服务器"看得见"的只有密文

Thunderbolt 的跨设备同步基于 PowerSync：每台设备本地有一个 SQLite 数据库，PowerSync 服务在 SQLite 与后端 PostgreSQL 之间流转增量数据。完整说明见 docs/architecture/multi-device-sync.md。

如果数据原样上传，服务器就能读取一切。Thunderbolt 的做法是在同步管道中插入一层加密中间件：

• 下载时：密文在写入本地 SQLite 之前先解密，本地数据库永远是明文，应用体验零损耗；
• 上传时：明文在离开本地之前先加密，服务器上只落密文。

加密的开关只有一个后端环境变量E2EE_ENABLED（默认关闭），前端在启动时从GET /v1/config读取该标志并缓存到localStorage，见 src/db/encryption/config.ts。关闭时自动信任设备、跳过信封流程；开启后则必须完成"设备信任"流程才能同步——这正是零知识安全模型的分界线。

二、密钥层级：一把内容密钥，N 个设备信封

整个设计围绕一个概念展开——内容密钥（Content Key, CK）：每个账号只有 1 把AES-256-GCM密钥，负责加密该账号的全部用户数据，在所有设备间保持一致。

每台设备再各自生成两把密钥对，私钥永远不出设备：

用一张简图表达"一钥多信封"的关系（源自 docs/architecture/e2e-encryption.md）：

┌──────────────┐ │ CK │ 一把密钥，加密所有记录 └──────┬───────┘ 为每台设备单独包装信封 ┌─────────────┬──────┴──────┐ ▼ ▼ ▼ 设备1的信封 设备2的信封 设备3的信封 │ │ │ 用私钥1解包 用私钥2解包 用私钥3解包 ▼ ▼ ▼ 同一个 CK 同一个 CK 同一个 CK

这就是零知识的关键：服务器存的是 N 个互相独立的信封，任何一个信封都不暴露 CK 本身。撤销一台设备，只需删除它的信封，那台设备立刻再也解不出数据。

三、混合信封：经典 ECDH 撞上后量子 ML-KEM

信封是怎么"包装"CK 的？核心实现在 src/crypto/primitives.ts：

1. 发送方生成一个临时 ECDH P-256 密钥对，与目标设备的公钥算出共享秘密 ①；
2. 同时用目标设备的ML-KEM-768公钥做后量子封装，得到共享秘密 ②；
3. 两个共享秘密经HKDF-SHA256派生出一把临时 AES-KW-256 包装密钥；
4. 用这把临时密钥对 CK 做AES-KW包裹，最终信封结构为：[版本1B][临时公钥65B][ML-KEM密文1088B][包裹后的CK 40B]。

这套组合叫混合密钥封装，安全性质是：只要 ECDH 和 ML-KEM 中任意一个没被攻破，信封就安全。换句话说，未来即使量子计算机破解了 ECDH，ML-KEM 依然守得住 CK——这是典型的"防未来量子"设计。

四、设备流转：新设备如何安全拿到密钥

零知识架构下，CK 绝不能由服务器中转。Thunderbolt 为每种场景设计了独立流程（见 docs/architecture/e2e-encryption.md）：

新增设备必须经过"受信设备批准"这一步，意味着密钥分发永远发生在设备与设备之间的信任链里，服务器只是信封的"信箱"，不是"钥匙"。相关后端路由（设备注册、信封管理、金丝雀校验）集中在 backend/src/api/encryption.ts，且限制每账号最多 10 台设备。

五、金丝雀与恢复密钥：如何证明"这 24 个词是对的"

恢复密钥是最后一道保险，但它只会在屏幕上出现一次。写坏了、记岔了一个词怎么办？

金丝雀（canary）解决的就是验证问题。首次设置时，客户端生成一个随机机密，拼上固定前缀thunderbolt-canary-v1:<secret>后用 CK 加密，把密文存到服务器（实现见 src/crypto/canary.ts）。恢复流程中：

1. 客户端把 24 词通过 BIP-39 解码回 32 字节 CK（见 src/crypto/recovery-key.ts）；
2. 用这把 CK 解密金丝雀；
3. 前缀正确 → 密钥必然正确；顺便把解出的canarySecret作为持有证明提交给服务器（后端只存其哈希，无法反推）。

这样服务器能确认"用户确实拥有恢复密钥"，却始终不知道 CK 是什么。

六、明文去哪了：同步管道中的加密中间件

数据面则由encryptedColumnsMap这张"加密清单"统一驱动（见 src/db/encryption/config.ts）：

• chat_messages的content、parts、metadata
• models的name、url、vendor
• prompts、tasks、skills、projects的全部用户自创内容
• ……

新增一个加密列，只需在清单里加一行，下载解密与上传加密自动生效。密文在传输线上的格式统一为__enc:<iv>:<ciphertext>。

不同运行时的执行位置略有差异，详见 docs/architecture/powersync-sync-middleware.md：

两条路径殊途同归：最终写入本地 SQLite 的都是明文，而网络上和服务器上的永远是密文。

七、这套设计能对抗什么？

把各部件串起来，可以清晰地回答"威胁模型"：

• 🔓服务器被入侵：数据库里只有密文和信封，没有 CK，攻击者拿不到明文；
• 🏛️法律强制披露：后端架构上就不持有可读数据，"想给也给不了"；
• 🤖未来量子计算机：混合信封保证经典 + 后量子双保险；
• 📵设备丢失：在其余设备上撤销该设备，删除信封即永久失效；
• 💾全设备丢失：24 词恢复密钥 + 金丝雀验证，数据可完整找回。

⚠️ 需要说明：Thunderbolt 的端到端加密目前处于Preview阶段，尚未经历独立密码学审计（见 docs/architecture/e2e-encryption.md）。请妥善保管你的 24 词恢复密钥——它是唯一能救回全部数据的东西。

八、延伸阅读：源码与文档导航

想深入源码？按这条路线走最快：

一句话总结：Thunderbolt 的零知识同步 = 一把 CK 管所有数据 + 混合后量子信封把 CK 逐台设备安全送达 + 金丝雀兜底验证恢复密钥。后端从头到尾只是一个"存信封的仓库"——这就是"AI You Control"在密码学层面的真实含义 ⚡。

【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderbolt