AposaBackup
一个 Fabric 模组,用于自动备份 Minecraft 世界,支持本地存储和 S3 API(例如 Cloudflare R2)云备份。适用于专用服务器和单人世界。
功能
- 计划自动备份 — 可配置的间隔(默认:60 分钟)
- 手动备份 —
/backup create,可选添加注释
- 关机备份 — 服务器停止时自动备份
- 本地备份 — 完整的 ZIP 归档,带有轮换策略(保留最近的 N 个 + 每日快照)
- 云备份 — 通过 S3 API 向 Cloudflare R2 进行差异上传,并采用基于内容的寻址去重
- 恢复 — 两步恢复流程,需确认,恢复前会自动创建备份
- 下载 — 将云备份导出为本地 ZIP
- 游戏内通知 — 操作栏消息显示备份状态
- 热配置 — 所有设置均可通过命令更改,无需重启
安装
- 从 Releases 页面下载模组 JAR 文件
- 将其放入服务器或客户端的
mods/ 目录中
- 启动服务器 — 将在
config/aposabackup.json 生成默认配置
快速开始
# 创建手动备份
/backup create
# 创建带注释的备份
/backup create before big build
# 列出本地备份
/backup list
# 检查备份系统状态
/backup status
命令
所有命令都需要 OP 等级 3(管理员)权限。
| 命令 |
描述 |
/backup create [comment] |
创建本地备份 |
/backup cloud |
创建云备份(差异上传) |
/backup list [local|cloud] |
列出备份 |
/backup restore <id> |
准备恢复(需要确认) |
/backup confirm |
确认并执行恢复 |
/backup download <id> |
将云备份下载为本地 ZIP |
/backup delete <id> [local|cloud] |
删除备份 |
/backup info <id> |
显示备份详情 |
/backup status |
显示系统状态 |
/backup interval <min> |
设置备份间隔 |
/backup config <key> <value> |
更改配置 |
/backup config show |
显示当前配置 |
/backup config reload |
从文件重新加载 |
完整命令参考请参见 github/docs/COMMANDS.md。
配置
配置文件位于 config/aposabackup.json。所有选项也可以通过 /backup config 命令更改。
{
"version": 1,
"local": {
"enabled": true,
"backupDir": "./backups",
"format": "ZIP",
"compressionLevel": 6,
"intervalMinutes": 60,
"recentBackups": 10,
"dailyKeepDays": 7,
"shutdownBackup": true,
"excludePatterns": ["session.lock", "*.tmp"]
},
"cloud": {
"enabled": false,
"maxBackups": 30,
"dailyKeepDays": 7,
"uploadTimeoutSeconds": 300,
"retryCount": 3,
"r2": {
"accountId": "",
"accessKeyId": "",
"secretAccessKey": "",
"bucketName": "mc-server-backups",
"region": "auto",
"pathPrefix": "my-server/",
"customEndpoint": ""
}
},
"notification": {
"enabled": true,
"style": "ACTION_BAR"
}
}
详细配置参考请参见 github/docs/CONFIGURATION.md。
云备份(例如 Cloudflare R2)
AposaBackup 支持使用 Cloudflare R2 的 S3 兼容 API 进行差异云备份。
工作原理:
- 仅上传更改过的
.mca 区域文件(使用 SHA-256 内容寻址)
- 文件经过 gzip 压缩并存储为基于内容的寻址块
- 每次备份创建一个引用这些块的清单
- 当旧清单被删除时,未引用的块会被垃圾回收
设置: 请参阅 github/docs/CLOUD_SETUP.md 获取分步说明。
备份轮换策略
本地备份
- 近期备份:保留最近的 N 个备份(默认:10 个)
- 每日快照:自动保留每天的最后一次备份,持续 N 天(默认:7 天)
云备份
- 清单保留:保留最近的 N 个清单(默认:30 个)
- 每日快照:保留每天的清单,持续 N 天(默认:7 天)
- 垃圾回收:在清理清单后删除未引用的块
恢复流程
/backup restore world_2026-06-22_14-00-00.zip
→ “即将恢复备份。当前世界将首先被备份。”
/backup confirm
→ 创建恢复前备份 → 保存待处理的恢复操作 → 停止服务器
[服务器重启]
→ 检测到待处理的恢复 → 解压缩备份 → 世界已恢复
AposaBackup
A Fabric mod for automated Minecraft world backups with local storage and S3 API(e.g. Cloudflare R2) cloud backup support. Works on both dedicated servers and single-player worlds.
Features
- Scheduled Automatic Backups — Configurable interval (default: 60 min)
- Manual Backups —
/backup create with optional comments
- Shutdown Backups — Automatic backup when server stops
- Local Backup — Full ZIP archives with rotation policy (recent N + daily snapshots)
- Cloud Backup — Differential upload to Cloudflare R2 via S3 API with content-addressable deduplication
- Restore — Two-step restore with confirmation, auto-backup before restore
- Download — Export cloud backup as local ZIP
- In-game Notifications — Action bar messages for backup status
- Hot Configuration — All settings changeable via commands, no restart required
Installation
- Download the mod JAR from releases
- Place it in your server's or client's
mods/ directory
- Start the server — default config will be generated at
config/aposabackup.json
Quick Start
# Create a manual backup
/backup create
# Create a backup with comment
/backup create before big build
# List local backups
/backup list
# Check backup system status
/backup status
Commands
All commands require OP level 3 (admin) permission.
| Command |
Description |
/backup create [comment] |
Create a local backup |
/backup cloud |
Create a cloud backup (differential upload) |
/backup list [local|cloud] |
List backups |
/backup restore <id> |
Prepare restore (requires confirmation) |
/backup confirm |
Confirm and execute restore |
/backup download <id> |
Download cloud backup as local ZIP |
/backup delete <id> [local|cloud] |
Delete a backup |
/backup info <id> |
Show backup details |
/backup status |
Show system status |
/backup interval <min> |
Set backup interval |
/backup config <key> <value> |
Change configuration |
/backup config show |
Show current configuration |
/backup config reload |
Reload from file |
See github/docs/COMMANDS.md for full command reference.
Configuration
The config file is at config/aposabackup.json. All options can also be changed via /backup config.
{
"version": 1,
"local": {
"enabled": true,
"backupDir": "./backups",
"format": "ZIP",
"compressionLevel": 6,
"intervalMinutes": 60,
"recentBackups": 10,
"dailyKeepDays": 7,
"shutdownBackup": true,
"excludePatterns": ["session.lock", "*.tmp"]
},
"cloud": {
"enabled": false,
"maxBackups": 30,
"dailyKeepDays": 7,
"uploadTimeoutSeconds": 300,
"retryCount": 3,
"r2": {
"accountId": "",
"accessKeyId": "",
"secretAccessKey": "",
"bucketName": "mc-server-backups",
"region": "auto",
"pathPrefix": "my-server/",
"customEndpoint": ""
}
},
"notification": {
"enabled": true,
"style": "ACTION_BAR"
}
}
See github/docs/CONFIGURATION.md for detailed configuration reference.
Cloud Backup (e.g. Cloudflare R2)
AposaBackup supports differential cloud backups using Cloudflare R2's S3-compatible API.
How it works:
- Only changed
.mca region files are uploaded (SHA-256 content addressing)
- Files are gzip-compressed and stored as content-addressed chunks
- Each backup creates a manifest referencing the chunks
- Unreferenced chunks are garbage-collected when old manifests are deleted
Setup: See github/docs/CLOUD_SETUP.md for step-by-step instructions.
Backup Rotation Policy
Local Backups
- Recent backups: Keeps the last N backups (default: 10)
- Daily snapshots: Automatically preserves the last backup of each day for N days (default: 7)
Cloud Backups
- Manifest retention: Keeps the last N manifests (default: 30)
- Daily snapshots: Preserves daily manifests for N days (default: 7)
- Garbage collection: Deletes unreferenced chunks after manifest cleanup
Restore Flow
/backup restore world_2026-06-22_14-00-00.zip
→ "About to restore backup. Current world will be backed up first."
/backup confirm
→ Creates pre-restore backup → Saves pending restore → Stops server
[Server restarts]
→ Detects pending restore → Decompresses backup → World restored
评论 0
登录后参与评分
还没有评论,来抢沙发吧