6.0 KiB

Raw Blame History

用户数据备份设计（以导出/迁移为核心）

1. 背景与目标

本设计面向 person-panel 的“用户数据可携带性”场景，核心目标是让用户可以导出自己的文件与业务数据，并可用于后续迁移或恢复到兼容系统。

已确认目标与约束：

目标类型：用户可导出/迁移数据（非灾备优先）
交付形态：目录结构 + 清单 JSON
范围：用户全量业务数据（排除敏感凭据）
敏感策略：导出时可选原始/脱敏，默认脱敏

2. 设计原则

可迁移优先：导出格式稳定、可版本化、可校验
文件与数据一体：业务 JSON 与媒体文件同时导出
安全默认：默认脱敏，且永不导出高敏字段
一致性可解释：导出基于固定时间截点，避免数据漂移
演进兼容：通过 schemaVersion 管理未来格式升级

3. 总体架构

采用“异步导出任务 + 标准导出包”模式。

3.1 API 入口

POST /api/me/export/request
- 创建导出任务
- 参数：maskPolicy（masked | raw，默认 masked）
GET /api/me/export/tasks
- 查询当前用户导出任务列表与状态
GET /api/me/export/tasks/:id/download
- 下载导出结果（目录打包或直接目录挂载下载，按部署实现）

3.2 任务状态机

queued：任务已创建，待执行
running：导出中
succeeded：导出完成，可下载
failed：导出失败，包含错误信息
expired：产物过期被清理

3.3 一致性模型

任务进入 running 时写入 exportCutoffAt。所有 SQL 查询统一加上时间边界（可按表字段映射），保证导出结果在逻辑上对应同一时间点快照。

4. 导出包规范（v1）

4.1 目录结构

export-<userId>-<taskId>/
  manifest.json
  data/
    user.json
    profile.json
    timeline.json
    posts.json
    comments.json
    media-assets.json
    media-refs.json
    ...（其他用户归属资源）
  files/
    <storageKey 或分层路径>

4.2 manifest.json（关键字段）

schemaVersion: 1
exportedAt: 导出完成时间（ISO8601 UTC）
exportCutoffAt: 截点时间（ISO8601 UTC）
userId: 用户 ID
maskPolicy: masked 或 raw
stats: 各资源条数、文件数、总字节数
checksums:
- data: 每个 JSON 文件的 SHA256
- files: 每个文件的 SHA256 + 相对路径

4.3 编码与类型规范

JSON 使用 UTF-8
时间统一 ISO8601（UTC）
枚举保持稳定字符串值
布尔/数值不做字符串化

5. 数据边界与脱敏规则

5.1 导出范围（全量用户业务）

按“该用户可归属”原则导出：

用户基础信息（非敏感）
个人资料与配置
时间线、文章、评论等内容
媒体元数据（mediaAssets）与引用关系（mediaRefs）
其他用户域业务资源（按服务注册表补齐）

5.2 永不导出字段

无论 maskPolicy 取值，以下字段均不导出：

密码哈希与密码重置类 token
登录会话 token / 刷新 token
API 密钥、签名密钥、内部凭据
不可归属该用户的他人敏感数据

5.3 可配置脱敏字段

导出时支持策略切换：

masked（默认）：
- 邮箱：保留前后缀，隐藏中间
- 手机号：保留前 3 后 2
- IP：保留网段，隐藏主机位
- 设备标识：部分掩码
raw：
- 输出原值，但仍遵循“永不导出字段”排除规则

6. 文件导出策略（重点）

6.1 文件来源

从用户关联的 mediaAssets 读取 storageKey，在媒体目录（当前项目已有公开上传目录）中查找实体文件，复制到导出包 files/ 下。

6.2 文件-数据关联

data/media-assets.json 记录资产元数据与 storageKey
data/media-refs.json 记录 assetId 与业务对象关联
导入方据此可重建资源引用关系

6.3 完整性校验

每个导出文件生成 SHA256 写入 manifest.checksums.files。导入前可进行全量核验，防止传输损坏或篡改。

7. 执行流程与失败恢复

7.1 执行步骤

创建任务（queued）
Worker 抢占任务并置 running
记录 exportCutoffAt
分页导出各资源 JSON 到 data/
收集并复制媒体文件到 files/
计算校验并生成 manifest.json
置 succeeded 并返回下载能力

7.2 失败策略

任一步异常置 failed，记录 errorCode/errorMessage
任务目录按 taskId 隔离，失败不会污染其他任务
用户可重试，创建新任务而非复用失败产物

8. 安全与性能控制

8.1 安全控制

仅允许用户导出/下载自己的任务
下载链接短时有效（建议 10 分钟）
导出产物过期清理（建议 24~72 小时）
保留审计日志（发起人、时间、策略、结果）

8.2 性能控制

大表分页读取，避免内存峰值过高
文件复制并发数限流，避免 IO 打满
单用户同一时刻仅允许 1 个导出任务

9. 测试与验收标准

9.1 测试建议

单元测试：
- 字段白/黑名单过滤
- masked/raw 脱敏策略
- manifest 校验信息生成
集成测试：
- 用户全量导出流程（含媒体文件）
- 导出期间数据变动下的一致性行为
- 权限边界（越权访问导出任务）

9.2 验收标准

导出包包含该用户全量业务数据与关联文件
永不导出字段在任何策略下都不存在
masked 与 raw 行为符合预期
manifest 校验通过，引用关系可重建
中等数据量用户导出耗时在可接受范围

10. 分阶段落地计划（建议）

Phase 1：后端导出任务 + 导出包生成 + 基础下载
Phase 2：前端“数据导出中心”页面（发起、进度、下载、失败重试）
Phase 3：导入校验工具（离线校验 manifest 与文件完整性）

该设计聚焦“用户文件和数据可迁移”，优先保证格式稳定、数据完整与安全边界，便于后续演进到导入能力与跨环境迁移能力。

6.0 KiB Raw Blame History