Instant Backup
- By
Incremental world backup mod for Minecraft dedicated servers. 面向 Minecraft 专用服务器的增量存档备份模组
Instant Backup
Instant Backup · 极速备份
Incremental world backup mod for Minecraft dedicated servers
Blob dedup · Chunk COW · Async ZSTD · Scheduled backup · Offline CLI
Repository: github.com/limuqy/InstantBackup
Features
| Feature | Description |
|---|---|
| Incremental backup | XXHash64 change detection; only new or modified files are backed up |
| Blob deduplication | Identical content shared across backup versions to save disk space |
| Chunk COW | Mixin hooks chunk writes and captures original region data before overwrite |
| Async compression | Dedicated ZSTD thread pool; does not block the game main thread |
| Scheduled backup | Configurable interval, online-player check, Carpet bot exclusion |
| In-game commands | Full /backup subcommands: create, list, export, delete, etc. |
| Offline CLI | Manage backups after server shutdown; shares the same database as in-game |
| One-click scripts | Auto-generated InstantBackup.cmd / .sh for interactive REPL |
| Multi-loader | Single codebase for Fabric, Forge, and NeoForge |
| Multi-version | Manifold preprocessing + compat layer for multiple MC anchor versions |
| i18n | Built-in zh_cn (default) and en_us |
Supported Versions
| Minecraft | Java | Fabric | Forge | NeoForge |
|---|---|---|---|---|
| 1.18.2 | 17 | ✅ | ✅ | — |
| 1.19.4 | 17 | ✅ | ✅ | — |
| 1.20.1 | 17 | ✅ | ✅ | ✅ |
| 1.20.6 | 21 | ✅ | ✅ | ✅ |
| 1.21.4 | 21 | ✅ | ✅ | ✅ |
| 1.21.11 | 21 | ✅ | ✅ | ✅ |
Quick Start
Manual backup
/backup create main base done
/backup list
/backup statusExport & rollback
There is no in-game one-click restore. Recommended workflow:
/backup export <index>— export the chosen version as a ZIP- Stop the server
- Extract the ZIP and replace the world directory with backup contents
- Start the server
Exports are saved as backups/InstantBackup_<version_name>.zip by default.
Scheduled backup
Default interval is 3600 seconds (1 hour). Common settings:
/backup config interval 1800 # every 30 minutes
/backup config enabled true # enable scheduled backup
/backup config online_only true # backup only when players are online
/backup config exclude_bots true # exclude Carpet fake playersCommands
All commands require OP level 2.
| Command | Description |
|---|---|
/backup help |
Show help |
/backup create [note] |
Trigger manual backup (auto-migrates PENDING blobs before create) |
/backup list |
List backup versions |
/backup delete <index> |
Delete a version (includes blob GC) |
/backup export <index> |
Export a version as ZIP |
/backup migrate <index> |
Seal PENDING blobs for the version and all older ones |
/backup status |
Show backup/compression task progress |
/backup config [key] [value] |
View or change config |
/backup clean |
Remove all backup data |
List example:
=== Backup Versions ===
# Version Name Status Type Note
-- -------------------- --------- ------- --------
1 20260628_143025 Completed Manual main base done
2 20260628_120000 In Progress Auto -Configuration
Config file: config/instantbackup/instantbackup.properties
| Key | Default | Via command | Description |
|---|---|---|---|
general.language |
zh_cn |
✅ | Message language (zh_cn / en_us) |
backup.enabled |
true |
✅ | Enable scheduled backup |
backup.interval |
3600 |
✅ | Scheduled backup interval (seconds) |
backup.only_when_players_online |
true |
✅ | Skip scheduled backup when no players online |
backup.exclude_carpet_bots |
true |
✅ | Exclude Carpet Mod fake players |
compression.level |
19 |
✅ | ZSTD level (1–22) |
thread.count |
2 |
✅ | Backup thread pool size |
storage.max_versions |
30 |
✅ | Max retained versions (0 = unlimited) |
storage.path |
backups |
✅ | Backup storage path (restart required) |
backup.deferred_chunk_migration |
true |
❌ | Deferred chunk COW |
chunk.full_hash |
false |
❌ | Full hash for chunk files |
script.enabled |
true |
❌ | Generate offline launcher scripts |
Cross-drive example: set storage.path=D:/minecraft-backups and restart — blobs go to D: drive
简体中文
极速备份 · Instant Backup
面向 Minecraft 专用服务器的增量存档备份模组
Blob 去重 · 区块 COW · 异步 ZSTD · 定时备份 · 停服 CLI
特性一览
| 能力 | 说明 |
|---|---|
| 增量备份 | 基于 XXHash64 检测文件变化，仅备份新增或变更内容 |
| Blob 去重 | 相同内容跨备份版本共享物理文件，显著节省磁盘空间 |
| 区块 COW | Mixin 拦截区块写入，在覆盖前捕获原始 region 数据 |
| 异步压缩 | 独立线程池 ZSTD 压缩，不阻塞游戏主线程 |
| 定时备份 | 可配置间隔、玩家在线检测、Carpet 假人排除 |
| 游戏内命令 | /backup create / list / export / delete 等完整子命令 |
| 停服 CLI | 服务器关闭后仍可管理备份，与游戏内共用同一数据库 |
| 一键脚本 | 自动生成 InstantBackup.cmd / .sh，双击进入交互式 REPL |
| 多加载器 | 单一代码库构建 Fabric / Forge / NeoForge |
| 多版本 | Manifold 预处理 + compat 层，支持多个 MC 锚点版本 |
| 国际化 | 内置 zh_cn（默认）与 en_us |
支持的版本
| Minecraft | Java | Fabric | Forge | NeoForge |
|---|---|---|---|---|
| 1.18.2 | 17 | ✅ | ✅ | — |
| 1.19.4 | 17 | ✅ | ✅ | — |
| 1.20.1 | 17 | ✅ | ✅ | ✅ |
| 1.20.6 | 21 | ✅ | ✅ | ✅ |
| 1.21.4 | 21 | ✅ | ✅ | ✅ |
| 1.21.11 | 21 | ✅ | ✅ | ✅ |
快速开始
手动备份
/backup create 主城建设完成
/backup list
/backup status导出与回档
模组不提供游戏内一键回档，推荐流程为：
/backup export <序号>— 导出指定版本为 ZIP- 停服
- 解压 ZIP，用备份内容替换世界目录
- 启动服务器
导出文件默认保存为 backups/InstantBackup_<版本名>.zip。
定时备份
默认每 3600 秒自动备份一次。常用配置：
/backup config interval 1800 # 间隔 30 分钟
/backup config enabled true # 启用定时备份
/backup config online_only true # 仅玩家在线时备份
/backup config exclude_bots true # 排除 Carpet 假人命令参考
所有命令需要 OP 等级 2。
| 命令 | 说明 |
|---|---|
/backup help |
显示帮助 |
/backup create [备注] |
手动触发备份（create 前自动 migrate PENDING blob） |
/backup list |
查看备份版本列表 |
/backup delete <序号> |
删除指定版本（含 blob GC） |
/backup export <序号> |
导出指定版本为 ZIP |
/backup migrate <序号> |
封存指定版本及更早版本的 PENDING blob |
/backup status |
查看备份/压缩任务进度 |
/backup config [键] [值] |
查看或修改配置 |
/backup clean |
清理所有备份数据 |
列表示例：
=== 备份版本列表 ===
序号 版本名称 状态 类型 备注
---- -------------------- -------- ------- --------
1 20260628_143025 已完成 手动 主城建设完成
2 20260628_120000 进行中 自动 -配置
配置文件：config/instantbackup/instantbackup.properties
| 配置键 | 默认值 | 命令可改 | 说明 |
|---|---|---|---|
general.language |
zh_cn |
✅ | 消息语言（zh_cn / en_us） |
backup.enabled |
true |
✅ | 是否启用定时备份 |
backup.interval |
3600 |
✅ | 定时备份间隔（秒） |
backup.only_when_players_online |
true |
✅ | 仅玩家在线时定时备份 |
backup.exclude_carpet_bots |
true |
✅ | 排除 Carpet Mod 假人 |
compression.level |
19 |
✅ | ZSTD 压缩等级（1–22） |
thread.count |
2 |
✅ | 备份线程池核心数 |
storage.max_versions |
30 |
✅ | 最大保留版本数（0 = 不限） |
storage.path |
backups |
✅ | 备份存储路径（改后需重启） |
backup.deferred_chunk_migration |
true |
❌ | 区块延迟 COW |
chunk.full_hash |
false |
❌ | 区块文件全量 hash |
script.enabled |
true |
❌ | 是否生成停服一键脚本 |
跨盘符示例：在配置文件中设置 storage.path=D:/minecraft-backups 并重启，blob 写入 D 盘
The Instant Backup Team
