SiYuan 加密笔记本深度解析：本地数据加密、密钥管理与隐私保护完全指南-育师

SiYuan 加密笔记本深度解析：本地数据加密、密钥管理与隐私保护完全指南

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

SiYuan（思源笔记）是一款开源、隐私优先的自托管知识工作空间，其加密笔记本功能可将本地数据全盘加密：.sy文档、资源文件、数据库文件和 SQLite 索引在磁盘上全部以密文存储，通过主密码和密钥包络机制管理，即使设备丢失或磁盘数据被恢复，没有主密码也只能看到乱码密文。本文将从加密原理、密钥管理、隐私边界到日常使用习惯，带你完整看懂这项隐私保护能力。

🔐 什么是加密笔记本：你的"本地数据保险箱"

在 SiYuan 中，加密笔记本是一种特殊笔记本：创建时输入主密码，之后该笔记本下的所有内容都加密落盘。它与普通笔记本的关键区别如下：

维度	普通笔记本	加密笔记本
`.sy`文档	明文 JSON 落盘	AES-256-GCM 密文落盘，读时透明解密
assets 资源文件	明文二进制 + 原始文件名	密文存储，文件名脱敏（原始名加密保存）
SQLite 索引库	写入全局`siyuan.db`	每个加密笔记本独立 SQLCipher 加密库
全局搜索 / 关系图	参与	完全不参与（数据物理隔离）
打开方式	直接打开	需输主密码解锁（约 1 秒密钥派生）

一句话理解：加密笔记本是一个"孤岛"——数据物理隔离、操作走专用入口、普通笔记本零影响。完整的设计规格见官方文档 docs/ENCRYPTED-NOTEBOOK.zh-CN.md。

🗝️ 本地数据加密原理：KEK + DEK 双层密钥架构

SiYuan 加密笔记本采用业界标准的**包络加密（Envelope Encryption）**架构，这也是"密钥管理"的核心：

用户主密码 │ Argon2id（64MB 内存硬度，抗暴力破解） ▼ KEK（密钥加密密钥，仅存内存，用完即弃） │ AES-256-GCM 包络 ├─→ 解开 DEK₁ → 加密笔记本 1 的全部数据 └─→ 解开 DEK₂ → 加密笔记本 2 的全部数据

KEK：由主密码经 Argon2id 派生（OWASP 推荐算法），只用于解开各笔记本的 DEK，从不触碰数据本身；
DEK：每个加密笔记本独立生成一把 32 字节随机密钥，真正用于加密.sy、assets、数据库文件；
改密码极快：修改主密码只需重新"包络"各 DEK，无需重新加密任何文档，秒级完成；
KEK 用完即弃：每次解锁都重新派生，解锁笔记本 A 绝不影响笔记本 B 的锁定状态，隔离性极强。

全局密钥参数（MasterSalt、KEK 校验器、Argon2 参数）由 kernel/conf/notebook_crypto.go 中的NotebookCrypto结构体维护并随conf.json持久化；数据文件层面的透明加解密由 kernel/filesys/crypto_hook.go 的DEKProvider回调注入实现——读盘后解密、写盘前加密，对上层完全透明；密码派生与密钥生命周期管理在 kernel/model/crypto.go 中实现，对外 API 入口见 kernel/api/notebook.go。

📦 加密范围全表：什么被加密，什么不会被

类别	是否加密保护
`.sy`文档正文（含自定义属性）	✅
assets 二进制内容 + 原始文件名	✅
数据库（数据库）文件（列/行/视图配置）	✅
content 与 blocktree 两个 SQLite 索引库	✅（SQLCipher）
历史目录中的`.sy`与数据库快照	✅（密文原样存储）
`conf.json`中的 MasterSalt / 校验器	❌（设计上 salt 不保密，verifier 是密文）
元数据（文件数量、目录结构、文件大小、修改时间、资源扩展名）	❌（加密不掩盖元数据）

值得注意的细节：加密笔记本的 SQLite 索引物理独立于全局库（siyuan-encrypted-<boxID>.db），因此它天然不参与全局全文搜索、语义搜索、嵌入向量化和关系图——这是"数据不进出孤岛"的底层保障：

🛡️ 隐私保护细节：隔离设计与安全边界

SiYuan 为加密笔记本设计了多层隐私边界（详见 docs/ENCRYPTED-NOTEBOOK.zh-CN.md §9-§12、§16）：

跨边界引用被禁止：普通 ↔ 加密、加密 A ↔ 加密 B 之间的块引、文档移动、数据库镜像全部被拒绝（落库前还会做兜底校验，跨边界引用自动降级为纯文本）；
原始文件 API 全拦截：/api/file/getFile等通用接口拒绝读写加密笔记本下的任何文件，防止密文泄漏或明文破坏；
AI/LLM 可见性由解锁状态决定：锁定后 AI、MCP、智能体均无法读取；解锁后与普通笔记本一致——官方建议的安全习惯就一条：敏感内容用完即锁；
重启即锁定：DEK 只存在于进程内存，应用重启后所有加密笔记本强制关闭，需重新输主密码；
锁定即清理：关闭笔记本会撤销受管 DEK 句柄、删除加密 SQLite 库，并尽力清理内核管理的明文缓存与临时文件。

需要清醒认识到的安全边界：加密保护的是静态数据机密性和锁定后的不可达性。解锁期间已授权的应用内调用方（API、插件、AI）可读明文；操作系统交换区、崩溃转储等瞬时副本不在承诺范围内。因此官方建议：日常笔记放普通笔记本，只把真正敏感的内容（隐私日记、财务记录、工作机密、医疗信息）放进加密笔记本。

📱 密钥管理：备份、跨设备恢复与修改密码

忘记密码 = 数据永久不可恢复（没有后门），所以密钥备份是密钥管理的第一要务：

自动备份：启用加密或修改密码时，整套密钥材料（MasterSalt / 校验器 / KDF 参数）会刷新到<DataDir>/.siyuan/notebook-crypto-backup.json，并随数据同步进入云端；
跨设备恢复零操作：新设备完成同步后，密钥备份自动拉取、内核自动恢复"已启用"状态，直接输主密码即可解锁，无需手动"启用"；
手动导出/导入：在设置 → 访问授权 → 加密笔记本可手动导出/导入密钥备份文件，作为同步之外的独立恢复途径（跨账号迁移、离线转存）；
备份完整性校验：备份文件带 SHA-256 校验和与 KEK HMAC，损坏或被篡改会被安全拒绝，不会静默放行；
修改主密码：即时完成（仅重新包络 DEK），备份自动刷新。注意官方明确提示：改密不能吊销旧主密码的解密能力，若怀疑旧密码泄露，应把内容迁移到新建加密笔记本（新 DEK）。

🚀 上手步骤：三步启用加密笔记本

启用：进入设置 → 访问授权 → 加密笔记本，打开开关并设置主密码（双输入确认 + 风险确认）。建议 12 位以上，混合大小写、数字与符号，并用密码管理器保存；
创建：在文件面板"更多"菜单中选择"新建加密笔记本"，输入名字 + 主密码，自动解锁并打开；
日常使用：点击锁定的笔记本 → 输主密码 → 等待约 1 秒（Argon2id 派生）→ 打开；关闭笔记本即锁定。用完即锁是最重要的安全习惯。

导入.sy.zip/ Markdown 会自动加密落盘；导出需先解锁、导出的是明文，锁定状态下拒绝导出。功能上需注意的边界：加密笔记本不支持闪卡、书签、标签和资源文件重命名（详见设计文档 §14 功能限制）。

✅ 总结：一张表看懂 SiYuan 加密笔记本

关注点	结论
加密算法	AES-256-GCM（数据）+ Argon2id（密钥派生）+ SQLCipher（索引库）
密钥架构	主密码 → KEK（内存）→ 每笔记本独立 DEK，改密秒级
隐私边界	孤岛式隔离，不进全局搜索/关系图/AI 嵌入，跨边界操作全部拒绝
恢复能力	密钥备份随同步自动分发，跨设备零操作恢复；主密码丢失不可恢复
适合场景	隐私日记、财务/医疗记录、工作机密
不适合场景	需要全局搜索、跨笔记本引用的日常知识网络

SiYuan 的加密笔记本用"包络加密 + 物理隔离 + 尽力清理"三件套，在完全本地的前提下提供了接近企业级的数据保护——这也是其"隐私优先、自托管"定位的核心体现。更多项目介绍可参阅 README.zh-CN.md，密钥与同步相关实现见 kernel/model/conf.go 与 kernel/conf/box.go。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考