
CaCl2Backup
一个简单的备份模组,支持多线程。
CaCl2Backup
中文 | English
一个为 Fabric 设计的综合性 Minecraft 服务器备份模组。
特性
- 三种备份触发器 - 间隔、每日定时和服务器停止触发器,可自由组合
- 多线程压缩 - 使用多线程并行压缩,显著加快备份速度
- 自动清理 - 备份后自动清理旧备份,同时支持数量和时间限制
- 完整还原 - 从备份完整还原世界存档
- 标签系统 - 为备份添加标签以便识别(特殊字符自动替换为下划线)
- 索引操作 - 通过索引号快速选择备份,无需输入完整文件名
- 实时状态 - 查看备份状态、配置和备份列表
- 热重载配置 - 无需重启服务器即可重载配置
- 自动重启还原 - 可选择在还原备份后自动重启服务器
要求
- Minecraft 26.0+(26.x 系列)
- Fabric Loader 0.15.0+
- Fabric API
- Java 25+
安装
- 确保已安装 Fabric Loader 和 Fabric API
- 将模组 JAR 文件放入服务器的
mods文件夹 - 启动服务器 - 模组将自动生成配置文件
命令参考
所有命令均需要 OP 权限,并使用 /backup 前缀。
基础命令
| 命令 | 描述 | 示例 |
|---|---|---|
/backup create [label] |
创建手动备份(可选标签) | /backup create before_update |
/backup list |
列出所有可用备份(显示索引号) | /backup list |
/backup status |
显示当前配置和状态 | /backup status |
/backup reload |
重载配置文件 | /backup reload |
/backup cleanup |
手动清理旧备份 | /backup cleanup |
还原与删除
| 命令 | 描述 | 示例 |
|---|---|---|
/backup restore <index/filename> |
从指定备份还原世界 | /backup restore 1 |
/backup delete <index/filename> |
删除指定备份 | /backup delete 2 |
提示: 使用 /backup list 查看备份索引号,然后直接使用索引。
配置命令
| 命令 | 描述 | 示例 |
|---|---|---|
/backup config |
显示所有配置选项 | /backup config |
/backup config interval [<minutes>] |
显示/设置备份间隔 | /backup config interval 60 |
/backup config maxbackups [<count>] |
显示/设置最大备份数量 | /backup config maxbackups 20 |
/backup config maxage [<days>] |
显示/设置最大备份保留天数 | /backup config maxage 14 |
/backup config autocleanup [<on/off>] |
显示/设置自动清理 | /backup config autocleanup on |
/backup config threads [<count>] |
显示/设置压缩线程数 | /backup config threads 4 |
/backup config level [<1-9>] |
显示/设置压缩级别 | /backup config level 6 |
/backup config autorestart [<on/off>] |
显示/设置还原后自动重启 | /backup config autorestart on |
/backup config restartdelay [<seconds>] |
显示/设置自动重启延迟 | /backup config restartdelay 60 |
/backup config restartmessage [<message>] |
显示/设置重启消息({seconds} 占位符) | /backup config restartmessage "Server will restart in {seconds}s..." |
/backup config broadcastrestart [<on/off>] |
显示/设置重启消息广播 | /backup config broadcastrestart on |
/backup config trigger |
显示所有触发器状态 | /backup config trigger |
/backup config trigger interval [<on/off>] |
显示/设置间隔触发器 | /backup config trigger interval on |
/backup config trigger server_stop [<on/off>] |
显示/设置服务器停止触发器 | /backup config trigger server_stop on |
/backup config trigger schedule [<on/off>] |
显示/设置定时触发器 | /backup config trigger schedule on |
/backup config trigger schedule add <HH:mm> |
添加定时时间 | /backup config trigger schedule add 03:00 |
/backup config trigger schedule remove <HH:mm> |
移除定时时间 | /backup config trigger schedule remove 03:00 |
/backup config trigger schedule clear |
清除所有定时时间 | /backup config trigger schedule clear |
配置文件
配置文件位置:config/cacl2backup.json
{
"backupIntervalMinutes": 30,
"maxBackups": 10,
"compressionThreads": 8,
"compressionLevel": 6,
"autoBackupEnabled": true,
"autoCleanupEnabled": true,
"maxBackupAgeDays": 7,
"backupFolderName": "backups",
"broadcastBackupMessages": true,
"saveOnBackup": true,
"autoRestartAfterRestore": false,
"restartDelaySeconds": 60,
"restoreRestartMessage": "Server will restart in {seconds} seconds to complete restore...",
"broadcastRestoreMessage": true,
"triggers": {
"interval": {
"enabled": true,
"interval_minutes": 30
},
"server_stop": {
"enabled": false
},
"schedule": {
"enabled": false,
"times": ["03:00", "15:00"]
}
}
}
配置选项
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
backupIntervalMinutes |
int | 30 | 自动备份间隔(分钟,最小值为 1) |
maxBackups |
int | 10 | 保留的最大备份数量 |
compressionThreads |
int | CPU 核心数 | 压缩线程数 |
compressionLevel |
int | 6 | 压缩级别(1-9),1 最快但压缩率最低,9 最慢但压缩率最高 |
autoBackupEnabled |
boolean | true | 启用自动备份 |
autoCleanupEnabled |
boolean | true | 启用旧备份自动清理 |
maxBackupAgeDays |
int | 7 | 备份最大保留天数 |
backupFolderName |
String | "backups" | 备份文件夹名称 |
broadcastBackupMessages |
boolean | true | 向所有玩家广播备份消息 |
saveOnBackup |
boolean | true | 备份前保存世界 |
autoRestartAfterRestore |
boolean | false | 还原后自动重启服务器 |
restartDelaySeconds |
int | 60 | 自动重启延迟秒数(最小值为 10) |
restoreRestartMessage |
String | "Server will restart in {seconds} seconds..." | 重启消息模板,{seconds} 会被替换为延迟时间 |
broadcastRestoreMessage |
boolean | true | 广播重启消息 |
triggers.interval.enabled |
boolean | true | 启用间隔备份触发器 |
triggers.interval.interval_minutes |
int | 30 | 间隔备份间隔(分钟) |
triggers.server_stop.enabled |
boolean | false | 启用服务器停止备份触发器 |
triggers.schedule.enabled |
boolean | false | 启用每日定时备份触发器 |
triggers.schedule.times |
list | [] | 每日备份时间(HH:mm 格式,例如 ["03:00","15:00"]) |
使用指南
创建备份
手动备份(建议在执行重要操作前进行):
/backup create before_major_update
查看备份列表:
/backup list
示例输出:
[CaCl2Backup] Available backups (5):
1. 2024-02-20 10:30:00 [before_update] - 125.3 MB
2. 2024-02-19 22:00:00 [auto] - 124.8 MB
3. 2024-02-19 10:00:00 - 123.5 MB
...
还原世界
警告:还原操作将覆盖当前世界存档!
查看备份列表以获取索引号:
/backup list使用索引进行还原:
/backup restore 1行为取决于配置:
- autoRestartAfterRestore=false(默认):手动停止服务器以完成还原
- autoRestartAfterRestore=true:模组将在指定延迟后自动重启服务器
世界将在下次服务器启动时自动替换
配置自动重启行为:
/backup config autorestart on # 启用自动重启
/backup config restartdelay 60 # 设置延迟为 60 秒
/backup config restartmessage "Server will restart in {seconds} seconds..." # 自定义消息
/backup config broadcastrestart on # 启用广播
删除备份
使用索引删除:
/backup delete 2
备份触发器
三个独立触发器,可自由组合:
| 触发器 | 默认值 | 描述 |
|---|---|---|
| 间隔 | 开启 | 每隔 N 分钟自动备份 |
| 定时 | 关闭 | 每天在特定时间备份(例如 03:00 和 15:00) |
| 服务器停止 | 关闭 | 服务器正常关闭时备份 |
| 手动命令 | — | 随时运行 /backup create [label] |
示例配置:
// 仅启用服务器停止 + 每日凌晨 3 点备份,禁用间隔
"triggers": {
"interval": { "enabled": false },
"server_stop": { "enabled": true },
"schedule": { "enabled": true, "times": ["03:00"] }
}
备份文件命名
backup_YYYY-MM-DD_HH-mm-ss.zip # 无标签
backup_YYYY-MM-DD_HH-mm-ss_label.zip # 带标签
示例:
backup_2024-02-20_10-30-00.zipbackup_2024-02-20_10-30-00_before_update.zip
标签命名规则:
- 允许:字母
a-zA-Z、数字0-9、下划线_、连字符- - 其他字符(空格、特殊符号等)自动替换为下划线
_
性能
多线程压缩
模组使用并行压缩,为大型世界显著加快备份速度:
| 世界大小 | 1 线程 | 4 线程 | 8 线程 |
|---|---|---|---|
| 500 MB | ~45 秒 | ~15 秒 | ~10 秒 |
| 2 GB | ~3 分钟 | ~1 分钟 | ~40 秒 |
| 5 GB | ~8 分钟 | ~2.5 分钟 | ~1.5 分钟 |
压缩级别对比
| 级别 | 压缩率 | 速度 | 使用场景 |
|---|---|---|---|
| 1-3 | ~40% | 最快 | 频繁备份、SSD 存储 |
| 4-6 | ~50% | 平衡 | 日常使用(推荐) |
| 7-9 | ~55% | 较慢 | 存储空间有限 |
最佳实践
定期检查备份
- 定期运行
/backup list确认备份已创建 - 定期测试还原流程以确保备份可用
- 定期运行
合理的保留策略
maxBackups和maxBackupAgeDays同时生效- 建议:至少保留 3-5 个有效备份
重要操作前手动备份
- 模组更新前
- 大型建筑项目前
- 服务器版本升级前
异地备份
- 定期将备份文件夹复制到其他位置
- 考虑使用云存储同步备份
故障排除
备份失败
问题: Backup failed: World directory not found
解决方案: 确认服务器世界文件夹命名为 world。
还原后世界出现问题
问题: 还原后世界数据不完整
解决方案:
- 确保还原完成后服务器已重启
- 检查备份文件是否完整(文件大小正常)
- 尝试使用其他备份文件
权限问题
问题: 无法执行命令
解决方案: 确保玩家已被设置为 OP(使用 /op player_name)。
开发信息
- 作者: CaCl2
- 版本: 1.1.1
- 许可证: MIT
- Minecraft 版本: 26.0+(26.x 系列)
- Fabric API 版本: 0.146.1+
更新日志
1.1.1
- 修复 — 旧备份自动清理不生效(Gson 反序列化未校验
maxBackups、maxBackupAgeDays、autoCleanupEnabled的默认值,导致从旧配置文件迁移时自动清理被静默禁用) - 修复 — 清理逻辑
else if导致按数量删除和按时间删除相互干扰;重写为独立检查,精确保留maxBackups个备份
1.1.0
- 备份触发器重构 — 三个独立触发器:间隔、定时和服务器停止
- 触发器可自由组合,通过
triggers配置节控制 - 旧配置文件自动迁移;保留已有的间隔设置
- 新增触发器命令:
/backup config trigger interval/schedule/server_stop - 支持多个每日备份时间(例如
["03:00","15:00"]) - 服务器关闭时同步备份(使用
createBackupSync) - Minecraft 版本支持扩展到整个 26.x 系列(
>=26.0 <27.0) - 移除旧版
/backup config autobackup,统一到trigger interval - 安全修复 — Zip Slip 路径遍历防护、备份名称路径过滤、TOCTOU 竞态条件修复
- 定时触发器夏令时正确性、并发列表安全、命令规范化
1.0.2
- 重构还原流程:移除
/backup restarter命令,自动重启整合到/backup restore - 新增配置选项:
autoRestartAfterRestore、restartDelaySeconds、restoreRestartMessage、broadcastRestoreMessage - 新增配置命令:
/backup config autorestart、/backup config restartdelay、/backup config restartmessage、/backup config broadcastrestart
1.0.1
- 更新至 Minecraft 26.1.2
- 添加 GitHub Release 工作流
- Java 版本要求提升至 25+
1.0.0
- 初始发布
- 多线程压缩
- 定时自动备份
- 旧备份自动清理
- 完整还原功能
- 标签系统
- 基于索引的快速选择
- 热重载配置
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。