Logo

第 3 章 系统架构与数据流

本章从组件、数据对象与数据流三个层面解释 FileBolt 如何完成“客户端加密 / 服务端只处理密文”的零知识文件传输。 重点说明：哪些数据在客户端、服务端与对象存储中出现；哪些数据必须严格不出现（例如 CEK）；以及上传、下载与发送方审计的典型路径。

文档信息

白皮书版本
v1.0
最后更新
2026-01-14

上一章： 第 2 章 威胁模型与信任边界

3.1 组件概览

系统按职责分为客户端、应用服务端/API 与对象存储三部分，并在此基础上提供发送方管理与审计视图。

  • Web 客户端：分片、加密、上传；下载、校验、解密；生成与解析分享链接（含 fragment）。
  • 应用服务端 / API：创建 transfer、签发/校验 token、提供 manifest、控制密文访问、记录审计数据、执行撤销/删除。
  • 对象存储：保存密文分片（chunk objects）。
  • 发送方控制面板：仅发送方可访问的管理视图，用于撤销/删除与审计查看。

关键约束：服务端与对象存储只处理密文与必要元数据；CEK 只在客户端生成与使用，不进入服务端信任边界。

3.2 核心数据对象

系统对关键对象进行显式建模，便于实现访问控制、撤销与审计隔离。

  • Transfer：传输实体，由服务端生成 transferId；包含到期策略、访问控制策略与文件集合。
  • File：Transfer 内文件实体，包含 fileId 与公开参数（例如 cryptoVersion、noncePrefix、chunkSize）。
  • Chunk：密文分片对象，按 chunkIndex 编号存放在对象存储中。
  • Manifest：公开参数与分片映射集合，用于指导下载端获取分片并解密；不包含 CEK。
  • Audit：下载相关事件数据（计数/进度/时间等），仅发送方可见。

Manifest 的角色是“公开参数与映射索引”：它可以由服务端提供与存储，但其内容必须保持在零知识边界内， 不能包含 CEK 或任何可推导 CEK 的材料。

3.3 上传数据流

  1. 创建传输：客户端请求服务端创建 transfer；服务端 MUST 生成并返回 transferId。
  2. 签发上传 token：服务端 MUST 签发上传用短期访问 token（会话型、查表），并绑定 transferId、作用域与过期时间。
  3. 客户端生成密钥与参数：客户端为每个文件生成 CEK（16 字节）与 noncePrefix（8 字节安全随机），并确定 cryptoVersion 与 chunkSize。
  4. 分片与加密：客户端按固定 16MB 分片，并对每个分片执行 AES-128-GCM 加密；AAD 绑定上下文（详见第 5 章）。
  5. 上传密文分片：客户端使用上传作用域 token 上传密文分片；服务端与对象存储 MUST NOT 接触 CEK。
  6. 写入 manifest：客户端/服务端写入或更新 manifest（公开参数与分片映射）；manifest MUST NOT 包含 CEK。
  7. 生成分享链接：客户端构造最终分享链接：/transfer?k=<transferId>#<cek_b64url>；CEK 仅存在于 fragment。

上传链路中，服务端负责“身份与访问控制信号”（transferId、token、到期策略），客户端负责“密钥与加密”。 这是零知识边界成立的关键。

3.4 下载数据流

  1. 访问链接：下载方访问 /transfer?k=<transferId>#<cek_b64url>。
  2. 解析 CEK：客户端从 URL fragment 解析 CEK；fragment 不随 HTTP 请求发送到服务端。
  3. 获取 manifest：客户端向服务端请求 manifest；读取 manifest MUST 使用明确作用域的短期 token（例如 read_manifest）。
  4. 获取密文分片：客户端按 manifest 指示拉取密文分片；读取分片 MUST 使用不同作用域 token（例如 read_chunk）。
  5. 解密与校验：客户端逐片解密并验证 GCM tag；任何认证失败必须失败关闭，拒绝输出任何部分明文。
  6. 清理与最小化：客户端在解析 fragment 后 SHOULD 尽早移除地址栏 #...（例如 history.replaceState），并在完成后清理内存中的密钥材料。

下载链路实现了“双重门槛”：token 决定能否取得密文，CEK 决定能否解密密文。二者分离可降低单点泄露风险。

3.5 发送方管理与审计数据流

  • 发送方登录：发送方通过一次性 magic link 登录后获取长期登录 token，并存储于 localStorage。
  • 管理操作授权：删除 transfer、移除文件、查看审计信息等管理操作 MUST 使用长期登录 token 授权。
  • 审计隔离：审计数据（下载次数/进度等）仅对发送方可见；下载方 MUST NOT 通过任何 API/缓存/错误信息获得发送方视图数据。
  • 撤销：发送方删除 transfer 或移除文件后，服务端 MUST 拒绝相关资源继续访问（manifest/密文读取与 token 续期）。

审计能力必须与零知识边界一致：它不应要求记录 CEK 或明文内容，仅依赖密文层面的事件与最小化元数据。

3.6 数据可见性与最小化原则

为保证零知识承诺与降低泄露面，系统对数据可见性做强约束：

  • CEK：仅客户端可见；服务端/对象存储/日志/监控 MUST NOT 出现。
  • 明文内容：仅客户端短暂出现；服务端 MUST NOT 持久化或缓存明文。
  • 密文分片：对象存储可见；可被读取但不应导致明文泄露；访问必须受 token 控制。
  • manifest：服务端可见；仅包含公开参数与分片映射；必须受 token 控制。
  • 审计数据：服务端可见；仅发送方可读；下载接口不得返回审计字段。

本章仅描述“数据在哪里出现与如何流动”。加密参数与失败模式等可验证规范在第 5 章中定义；Web 安全隔离与日志最小化分别在后续章节展开。