CloudBridge：从资源直传到独立恢复

最新提交：提交 948f3a3。版本记录自动同步；正文与配图以文末核对说明为准。

CloudBridge 是我做的多项目资源上传与加密备份工具。 它把“项目随时能读取文件”和“原环境丢失后仍能恢复内容”分成两件事来处理。 前者使用 S4 原文件，后者依靠夸克里的加密归档、独立恢复清单与单独保管的密钥。

本文依据 codex/unattended-v0.5.1-v0.5.2 分支，详细介绍 V0.5.2 的实现。 先看文件如何流转，再看完成条件、失败接续和独立恢复； 文末区分已有验收记录与尚未完成的事项。

一份资源，分开承担三种用途复制章节链接

双云不是把同一个文件随便复制两遍。 S4 保存供日常访问的原始字节，夸克保存带文件名加密的备份，SQLite 记录任务与映射。

当前适配器明确限定为 S4 主存储 + 夸克加密备份。 没有自动主备切换，也不把一端删除传播到另一端； 新供应商仍需单独设计与验证。

实现由哪些模块组成复制章节链接

服务端使用 Python / FastAPI，网页沿用原生 HTML 与 JavaScript，持久状态由 SQLite WAL 保存。 上传、后台备份与独立恢复分开实现，但共享同一份资源身份与校验规则。

怎样才算真正上传完成复制章节链接

客户端直传，服务端确认复制章节链接

网络中断后，优先找回原任务。 创建时会核对项目、分类、文件类型、大小与路径，并区分三种重复情况：

• 同键、同请求：返回原任务，接着处理。
• 同键、不同请求：明确报冲突。
• 同项目重复内容：默认提醒，明确允许后才新建对象。

三项证据，共同决定 COMPLETE复制章节链接

worker 重新读取已验证的 S4 原文件，生成加密归档，上传夸克，再把备份下载回来。 主存储、备份与恢复三个分项全部验证通过，才满足完成条件。

CLI 的 --wait 等待的是这套验证，不只是 S4 PUT 结束。 调用方应检查 storage_status.complete 与分项状态； 历史完成事件说明当时验证过，后续仍需巡检与恢复演练。

加密与分块，各自解决什么问题复制章节链接

原文件逐份归档，内部文件名也加密复制章节链接

每份资源对应一个 7z，内部保存原文件和 manifest。 实现使用 LZMA2 + AES-256，并开启文件头加密； 归档生成后还会尝试无密码枚举，确认内部文件名无法直接列出。

恢复检查分三层进行：

1. 归档：核对完整大小与 SHA-256。
2. 内部结构：检查成员、路径、类型、解压大小，以及 manifest 的身份和映射。
3. 原始文件：再次核对字节数与 SHA-256。

文件名加密针对备份归档； S4 Key 仍保留原文件名。

大归档先加密，再切片复制章节链接

分块依据的是加密后的归档大小，不是原文件大小。 它用于适应当前账户与官方接口的下载条件，不是对所有会员或客户端的统一限制判断。

分块计划在首次上传前保存每块的顺序、大小、哈希与远端映射。 恢复时：

• 先查远端：即使有本地好块，也确认远端块仍然存在。
• 复用好块：减少重复下载，坏块单独重试。
• 完整再继续：缺块、错序、篡改或未知格式都不能判为成功。

网页关掉、进程退出之后复制章节链接

任务存在 SQLite WAL 中，不依赖网页或 worker 的内存。 资源身份、归档计划、已完成块、尝试次数、下次重试时间与事件一起持久保存。 重启后，中断的备份阶段重新排队，沿用同一任务继续执行。

任务级自动尝试预算为 3 次，退避封顶 300 秒； 正常前两次可重试失败后分别等待约 30、60 秒。 块下载内部也有独立的尝试预算，不能把任务预算理解成只会发三次网络请求。

macOS 启动器监督 API 与单 worker，重复启动复用服务，worker 意外退出后可被重新拉起。 关闭网页或启动终端不清空队列； 电脑关机期间不会继续工作，也没有自动安装开机启动服务。

1GiB 限制在哪里复制章节链接

中间处理使用最大 1GiB 的独立限额卷，另有应用预算，提前估算归档、分块和验证所需空间。 当前源文件上限为 64MiB； 预算公式 6 × 源文件大小 + 8MiB 对 64MiB 输入约为 392MiB。

这个限制针对中间工作卷，不包含整个服务的数据库、离线依赖、恢复包和最终输出。 空间不足时明确报错，不自动扩容，也不扫描删除其他任务或历史备份。

独立恢复包：保存定位能力复制章节链接

恢复包保存“如何找到并核对文件”，云端归档才保存文件内容。 两者与单独保管的密钥齐全，才能在原运行环境不可用时继续恢复。

打开目录前先认证，恢复文件前再校验。 包可附带软件 wheel 与平台依赖，方便离线安装。

状态绿色，具体证明了什么复制章节链接

本机明文 exports 与独立加密包也分工不同。 前者帮助管理和运行接续，后者用于脱离原数据库的内容恢复； 任务 COMPLETE 不表示每次都已同步生成并异地保存新的独立包。

新环境怎样把内容找回来复制章节链接

在另一个工程里使用复制章节链接

已经完成安装和本人授权后，可以让工程记住使用的项目与分类。 工作区配置只选择已有权限，不创建新的云端授权。

cloudbridge --version
cloudbridge health
cloudbridge projects

cloudbridge init --project docs --category screenshots
cloudbridge upload ./example.png --wait

上面的项目、分类和文件名均为示例，以授权项目列表为准。

• 配置：init 创建非秘密的 .cloudbridge.json，不覆盖已有文件。
• 权限：服务端逐次检查项目、分类、文件类型与大小。
• 凭据：Token 由受保护文件提供，不放入配置或公开浏览器代码。

诊断、巡检与规模复制章节链接

检查运行条件，不等于重新验证内容复制章节链接

默认巡检保留历史证据与当前观测的区别。 元数据正常不能替代新鲜的内容证明； 需要后者时，执行明确选择资源的下载恢复。

管理查询变快，云端工作仍有成本复制章节链接

分页改善查询，每份文件的云端往返仍然存在。 一次完整备份的基本内容流量如下：

公开引用的边界复制章节链接

公开映射是可选能力，默认关闭，本文所据分支没有公网部署承诺。 只有策略允许的公开项目、明确的 HTTPS 基址和已验证图片，才进入显式发布流程。

已有证据，与尚待完成的事复制章节链接

下面是该分支验收文档记录的结果，不是本站本次重新执行的 CloudBridge 测试。

这一版保留已有业务 ID、对象位置和归档兼容性，没有自动迁移旧图库、转换历史备份或清理云端对象。 公开接入和新云供应商也不随本文收录而启用。

更新日志复制章节链接

项目与资料复制章节链接

源码项目：ArtoriaShu/cloudbridge（我的私有仓库）。 本文核对日期为 2026 年 10 月 28 日，来源提交为 948f3a3，版本基线 V0.5.2 开发分支。 版本记录跟随指定分支的提交，不把提交编号当作正式 Release，也不自动重写本文。

• 完整实现指南：模块、状态、加密与恢复算法。
• V0.5.2 验收：测试分类、实云证据与限制。
• README：安装与已有授权环境的使用入口。
• 独立设备恢复检查表：材料保全与物理异机核验。

本页图解均为本站依据资料绘制的结构或流程示意，没有使用真实资源清单、账号、云端路径或恢复密钥。