Just Enough Backups 是一款 Fabric 模组,通过游戏内可用的工作流程为服务器端世界添加备份功能。
它支持:
- 完整、部分和差异备份
- 通过命令和界面进行手动备份
- 自动定时备份
- 可配置的公共备份/恢复公告
- 基于备份数量的保留策略
- 基于每个世界总备份大小的保留策略
- 从备份浏览器进行恢复准备
- 带有实时预览的可配置客户端 HUD 弹窗
- 并行(多线程)扫描、压缩和恢复解压
- ZIP 存档内的可选 Zstandard 压缩
- 可选的远程备份存储(兼容 S3 和 WebDAV)
- 可选的 Mod Menu 集成
该模组的设计旨在将实际的备份逻辑保留在服务器端,同时通过客户端界面提供管理和配置功能。
远程存储
远程存储默认处于禁用状态。配置界面设有专门的“远程”选项卡,包含提供商选择器、启用开关以及用于 S3(端点、区域、存储桶、前缀、访问密钥、秘密密钥)和 WebDAV(URL、前缀、用户名、密码)的字段。对于 S3,存储桶和区域是必填项;端点对于 AWS 是可选的,也可以指向兼容 S3 的服务。对于 WebDAV,请设置集合 URL。凭证可以直接在界面中配置(敏感信息会被隐藏),也可以在 config/justenoughbackups.json 中设置,或通过环境变量设置,后者优先级更高且可避免在磁盘上以明文形式存储秘密信息。
在服务器配置中设置凭证或使用环境变量,后者优先级更高:
- S3:
JEB_S3_ACCESS_KEY_ID 和 JEB_S3_SECRET_ACCESS_KEY
- WebDAV:
JEB_WEBDAV_USERNAME 和 JEB_WEBDAV_PASSWORD
远程端点请使用 HTTPS。仅接受纯 HTTP 用于回环开发端点。远程备份在上传并通过 SHA-256 验证后发布;其目录包含元数据和校验和。保留策略会保护增量链所需的基准备份。恢复时会以流式方式下载每个必需的存档到隔离的暂存区,验证其校验和,然后在准备替换世界之前验证重建的世界。remoteStorage.maxRetries 限制了上传尝试次数;WebDAV 上传失败会重新启动压缩和传输过程,但中断的上传不会在进程重启后恢复。切勿将凭证放入共享或已提交的配置文件中。
功能
备份类型
- 完整备份 (Full):在备份时刻创建整个世界的完整快照。不需要基准备份,并作为后续增量备份的基础。
- 部分备份 (Partial):创建一个增量备份,仅包含自最近一次任何类型备份(完整、部分或差异)以来发生更改的文件。它以该最近的备份作为基准。
- 差异备份 (Differential):创建一个增量备份,仅包含自最近一次完整备份以来发生更改的文件。差异备份存储在单独的保留存储桶中,与部分备份分开,允许独立的保留策略。
备份之间的依赖关系会被跟踪。保留和删除操作会尊重这些依赖关系,因此当较新的部分或差异备份仍依赖于它们时,所需的基准备份会被保留。
自动备份
自动备份由每种类型的调度程序(FULL、DIFFERENTIAL、PARTIAL)驱动,并可配置为:
- 根据每种备份类型的配置间隔独立运行
- 在自动备份开始前发送可选的公共警告
- 如果自上次备份以来没有玩家在线,则暂停
- 在服务器启动时运行
- 在服务器停止时运行
公共公告可以发送到聊天栏、动作栏,或者禁用。
保留策略
保留策略可以同时通过两种方式配置:
- 基于数量的保留
- 保留最新的
X 个完整备份
- 保留最新的
X 个部分备份
- 保留最新的
X 个差异备份
- 每个世界的大小上限
- 为世界备份文件夹的总大小设置可选硬上限
- 应用于最终发布的备份集
- 尊重依赖链
如果新备份即使删除所有允许删除的备份后仍会超出配置的空间上限,则创建失败,而不是发布无效的最终状态。
性能:并行处理
备份和恢复使用多个工作线程来加速大型世界:
- 扫描/哈希计算:世界快照扫描跨
threadCount 个线程运行(最多每个 CPU 核心一个),并行读取和哈希文件
- 压缩:ZIP 存档使用并行压缩写入
- 恢复解压:备份 ZIP 文件跨
threadCount 个线程提取
线程数量由配置文件中的 threadCount 控制,可在 1 到最大 CPU 线程数之间设置(默认值:CPU 核心数减二)。较低的值会降低 CPU 使用率;较高的值会加速大型世界。
ZIP 压缩默认使用 DEFLATED,deflateCompressionLevel 控制压缩级别(1–9,默认值:6)。compressionMethod: "ZSTANDARD" 写入 ZIP 方法 93 条目,zstdCompressionLevel 控制级别(1–22,默认值:3)。DEFLATED 和 ZSTANDARD 均使用并行多线程压缩。对于 Zstandard,大条目会被溢出到临时暂存文件以限制内存使用。现有的 DEFLATED 存档仍然受支持。Zstandard 存档需要模组的 Zstandard 阅读器,可能无法在旧版 ZIP 实用程序中打开。
备份管理界面
备份浏览器包括:
- 刷新
- 创建备份
- 重命名备份
- 删除备份
- 恢复备份
- 依赖感知的内联详情
- 搜索/过滤
手动创建备份支持来自命令行和 UI 的自定义文件名。
配置 UI 和弹窗预览
配置界面提供以下选项:
- 备份模式和调度器选项
- 远程存储设置(提供商选择、S3/WebDAV 选项、重试次数)
- 保留规则
- 权限级别
- 完整性模式
- 备份目录和临时备份目录
- 排除路径
- 压缩方法和级别选项
- 启动备份最小年龄限制
- 弹窗文本、颜色、频道和布局
弹窗预览屏幕允许你在保存前移动并预览 HUD 状态。
在专用服务器上,配置界面仅客户端可用:它显示 HUD 和预览标签页(这些设置仅本地应用于弹窗),服务器设置需在服务器的 config/justenoughbackups.json 文件中编辑,随后执行 /jeb config reload。在单人游戏中,整个配置是共享的,并且可以从该界面进行编辑。
命令
根命令为:
/jeb
可用命令:
/jeb now
/jeb now <name>
/jeb create full
/jeb create full <name>
/jeb create partial
/jeb create partial <name>
/jeb create differential
/jeb create differential <name>
/jeb list
/jeb next
/jeb restore <backup>
/jeb config reload
注意:
<name> 是可选的,经过清理后成为实际的 .zip 文件名。
<backup> 是可见的备份名称,可带或不带 .zip 后缀。Tab 补全建议的是可见名称。
- 恢复是异步准备的,然后服务器关闭,以便在下一次启动时安全应用恢复。
/jeb next 显示多调度摘要,按接近程度排序,展示所有已配置备份类型的剩余时间和确切执行时间戳。
- 命令访问遵循配置的权限级别。
默认键位绑定
客户端键位绑定:
这些是标准的 Minecraft 键位绑定,可以在“控制”中更改。
配置
模组将配置文件写入:
config/justenoughbackups.json
主要配置区域:
backupMode
pauseAutomaticBackupsWithoutPlayers
backupOnServerStart
backupOnServerStop
automaticSchedule
full (enabled, intervalMinutes)
differential (enabled, intervalMinutes)
partial (enabled, intervalMinutes)
automaticBackupWarningEnabled
automaticBackupWarningMinutes
commandPermissionLevel
messageChannel
integrityMode
includeSummaryFile
minimumFreeSpaceReserveMb
threadCount
compressionMethod
deflateCompressionLevel
zstdCompressionLevel
startupBackupThreshold
fullMinutes
partialMinutes
differentialMinutes
remoteStorage
enabled
provider (S3 或 WEBDAV)
maxRetries
- S3 选项:
s3Endpoint, s3Region, s3Bucket, s3Prefix, s3AccessKey, s3SecretKey
- WebDAV 选项:
webDavUrl, webDavPrefix, webDavUsername, webDavPassword
backupDirectory
tempBackupDirectory
excludedPaths
excludeSafetyBackupsFromIncremental
retention
full
incremental
differential
maxTotalSizeMb
popup
backupDirectory 可以是相对于游戏目录的路径,也可以是绝对路径。
tempBackupDirectory 控制备份 ZIP 在移动到 backupDirectory 之前被压缩的位置。它可以是相对于游戏目录的路径,也可以是绝对路径。留空表示在备份目录内压缩(默认)。当备份存储在缓慢或网络驱动器上时,建议将其指向本地驱动器,因为只有完成的 ZIP 文件才会被传输到备份位置。
excludedPaths 使用相对于世界根目录的路径。文件夹条目排除整个子树,而文件条目仅排除特定文件。
示例:
voxy
voxy/cache.db
excludeSafetyBackupsFromIncremental 防止“旧世界恢复”安全备份被用作增量/差异备份的基础。
threadCount 控制并行扫描、压缩和恢复提取,并在 1 和 CPU 线程数之间进行限制。
compressionMethod 在标准 DEFLATED ZIP 压缩和 ZSTANDARD (ZIP 方法 93) 之间进行选择。两种方法都使用并行多线程压缩。deflateCompressionLevel 配置 Deflate 级别,从 1(最快)到 9(最小,默认值:6)。zstdCompressionLevel 配置 Zstandard 级别,从 1(最快)到 22(超压缩,默认值:3)。
startupBackupThreshold 设置每种类型的最成功备份的最小年龄(分钟),在此之后才会运行该类型的启动备份。值为 0 保持现有行为。计划备份和关机备份不受影响。
在创建备份之前,模组还会检查备份目标文件系统上的可用磁盘空间。检查非常保守,要求:
(当前世界大小 * 2) + minimumFreeSpaceReserveMb
如果空间不足,将在写入临时 ZIP 之前中止备份创建。
备份命名
手动备份支持自定义名称:
- 来自命令:
/jeb now My backup
- 来自备份 UI 中的创建对话框
如果未提供自定义名称,模组使用基于类型和时间戳的自动命名方案。
重命名使用与手动创建相同的清理规则,以保持命名行为的一致性。
许可证
本项目根据 MIT 许可证 授权。
Just Enough Backups is a Fabric mod that adds server-side world backups with a usable in-game workflow.
It supports:
- full, partial, and differential backups
- manual backups through commands and UI
- automatic scheduled backups
- configurable public backup/restore announcements
- retention by backup count
- retention by total backup size per world
- restore preparation from the backup browser
- a configurable client HUD popup with live preview
- parallel (multi-threaded) scanning, compression, and restore extraction
- optional Zstandard compression inside ZIP archives
- optional remote backup storage (S3-compatible and WebDAV)
- optional Mod Menu integration
The mod is designed to keep the actual backup logic on the server side while exposing management and configuration through a client UI.
Remote storage
Remote storage is disabled by default. The configuration screen has a dedicated Remote tab with a provider selector, enable switch, and fields for S3 (endpoint, region, bucket, prefix, access key, secret key) and WebDAV (URL, prefix, username, password). For S3, bucket and region are required; the endpoint is optional for AWS and can point to an S3-compatible service. For WebDAV, set the collection URL. Credentials can be configured directly in the screen (secrets are masked) or set in config/justenoughbackups.json or through environment variables, which take precedence and avoid storing plaintext secrets on disk.
Set credentials in the server config or use environment variables, which take precedence:
- S3:
JEB_S3_ACCESS_KEY_ID and JEB_S3_SECRET_ACCESS_KEY
- WebDAV:
JEB_WEBDAV_USERNAME and JEB_WEBDAV_PASSWORD
Use HTTPS for remote endpoints. Plain HTTP is accepted only for loopback development endpoints. Remote backups are published after upload and SHA-256 verification; their catalog contains the metadata and checksum. Retention protects bases required by incremental chains. Restore downloads each required archive as a stream into isolated staging, verifies its checksum, then verifies the reconstructed world before preparing the world replacement. remoteStorage.maxRetries bounds upload attempts; a failed WebDAV upload restarts compression and transfer, while interrupted uploads are not resumed across process restarts. Do not place credentials in shared or committed config files.
Features
Backup types
- Full: creates a complete snapshot of the entire world at the moment of backup. No base backup is required and it serves as the foundation for later incremental backups.
- Partial: creates an incremental backup containing only the files that have changed since the most recent backup of any type (full, partial, or differential). It uses that most recent backup as its base.
- Differential: creates an incremental backup containing only the files that have changed since the most recent full backup. Differential backups are stored in a separate retention bucket from partial backups, allowing independent retention policies.
Dependencies between backups are tracked. Retention and delete operations respect those dependencies, so required base backups are preserved when newer partial or differential backups still depend on them.
Automatic backups
Automatic backups are driven by per-type schedulers (FULL, DIFFERENTIAL, PARTIAL) and can be configured to:
- run independently based on configured intervals for each backup type
- send optional public warning before an automatic backup starts
- pause when no players have been online since the last backup
- run on server start
- run on server stop
Public announcements can be sent to chat, sent to the action bar, or disabled.
Retention policy
Retention can be configured in two ways at the same time:
- count-based retention
- keep the newest
X full backups
- keep the newest
X partial backups
- keep the newest
X differential backups
- size cap per world
- optional hard cap for the total size of a world's backup folder
- applied to the final published backup set
- respects dependency chains
If a new backup would exceed the configured space cap even after deleting every backup that is allowed to be removed, creation fails instead of publishing an invalid final state.
Performance: parallel processing
Backups and restores use multiple worker threads to speed up large worlds:
- scanning / hashing: the world snapshot scan runs across
threadCount threads (up to one per CPU core), reading and hashing files in parallel
- compression: the ZIP archive is written with parallel compression
- restore extraction: backup ZIP files are extracted across
threadCount threads
The number of threads is controlled by threadCount in the config and can be set between 1 and the maximum number of CPU threads (default: CPU cores minus two). Lower values reduce CPU usage; higher values speed up large worlds.
ZIP compression uses DEFLATED by default, with deflateCompressionLevel controlling the compression level (1–9, default: 6). compressionMethod: "ZSTANDARD" writes ZIP method 93 entries and zstdCompressionLevel controls the level (1–22, default: 3). Both DEFLATED and ZSTANDARD use parallel multi-threaded compression. For Zstandard, large entries are spilled to temporary scratch files to bound memory usage. Existing DEFLATED archives remain supported. Zstandard archives require the mod's Zstandard reader and may not open in older ZIP utilities.
Backup management UI
The backup browser includes:
- refresh
- create backup
- rename backup
- delete backup
- restore backup
- dependency-aware inline details
- search/filtering
Manual backup creation supports a custom file name from both the command line and the UI.
Config UI and popup preview
The config screen exposes:
- backup mode and scheduler options
- remote storage settings (provider selection, S3/WebDAV options, retries)
- retention rules
- permission level
- integrity mode
- backup directory and temporary backup directory
- excluded paths
- compression method and level options
- startup backup minimum age limits
- popup text, colors, channels, and layout
The popup preview screen lets you move and preview the HUD state before saving.
On a dedicated server the config screen is client-side only: it shows the HUD and Preview tabs (which apply locally to the popup), and server settings are edited on the server's config/justenoughbackups.json file followed by /jeb config reload. In single-player the whole config is shared and editable from the screen.
Commands
The root command is:
/jeb
Available commands:
/jeb now
/jeb now <name>
/jeb create full
/jeb create full <name>
/jeb create partial
/jeb create partial <name>
/jeb create differential
/jeb create differential <name>
/jeb list
/jeb next
/jeb restore <backup>
/jeb config reload
Notes:
<name> is optional and becomes the real .zip file name after sanitization.
<backup> is the visible backup name, with or without the .zip suffix. Tab completion suggests the visible name.
- restore is prepared asynchronously and then the server shuts down so the restore can be applied safely on the next startup.
/jeb next displays a multi-schedule summary showing remaining times and exact execution timestamps for all configured backup types, sorted by proximity.
- command access follows the configured permission level.
Default keybindings
Client-side keybindings:
B: open backup management
N: open config screen
These are regular Minecraft keybindings and can be changed in Controls.
Configuration
The mod writes its config file to:
config/justenoughbackups.json
Main config areas:
backupMode
pauseAutomaticBackupsWithoutPlayers
backupOnServerStart
backupOnServerStop
automaticSchedule
full (enabled, intervalMinutes)
differential (enabled, intervalMinutes)
partial (enabled, intervalMinutes)
automaticBackupWarningEnabled
automaticBackupWarningMinutes
commandPermissionLevel
messageChannel
integrityMode
includeSummaryFile
minimumFreeSpaceReserveMb
threadCount
compressionMethod
deflateCompressionLevel
zstdCompressionLevel
startupBackupThreshold
fullMinutes
partialMinutes
differentialMinutes
remoteStorage
enabled
provider (S3 or WEBDAV)
maxRetries
- S3 options:
s3Endpoint, s3Region, s3Bucket, s3Prefix, s3AccessKey, s3SecretKey
- WebDAV options:
webDavUrl, webDavPrefix, webDavUsername, webDavPassword
backupDirectory
tempBackupDirectory
excludedPaths
excludeSafetyBackupsFromIncremental
retention
full
incremental
differential
maxTotalSizeMb
popup
backupDirectory may be relative to the game directory or an absolute path.
tempBackupDirectory controls where the backup ZIP is compressed before being moved into backupDirectory. It may be relative to the game directory or an absolute path. Leave it empty to compress inside the backup directory (default). Pointing it at a local drive is recommended when backups are stored on a slow or networked drive, since only the finished ZIP is then transferred to the backup location.
excludedPaths uses paths relative to the world root. A folder entry excludes that full subtree, while a file entry excludes only that specific file.
Examples:
voxy
voxy/cache.db
excludeSafetyBackupsFromIncremental prevents "Old_World restore" safety backups from being used as base for incremental/differential backups.
threadCount controls parallel scanning, compression, and restore extraction, and is clamped between 1 and the number of CPU threads.
compressionMethod selects between standard DEFLATED ZIP compression and ZSTANDARD (ZIP method 93). Both methods use parallel multi-threaded compression. deflateCompressionLevel configures the Deflate level from 1 (fastest) to 9 (smallest, default: 6). zstdCompressionLevel configures the Zstandard level from 1 (fastest) to 22 (ultra compression, default: 3).
startupBackupThreshold sets the minimum age in minutes for the most recent successful backup of each type before a startup backup of that type runs. A value of 0 keeps the existing behavior. Scheduled and shutdown backups are unaffected.
Before creating a backup, the mod also checks free disk space on the backup destination filesystem. The check is conservative and requires:
(current world size * 2) + minimumFreeSpaceReserveMb
If that space is not available, backup creation is aborted before the temporary ZIP is written.
Backup naming
Manual backups support custom names:
- from commands:
/jeb now My backup
- from the create dialog in the backup UI
If no custom name is provided, the mod uses the automatic naming scheme based on type and timestamp.
Rename uses the same sanitization rules as manual creation to keep naming behavior consistent.
License
This project is licensed under the MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧