CaCl2Backup

模组

· 作者 RealCaCl2

一个简单的备份模组,支持多线程。

0 本站下载 0 关注 更新于 3 个月前

需要前置:Fabric API

最新 1.2.0 · 26.2 · Fabric

一键开服(送7天)

CaCl2Backup

中文 | English

一款专为 Fabric 设计的综合性 Minecraft 服务器备份模组。

功能特性

  • 三种备份触发方式 - 支持间隔时间、每日定时和服务器停止触发,可自由组合
  • 多线程压缩 - 使用多个线程并行压缩,显著加快备份速度
  • 自动清理 - 备份后自动清理旧备份,支持按数量和保留天数限制
  • 完整还原 - 从备份中完全恢复世界存档
  • 标签系统 - 为备份添加标签以便轻松识别(特殊字符会自动替换为下划线)
  • 索引操作 - 通过索引编号快速选择备份,无需输入完整文件名
  • 实时状态 - 查看备份状态、配置信息和备份列表
  • 热重载配置 - 无需重启服务器即可重新加载配置文件
  • 自动重启还原 - 可选在还原备份后自动重启服务器

依赖要求

  • Minecraft 26.0+ (26.x 系列)
  • Fabric Loader 0.15.0+
  • Fabric API
  • Java 25+

安装方法

  1. 确保已安装 Fabric Loader 和 Fabric API
  2. 将模组 JAR 文件放入服务器的 mods 文件夹
  3. 启动服务器 - 模组将自动生成配置文件

命令参考

所有命令需要 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
...

恢复世界

警告:恢复操作将覆盖当前世界存档!

  1. 查看备份列表以获取索引号:

    /backup list
    
  2. 使用索引进行恢复:

    /backup restore 1
    
  3. 行为取决于配置:

    • autoRestartAfterRestore=false(默认):手动停止服务器以完成恢复
    • autoRestartAfterRestore=true:模组将在指定延迟后自动重启服务器
  4. 世界将在下次服务器启动时自动替换

配置自动重启行为:

/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% 较慢 存储空间有限

最佳实践

  1. 定期检查备份

    • 定期运行 /backup list 以确认备份已创建
    • 定期测试恢复过程,确保备份可用
  2. 合理的保留策略

    • maxBackups 和 maxBackupAgeDays 同时生效
    • 建议至少保留 3-5 个有效备份
  3. 重要操作前手动备份

    • 模组更新前
    • 大型建筑项目前
    • 服务器版本升级前
  4. 异地备份

    • 定期将备份文件夹复制到其他位置
    • 考虑使用云存储同步备份

故障排除

备份失败

问题: Backup failed: World directory not found

解决方案: 确认服务器世界文件夹名为 world。

恢复后世界出现问题

问题: 恢复后世界数据不完整

解决方案:

  1. 确保恢复完成后重启服务器
  2. 检查备份文件是否完整(文件大小是否正常)
  3. 尝试使用其他备份文件

权限问题

问题: 无法执行命令

解决方案: 确保玩家已被设置为 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

  • 初始版本发布
  • 多线程压缩
  • 计划自动备份
  • 自动清理旧备份
  • 完整还原功能
  • 标签系统
  • 基于索引的快速选择
  • 热重载配置

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源