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.zip
backup_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
- 备份触发器重构 — 三个独立的触发器:Interval(间隔)、Schedule(计划)和 Server Stop(服务器停止)
- 触发器可自由组合,通过
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 竞态条件修复
- Schedule 触发器的夏令时正确性、并发列表安全性、命令标准化
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
- 初始版本发布
- 多线程压缩
- 计划自动备份
- 自动清理旧备份
- 完整还原功能
- 标签系统
- 基于索引的快速选择
- 热重载配置
CaCl2Backup
中文 | English
A comprehensive Minecraft server backup mod designed for Fabric.
Features
- Three Backup Triggers - Interval, daily schedule, and server stop triggers that can be combined freely
- Multi-threaded Compression - Parallel compression using multiple threads for significantly faster backups
- Automatic Cleanup - Post-backup automatic cleanup of old backups with both count and age limits
- Full Restore - Complete world save restoration from backups
- Label System - Add labels to backups for easy identification (special characters auto-replaced with underscores)
- Index Operations - Quickly select backups by index number without typing full filenames
- Real-time Status - View backup status, configuration, and backup list
- Hot Reload Config - Reload configuration without restarting the server
- Auto-Restart Restore - Optionally auto-restart the server after restoring a backup
Requirements
- Minecraft 26.0+ (26.x series)
- Fabric Loader 0.15.0+
- Fabric API
- Java 25+
Installation
- Ensure Fabric Loader and Fabric API are installed
- Place the mod JAR file into your server's
mods folder
- Start the server - the mod will automatically generate the configuration file
Command Reference
All commands require OP privileges and use the /backup prefix.
Basic Commands
| Command |
Description |
Example |
/backup create [label] |
Create a manual backup (optional label) |
/backup create before_update |
/backup list |
List all available backups (shows index numbers) |
/backup list |
/backup status |
Show current configuration and status |
/backup status |
/backup reload |
Reload configuration file |
/backup reload |
/backup cleanup |
Manually clean up old backups |
/backup cleanup |
Restore & Delete
| Command |
Description |
Example |
/backup restore <index/filename> |
Restore world from specified backup |
/backup restore 1 |
/backup delete <index/filename> |
Delete specified backup |
/backup delete 2 |
Tip: Use /backup list to view backup index numbers, then use the index directly.
Configuration Commands
| Command |
Description |
Example |
/backup config |
Show all configuration options |
/backup config |
/backup config interval [<minutes>] |
Show/set backup interval |
/backup config interval 60 |
/backup config maxbackups [<count>] |
Show/set maximum backup count |
/backup config maxbackups 20 |
/backup config maxage [<days>] |
Show/set maximum backup age |
/backup config maxage 14 |
/backup config autocleanup [<on/off>] |
Show/set auto cleanup |
/backup config autocleanup on |
/backup config threads [<count>] |
Show/set compression thread count |
/backup config threads 4 |
/backup config level [<1-9>] |
Show/set compression level |
/backup config level 6 |
/backup config autorestart [<on/off>] |
Show/set auto-restart after restore |
/backup config autorestart on |
/backup config restartdelay [<seconds>] |
Show/set auto-restart delay |
/backup config restartdelay 60 |
/backup config restartmessage [<message>] |
Show/set restart message ({seconds} placeholder) |
/backup config restartmessage "Server will restart in {seconds}s..." |
/backup config broadcastrestart [<on/off>] |
Show/set restart message broadcast |
/backup config broadcastrestart on |
/backup config trigger |
Show all trigger statuses |
/backup config trigger |
/backup config trigger interval [<on/off>] |
Show/set interval trigger |
/backup config trigger interval on |
/backup config trigger server_stop [<on/off>] |
Show/set server stop trigger |
/backup config trigger server_stop on |
/backup config trigger schedule [<on/off>] |
Show/set schedule trigger |
/backup config trigger schedule on |
/backup config trigger schedule add <HH:mm> |
Add a schedule time |
/backup config trigger schedule add 03:00 |
/backup config trigger schedule remove <HH:mm> |
Remove a schedule time |
/backup config trigger schedule remove 03:00 |
/backup config trigger schedule clear |
Clear all schedule times |
/backup config trigger schedule clear |
Configuration File
Configuration file location: 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"]
}
}
}
Configuration Options
| Option |
Type |
Default |
Description |
backupIntervalMinutes |
int |
30 |
Auto-backup interval in minutes (minimum: 1) |
maxBackups |
int |
10 |
Maximum number of backups to keep |
compressionThreads |
int |
CPU cores |
Number of compression threads |
compressionLevel |
int |
6 |
Compression level (1-9), 1 is fastest with lowest ratio, 9 is slowest with highest ratio |
autoBackupEnabled |
boolean |
true |
Enable automatic backups |
autoCleanupEnabled |
boolean |
true |
Enable automatic cleanup of old backups |
maxBackupAgeDays |
int |
7 |
Maximum backup age in days |
backupFolderName |
String |
"backups" |
Backup folder name |
broadcastBackupMessages |
boolean |
true |
Broadcast backup messages to all players |
saveOnBackup |
boolean |
true |
Save world before backup |
autoRestartAfterRestore |
boolean |
false |
Auto-restart server after restore |
restartDelaySeconds |
int |
60 |
Auto-restart delay in seconds (minimum: 10) |
restoreRestartMessage |
String |
"Server will restart in {seconds} seconds..." |
Restart message template, {seconds} is replaced with delay |
broadcastRestoreMessage |
boolean |
true |
Broadcast restart message |
triggers.interval.enabled |
boolean |
true |
Enable interval backup trigger |
triggers.interval.interval_minutes |
int |
30 |
Interval backup interval in minutes |
triggers.server_stop.enabled |
boolean |
false |
Enable server stop backup trigger |
triggers.schedule.enabled |
boolean |
false |
Enable daily schedule backup trigger |
triggers.schedule.times |
list |
[] |
Daily backup times (HH:mm format, e.g. ["03:00","15:00"]) |
Usage Guide
Creating Backups
Manual backup (recommended before important operations):
/backup create before_major_update
View backup list:
/backup list
Example output:
[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
...
Restoring World
Warning: Restore operation will overwrite the current world save!
-
View backup list to get index number:
/backup list
-
Restore using index:
/backup restore 1
-
Behavior depends on configuration:
- autoRestartAfterRestore=false (default): Manually stop the server to complete restore
- autoRestartAfterRestore=true: Mod auto-restarts server after specified delay
-
World is automatically replaced on next server startup
Configure auto-restart behavior:
/backup config autorestart on # Enable auto-restart
/backup config restartdelay 60 # Set delay to 60 seconds
/backup config restartmessage "Server will restart in {seconds} seconds..." # Custom message
/backup config broadcastrestart on # Enable broadcast
Deleting Backups
Delete using index:
/backup delete 2
Backup Triggers
Three independent triggers that can be combined freely:
| Trigger |
Default |
Description |
| Interval |
On |
Auto-backup every N minutes |
| Schedule |
Off |
Backup at specific times daily (e.g. 03:00 and 15:00) |
| Server Stop |
Off |
Backup when server shuts down normally |
| Manual Command |
— |
Run /backup create [label] anytime |
Example configuration:
// Only enable server stop + daily 3 AM backup, disable interval
"triggers": {
"interval": { "enabled": false },
"server_stop": { "enabled": true },
"schedule": { "enabled": true, "times": ["03:00"] }
}
Backup File Naming
backup_YYYY-MM-DD_HH-mm-ss.zip # No label
backup_YYYY-MM-DD_HH-mm-ss_label.zip # With label
Examples:
backup_2024-02-20_10-30-00.zip
backup_2024-02-20_10-30-00_before_update.zip
Label naming rules:
- Allowed: letters
a-zA-Z, digits 0-9, underscore _, hyphen -
- Other characters (spaces, special symbols, etc.) are auto-replaced with underscore
_
Performance
Multi-threaded Compression
The mod uses parallel compression to significantly speed up backups for large worlds:
| World Size |
1 Thread |
4 Threads |
8 Threads |
| 500 MB |
~45s |
~15s |
~10s |
| 2 GB |
~3min |
~1min |
~40s |
| 5 GB |
~8min |
~2.5min |
~1.5min |
Compression Level Comparison
| Level |
Ratio |
Speed |
Use Case |
| 1-3 |
~40% |
Fastest |
Frequent backups, SSD storage |
| 4-6 |
~50% |
Balanced |
Daily use (recommended) |
| 7-9 |
~55% |
Slower |
Limited storage space |
Best Practices
-
Regular Backup Checks
- Run
/backup list regularly to confirm backups are created
- Test restore process periodically to ensure backups are usable
-
Reasonable Retention Policy
- Both
maxBackups and maxBackupAgeDays apply simultaneously
- Recommended: Keep at least 3-5 valid backups
-
Manual Backup Before Important Operations
- Before mod updates
- Before major building projects
- Before server version upgrades
-
Off-site Backups
- Periodically copy backup folder to another location
- Consider cloud storage sync for backups
Troubleshooting
Backup Failed
Problem: Backup failed: World directory not found
Solution: Confirm the server world folder is named world.
World Issues After Restore
Problem: Incomplete world data after restore
Solution:
- Ensure server is restarted after restore completes
- Check if backup file is complete (normal file size)
- Try using a different backup file
Permission Issues
Problem: Cannot execute commands
Solution: Ensure the player has been set as OP (use /op player_name).
Development Info
- Author: CaCl2
- Version: 1.1.1
- License: MIT
- Minecraft Version: 26.0+ (26.x series)
- Fabric API Version: 0.146.1+
Changelog
1.1.1
- Fix — Auto cleanup of old backups not working (Gson deserialization did not validate default values for
maxBackups, maxBackupAgeDays, and autoCleanupEnabled, causing auto cleanup to be silently disabled when migrating from older config files)
- Fix — Cleanup logic
else if caused count-based and age-based deletion to interfere with each other; rewritten with independent checks to keep exactly maxBackups backups
1.1.0
- Backup trigger refactoring — Three independent triggers: Interval, Schedule, and Server Stop
- Triggers can be combined freely, controlled via
triggers config section
- Old config files auto-migrate; existing interval settings are preserved
- New trigger commands:
/backup config trigger interval/schedule/server_stop
- Support for multiple daily backup times (e.g.
["03:00","15:00"])
- Sync backup on server shutdown (using
createBackupSync)
- Minecraft version support expanded to entire 26.x series (
>=26.0 <27.0)
- Removed legacy
/backup config autobackup, unified under trigger interval
- Security fixes — Zip Slip path traversal protection, backup name path filtering, TOCTOU race condition fix
- Schedule trigger DST correctness, concurrent list safety, command standardization
1.0.2
- Refactored restore flow: Removed
/backup restarter command, auto-restart integrated into /backup restore
- New config options:
autoRestartAfterRestore, restartDelaySeconds, restoreRestartMessage, broadcastRestoreMessage
- New config commands:
/backup config autorestart, /backup config restartdelay, /backup config restartmessage, /backup config broadcastrestart
1.0.1
- Updated to Minecraft 26.1.2
- Added GitHub Release workflow
- Java version requirement raised to 25+
1.0.0
- Initial release
- Multi-threaded compression
- Scheduled auto-backups
- Automatic cleanup of old backups
- Full restore functionality
- Label system
- Index-based quick selection
- Hot reload configuration
评论 0
登录后参与评分
还没有评论,来抢沙发吧