Monica

简体中文

English
日本語
Tiếng Việt
Русский

简体中文

English
日本語
Tiếng Việt
Русский

主题

JoyinJoester2026-05-30
1868
6.8m

MDBX 产品规范 ​

版本：MDBX-1-DRAFT

本文中的 MUST、MUST NOT、SHOULD、SHOULD NOT、MAY 按 RFC 2119 语义理解。

1. 摘要 ​

MDBX 是一种本地优先的加密密码数据库格式与实现架构。 它的目标是解决 KDBX 在网盘同步、冲突处理、大库性能、附件膨胀、长期维护性方面的痛点。

MDBX 必须以 project 作为密码组织主容器，并且必须在数据库层原生支持附件。 这两个属性属于基础架构约束，不是可选增强项。

2. 产品目标 ​

MDBX 必须同时实现以下目标：

  • 完全离线可打开、可编辑、可搜索、可导出、可恢复
  • 长期可读、可迁移、可归档
  • 小修改保存成本低、同步成本低
  • 避免 KDBX 常见的全文件重写模式
  • 支持多设备编辑同一 vault，并对冲突进行明确处理
  • 支持附件，但不能让普通编辑被大附件拖慢
  • 具备现代安全默认值和可切换的 Tiga 安全状态

3. 非目标 ​

MDBX 不要求：

  • 中心同步服务器
  • 专有云后端
  • 永久在线协作
  • 不透明且无文档的私有二进制格式
  • 对云存储提供方完全隐藏所有元数据

4. 核心原则 ​

4.1 本地优先 ​

MDBX 实现必须允许用户在无服务器条件下完成创建、读取、更新、删除、搜索、导出、备份、恢复。

4.2 4ever and 4ever ​

格式必须优先保证长期稳定。 新版本必须能读取旧版本。 在可能情况下，旧实现应能安全忽略未知但非关键的新字段。 实现不得在迁移中故意让用户数据变成孤岛；数据安全优先于便利性、清理和格式简化。

4.3 Tiga 三安全状态 ​

MDBX 必须支持三档安全模式：

  • power
  • multi
  • sky

这些模式必须影响密码学参数、缓存行为和便利性能力。 兼容性显示名可以使用：Power Type、Multi Type、Sky Type。 语义映射为：power = 最高防护，multi = 平衡默认，sky = 灵活便携但仍然安全。 细节见 03-security-spec.md 与 03-security-spec.zh-CN.md。

4.4 类 Git 冲突防止机制 ​

MDBX 必须保留足够的历史和因果元数据，用于检测并发修改，并安全合并无冲突变更。

4.5 性能必须明显优于 KDBX ​

MDBX 必须在真实世界 vault 中实现明显优于 KDBX 的保存、加载、搜索、云盘同步体验。

5. MDBX 必须解决的 KDBX 核心痛点 ​

MDBX 的存在意义之一，就是改善以下方面：

  • 同步冲突和合并困难
  • 单库损坏影响面太大
  • 全文件重写成本高
  • 大附件导致文件体积和同步压力过大
  • 跨客户端兼容语义不清
  • 某些生态下默认安全参数不足
  • 多设备频繁编辑体验差
  • 大库性能明显下降

6. 主领域模型 ​

6.1 以 Project 为中心的存储模型 ​

密码必须按 project 存储。 单纯的无序平铺密码条目袋模型不符合规范。

project 是用户可感知的主单位。 例如：

  • 一个网站账号
  • 一个公司工作空间
  • 一个银行关系
  • 一个 App 账号
  • 一个基础设施环境
  • 一个个人身份包

一个 project 可以包含：

  • 一个或多个登录条目
  • 一个或多个安全笔记
  • 一个或多个卡片或身份记录
  • 一个或多个 TOTP 或 Passkey 记录
  • 零个或多个附件
  • 标签、分组、收藏、归档等元数据

6.2 Entry 模型 ​

entry 是 project 内部的具体类型化记录。 推荐的 entry 类型包括：

  • login
  • note
  • card
  • identity
  • totp
  • passkey
  • ssh-key
  • api-token
  • document-ref

实现可以把少量项目级摘要字段直接放在 project 对象上以加速 UI，但不能破坏 project -> entry 层级关系。

6.3 Attachment 模型 ​

MDBX 从版本 1 起就必须为附件预留原生数据库结构。 附件不能被当成未来再说的扩展点。

每个附件至少必须拥有：

  • 稳定的附件 ID
  • 归属的 project ID
  • 可选的 entry ID
  • 加密元数据
  • 完整性 hash
  • 大小元数据
  • 媒体类型元数据
  • 存储模式元数据
  • 创建和更新时间元数据

附件存储模式可以包括：

  • 小附件内嵌
  • 分块内嵌
  • 外部引用但以内容 hash 绑定

即使 MVP 只支持其中一部分模式，附件元数据 schema 也必须先定义好。

7. 必需对象类型 ​

最小对象模型必须包含：

  • project
  • entry
  • attachment
  • tombstone
  • commit
  • branch-ref
  • device-ref
  • snapshot

推荐但可后续加入的对象类型：

  • group
  • conflict
  • key-epoch
  • audit-event
  • plugin-state

8. Project 对象要求 ​

project 对象必须具备足以支持以下能力的字段：

  • 稳定身份标识
  • 显示标题
  • 描述或说明引用
  • 分组/文件夹归属
  • 标签
  • 收藏或置顶状态
  • 归档或回收站状态
  • 当前对象版本元数据
  • 附件摘要元数据

project 最好能够在不解密全部子 entry 的前提下渲染列表和概览。

9. Entry 对象要求 ​

entry 对象必须包含：

  • 稳定 entry ID
  • 父级 project ID
  • entry 类型
  • 加密字段载荷
  • 字段级或记录级版本元数据
  • 创建和修改时间元数据
  • 删除状态

如果某种 entry 含有秘密字段，那么同一秘密字段的并发冲突绝不能静默自动合并。

10. Attachment 对象要求 ​

attachment 对象至少必须支持以下元数据字段：

  • attachmentId
  • projectId
  • entryId 可空
  • fileName 加密
  • mediaType 加密或采用隐私安全编码
  • originalSize
  • storedSize
  • contentHash
  • storageMode
  • chunkCount
  • createdAt
  • updatedAt
  • deleted

即使未来附件的具体二进制存储方式演进，附件元数据结构也应尽量保持稳定。

11. 用户体验要求 ​

符合规范的产品最好向用户清晰暴露以下概念：

  • 当前 Tiga 模式
  • vault 同步状态
  • project 列表
  • project 详情
  • 附件存在与否
  • 历史版本或变更状态
  • 冲突状态

用户必须能够清楚知道哪些秘密属于哪个 project。

12. 导入与迁移 ​

KDBX 导入必须映射到 project 模型。

默认映射规则：

  • 一个导入的逻辑项变成一个 project
  • 主密码/登录数据变成一个 entry
  • 笔记、TOTP、Passkey、卡片、补充材料变成同一 project 下的兄弟 entry 或子类型记录
  • 导入的文件变成 attachment 对象

如果源格式本身没有明确 project 语义，导入器也必须以确定性方式构造 project。

13. 兼容性规则 ​

未来的 MDBX 版本必须保留以下不变量：

  • project 仍是一等主容器
  • 附件元数据仍是一等结构
  • 低版本能检测不支持的关键扩展
  • 非关键未知字段可被保留
  • 迁移前、迁移中、迁移后都必须保持旧 vault 可读
  • 除非用户明确选择更严格的 Tiga 策略，否则便携解锁路径应保持可用

14. 拒收规则 ​

以下设计一律视为不符合规范：

  • 整个 vault 只有 entry，没有 project 主容器
  • 附件处理没有被明确定义
  • 日常小修改默认要重写整个 vault
  • 正常本地状态依赖服务器才能成立
  • 同一秘密字段冲突被静默自动合并
最近更新