Skip to content

feat: 支持Cloudflare R2 数据备份功能,支持加密、定时备份、轮替与下载解密#110

Open
Jimmy-Bots wants to merge 4 commits intobasketikun:mainfrom
Jimmy-Bots:cf-backup
Open

feat: 支持Cloudflare R2 数据备份功能,支持加密、定时备份、轮替与下载解密#110
Jimmy-Bots wants to merge 4 commits intobasketikun:mainfrom
Jimmy-Bots:cf-backup

Conversation

@Jimmy-Bots
Copy link
Copy Markdown
Contributor

变更说明

本次改动为管理员设置页新增了 Cloudflare R2 备份能力,支持将关键数据按压缩包形式备份到 R2,并提供定时执行、轮替清理、历史查看、手动备份、删除和下载等管理能力。

整体实现尽量沿用现有配置与设置页结构,以增量方式接入,没有重构原有系统配置、存储抽象或管理页框架。

主要改动

1. 新增 Cloudflare R2 备份配置与管理入口

在管理员设置页新增独立的备份管理卡片,支持配置:

  • Cloudflare Account ID
  • Access Key ID
  • Secret Access Key
  • Bucket
  • Prefix
  • 定时备份间隔
  • 轮替保留数量
  • 是否启用加密
  • 加密口令
  • 备份内容选择

同时支持以下管理操作:

  • 测试 R2 连接
  • 手动执行备份
  • 查看历史备份列表
  • 查看备份详情
  • 删除远端备份
  • 下载备份文件

2. 新增定时备份与轮替能力

后端新增独立的备份服务,在服务启动后后台运行定时轮询逻辑。

当启用定时备份后,会按配置的时间间隔自动执行备份;备份成功后,如果配置了保留数量限制,会自动删除更旧的远端备份对象,实现简单轮替。

同时支持手动触发备份,与定时备份共用同一套执行逻辑和状态记录。

3. 备份内容改为原始多文件压缩包格式

备份产物为多文件压缩包格式。

当前备份文件格式为:

  • 未加密:.tar.gz
  • 已加密:.tar.gz.enc

压缩包内按json原始结构保存数据,例如:

  • config.json
  • data/register.json
  • data/cpa_config.json
  • data/sub2api_config.json
  • data/logs.jsonl
  • data/image_tasks.json
  • data/images/...
  • snapshots/accounts.json
  • snapshots/auth_keys.json
  • backup-metadata.json

其中:

  • 本地配置类数据保留原始文件形态
  • 账号与用户密钥从当前存储后端导出为快照文件
  • 这样无论当前底层存储是 jsonsqlitepostgres 还是 git,都能进入统一备份包

4. 支持可选加密备份

当启用加密后,备份压缩包会在上传到 R2 前使用 openssl 进行加密。

为了保证容器环境可用,本次也补充了运行时所需依赖,使 Docker 部署下加密备份可以正常工作。

5. 支持备份详情查看

后端新增备份详情解析能力,前端可以查看:

  • 备份创建时间
  • 触发方式
  • 应用版本
  • 当时的存储后端信息
  • 压缩包内包含的文件列表
  • 每个文件的大小与 SHA256
  • 快照文件记录数

这样可以在不恢复备份的情况下先确认备份内容是否符合预期。

6. 支持下载备份文件

新增备份下载接口,管理员可以直接从设置页下载远端备份对象。

对于未加密备份,会直接下载 .tar.gz 文件。

对于已加密备份,本次进一步补充了“下载时自动解密”逻辑:

  • 后端会在下载时使用当前配置中的加密口令先解密
  • 返回给浏览器的是可直接使用的 .tar.gz
  • 前端会优先使用后端返回的下载文件名,避免继续保留 .enc 后缀

这样用户下载加密备份时,不需要再手动处理 .enc 文件。

7. 备份状态与配置职责拆分

备份配置保存在系统配置中,而备份运行状态单独保存在独立状态文件中,避免将运行态混入配置本身。

这样可以更清晰地区分:

  • backup:期望配置
  • backup_state:最近一次执行结果与状态

影响范围

  • 管理员设置页
  • 系统配置与备份状态管理
  • Cloudflare R2 备份执行链路
  • 备份详情、删除与下载接口
  • Docker 运行环境依赖

验证情况

  • 已完成相关后端文件的 Python 编译检查
  • 已确认支持手动备份、历史列表、详情查看、删除和下载
  • 已确认加密备份下载时会自动解密
  • 已修复前端下载文件名仍保留 .enc 后缀的问题
  • 前端完整类型检查暂未执行,当前环境缺少 web/node_modules

备注

  • 当前备份格式仅支持新的多文件 tar.gz 压缩包方案
  • 已加密备份在查看详情或下载解密时,依赖当前配置中存在正确的加密口令
  • 本次改动暂未包含“备份恢复”能力,仅提供备份生成、查看、删除和下载

效果展示

image

@Jimmy-Bots
Copy link
Copy Markdown
Contributor Author

当前未做备份恢复功能,从之前 #103 被close看来可能一些配置的热重载似乎目前不考虑

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant