配置文件

配置文件详解¶

这是对配置文件的完整解释。如果你想深入了解它，那就接着往下看吧

根配置¶

这是配置文件中的根 json 对象

{
    "enabled": true,
    "debug": false,
    "storage_root": "./pb_files",
    "concurrency": 1,

    // 子配置。详见以下各节
    "command": {/* 命令配置 */},
    "server": {/* 服务器配置 */},
    "backup": {/* 备份配置 */},
    "scheduled_backup": {/* 定时备份配置 */},
    "prune": {/* 修剪配置 */},
    "database": {/* 数据库配置 */}
}

enabled¶

插件的开关。设置为 false 以禁用插件

• 类型：bool
• 默认值：false

debug¶

调试开关。设置为 true 以启用调试日志

• 类型：bool
• 默认值：false

storage_root¶

Prime Backup 储存各种数据文件所用的根目录

这是一个相对于 MCDR 工作目录的相对路径。默认情况下，根目录将是 /path/to/mcdr_root/pb_files

• 类型：str
• 默认值："./pb_files"

concurrency¶

在任何任务 / 操作的执行期间使用的最大并发数

将并发数设置为更高的值（例如 4）可以加快备份创建和回档等操作的速度， 但这也会让这些操作消耗更多的 CPU

值 0 表示使用 50% 的 CPU

• 类型：int
• 默认值：1

命令配置¶

{
    "prefix": "!!pb",
    "permission": {
        "root": 0,
        "abort": 1,  
        "back": 2,
        "confirm": 1,
        "database": 4,
        "delete": 2,
        "delete_range": 3,
        "export": 4,
        "list": 1,
        "make": 1,
        "prune": 3,
        "rename": 2,
        "show": 1,
        "tag": 3
    },
    "confirm_time_wait": "1m",
    "backup_on_restore": true,
    "restore_countdown_sec": 10
}

prefix¶

MCDR 中，Prime Backup 所有命令的前缀。通常你不需要更改它

• 类型：str
• 默认值："!!pb"

permission¶

所有子命令所需的 MCDR 权限等级 的最低要求

它是一个从字符串映射到整数的映射表，存储所有子命令的权限级别要求。 如果子命令不在映射表中，将使用 1 作为默认的权限等级要求

例如，在默认配置中，"back" 被映射到 2， 这意味着 !!pb back 命令需要权限级别 >=2 才能执行

特别地，"root" 指的是根命令，通常即 !!pb 指令

• 类型：Dict[str, int]

confirm_time_wait¶

有一些命令需要用户输入 !!pb confirm 才可继续执行。 这里定义了这些命令的最长等待时间

若等待超时，则命令将被取消执行

• 类型：Duration
• 默认值："1m"

backup_on_restore¶

在回档至指定备份前，是否要自动创建一个备份。这一类备份被称为“回档前备份”，类型为临时备份

这是一道为那些傻瓜用户准备的安全保障

• 类型：bool
• 默认值：true

restore_countdown_sec¶

在回档时，关闭 Minecraft 服务器前，执行倒计时的持续秒数

• 类型：int
• 默认值：10

服务器配置¶

与 Minecraft 服务器交互相关的选项

{
    "turn_off_auto_save": true,
    "commands": {
        "save_all_worlds": "save-all flush",
        "auto_save_off": "save-off",
        "auto_save_on": "save-on"
    },
    "saved_world_regex": [
        "Saved the game",
        "Saved the world"
    ],
    "save_world_max_wait": "10m"
}

turn_off_auto_save¶

是否应在进行备份之前关闭自动保存

由于关闭自动保存可以确保在备份期间，Minecraft 存档文件不会发生变化，因此建议将此选项设置为 true

• 类型：bool
• 默认值：true

commands¶

Prime Backup 使用的 Minecraft 指令的集合。目前它们仅在创建备份期间使用

Prime Backup 在创建备份时的操作时序如下：

1. 如果配置 turn_off_auto_save 为 true，则使用子配置 auto_save_off 存储的命令关闭自动保存
2. 使用子配置 save_all_worlds 存储的命令，触发服务器保存
3. 等待直到世界保存完毕，即服务器输出与 saved_world_regex 的某一个正则表达式成功匹配
4. 创建备份
5. 如果配置 turn_off_auto_save 为 true，则使用子配置 auto_save_on 存储的命令打开自动保存

saved_world_regex¶

一个正则表达式列表，用于识别服务器是否已保存完成

• 类型：List[re.Pattern]

save_world_max_wait¶

在创建备份期间，等待世界保存完成的最长等待时间

• 类型：Duration
• 默认值："10m"

备份配置¶

与创建配置具体细节相关的配置

{
    "source_root": "./server",
    "source_root_use_mcdr_working_directory": false,
    "targets": [
        "world"
    ],
    "ignored_files": [],
    "ignore_patterns": [
       "**/session.lock"
    ],
    "follow_target_symlink": false,
    "hash_method": "xxh128",
    "compress_method": "zstd",
    "compress_threshold": 64
}

source_root¶

进行备份/还原操作的根目录

通常应该是 MCDR 配置中，服务端的 工作目录， 即默认情况下的 server 目录

• 类型：str
• 默认值："./server"

source_root_use_mcdr_working_directory¶

若设置为 true，则使用 MCDR 配置中，服务端的工作路径作为 source_root 的值。 此时，配置文件中 source_root 键的值将被忽略

• 类型：bool
• 默认值：false

targets¶

要备份的目标文件/目录

通常来讲，你需要在整理添加你的存档文件夹的名字

例如，对于像 bukkit 那样把每个维度存在独立的文件夹里的服务器，你可能需要这么配置：

"targets": [
    "world",
    "world_nether",
    "world_the_end"
]

• 类型：List[str]

ignored_files¶

在备份时忽略的文件名列表

若文件名字符串以 * 开头，则将忽略以指定字符串结尾的文件， 如 *.test 表示忽略所有以 .test 结尾的文件，如 a.test

若文件名字符串以 * 结尾，则将忽略以指定字符串开头的文件， 如 temp* 表示忽略所有以 temp 开头的文件，如 tempfile

• 类型：List[str]

ignore_patterns¶

一个 gitignore 风格 的模板串列表，用于在创建备份的过程中匹配并忽略指定的文件 / 文件夹

模板串匹配时的根路径是 source_root。 例如，如果 source_root 是 server，那么模板串 world/trash*.obj 将匹配 server/world/trash1.obj

默认包含一个 **/session.lock 模板串，用于匹配位于任何位置的，名为 session.lock 的文件， 以解决 Windows 下 session.lock 被服务端占用导致备份失败的问题

• 类型：List[str]

follow_target_symlink¶

在设为 true 时，对于类型为符号链接的 备份目标， Prime Backup 除了会创建它们的备份外， 还会把符号链接的实际目标包括在备份目标中

例如，对于以下符号链接关系图：

world --> foo --> bar
^
备份目标

Prime Backup 除了会保存 world 这个符号链接外，还会保存 foo 符号链接，和最终的的 bar 文件夹

• 类型：bool
• 默认值：false

hash_method¶

对文件进行哈希时所使用的算法。可用选项："xxh128"、"sha256"、"blake3"

哈希算法	描述	速度	密码学安全性
xxh128	一种极快的、高质量的 128 位哈希算法，不提供密码学安全性。推荐使用，除非你想要理论上的极端安全	★★★★★
sha256	一种广泛使用的、密码学安全的 256 位哈希算法。它比 xxh128 慢，但如果 CPU 带硬件加速的话也不会太慢	★★
blake3	一种高效的、密码学安全的哈希算法。比 sha256 快很多，但是依然比 xxh128 慢	★★★☆

pip3 install blake3

• 类型：str
• 默认值："xxh128"

compress_method¶

在储存备份中的文件时，所使用的压缩方法

pip3 install lz4

• 类型：str
• 默认值："zstd"

compress_threshold¶

对于大小小于 compress_threshold 的文件，不启用压缩。它们将以 plain 格式存储

• 类型：int
• 默认值：64

定时备份配置¶

定时备份功能的配置

该功能会定期为服务器自动创建备份

{
    "enabled": false,
    "interval": "12h",
    "crontab": null,
    "jitter": "10s",
    "reset_timer_on_backup": true,
    "require_online_players": false,
    "require_online_players_blacklist": []
}

enabled, interval, crontab, jitter¶

见 定时作业配置 小节

reset_timer_on_backup¶

是否在每次手动备份时重置计划定时器

该功能仅在定时备份作业使用间隔模式的定时器的时候，才有效果

• 类型：bool
• 默认值：true

require_online_players¶

若设为 true，则只有在服务器中存在玩家时，才正常进行定时备份。 如果所有玩家均已离线，则在下一次定时备份完成后，之后的定时备份都会被跳过。 也就是说，Prime Backup 在没有玩家在线上时，只会触发一次定时备份

时间线举例：

flowchart LR
    subgraph g1[有玩家在线]
    b1[8:00\n备份创建] --> b2
    end

    subgraph g2[无玩家在线]
    b2[9:00\n备份创建] --> b3
    b3[10:00\n备份创建] --> b4:::disabled
    b4[11:00\n备份跳过] --> b5:::disabled
    end

    subgraph g3[有玩家在线]
    b5[12:00\n备份跳过] --> b6
    b6[13:00\n备份创建]
    end

    classDef disabled fill:#eee,stroke:#aaa,color:gray

• 类型：bool
• 默认值：false

require_online_players_blacklist¶

在 require_online_players 判断是否存在玩家在线时， 排除的玩家名正则表达式列表

如果你希望服务器中只有某些玩家在线的时候，也视作服务器中不存在玩家， 不进行定时备份，则可以使用该选项

配置举例：

"require_online_players_blacklist": [
    "bot_.*",  // 匹配所有以 "bot_" 为前缀的玩家名
    "Steve"    // 匹配 "Steve" 这个玩家名
]

• 类型：List[re.Pattern]
• 默认值：[]

清理配置¶

Prime Backup 的备份清理功能可用于自动清理过时备份

{
    "enabled": true,
    "interval": "3h",
    "crontab": null,
    "jitter": "20s",
    "timezone_override": null,
    "regular_backup": {
        "enabled": false,
        "max_amount": 0,
        "max_lifetime": "0s",
        "last": -1,
        "hour": 0,
        "day": 0,
        "week": 0,
        "month": 0,
        "year": 0
    },
    "temprory_backup": {
        "enabled": true,
        "max_amount": 10,
        "max_lifetime": "30d",
        "last": -1,
        "hour": 0,
        "day": 0,
        "week": 0,
        "month": 0,
        "year": 0
    }
}

它包含两种清理设置，分别针对于如下两种类型的备份：

• regular_backup: 针对常规备份，即非临时备份
• temporary_backup: 针对临时备份，如回档前的备份

每种清理设置都详细描述了存档的保留策略

Prime Backup 会执行以下步骤来决定删除/保留哪些备份

1. 使用 last, hour, day, week, month, year， 基于 PBS 保留策略，筛选出要删除/保留的备份
2. 使用 max_amount、max_lifetime 这两条规则，在第一步保留的那些备份里，筛出那些旧的和过期的备份
3. 收集上述两次筛选过程中，找到的哪些需要删除的备份，并逐个进行删除

删除备份相关的决策结果会以日志形式储存在 数据根目录 的 logs/prune.log 文件里

Backup #147 at 2023-12-10 21:49:09: keep=True reason=keep last 1
Backup #146 at 2023-12-10 21:36:10: keep=True reason=keep last 2
Backup #145 at 2023-12-10 21:26:25: keep=True reason=keep last 3
Backup #144 at 2023-12-10 21:21:22: keep=False reason=superseded by 145 (hour)
Backup #143 at 2023-12-10 21:16:19: keep=False reason=superseded by 145 (hour)
Backup #142 at 2023-12-10 21:11:14: keep=False reason=superseded by 145 (hour)
Backup #141 at 2023-12-10 21:05:06: keep=False reason=superseded by 145 (hour)
Backup #140 at 2023-12-10 21:00:03: keep=True reason=protected
Backup #139 at 2023-12-10 20:55:01: keep=True reason=keep hour 1
Backup #138 at 2023-12-10 20:49:57: keep=False reason=superseded by 139 (hour)
Backup #137 at 2023-12-10 20:44:53: keep=False reason=superseded by 139 (hour)
Backup #136 at 2023-12-10 20:39:45: keep=False reason=superseded by 139 (hour)
Backup #135 at 2023-12-10 20:34:41: keep=False reason=superseded by 139 (hour)
Backup #128 at 2023-12-10 19:59:06: keep=True reason=keep hour 2
Backup #116 at 2023-12-10 18:56:14: keep=True reason=keep hour 3
Backup #104 at 2023-12-10 17:55:35: keep=False reason=superseded by 116 (day)
Backup #22 at 2023-12-09 23:59:53: keep=True reason=keep day 1

max_amount¶

定义要保留的最大备份数量，例如 10 表示最多保留最新的 10 个备份

设置为 0 表示无限制

• 类型：int

max_lifetime¶

定义所有备份的最大保存时长。超出给定时长的备份将被清理

设置为 0s 表示无时长限制

• 类型：Duration

last, hour, day, week, month, year¶

一组 PBS 风格的清理选项，用于描述备份的删除/保留方式

查看 清理模拟器 了解这些选项的更多解释

清理模拟器 也可用于模拟备份的保留策略

注意：值 0 表示不为该区间保留任何备份；值 -1 表示该区间可以保留无限多的备份，与设为极大值等价

• 类型：int

enabled, interval, crontab, jitter¶

见 定时作业配置 小节

timezone_override¶

在备份清理时所使用的时区。默认情况下（使用 null 值），Prime Backup 将使用本地时区

例子：null, "Asia/Shanghai", "US/Eastern", "Europe/Amsterdam"

• 类型：Optional[str]
• 默认值：null

数据库配置¶

Prime Backup 所使用的 SQLite 数据库的相关配置

{
    "compact": {
        "enabled": true,
        "interval": null,
        "crontab": "0 7 * * *",
        "jitter": "1m"
    },
    "backup": {
        "enabled": true,
        "interval": null,
        "crontab": "0 6 * * 0",
        "jitter": "1m"
    }
}

子配置 compact 和 backup 描述了与数据库相关的定时作业

compact¶

数据库精简作业

它对数据库使用了 VACUUM指令， 以精简数据库文件，并释放未使用的空间

backup¶

数据库备份作业

默认情况下，Prime Backup 会定期在 数据根目录 内的 db_backup 目录中创建数据库备份，以防数据库文件损坏而导致无法访问备份

数据库备份将以 .tar.xz 格式存储，不会占用太多空间

enabled, interval, crontab, jitter¶

见 定时作业配置 小节

子配置项说明¶

定时作业配置¶

一个定时作业相关的配置，用于描述该作业会在什么时候执行。有两种模式：

• 间隔模式：按给定的时间间隔执行作业。第一次执行也要等待给定的间隔
• 定时模式: 在特定时间执行作业，由 crontab 字符串描述

若作业被启用，你必须选择上述模式之一，并正确设置相关配置值

// 例子
{
    "enabled": true,
    "interval": "1h",
    "crontab": null,
    "jitter": "10s"
}

enabled¶

作业的开关。设为 true 以启用该作业，设为 false 以禁用该定时作业

• 类型：bool

interval¶

在间隔模式中使用。两次任务之间的时间间隔

若作业未使用间隔模式，其值应为 null

• 类型：Optional[str]

crontab¶

在定时模式中使用。描述定时计划的一个 crontab 字符串

你可以使用 https://crontab.guru/ 来创建一个 crontab 字符串

若作业未使用定时模式，其值应为 null

• 类型：Optional[str]

jitter¶

两次作业之间，执行之间的抖动

下一个任务的实际执行时间，将在范围 [0, jitter] 内进行随机偏移

设置为 "0s" 表示无抖动

• 类型：str

特殊的值类型¶

Duration¶

使用字符串描述的时间持续长度，如："3s"、"15m"

Duration 由两部分组成：数字和时间单位。

对于数字部分，它可以是整数或浮点数

对于单位部分，参见下表：