📦 Monica WebDAV 备份格式规范

摘要

本规范定义了 Monica 本地密码库在进行 WebDAV 自动化备份与数据流转时的归档结构、底层数据格式及加密协议。本规范旨在确保数据的跨平台解析能力与极致的隐私安全。

---

1. 概述

Monica 的 WebDAV 备份机制会将用户选定的核心数据打包成一个标准的 ZIP 压缩包（未加密时为 .zip，启用高强度备份加密时为 .enc.zip）。

该备份包内部摒弃了传统冗余的二进制数据库直接导出方案，采用了由 .json 核心数据、.csv 汇总文件 和 媒体资源（Images） 组成的松耦合结构，便于未来的跨平台数据审计与精确恢复。

---

2. 备份包目录结构

一个标准的备份 ZIP 包解压后的目录树状结构如下所示：

/ (根目录)
├── passwords/                  # 密码条目数据（高内聚分开存储）
│   ├── password_1_1700000.json
│   └── password_2_1700001.json
├── notes/                      # 笔记条目数据
│   └── note_5_1700002.json
├── images/                     # 图片资源（如加密存储的证件照、附件等）
│   └── image_20240101.jpg
├── trash/                      # 回收站归档（支持软删除数据恢复）
│   ├── trash_passwords.json
│   └── trash_secure_items.json
├── categories.json             # 独立的全局分类排版信息
├── Monica_20240101_password.csv # 密码扁平化汇总（供人工查阅与兼容导出）
├── Monica_20240101_totp.csv     # TOTP 双重验证汇总
├── common_account.json         # 常用账号及自动填充配置
├── webdav_config.json          # WebDAV 当前节点连接配置（支持无缝迁移）
├── timeline_history.json       # 审计日志（操作时间线）
└── generated_history.json      # 强密码生成器历史记录

---

3. 详细文件格式规范

3.1 密码条目 (passwords/password_{id}_{timestamp}.json)

每个密码条目单独封装为一个独立的 JSON 文件，避免单一主文件损坏导致的密码库全面崩溃。

字段	类型	说明
id	Long	原始数据库 ID
title	String	密码项标题（如 Google）
username	String	账号 / 用户名
password	String	密码（明文或加密，取决于是否启用了整体备份加密）
website	String	关联网址 / Domain
notes	String	备注文本
isFavorite	Boolean	是否加入收藏夹
categoryId	Long?	所属分类 ID（可为空）
categoryName	String?	分类名称（用于跨设备异地恢复时自动重建分类树）
authenticatorKey	String	绑定的二阶段双重验证 (TOTP) 密钥
loginType	String	认证类型：PASSWORD（传统）或 SSO（单点登录）
ssoRefEntryId	Long?	SSO 关联的父级密码条目 ID

💡 点击查看密码条目完整 JSON 示例

{
  "id": 1,
  "title": "Google",
  "username": "user@gmail.com",
  "password": "mySecurePassword123",
  "website": "[https://accounts.google.com](https://accounts.google.com)",
  "notes": "个人主账号，包含重要的云端数据",
  "isFavorite": true,
  "categoryId": 2,
  "categoryName": "Social",
  "authenticatorKey": "NBSWY3DPEB3W64TBNQ======",
  "loginType": "PASSWORD",
  "ssoRefEntryId": null
}

3.2 笔记条目 (notes/note_{id}_{timestamp}.json)

字段	类型	说明
notes	String	笔记正文（支持 Markdown 或纯文本）
imagePaths	String	关联的图片文件名列表（多个文件以逗号 , 分隔）

3.3 配置文件汇总

categories.json

// 存储全局分类信息及其前端 UI 排序权重
[
  { "id": 1, "name": "Work", "sortOrder": 0 },
  { "id": 2, "name": "Social", "sortOrder": 1 }
]

common_account.json

// 存储用户在设置中配置的用于快速自动填充的个人信息面板
{
  "email": "myemail@example.com",
  "phone": "13800138000",
  "autoFillEnabled": true
}

webdav_config.json

// 用于新旧设备无缝迁移、接管 WebDAV 基础设施
{
  "url": "[https://dav.jianguoyun.com/dav/](https://dav.jianguoyun.com/dav/)",
  "username": "monica_user@dav.com",
  "encryptedPassword": "U2FsdGVkX19..." // ⚠️ 此密码会使用用户的“备份密码”进行二次硬件级加密
}

3.4 回收站机制 (trash/)

• trash_passwords.json：包含所有已进入回收站的密码条目，底层结构与普通密码一致，但额外追加了 deletedAt 高精度时间戳。
• trash_secure_items.json：包含已软删除的私密笔记、银行卡、安全密钥等其他扩展资产。

3.5 兼容性 CSV 文件 (*.csv)

TIP

这些 CSV 文件（如 Monica_20240101_password.csv）主要用于人工直接查阅或应对其他主流密码管理器的格式导入。Monica 自身的完整跨设备恢复逻辑完全不依赖 CSV，而是 100% 采用上面定义的 JSON 结构体。

---

4. 加密机制

当用户在应用的 设置 ➔ 备份设置 中启用 「备份加密」 时，数据流将切换至纯血安全防御模式：

[原始压缩数据流] ➔ [EncryptionHelper] ➔ [AES-256-GCM 加密] ➔ 导出为 .enc.zip 文件

1. 二进制流加密：整个标准 ZIP 文件的数据不会落地为明文，而是直接被视为原始二进制数据流。
2. 算法选型：采用具有认证加密特性的 AES-256-GCM 高阶算法，提供加密防窥与防数据篡改的双重校验能力。
3. 扩展名标识：加密生成的物理归档文件扩展名严格限定为 .enc.zip。
4. 二进制文件头 (Header)：文件头部固定包含专属魔法字节群：

• MONICA_ENC_V1（版本识别标识）
• 高熵随机 Salt（盐值）
• 随机 IV（初始化向量）

---

5. 跨设备恢复与冲突降级逻辑

数据恢复阶段，客户端应用将严格执行以下流水线生命周期：

1. 解密与验证：解码 .enc.zip ➔ 校验头部信息 ➔ 通过主密码派生密钥解密流 ➔ 释放至内存沙盒。
2. ID 冲突级联降级处理：

• 若解压读取的原 JSON id 在当前设备数据库中已存在，系统拒绝覆盖已有数据。
• 触发自动降级：为新拷贝生成全新物理 Long ID 插入数据库。

3. 关联关系重组（ID 映射修复）：

• 系统将自动扫描并建立一组 旧 ID ➔ 新 ID 的内存映射表。
• 自动修复 ssoRefEntryId、绑定账号与对应 TOTP 的关联关系，确保链接完好不中断。

4. 媒体归档转移：

• 自动解算 images/ 目录下的所有二进制资产。
• 安全地将图片与证件附件复制到当前设备应用的沙盒私有目录（context.filesDir），并重新绑定对应笔记的内置相对路径。