跳到正文
青青方块
登录 一键开服

CaCl2Backup

作者：RealCaCl2

A simple backup mod, supports multi-threads.

模组 Fabric 存储 实用 管理
收藏

介绍

中文介绍正在准备中，下面暂时显示原文。

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

  1. Ensure Fabric Loader and Fabric API are installed
  2. Place the mod JAR file into your server’s mods folder
  3. 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!

  1. View backup list to get index number:
   /backup list
  1. Restore using index:
   /backup restore 1
  1. Behavior depends on configuration:
  • autoRestartAfterRestore=false (default): Manually stop the server to complete restore
  • autoRestartAfterRestore=true: Mod auto-restarts server after specified delay
  1. 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

  1. Regular Backup Checks
  • Run /backup list regularly to confirm backups are created
  • Test restore process periodically to ensure backups are usable
  1. Reasonable Retention Policy
  • Both maxBackups and maxBackupAgeDays apply simultaneously
  • Recommended: Keep at least 3-5 valid backups
  1. Manual Backup Before Important Operations
  • Before mod updates
  • Before major building projects
  • Before server version upgrades
  1. 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:

  1. Ensure server is restarted after restore completes
  2. Check if backup file is complete (normal file size)
  3. 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

常见问题

CaCl2Backup 支持哪些 Minecraft 版本？

CaCl2Backup 支持 Minecraft Java 版 26.1–26.2，共 4 个版本，可用的加载器：Fabric。下载时注意选择和你游戏版本一致的文件。

CaCl2Backup 怎么安装？

先用 PCL2 或 HMCL 启动器安装对应版本的 Fabric，再把下载的 .jar 文件放进游戏目录的 mods 文件夹，重新启动游戏即可。开启了版本隔离的，mods 文件夹在 versions/版本名 下面。运行环境：仅服务端。

评论

登录后评论和评分